ui: the tour and the contextual help follow the badge bar, the slide-over and the dock

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/ui_app.hpp

@@ -73,9 +73,11 @@ enum class EventGroupKind {
 /// do not exist yet.
 struct TourStop {
   GtkWidget* target;
-  /// The named page of the view's `page_stack` the target lives on, or nullptr when the stop needs no
-  /// page. The tour selects it as the stop is entered, so a target on a page the user has left is
-  /// made visible instead of being walked over or spotlighted where it is not.
+  /// The page the target lives on, or nullptr when the stop needs none. What a page *is* depends on
+  /// the view: a named page of its `page_stack` (the chooser), or whatever its `on_page` hook opens
+  /// (the main window: a slide-over page id). The tour selects it as the stop is entered, so a target
+  /// on a page the user has left is made visible instead of being walked over or spotlighted where it
+  /// is not. A stop with no page *closes* what an `on_page` hook opened.
   const char* page;
   const char* title;
   const char* body;
@@ -103,6 +105,16 @@ struct TourView {
   /// sidebar; the chooser's two pages), so it is the view's and not each stop's. Set where the walk
   /// begins, when the widgets exist; null leaves every stop on the page it finds.
   GtkWidget* page_stack = nullptr;
+  /// The alternative to `page_stack` for a surface that is not a stack: when set it *replaces* the
+  /// stack mechanism for this view, and is called with each stop's `page` as the stop is entered --
+  /// `nullptr` meaning "no page needed" -- and with `nullptr` as the walk ends. The main window's opens
+  /// and closes the slide-over through it; the chooser keeps `page_stack`.
+  void (*on_page)(void* user, const char* page) = nullptr;
+  void* page_user = nullptr;
+  /// Optional, with `on_page`: whether the surface `on_page` opened has finished appearing. A stop that
+  /// names a page is not spotlit while this answers false -- a panel that is still sliding in is a
+  /// target that moves, and a spotlight that follows it for 120 ms reads as a glitch. Null means "ready".
+  bool (*page_settled)(void* user) = nullptr;
   /// Runs when the walk passes its last stop (Next/Finish, never Skip): the chooser's hands the tour
   /// on to the application through `Config::tour_pending`.
   void (*on_done)(void* user) = nullptr;
@@ -2114,6 +2126,10 @@ void tour_end(TourView& view);
 void tour_update(TourView& view);
 /// The widget the current stop points at, or nullptr when the walk is not on a stop.
 GtkWidget* tour_target(TourView& view);
+/// The part of `target` that is on screen, in `overlay`'s coordinates: its bounds intersected with every
+/// scrolled window above it. False when it cannot be measured yet or is scrolled out of sight entirely.
+/// The spotlight is drawn from it, and the probe reads the spotlight against it.
+bool tour_target_bounds(GtkWidget* target, GtkWidget* overlay, graphene_rect_t* out);
 
 /// Builds the *window's* tour inside `app.tour.overlay`. Called once, as the overlay is inserted.
 void build_tour(App& app);