# Invariants: GTK traps, the status bar, the icons and the manual The GTK signal-signature and dialog-lifetime traps this app has already fallen into, plus the status bar's two tiers, the bundled icons and how the Mallard manual is installed and opened. Part of [CLAUDE.md](../../CLAUDE.md). These are rules that cost a defect to learn; read the ones touching the area you are editing before you edit it. - **The status line's per-second fields are measured once a second, not per frame.** `App::stored_rate`/`declared_rate` and the label's tooltip are refreshed on the same tick as the channel dump; the status line only formats what is already there. The badge's markup is likewise rewritten on a change of phase (twice a second), never on all sixty frames. - **A `notify::` handler takes three parameters, a `value-changed` handler two.** `GObject::notify` passes `(GObject*, GParamSpec*, gpointer)` while `GtkSpinButton::value-changed` passes `(GtkSpinButton*, gpointer)`, so one callback cannot serve both: on the `notify::` connection the `GParamSpec*` lands in the `user_data` slot and the handler dereferences it as its `App*`. `G_CALLBACK` is a cast, so nothing warns. That is why the trigger panel's spin buttons and its dropdowns have separate thin entry points (`on_trigger_field_changed`, `on_trigger_drop_changed`) onto one `publish_trigger_fields()`: changing the edge or Normal/Single dropdown used to segfault outright. `UDPSCOPE_PROBE_FIELDS_MS` is the guard. - **`MeasureDialog` and `MathDialog` are brace-initialised *positionally* in `src/ui.cpp`**, so a field added in the middle of either silently shifts every argument after it: add at the end of the widget group and read the initialiser in the same commit. A row array widened by a new control is the same trap from the other side -- a `rows[N]` that was not grown shows a control the sync never touches, and the compiler says so as an out-of-bounds warning on `rows`. - **A control that cannot affect the current type is *hidden*, not disabled**: the trigger's band row is hidden for `dropout`, the measurement's for every non-crossing type, and the node editor's median row for every op but `de-noise`. A greyed row is a question the user can see and cannot answer. - **`GtkDropDown`'s `notify::selected` arrives after the `set_selected()` that caused it returns**, so the `updating_panels` flag — set around a programmatic write and cleared when it returns — does *not* suppress it. Where the write is part of a readout the handler reads back, that is a feedback loop: `sync_window_display()` writes a value rounded for reading into the window entry and picks the unit for it, and the late notify had `on_window_unit_changed()` re-parse that rounded text, turning a 500 s request into 499.98 s. The guard is `App::window_sync_unit` — the unit we last synced — and a selection equal to it is ours, since GTK only notifies on a change. Any new control that both writes and reads a `GtkDropDown` needs the same shape; the flag alone is not enough. - **The header bar's buttons are icon-only**, so headless probes must reach them through the `App` pointers (`trigger_toggle`, `pause_button`, …), not via `find_labelled_button()`. The **pane switches are toolbar buttons** too (`cursors_toggle`, `measures_toggle`, `math_toggle` -- packed with `header_bar_pack_end()`, where the **first** packed is the rightmost, and the bar is an *ancestor* rather than the parent because packing parents into an internal box), and the cursors pane owns its own **Reset** button rather than the overflow menu owning one for it. The dump prints `panel controls: … ; toolbar, left to right: …` to say where they are and in what order. The widget tree's child order *is* the visual order left to right, so that line reads as the *reverse* of the pack order -- it is how an arrangement gets checked with no screenshot, and it is what finally settled the pack-order rule above (two comments in `build_toolbar()` disagreed with each other and one of them with reality): it is computed on the first *tick*, because the dump runs after the window is destroyed and asking GTK about a widget then is four criticals, which is how the first version of that line earned them. What stays in the menu is what acts on the *data* (Fit, Export, Configurations) and the one editor that is not a pane (the layout editor): the signal list is a section of the sidebar's dock, so there is nothing left to reveal or hide about it. The Arm/Disarm button in the trigger panel still has text. - **Five of this app's icons are its own, and they are a `GResource` compiled into the binary.** No icon theme has a glyph for an oscilloscope trigger, a pair of cursors or a measurement ruler, and the stock names those buttons used to carry said something else entirely: a *record dot* for the trigger and three different **magnifiers** for cursors, measurements and math. `src/icons/scalable/actions/udpscope-{trigger,cursors,measure,events,resize-rows}-symbolic.svg` are the five action icons. `udpscope-math-symbolic` left with the toolbar toggle that was its last user; `udpscope-measure-symbolic` **stayed**, because the Preferences window's Plot page carries it -- an icon with a live user is not an orphan, whatever the toggle that introduced it did -- and it is the Preferences window's icon. The sidebar has **no tabs any more** (it is one dock): two tab glyphs (`udpscope-tab-measure-symbolic`, `udpscope-tab-signals-symbolic`, each a 32x16 pair) were drawn for them and judged not understandable enough, so the tabs were text, and both SVGs were deleted. The *trigger's* own icon was redrawn to the Signals glyph's picture at that time and kept it. - **A shortcut table row's `accel` is GTK accelerator syntax, and a pointer gesture has none.** `src/shortcuts.cpp`'s strings are handed to `AdwShortcutsItem`, which parses them with `gtk_accelerator_parse()` — so they are `"space"`, `"e"`, `"slash"`, `"plus minus"` (a space-separated pair is the "either of these" form the label draws as `+ / -`), never the prose `"Ctrl+E"` or `"+ / -"`. Neither GTK's syntax nor libadwaita's knows a **wheel or a drag**: `"Wheel"` costs a `Failed to parse` warning and draws an empty cell. Those six rows therefore carry `accel = ""` and put the prose in `subtitle`, which is the one field that is free text. A row added with a parse error is otherwise silent — the overview still opens and the row is simply blank — so read the probe run's stderr for `Failed to parse` after touching either table. - **The status bar is two tiers, and the dump reads the detail one.** `format_glance()` writes the bar and `format_detail()` writes both the popover's prose and `App::status_detail`, which is what `exit_probe_step3`/`exit_probe_step2` copy into `dbg_mode_live`/`dbg_mode_triggered`. Those two used to read the *label*, and the label no longer carries `packets`, `gaps`, `plot 1:` or the buffer figures — so a `gtk_label_get_text()` there would silently reduce every documented `mode …:` assertion to four fields. The glance line's state field is **one word from a fixed set** (`connecting`, `live`, `paused`, `armed`, `capturing`, `event held`, `disarmed`) for the layout reason above; a word **wider than the widest already there**, or a field whose width tracks the stream, breaks the row the plot is laid out under. The set may grow — `connecting` was added for the no-CONFIG state — but only on that condition, and the check is the dump's `max_glance_chars`. `connecting` is derived from `have_config` alone and sits **ahead of every other branch**, including the display mode's: with no signal list, every other word claims something that does not exist yet. The `mode` prose branches the same way for the same reason, which is what keeps the two tiers from disagreeing. - **The ⓘ popover's widgets are built once and only their text is set.** It is visible when the tick updates it, so a rebuild is a per-frame relayout of a widget on screen. `update_status_popover()` only ever calls `gtk_label_set_text()`, and `popover_rebuilds` in the dump is the assertion. - **The About dialog and the shortcut overview are opened by `show_about()` and `show_shortcuts()`, and each closes with the matching call; the manual is *not* one of these.** `show_help()` hands the `help:` URI to the desktop help viewer (`GtkUriLauncher`, i.e. Yelp) — a process of its own that cannot be closed from here — because the manual is a Mallard set installed for the freedesktop `help:` URI, not a GResource in this binary (see the help bullet below). So there is exactly **one `GtkWindow`** among *that pair*: the shortcut overview. It closes with `gtk_window_close()`, which emits `close-request` so the handler that nulls the file-scope pointer runs. `gtk_window_destroy()` does **not** emit that signal and must not be used — the math dialog fell into exactly this trap, and the pointer then points at a dead widget until the next attempt to open the same window. **A `close-request` handler's return value is load-bearing too, and its absence is silent**: the signal is `gboolean`, `TRUE` means "handled" and suppresses the default handler that destroys the window, and `G_CALLBACK` is a cast — so a `void` lambda in the slot compiles without a warning and GTK reads whatever the compiler left in the return register as the verdict. The Configurations dialog (`open_configurations()`) was written that way, and the built binary returns non-zero from the lambda, so **both its Close button and the window manager's close button emitted `close-request`, were told "handled", and the dialog stayed up** — "the configurations dialog cannot be closed", which no reading of the callback's type can see. Every `close-request` handler therefore returns `FALSE` explicitly (the chooser's `on_chooser_close()`, the overview's `on_window_close()`, the math dialog's, and this one). The About dialog (an `AdwAboutDialog`) is an **`AdwDialog` and not a `GtkWindow`**: it closes with `adw_dialog_close()` and clears on `::closed`, there being no `::close-request` on an `AdwDialog`. It shares one `on_dialog_closed()` handler with the About pointer, keyed by a **pointer to the pointer** it must null (`&g_about`), which keeps the handler honest without knowing which dialog it is. One `GtkWidget*` (or `AdwDialog*`) per window, nulled in its own close handler, is the shape that prevents the double-open defect. `close_help_windows()` (misnamed now) closes just the two dialogs; a failed *launch* is reported by the launcher's own callback with a `GtkAlertDialog`, so a click that cannot open the manual says so. That callback is also `show_help()`'s **optional reporter** (`std::function`) — the one hook that runs on the success path, where no window of ours is left to observe; the probe uses it and nothing else does. - **`build_info.cpp` is generated, never committed.** `cmake/write_build_info.cmake` runs at configure time (so `add_executable` can name the file) and again on every build through `udpscope_build_info` (so the commit and the timestamp belong to the binary that is running). `git` absent leaves `kCommit` at `"unknown"` and the build succeeds. The About dialog and the `[help]` probe both read `kVersion`, `kCommit` and `kTimestamp` from it; `settings=` in the probe reads `config_dir()`, which is the path the session file is written to. - **The keyboard zoom's modifiers are not the wheel's.** `+`/`-` with **Ctrl** restricts to x and with **Alt** to y, while the wheel keeps upstream's Shift = x / Ctrl = y convention. The two cannot agree: Shift is unusable on the keyboard path because `key_from()` folds `'+'` and `'='` onto `kKeyZoomIn` — `+` *is* Shift+`=` on common layouts, so a bare zoom-in already arrives with `Mod::Shift` set. Ctrl+Alt together zooms neither axis, which needs no special case. The guards are `deps/plotter`'s own `ctrl_plus_zooms_only_x` and `alt_plus_zooms_only_y` tests, plus `UDPSCOPE_PROBE_ZOOMKEYS_MS`. - **A help page is a Mallard file, and the manual is *not* in the binary.** `help/C//` holds `index.page`, one `.page` per subject, and the `figures/*.png` the pages link, and the whole set is installed (the `install()` rule in CMakeLists) to `/help/C//` — the path the freedesktop Help System Specification's `help:` URI resolves `help:` to. The document identifier is *derived from the desktop file's basename* (`org.udpscope.app.desktop.in` → `org.udpscope.app`), so it is the `.desktop` name, the GApplication id and the install directory at once; `UDPSCOPE_HELP_NAME` and `UDPSCOPE_HELP_DIR` are compiled in from that one place. `show_help()` opens `help:` with `GtkUriLauncher` (Yelp runs in its own process, so nothing here holds a pointer to it), and its failure callback shows a `GtkAlertDialog`. That failure is **careful about which thing is missing**: `gtk_uri_launcher_launch_finish()` reports a launch that could not be handed over — the *handler's* absence — and cannot tell that from a document that was never installed, so `help_installed_path()` walks the specification's own `$XDG_DATA_HOME/help///` then `$XDG_DATA_DIRS/help///` for an `index.page` and the dialog says which one it is: with the manual there, install a viewer (for example `yelp`); with it absent, the identifier and the install command, the **system-wide** form first (`cmake -DCMAKE_INSTALL_PREFIX=/usr .. && sudo cmake --build build --target install-help`), the no-root `install-help-user` second with its caveat (see the location rule below) — and a viewer as well, the second possibility the error alone cannot rule out. Reporting a missing *document* as a missing *handler* is the defect that shape avoids. `UDPSCOPE_PROBE_HELP_MS` launches it too, and its `[help] launch attempted= done= ok= error='' installed=` line is the reading — `ok=1` is the URI handed to a viewer and not a window on screen, since Yelp is another process and cannot map one headlessly; `installed=` sits beside it because a failing `ok=0` has to be read against whether the document was there at all. `UDPSCOPE_PROBE_HELP_MS` no longer parses pages — they are files, not markup in a resource — so its `[help]` line asserts the set is *there*: `topics` (the `.page` files other than `index.page`), `index`, and `figures`, scanned from `UDPSCOPE_HELP_DIR`. `topics=0 index=0` means the manual is missing from the tree, which is the finding the old `parsed != pages` used to name. `cmake --build build --target test-help` checks the set the way `test-ui` checks the `.ui` files: `yelp-check`'s offline subcommands (links, media, orphans, ids) and a `yelp-build html` render. `yelp-check validate` is deliberately absent — it fetches the Mallard RelaxNG schema over the network and fails offline for that reason, not for a fault in the pages. The figures come from `tools/make-help-shots.sh`, which drives the app headlessly against the mock and annotates a grab (GTK4 must be forced to the Cairo renderer, `GSK_RENDERER=cairo`, or the X11 surface reads back blank). Mallard is translatable with `itstool`, but there is no i18n set-up here: only the `C` set is authored. **A user-local help set is one Yelp cannot draw the figures of, so the system-wide install is the one to recommend — and this is a *location* rule, not a markup or a file rule.** Yelp sandboxes its WebKit subprocess, and that sandbox exposes the system help directories (`/usr/share/help`, `/usr/local/share/help`) but not `$XDG_DATA_HOME/help`: the pages load, their `` figures do not, because each figure is a *separate file* the page references rather than something embedded in it. The symptoms read as anything but a location problem — opening a page *as a file* renders it with no images, and opening it through the app's `help:` URI leaves the viewer spinning **for ever**, the failed image fetch meaning the page's load event never fires while the sidebar title still updates, which looks like a navigation failure rather than a missing resource. A shipped GNOME page that carries a figure (`/usr/share/help/C/accerciser/api_browser_plugin.page`) draws either way, which is what isolates the cause to where the set *lives*. `make install-help` (into `/usr/local`) followed by `yelp /usr/local/share/help/C//.page` works; the same set under `~/.local/share/help` does not. Two genuine defects were chased and fixed before the location was found — a `
` with no `` and a `bKGD` chunk the PNG spec forbids on an alpha image — so do not read a figure that will not draw as a repeat of either, and do not revert those fixes: this is why both the failure alert in `src/help_window.cpp` and the manual's own `overview.page` name the system-wide install first and state the user-local one's caveat beside it. - **The chooser carries the same help affordances as the window, and the tour request crosses as a value — not a global.** The source chooser runs *before* `App` exists, so a user who has not started yet is the one least able to find the help; its header bar therefore has a help `GtkMenuButton` (the `.ui` holds the button, code holds the rows) whose three entries are the window's Help view's the same way — `ui_impl::menu_button()`/`menu_toggle()`, the app's own row shape — with the `.udpscope-menu` class on the popover. That class's rules only exist once `install_css()` has run, so `choose_source()` calls it before building the rows (`install_css()` is idempotent precisely because it now has two callers; the app's `on_activate()` still calls it and is a no-op by then). The rows show **no accelerators**: the window's Help view prints `F1`/`Ctrl+T` because the window binds them, and this dialog binds none, so a key printed here would be documentation that does nothing. *Documentation* calls `show_help()` straight from the chooser (the manual is another process and needs nothing of the app); *Enable contextual help* writes the settings file, which is what the app reads when it starts a moment later, and **re-syncs this dialog's own "(i)" rows** through `chooser_help_sync()`; *Guided tour* starts a tour **of this window** -- the chooser's own walk -- and that walk's last stop sets **`Config::tour_pending`**, the one value `main()` owns and hands to both `choose_source()` and `run_ui()` (`open_waveform` and the preferences' relative time cross the same way). `on_activate()` schedules `tour_start_requested()` 1.5 s later, the same delay the first-run auto-start uses, and **that callback is separate from `tour_autostart()` on purpose**: it sets `tour_requested`, not `tour_auto_started`, so `help layer:` says which of the two started the window's half instead of conflating a user's request with a first run. The chooser's half has its own entry points in `source_dialog.cpp` (`chooser_tour_begin`, `chooser_tour_autostart`), and *that* walk is what a first run meets first -- see the tour bullets in the help-affordance section below. - **A `GtkPaned` hands its start child at least its minimum unless the position says otherwise.** Putting the events pane in a paned is what makes its width the user's to drag -- but with the position left alone, `shrink-start-child` or not, the pane's minimum is reserved as an empty column while it is *closed*, and the plot pays for a pane nobody opened. The position is the only knob that says "no room": store the width when it is closed (reading `gtk_paned_get_position()` *before* zeroing it) and set 0, restoring it when the pane opens. `gtk_paned_set_shrink_start_child(TRUE)` is still needed, or the minimum would clamp even a zero position. - **An unrevealed `GtkRevealer` measures 0x0 and is still given the leftover width.** `reveal_child = FALSE` makes both the revealer's minimum and its natural size zero -- and its box then hands it everything the expanding sibling beside it did not claim, so a *collapsed* pane reserved a 310-pixel empty column between the window edge and a plot drawn 630 pixels wide in a 1270-pixel window. Every vertical revealer in the side panel hides this, because there the leftover goes down instead of across. `gtk_widget_set_visible()` is what a layout honours, so anything that must not take room has to be hidden and not merely unrevealed; the revealer keeps the slide while the pane *is* open. The allocated width is how this was found -- the revealer's own measure said 0. **The sidebar is one dock now, and has no `GtkRevealer` left in it**: a single `GtkScrolledWindow` (`dock_scroller`) holding the signal list, the cursors and the measurements one under another. It replaced an `AdwViewSwitcher` over an `AdwViewStack`, whose four text tabs did not fit 320 px (and a source can add more); a source kind's own panels are slide-over pages, not dock sections. The reason is the one this trap teaches: sections competing for one 320 px column each left every one of them short of room, and a scroller gives each its natural height. `m` and `g` scroll the dock to the cursors and to the signal list (`dock_show_section()`). A *feature's* on/off is no longer a visibility at all -- the **cursors'** toggle sets its pane's **body** insensitive -- the readout has nothing to show with the instruments off -- and the *body* and not the pane, because the pane's heading carries its own switch (see the next bullet). The **trigger's body is deliberately never disabled**: a trigger is configured *before* it is switched on, so switching it off to change it, or to read what it is set to, is the ordinary way to work. It used to go insensitive with the mode, which left the settings unreachable exactly when a user wanted to change them; `trigger panel sensitive …=1` is the regression guard, and a `0` there means the configuration has been locked out again. The trap itself does not go away with the widget: a section scrolled out of view is still laid out, but **ask about state, not about size** still holds for anything a tick reads. - **The dock is shown but insensitive until the stream has signals ("disable, do not hide").** `update_side_visibility()` and the tick's per-frame block set the column's visibility from the user's wish alone (`sidebar_wanted`) and the dock's *sensitivity* from `have_signals`; the toolbar's Dock button stays sensitive throughout. The wish is persisted (`dock = true|false` in the session file) and a change of it schedules a save. There is no tab icon to keep clear any more: the `keep_tabs_icon_free()` workaround for `AdwViewSwitcherButton`'s placeholder `[x]` image went with the switcher, and `dock:` in the dump replaces the `switcher:` line. - **An *overlaid* sidebar covers the plot, so a drag out of it has nowhere to land.** `collapsed` in an `AdwOverlaySplitView` means the sidebar sits *on* the plot rather than beside it: the pointer is over the list, never over a drop target, and a signal can be dragged but not dropped. `row_drag_sidebar()` hides the sidebar on `drag-begin` and restores it on `drag-end` — only when collapsed, because side by side the plot is already visible and hiding the list the drag started in would be startling. `pane drag: sidebar hidden for the drag=1 restored after it=1` is the reading; the state is forced collapsed the way the sidebar probe forces it. - **A stock icon name has to be one *Adwaita* has, and a blank button is the failure mode.** The two panes' `[edit]` buttons are `document-edit-symbolic` (the pencil: edit) and `object-select-symbolic` (the check: done). The done one was `emblem-ok-symbolic`, which breeze ships and **Adwaita does not** — so the button that leaves configuration mode was blank, which no other reading could see: the button worked, the layout was unchanged, and only `pane edits:` (the two names and `gtk_icon_theme_has_icon()`'s verdict, clicked into each mode) would say so. Check a name against `/usr/share/icons/Adwaita` before using it; a name found under `breeze` is not an answer. - **A pane's heading switch and the header bar's button are one control in two places.** Each pane's heading (`build_trigger_panel()` builds the trigger's, `cursors-panel.ui` has the cursors' in its `head`) carries a `GtkSwitch` that runs the *same action* the toolbar button runs, and `sync_panel_switches()` re-reads each pair from the toolbar's state after any change — so clicking either end moves both, and `panel switches: trigger=1/1 cursors=1/1` is the reading. Two traps: a `GtkSwitch` emits `notify::active` for a *programmatic* write as well, so the sync holds a guard (`App::panel_switch_sync`) or the program's own write comes back as a click; and the switch must stay *out* of what the pane disables, because a control inside an insensitive parent cannot be clicked — a switch that greyed out with its own pane could never turn it back on. That is why the sensitive target is the pane's **body** (`trigger_body`, `cursors_body`) and not the pane. - **A list box outlives the children of the pane it sits in, and the teardown order is not yours to choose.** Tearing the window down finalizes the events pane's buttons, then the list box, and the list's own `selected-rows-changed` then reaches a handler holding the freed pointers: four `Gtk-CRITICAL`s from `gtk_widget_set_sensitive` and a read of memory nobody owns. `close-request` is *not* the hook -- `UDPSCOPE_EXIT_AFTER_MS` ends the self-check with `gtk_window_destroy()`, which does not emit it. The hook that does work is `App::window`: every teardown path clears it *before* the widgets go (the exit probe says so in a comment: "stop the tick before the widgets go"), so a handler that can fire during teardown checks that first, rather than asking GTK whether a pointer is still a widget. - **A `GtkPicture`'s natural size *is* its content, so a size request on it is a floor, not a cap.** A 480x160 texture in a row of a list claims the row's whole width and squeezes the text beside it out of the row -- the box gives a non-expanding child its natural size and grows it further when the expanding child has nothing left to take. Give the picture a **frame** whose size request equals the **scaled texture's** size (natural == minimum, which is what stops the box growing it), and scale the texture once at decode: it is also what keeps a per-row cache at 12 KB per picture rather than 300. - **A pointer to a widget inside a list survives the list being rebuilt.** `events_thumb` named a row's picture across `refresh_events_pane()`, which removes every row first: the next reader of that pointer got a `Gtk-CRITICAL` from `gtk_picture_get_paintable` on freed memory (the four criticals read as "the pane is empty"). A rebuild has to null what it is about to destroy, not only rebuild it. - **`gtk_picture_set_filename()` can render nothing, silently.** It hands the file to the image loader's sandboxed, asynchronous decoder, which on this machine fails without a message: the picture keeps a *paint-able* and takes an allocation, so a probe that checks `gtk_picture_get_paintable()` reads success while the pane shows an empty rectangle (the event pane's preview did exactly that). `gdk_texture_new_from_filename()` decodes the same file on this thread and `gtk_picture_set_paintable()` hands over the result -- and a NULL texture at least says so. A picture that must be on screen is also a picture with a **height request**: `can_shrink` alone asks for no height at all in a box. - **A cache that is the *only* source of a widget's content must be created by the thing that reads it.** The event pane's thumbnails come from an `EventThumbCache` hung off the list box with `g_object_set_data_full`, and `event_preview_texture()` answers out of that cache or not at all. Nothing ever created it — so for as long as the pane existed, **every** row came up without a picture, which is what "event screenshot are unusable and sometime missing" was. A missing cache there is not a slow path, it is a blank one; `event_thumb_cache()` therefore creates one on first use. Owned by the **list**, because nothing else has the pane's lifetime: textures of a list that no longer exists are so much held memory, and the destroy notify is where they are unref'd. - **Hover magnification is a tooltip, not a popover of ours.** A row's thumbnail is 138 px wide and the stored preview is 480: the small one says *which* event this is, and the zoom says what is in it. GTK's own tooltip (`gtk_widget_set_has_tooltip` + `query-tooltip` + `gtk_tooltip_set_custom`) is shown, placed, dismissed **and destroyed** by GTK, and takes no pointer grab. A popover per row would be a parented widget to unparent on every rebuild of the pane — one defect below — and a grab to lose, for a thing with no interaction in it. Two details: `can_shrink` must be FALSE on the tooltip's picture or the tooltip is given the smallest size its content allows (the opposite of the point), and the path handed to the handler has to be **owned by the closure** (`g_signal_connect_data` with a destroy func), since the record it came from is a loop variable. - **Unparenting a popover inside its own `closed` emission is a use-after-free.** Dismissals go through `gtk_popover_popdown()`, which emits `closed`; a handler that unparents the popover there drops the reference the parent held, the widget dies, and GTK's own popdown path then runs on freed memory — `gtk_popover_get_autohide: assertion 'GTK_IS_POPOVER (popover)' failed`, on every menu entry that dismisses its popover, which is every entry there is. `on_popover_closed()` therefore defers the unparent by one idle and holds a reference across it (`g_idle_add_full(..., g_object_ref(popover), g_object_unref)`), so the popover outlives the emission that dismissed it. - **`find_accel()` masks the modifiers before comparing.** Lock, Num-Lock and the pointer buttons all arrive in `GdkModifierType`, so an unmasked compare matches no table row at all once Caps Lock is on. - **A UI file is data, and a mistake in it is a runtime abort, not a build failure.** `.ui` files live in `src/ui/` and are compiled into the binary by the third GResource (`udpscope-ui.gresource.xml`, `prefix=/org/udpscope/ui`), loaded with `gtk_builder_new_from_resource()`. `preprocess="xml-stripblanks"` catches a *malformed* file at build time -- which is why it is on every file in every bundle -- and that includes an XML rule easy to break by hand: **a comment may not contain a double hyphen**, so prose written the way every C++ comment in this project is written (` -- like this -- `) fails the build with a caret under the offending character. Use an em dash in a UI file. What it cannot catch is a file that is valid XML but wrong for GTK, and that is what `cmake --build build --target test-ui` is for: it round-trips every file through `blueprint-compiler`, which type-checks properties and child types against the GIR -- for *every* file, rather than for the windows a probe happens to open (see [build-and-run.md](build-and-run.md)). Without that check, `GtkBuilder` reports such a file with a **`Gtk-ERROR`, which aborts the process** by default, so a window built from bad markup takes the application down rather than failing to appear. Two more paid for: a `GIcon` property takes an **object**, not a name (`foo` is read as a reference to another object and fails with "Object with ID foo not found" -- the icon is a nested `GThemedIcon`); and a `.ui` big enough to exceed 4095 characters needs `-Wno-overlength-strings` on its generated source, because glib-compile-resources writes each file as one C string literal and the warning fires on generated *data*. - **Deprecated widgets may be the right widget, as long as no deprecated *function* is called.** The shortcut overview is a `GtkShortcutsWindow` (`gtk/deprecated/`, deprecated in 4.20) because libadwaita's successor, `AdwShortcutsDialog`, cannot draw a mouse gesture: `AdwShortcutsItem` has no icon property at all, so its shortcut cell can only be an accelerator, and its cell reads "No Shortcut" when there is none. `GtkShortcutsShortcut` has one generic gesture type whose `icon` *is* drawn. Loading the window from a `.ui` and presenting it as a `GtkWindow` names no deprecated function, so the build stays at its four warnings. When such a window closes, its builder is **replaced on the next opening**, not kept: the window belongs to the builder's object list and a destroyed `GtkWindow` cannot be presented again. - **An `AdwDialog` is not a `GtkWindow`, and not every toplevel is a widget either.** The preferences are an `AdwDialog`, which is a `GObject` that a *window* presents, so it cannot parent a `GtkFileDialog`: the form keeps the window it was opened with (`PrefsForm::parent`, the caller's) and hands that to the picker. Two things follow, and each cost a run. In its floating presentation mode an `AdwDialog` adds a **native surface** to `gtk_window_get_toplevels()`, so that list holds things that are neither `GtkWindow`s nor widgets -- `GTK_WINDOW()` on one is a segfault inside `gtk_window_close()`, and `g_object_unref()` on one is a `GLib-GObject-CRITICAL`. Anything walking it must test `GTK_IS_WIDGET()` *and* `GTK_IS_WINDOW()` first, and a probe should not walk it at all where a cancellable will do. - **A folder chooser outlives the dialog that opened it unless something cancels it.** The picker's answer writes a row, and the row is gone once the dialog closes. `PrefsForm::browse_cancel` is cancelled by the `closed` handler and replaced by the next chooser: one open picker at a time, and none that can call back into a cleared form. It is also how a probe takes the cancel path without a mouse. - **An `AdwApplicationWindow` refuses a titlebar, and refuses it by *aborting*.** `gtk_window_set_titlebar()` on one is a fatal `Adwaita-ERROR` (`is not supported for AdwApplicationWindow`), not a warning that leaves the window merely ugly. The main window is therefore a `GtkApplicationWindow` -- an Adw window would want its header as an `AdwToolbarView`'s top bar instead -- and `build_toolbar()`'s `GtkHeaderBar` stays the window's own titlebar, which is also what gives the window its controls: a `GtkHeaderBar` draws them only as a titlebar. - **libadwaita's rows do not share one property set, and a `.ui` is where that shows.** An `AdwEntryRow` is an `AdwPreferencesRow`: it has a `title` and **no `subtitle`**. `AdwSpinRow` and `AdwSwitchRow` are `AdwActionRow`s and have both. A hint about an entry -- "empty = unicast" -- therefore belongs in the *group's* `description`, which is the better place for it anyway: a placeholder vanishes as soon as there is a value, and a description does not. And an `AdwDialog` has **no `content` property**: its child is a plain ``, where an `AdwToolbarView` does take `content`. Both mistakes are a `Gtk-ERROR` at load, so both abort the process, and both are caught by the probe that opens every window rather than by anything at build time. - **A dialog reachable from two windows cannot own its state in either.** The preferences open from the main window's menu *and* from the source chooser, which exists before `App` does (`main()` chooses a source, then builds the model and the UI). The widgets therefore live in a `PrefsForm` the caller owns — `App::prefs`, `Chooser::prefs` — and what a change *means* is a callback, because it means different things on the two sides. Both are plain members of their owners, on the same stack frame, so nothing can outlive the frame that built it. - **A transient window is destroyed before its parent.** `chooser_finish()` destroys the preferences window before the chooser, and nulls the pointer *before* the destroy so `close-request` cannot re-enter a dead window. GTK does not promise to take a transient down with its parent, and a window whose handlers point into a returned stack frame is how this project already earned one use-after-free. - **A `_` in a label is a mnemonic only on a widget that was asked for one.** GTK reads the underscore as "the next letter is this widget's accelerator, and draw it underlined", so wherever the widget has not been asked, GTK draws the underscore *literally* -- which is what `_Directory`, `_Server`, `Keep _events` and eleven more titles did in the two preference forms, for as long as they existed. Two different switches, FALSE by default in both cases: `GtkLabel`/`GtkButton` take `use-underline`, and the rows take **`AdwPreferencesRow:use-underline`** ("whether an embedded underline in the title indicates a mnemonic"). The row classes that carry it are not all related -- `AdwEntryRow` has its own, while `AdwSpinRow`/`AdwComboRow`/`AdwSwitchRow` get it through `AdwActionRow` -- so `row_underlines()` asks by name on a `GObject` (`g_object_class_find_property`, then `g_object_get`) instead of casting to one row type: casting a row whose type is only forward-declared in that translation unit does not even compile. `test-ui` is what catches the property being set on a class that does not have it -- it validates every property against the GIR, inherited ones included. - **A mnemonic is unique per window, and the first match wins.** `_Cancel` and `_Connect` both claimed C in one form, so `Alt+C` could only ever reach one of them and the other's marker was unreachable -- worse than no mnemonic, because the underscore is there in the source for a reader to trust. `Conn_ect` freed it. Rows on different pages of a preferences dialog may share a letter: an unshown page cannot be activated. - **A `GtkExpander`'s child is not in the widget-parent chain.** `gtk_widget_get_parent()` on the widget an expander holds answers NULL, before *and* after the window is presented, while `gtk_expander_get_child()` returns it -- measured all three ways (the `.ui`'s `child` property, a code `gtk_expander_set_child()`, a code-made expander). So a probe that walks parents to prove a widget is inside a panel reads 0 for everything behind an expander, on a panel that is entirely correct; the walk has to start at `gtk_expander_get_child()`. That mistake cost a false regression, a "the property does not attach it" conclusion drawn from it, and a pointless second root in the file before the throwaway program settled it. Related: `gtk_expander_set_child()` asserts that its child has no parent yet, so a block the `.ui` has already put in the panel cannot then be handed to an expander -- the file's `child` property is the right way, and it works. - **`--` is not allowed inside an XML comment, and a `.ui` comment is XML.** `` is a parse error: `xml-stripblanks` fails the build, and `make test-ui` prints `FAIL ` with **no** message under it, because blueprint-compiler's decompiler aborts on the malformed XML before it can report anything -- the bare `FAIL` line is that mistake and nothing else. The house style for a dash in prose is the em dash, which is why no other `.ui` in `src/ui/` contains a double hyphen. It has cost two slices a debugging round for one character. - **A `.ui` file instantiates its objects once, so anything whose *count* is data cannot live in one.** The layout editor's overlay buttons are one per row, plus one per boundary between them: a `GtkBuilder` would hand back the first and nothing for the rest, and there is no "prototype the code copies" in the format. They are therefore code, and what they share -- the icon, the two CSS classes that make a small round on-screen-display control, and the size -- is one function (`layout_overlay_button()`) rather than three copies. The same reason keeps the math editor's palette and parameter rows in code: their count follows the model, not the file. `.ui` files are for the frame, and the frame is what has no count. - **A code-added child of a header bar lands *after* the file's, so going first means using a slot.** `gtk_header_bar_pack_start()` appends to the start group and there is no prepend. The time-window control is code -- its menu's rows come from the buffer's limits -- and belongs at the bar's head, so `header-bar.ui` declares an empty `window_control_slot` box as its first start child and the code appends the control into it. Packing the control straight onto the bar would have put it to the right of everything the file packed, and `[udpscope] header:` (`window_button_w=130 bar_w=756`) is the reading that shows such a move. - **`` is added leftwards-from-the-right, in document order.** A header bar's end group reads the *reverse* of the file: `header-bar.ui` declares menu, sidebar, math, measures, cursors and the screen shows cursors, measures, math, sidebar, menu. The three comments this replaced each had it wrong once, which is why the order is the file's now and a byte-for-byte diff of the probe is the check. - **A widget can end up in the wrong container, and only a *structural* read notices.** `math_body` was written as a `` of the *window* instead of the box above it when the math editor's frame moved into a `.ui`. A `GtkWindow` takes exactly one default ``, so nothing failed: the body -- with the canvas and the parameter form inside it -- was left parentless, `visible` but never `mapped`, size `0x0`, drawing nothing. The symptom was "the editor opens and the canvas is blank", with the window sized around its remaining children. `check_ui` passes such a file; `xml-stripblanks` passes it; so does every probe that reads *values* off the widgets inside. What catches it is a reading that walks *up* from the widget (`in_dialog=1`) or asks whether it was ever given an allocation (`mapped=1`, `canvas=420x836`). When a frame moves into a file, the probe that proves it has to read the frame's *structure*, not only the numbers it holds. - **A popover's autohide is only as good as its grab.** `GtkPopover` dismisses itself when it loses the pointer grab -- and the grab is the thing that can be missing: a window manager moving it, a nested popover (a `GtkDropDown`'s menu, which the time-window row has) taking it, and *every* headless run, where there is no manager to hand one out and the probes have to turn autohide off before a popover will stay up to be measured. The symptom is "sometimes it is awkward to close": a click anywhere else leaves the bubble up. `on_window_popover_press()` states the rule outright instead -- any press that reaches the window's own surface closes the window popover. That needs no hit test beyond the button, because a popover *is* its own surface and a click inside it never arrives; the button is left to its own click, whose toggle is what closes it. `[windowpop]` reads both halves, with autohide off so it is testing the rule and not the grab. - **A notice shares the status line with the glance, so it has to *look* like a message.** The status bar renders `app.notice + " | " + glance` in one label, which is exactly where a reader skimming the routine text ("live · 9.97 kS/s · 2 s window") will not see it: a refused drop that said "plot 1 holds four signals already" was read as no feedback at all. While a notice is fresh the label carries the stock `.warning` class, so a message looks like a message and the class goes when the notice does. Two corollaries worth knowing: the line composes on its own cadence, so a notice can appear a beat after it was set (do not read the label in the same tick a handler ran), and a refusal should say what to *do* about it -- "drop it on another plot, or add a row with the layout editor (L)" rather than the bare statement of the limit. - **The status line cannot cover the gap before the window exists, so a window does.** Between the chooser closing and `gtk_window_present()` there is no main loop at all: the chooser destroyed its own window, then `main()` allocates the sample buffer, waits for the first CONFIG or reads a recording, and `on_activate()` builds every panel -- at a few gigabytes of buffer that is the ten seconds a user reported as "the dialog disappeared and nothing happened". `loading_show()`/`loading_hide()` (in `source_dialog.cpp`, beside the chooser they continue) keep an `AdwWindow` on screen across it, raised in `main()` **before** the model is constructed and taken down in `on_activate()` **after** the present -- either side is a frame of empty screen. Three rules it exists under: - **It must be painted before the caller blocks.** `gtk_window_present()` only queues the frame, and nothing after it runs a loop, so `loading_show()` ends in a nested `GMainLoop` quit by a timeout (the chooser's own idiom). Iterating pending events is *not* enough: a window needs a frame-clock cycle, and the frame clock only ticks while a loop runs. - **It says what the wait is, in words.** The spinner is frozen for the whole of it -- no loop -- and a progress bar would be a lie for the same reason, so the text carries the information: the address being connected to or the file being opened, and under it the buffer size, which is the number that explains the duration. It is `deletable=0` with no title buttons: a close button that cannot be serviced until the work is over is worse than none. - **Only the path that *asked* gets one.** `main()` raises it only when the chooser actually ran, which is why every documented probe (all of them pass `--server`) is on exactly the path it was before -- and a `--server` run never had a window to lose, so the post-present notice is the right place for it. `loading_hide()` is a no-op when none is up, so `run_ui()` needs no notion of which path it is on. ## The help affordance layer The `Help` submenu, the contextual help's "?" and the guided tour, and the traps each of them met. - **`gtk_widget_measure()` includes the widget's own margins.** Measured: a box whose natural width is 280 and whose `margin-start` is 453 reports `natural = 733`. That matters wherever a measure is used to *place* the widget and the margin *is* the placement: the width the widget was placed at comes back as its width, and the card of the guided tour walked between the bottom-right corner and the left of the target from frame to frame because of it (a `place_natural()` that set no size request did not help -- the margin alone was the loop). Take the margins off a measure that feeds a position back. `hdl`/`bd`-style CSS padding is *not* part of it, and neither is the other axis's margin, so it is `margin-start + margin-end` on the horizontal and top/bottom on the vertical. - **A widget's allocation is not `gtk_widget_get_width()`, and a measure is never a position.** GTK's `gtk_widget_get_width()`/`get_height()` return the widget's **content** box: `size_allocate` subtracts the CSS border and padding before storing them (measured on the tour card, which carries `border 1px` + `padding 12px`: `get_width()` reads 254 where the rectangle on screen is 280), so a card *placed* from it overhangs its own size and covers the target it is meant to sit beside. `gtk_widget_compute_bounds()` is that rectangle -- border and padding in, margins out -- and is what the probe's geometry and the help's figures already read. And `gtk_widget_measure()` cannot stand in for it: its size includes the widget's margins (the bullet above), and asking for a **height with a width** (`for_size`) on a widget whose margins were then subtracted from that width makes GTK warn `Trying to measure GtkBox ... for width of N, but it needs at least M` **once per frame**, because the for_size lands one margin short of the minimum the widget answers with. The guided tour's card therefore takes its size from `compute_bounds()` once a frame has run and falls back to a measure **with no for_size at all** (`-1`, the form GTK measures without that check) only on a frame with nothing allocated yet. The warning reaches no probe -- GTK is built with **structured logging**, so it goes through the log *writer* and never `g_log_set_handler()`/`g_log_set_default_handler()` -- which is why the exit dump counts GTK's own warnings through a writer function (`gtk warnings:`, which must read 0) as the one reading that can assert the class away. - **The overflow menu's `Help` submenu is a two-page `GtkStack`, and neither of the obvious alternatives works.** Rebuilding the rows -- the plot menu's own shape -- destroys `app.layout_toggle`, which points into the main view and which `sync_layout_editor()` and the `L` accel read; swapping the *popover's child* instead leaves whichever view is not showing with the popover as its only owner, so it is finalized the moment it is swapped out. The popover's child is a stack, the visible child is the view, and `gtk_popover_present()` re-measures a popover that is already up. `UDPSCOPE_PROBE_MENUS_MS` walks the *visible page*, which is the one line the stack cost the probe. - **A "(i)" joins its surface's row as a sibling, not as an overlay child.** An overlay child sits *on* whatever is under it -- and every panel heading already has a switch or a pencil in a corner. `src/ui_context_help.cpp` is a table of (id, title, body, shortcut, host) where the host is the *row* -- a panel's heading usually, and the row of a specific control (the "record events" switch, the pre-trigger share, the search block's expander *header*) where that is the thing being explained. The one exception is the plot, which has no heading: its "(i)" is an overlay child of the overlay the layout editor already uses, and its corner is free. The icon is **`dialog-information-symbolic`** -- `help-about-symbolic` is *already* the status bar's information button, and two "help" glyphs meaning different things on the same line is the trap the seven app icons exist to avoid; the dump reads the name back through the theme for the same reason the pane [edit] buttons do. `math_head` exists only while the math editor is open, so that row is skipped when it is null. - **A `GtkMenuButton` ignores both `min-width` and a size request, and the icon is a node *below* its `button` subnode.** The "(i)" is meant to be a *mark*, not a button, and the default is 34x34 (a 24 px floor plus 5 px of padding from Adwaita's `button` rule). Measured on libadwaita 1.10: setting `min-width`/`min-height` on the widget changed nothing, and neither did `gtk_widget_set_size_request()` -- the menu button's own measure wins. The node tree is `menubutton > button > box > image` (read off the CSS node dump), so `install_css()` reaches the glyph as `menubutton.udpscope-hint > button > box > image`. The direct-grandchild form `> button > image` matches **nothing** and is silent about it -- the glyph keeps its natural 16 px, which is why an earlier version shipped a 16x16 mark and took that for the floor it was not. Zeroing the outer node and the `button` subnode and asking the glyph for **12 px** (`min-width`/`min-height` *and* `-gtk-icon-size`, the latter what actually *scales* the drawing rather than clamping its box) gives **12x12**. (A class on the outer node alone leaves the subnode at 34; a class on the subnode alone shrank the width to 16 and left the height at 26.) There is no lower floor: the symbolic glyph renders at any request (measured down to 4 px), so 12 px is a legibility choice and not a limit. The dump's `hint=` reading is that number, measured with `gtk_widget_compute_bounds()` on the first *visible* hint -- a hint inside a collapsed `GtkExpander`'s *child* is not in the widget-parent chain at all and reads 0x0, which would look like a mark shrunk to nothing. That is why the search block's hint rides the expander's **header** (a `label-widget` box, `search_head` in `src/ui/trigger-panel.ui`, which *is* in the tree) rather than its child, and why the `[helpui] collapsed search:` reading asserts the header hint is mapped and 12x12 while the block is collapsed. - **Off is gone, not greyed, and the buttons are found by a data key rather than kept in a list.** The list is what the math editor cannot survive: its heading lives in a builder that is dropped and rebuilt on every opening, so a stored pointer into it would go stale one dialog later. A key on the button (`udpscope-help-hint`, carrying the surface's id) is both the mark that says "this is a hint" and the name the probe and the dump report it by, and removing a hint is `gtk_widget_unparent()`, which means the same thing for a box and for the plot's overlay. The button itself is `ui_impl::hint_button()` reached either by the table's `context_help_sync()` or by `context_help_button()` for a window with no `App` (the source chooser) -- one button, two callers, so the two windows cannot drift into two affordances. - **The guided tour takes no grab, and that is the whole reason it is an overlay.** Four dim rectangles around the hole are ordinary widgets that swallow the clicks that land on them and nothing else; `Skip`, `Finish` and `Escape` hide them, and there is no popover, no gesture and no grab to leak. The probe asserts it as a reading -- `controllers=` against the count taken before the tour opened -- rather than as a claim, because "no lingering grab" is exactly the sort of thing a later change can add back without noticing. - **The tour is one implementation over two windows.** `ui_impl::TourView` holds the overlay children and the walk's place in it (`tour_build`/`tour_begin`/`tour_advance`/`tour_end`/`tour_update`), and what differs between the windows is only the *stops*: a `TourStop` names a widget the owner resolves, so each window keeps its own table -- the main window's against `App` fields, `source_dialog.cpp`'s `kChooserStops` against the `Chooser`'s. A walk that passes its last stop calls the view's `on_done`; the window's passes null, the chooser's sets `Config::tour_pending`, which is how the two halves are one tour. `App` carries its own `TourView` (`app.tour`), so the machinery is compiled once and the probe reads either window's state by the same fields. - **A stop declares the page it stands on, and the tour selects that page as the stop is entered.** A stop whose target lives on another page of a stack -- the window's `signals` (and `trigger`) stops on the sidebar's `signals` page, the chooser's "Two kinds of input" stop on its `waveforms` page -- names that page in `TourStop::page`, and `show_step()` selects it from `TourView::page_stack` before anything is measured. The page switch is **not** followed by a one-shot measure: `show_step()` selects the page and `tour_update()`, which already runs every frame, fills the spotlight in on the frame *after*, when the new page has been laid out. A stack allocates the new page's widgets on the frame after the switch, so a measurement taken in the switch's own tick reads zero (the allocation bullet in [invariants-trigger-and-pinning.md](invariants-trigger-and-pinning.md)) -- and reading the page *name* back is fine immediately, because that is state and not geometry. - **The stop filter runs on `get_mapped()`, not `is_visible()`, and that is what separates a wrong page from a collapsed pane.** GTK 4.24's `gtk_widget_is_visible()` walks only the widgets' own `visible` flags up the parents; it does **not** consult `child_visible`. Both a `GtkStack`'s non-current pages and `AdwOverlaySplitView`'s hidden sidebar are hidden with `gtk_widget_set_child_visible()`, so a widget on another page, *and* one in a collapsed pane, both read `is_visible() == TRUE` (verified against 4.24.1) -- the old filter kept a stop it meant to drop and left the spotlight on a target with no allocation. `stop_is_walkable()` keeps a stop when its target is **mapped**, or when it names a page and the stack that page belongs to is mapped: a wrong page leaves the stack mapped, so the stop is kept and the page switch reveals it; a collapsed pane leaves the stack unmapped too, so no page can reveal it and the stop is dropped. The filter lives in `tour_begin()`, not in each window's `start_tour()`, both so the two windows cannot drift into two rules and because the rule needs the view's own `page_stack`. - **The chooser's tour needs an overlay over its *whole* window, and `AdwWindow`'s content is replaced, not wrapped.** Two of the chooser's stops name header-bar buttons, and an overlay inside the `AdwToolbarView`'s `content` would give them negative coordinates and clamp the hole to the top edge. So the overlay *becomes* the window's content and adopts the toolbar view -- and the order matters: `gtk_overlay_set_child()` refuses a child that still has a parent, so `adw_window_set_content(win, overlay)` goes **first** (that call is what unparents the toolbar view) and `gtk_overlay_set_child(overlay, content)` second. The builder's object list still owns the view, so nothing is finalized in between. Getting the order wrong is a `Gtk-CRITICAL` and an empty chooser, which is exactly what the first version of this did. - **The chooser's hints are its own table because it runs before `App`.** An `AdwEntryRow` is not a box and its editor is internal, so a hint cannot join the host/port fields as a sibling -- appending it to the `AdwPreferencesGroup` would make it a row under the field rather than a mark beside it, so no hint is invented for them and the group's own `description` carries that text. The two rows the dialog *does* have -- the heading above the saved-source list and the waveforms page's action row -- carry `chooser_sources` and `chooser_waveform`, added with the same `context_help_button()` the window uses and re-synced by its Help menu's toggle. - **The hole is kept from the last frame that could measure the target.** `gtk_widget_compute_bounds()` answers nothing on a frame that lands between two layout passes, and letting the hole empty there made the spotlight and the card jump to the corner and back; a *target that is not mapped* is the different case (a genuinely absent surface) and is what empties it. The placement is also re-measured on **every frame**, never once at the start: a widget's allocation is 0 on the frame it is first shown, and a window resize moves it under a one-shot measurement. - **The first-run tour is a `settings.toml` key (`tour_seen`), written when the tour *starts*.** Not "the settings file did not exist": a user who has already changed the theme has a file and has still never seen the tour. Written on the way *in*, because a user who skips it in the first second has still seen it. It starts **in the source chooser** when one is shown (the chooser is the surface a first run meets first, and the window's own auto-start is unreachable until the chooser has returned with a source) and in the window otherwise; either way it is a 1.5 s timer, so the window is up and laid out before anything points at it. The chooser's walk writes the key itself and hands the second half over by `Config::tour_pending`, so a first run is *one* tour that crosses the two windows. - **The `help figures:` line is captured on the tick, like every other size the dump prints.** It names ten surfaces' window-coordinate rectangles for the help's annotated figures, and the dump runs after the window is destroyed -- a `gtk_widget_compute_bounds()` there is the "no `gtk_widget_*` call in the dump" rule again. `is_visible()`, not `get_visible()`: a widget under a hidden parent -- the trigger summary while the pane is in configuration mode -- keeps its own flag true and reads 0x0, and a crop box drawn from that is a box over the wrong thing. Its numbers depend on the *window's* size, which under the documented `xvfb-run` is the window's 756x894 minimum (a 640x480 screen), so a run on a larger screen gives different rectangles for the same panels.