improving doc

CLAUDE.md

@@ -619,7 +619,26 @@ Two lines of the self-check output are assertions in disguise:
   so the panes the tick rewrites are measured directly. The `[width-probe]` lines are the
   per-change detail behind the `axes.w changes` count, and a step over 100 px dumps the widget
   tree's wide subtrees — that is what the documented, intermittent ~320 px step wants read.
-- `[help] pages=14 parsed=14 shortest='Overview' 1379 B; shortcuts: app=12 plot=13; about version=… commit=… built=… settings=… icon=org.udpscope.app; closed ok` (stderr, `UDPSCOPE_PROBE_HELP_MS`) — **`parsed` must equal `pages`** and no page may be empty: a missing resource or markup Pango rejects renders a one-line stand-in instead of failing, so the window *looks* fine and only this count notices. `settings=` must be a real path (the same one the About dialog shows). **`icon=` must read `org.udpscope.app`** — it is read back through `adw_about_dialog_get_application_icon()` while the dialog is open, so the dialog is asserted to *carry* the icon rather than merely to open (a `set_application_icon()` lost in an edit leaves a dialog that opens, looks almost right, and shows a generic placeholder). `closed ok` with **no `Gtk-CRITICAL`** is as much a crash test of three windows built, presented and closed in one run as it is a state check, and a stronger one than it was: the three are now closed by **two different calls**, so a mismatched pair crashes or leaks here. One of the three is a `GtkWindow` (the help window, `gtk_window_close()`); the About dialog and the shortcut overview are `AdwDialog`s and close with `adw_dialog_close()`, cleared on `::closed`. `shortest=` is the page title — a page whose body was never compiled into the binary is absent rather than empty, and a title alone is the stand-in's shape.
+- `[help] pages=14 parsed=14 shortest='Pause and play' 1434 B; shortcuts: app=12 plot=13; about version=… commit=… built=… settings=… icon=org.udpscope.app; closed ok` (stderr, `UDPSCOPE_PROBE_HELP_MS`) — **`parsed` must equal `pages`** and no page may be empty: a missing resource or markup Pango rejects renders a one-line stand-in instead of failing, so the window *looks* fine and only this count notices. `settings=` must be a real path (the same one the About dialog shows). **`icon=` must read `org.udpscope.app`** — it is read back through `adw_about_dialog_get_application_icon()` while the dialog is open, so the dialog is asserted to *carry* the icon rather than merely to open (a `set_application_icon()` lost in an edit leaves a dialog that opens, looks almost right, and shows a generic placeholder). `closed ok` with **no `Gtk-CRITICAL`** is as much a crash test of three windows built, presented and closed in one run as it is a state check, and a stronger one than it was: the three are now closed by **two different calls**, so a mismatched pair crashes or leaks here. One of the three is a `GtkWindow` (the help window, `gtk_window_close()`); the About dialog and the shortcut overview are `AdwDialog`s and close with `adw_dialog_close()`, cleared on `::closed`. `shortest=` is the page title — a page whose body was never compiled into the binary is absent rather than empty, and a title alone is the stand-in's shape.
+- `[menu] N 'label' accel='key' h=P label_x=X accel_right=R/W order=D ok=O`, one line per row,
+  then `[menu] rows=R expected=E order=D rows_bad=B popover_visible=V mapped=M button_mapped=B`
+  and `[menu] status pos=top bubble=WxH button_top=T button_right=R fits=F` (stderr,
+  `UDPSCOPE_PROBE_MENUS_MS`) — the two popovers the toolbar and the status bar open, measured with
+  the side panel hidden. **`rows_bad` must be 0 and `fits` must be 1.** What it asserts is what a
+  screenshot can only show an eye: every row's label starts at the *same* x (`label_x=26` for all
+  seven — a menu whose checkable rows indent their text and whose others do not is exactly what
+  "the text is not left-aligned" looks like), every shortcut ends at the row's own right edge
+  (`accel_right == W`), no row is over `kMenuRowMaxPx` (30) tall — Adwaita's button minimum is 34,
+  and seven of those is what made the popover read as a stack of dialogs until `.udpscope-menu`
+  trimmed it — and the rows arrive in the order its `kExpected` names. `[menu] status` is the ⓘ
+  bubble: **`pos` must read `top`**, which is set *after* `gtk_menu_button_set_popover()` because a
+  `GtkMenuButton` states a position of its own and the last word wins, and `button_top` must exceed
+  the bubble's height, because "below the button" is off the window's bottom edge — the bubble's
+  top edge stayed at the button with its body clipped away, which reads as an arrow disconnected
+  from its body. Run it **alone**: another probe that opens a window dismisses the popover, and
+  every row then reports `h=0`. It turns autohide off for its own measurement — a popover dismisses
+  itself when it loses the grab, and `xvfb-run` has no window manager to hand it one — and restores
+  it afterwards.
 - `[keys] a: armed 0->1 | space: paused 0->1 | t: trigger panel: 0->1 | … | editable focused: 'm' refused=1` (stderr, `UDPSCOPE_PROBE_KEYS_MS`) — **every `X->Y` pair must differ** and **`refused` must be 1**. The refusal is the whole reason the controller is in the bubble phase: every bare-letter accel is also a character, so an accel that fires while a `GtkEditable` has focus makes the window entry unusable. A pair reading `0->0` is an action whose dispatch does not reach the handler a click reaches. Note the format is `<key>: <widget-description>: <before>-><after>` — the name passed to `before_after()` includes the widget's description, so `t: trigger panel: 0->1` is the correct form (not `t: trigger panel 0->1` without the colon before the values).
 - `[zoomkeys] ctrl+plus x=[..]->[..] y_held=1 | alt+plus y=[..]->[..] x_held=1` (stderr, `UDPSCOPE_PROBE_ZOOMKEYS_MS`) — **both `_held` must be 1 and both zooms must still happen.** Run it inside a pinned state, where a frame cannot re-frame the other axis for its own reasons: `UDPSCOPE_PROBE_PAUSE_MS=1500 UDPSCOPE_PROBE_ZOOMKEYS_MS=2200`. A `_held=0` is the modifier not reaching the plotter's controller; an unchanged range on the *zoomed* axis is the opposite failure, the key doing nothing. Ctrl restricts to x and Alt to y; Ctrl+Alt zooms neither (no special case needed — neither flag alone fires).
 - `status bar: glance=[● live · 1.09 MS/s · 2 s window] max_glance_chars=53 detail_fields=11 popover_rebuilds=0` (exit dump) — **`max_glance_chars` must stay small** (under about 60) and **`popover_rebuilds` must be 0**. The status row is directly above the plot, so this is the "layout must not depend on content" rule read from the bar's own side: the state field is one word from a fixed set, the rate field is `%.3g` (so `10 kS/s`, never `10.0 kS/s`), and the only field trigger mode adds is the elapsed time, which steps units rather than growing digits. `detail_fields` is the popover's label count, a literal, so adding a label without thinking about layout shows up here. The glance rate format matters: `%.3g` drops the trailing zero that a `%.4g` or a fixed-precision format would keep — a rate that reads differently in the dump and in the help page is a format disagreement, and `14-status.txt`'s example must match it.
@@ -1433,6 +1452,10 @@ far the largest file.
   generated symbols cannot collide with the icons'), validated with `pango_parse_markup()` at
   load; a page that fails either lookup or parse renders a one-line stand-in and is excluded from
   `parsed`. `UDPSCOPE_PROBE_HELP_MS`'s `parsed` must equal `pages`.
+  A page may also carry screenshots (`HelpPage::images`, a null-terminated list of resources).
+  They are `GtkPicture`s **with a height request**: one created `can_shrink` asks for *no* height
+  at all inside a box, so without the request it is allocated nothing and the page renders its text
+  with a silent gap where its screenshots should be — which is what the first version did.
 - **`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.