Merge feature/gen-rate-and-tabs into feature/source-plugins

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

.gitignore

@@ -1 +1,2 @@
 build/
+__pycache__/

.superpowers/sdd/final-fixes-report.md

@@ -1,100 +0,0 @@
-# Final Fixes Report
-
-## Fix 1 — `known_sources()` round-trip check
-**File:** `src/layout_store.cpp`
-
-Changed the port parse to capture the end pointer and check `*end != '\0'`, then added a round-trip guard: `sanitize(host) + "_" + std::to_string(port) != stem` rejects any filename that `layout_path()` could not have written. This prevents `foo_8000x.toml` from being listed as `foo:8000` (whose `×` would unlink `foo_8000.toml`) and `_8000.toml` from yielding an empty host (whose `sanitize("")` round-trips to `__8000`). Also fixed include order (`<cstdio>` before `<cstdlib>` — Fix 6) and updated the `multicast`/`interface` comment to state the TOML rule directly rather than pointing at an adjacent comment (Fix 5).
-
-## Fix 2 — use-after-free: form outliving chooser, unguarded timeout
-**File:** `src/source_dialog.cpp`
-
-(a) Added form destruction at the top of `chooser_finish()`: null the pointer first (so `close-request` cannot re-enter), then `gtk_window_destroy()` the form. Any path that finishes the chooser while the form is up — a row click, Escape — previously left a window with four handlers bound to a dead stack frame.
-
-(b) Stored the id from `g_timeout_add()` for `pick_probe` in `pick_probe_id` and called `g_source_remove(pick_probe_id)` after `g_main_loop_run()` returns (guarded on non-zero). A row picked before the timeout fires would otherwise leave an armed source on the default main context pointing at the gone frame.
-
-## Fix 3 — false comment on empty-list placeholder
-**File:** `src/source_dialog.cpp`
-
-Replaced the false "Not a GtkListBoxRow, so it cannot be activated..." comment with the truth: GTK4 auto-wraps any non-row widget, but the wrapped row carries no `"source-index"` data, so `g_object_get_data()` returns null and `on_row_activated`'s bounds check refuses it.
-
-## Fix 4 — unreachable duplicate branch in `pick_probe()`
-**File:** `src/source_dialog.cpp`
-
-Removed the second `row == nullptr` guard; the `c.known.empty()` guard above it was the only case that produced a null row from the real list. Two identical print statements for one cause made the probe output ambiguous.
-
-## Fix 5 — cross-reference comment in `save_layout()`
-**File:** `src/layout_store.cpp`
-
-Replaced "for the same reason as `enabled` below" with the rule itself: a bare TOML key written after a `[[table]]` header belongs to that table, with `enabled` named as the historical example of where this lost a key.
-
-## Fix 6 — include ordering
-**File:** `src/layout_store.cpp`
-
-Swapped `<cstdlib>` and `<cstdio>` back into alphabetical order.
-
-## Fix 7 — CLAUDE.md probe text
-**File:** `CLAUDE.md`
-
-Fixed `picked nothing` → `picked nothing: the list is empty` to match the exact stderr output. Fix 4 did not change the emitted text, so no further adjustment needed.
-
-## Fix 8 — dead-port run must not overwrite a configured session
-**Files:** `src/ui.cpp`, `CLAUDE.md`, `README.md`
-
-Added `if (app.model->signals().empty()) return;` in `save_layout_now()`, immediately after the `source_port == 0` guard. A run that receives no CONFIG has an empty signal list and must not overwrite a file that holds real signal names — doing so produces `signals = ["", ...]`, which the chooser's filter refuses, silently removing the source from the list. Also deleted all 116 flattened `~/.config/udpscope/*.toml` files (confirmed all had no named signal). Updated CLAUDE.md (chooser invariant section) and README.md (source-chooser paragraph) to document the rule.
-
----
-
-## Verification
-
-### 1. Build
-```
-cmake --build build
-```
-Output: clean, only the three pre-existing warnings (unused `output_built`, two missing-field-initializer on `MathNode`).
-
-### 2. `/tmp/check_sources` (two new assertions added)
-```
-g++ -std=c++20 -Isrc -Ideps/plotter/include /tmp/check_sources.cpp src/layout_store.cpp src/math_channel.cpp src/measure.cpp -o /tmp/check_sources
-/tmp/check_sources
-```
-Output:
-```
-a session with no named signal is not listed               ok
-newest first                                               ok
-oldest last                                                ok
-the stored group comes back                                ok
-the row and signal counts are the file's                   ok
-the filename splits at the last underscore                 ok
-forget_source reports success                              ok
-forget_source removes exactly one                          ok
-foo_8000x.toml is not listed (trailing 'x' in port)        ok
-_8000.toml is not listed (empty host does not round-trip)  ok
-all ok
-```
-
-### 3. `/tmp/check_layout_rt`
-```
-/tmp/check_layout_rt
-```
-Output: all 11 assertions `ok`.
-
-### 4. End-to-end chooser + scope run
-```
-UDPSCOPE_PROBE_PICK_MS=800 UDPSCOPE_EXIT_AFTER_MS=6000 ./build/udpscope
-```
-Relevant output:
-```
-[sources] picked 127.0.0.1:8000 multicast= interface=
-[udpscope] layout loaded from /tmp/fix-e2e/udpscope/127.0.0.1_8000.toml
-[udpscope] frames=817 packets=818 gaps=0 channels=1 span=1677.722s stride=1
-[udpscope]   layout over 476 frames: axes.x 135..147, axes.w 722..734, viewport.w 870..870, y-gutter 88..100, x-ticks 20..21, x-desync 0
-[udpscope]   trace ink: 406 paints checked, 0 collapsed, 0 staircase, 0 short, worst cover 2.5%
-```
-
-### 5. Fix 8 dead-port assertion
-```
-timeout 15 xvfb-run -a env XDG_CONFIG_HOME=/tmp/fix-e2e UDPSCOPE_EXIT_AFTER_MS=4000 ./build/udpscope --server 127.0.0.1 --port 8000
-cat /tmp/fix-e2e/udpscope/127.0.0.1_8000.toml
-```
-File mtime stayed at 10:01 (written by the live mock run); the dead-port run at 10:02 did not touch it.
-File contents: `signals = ["sine", "", "", ""]` — the configured signal name was preserved.

CMakeLists.txt

@@ -11,6 +11,8 @@ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
 endif()
 
 find_package(Threads REQUIRED)
+# `CMAKE_INSTALL_DATADIR` (the `share` under the prefix) for the help set's install path.
+include(GNUInstallDirs)
 
 # --- libadwaita: the shortcut overview ---------------------------------------
 # GTK4's own `GtkShortcutsWindow` is deprecated as of 4.18 and libadwaita's
@@ -61,23 +63,146 @@ add_custom_command(
   COMMENT "Compiling udpscope icon resources"
   VERBATIM)
 
-# --- help pages: Pango markup in a GResource ----------------------------------
+# --- the manual: a Mallard help set, installed for the `help:` URI ------------
-# A second bundle beside the icons'. --c-name is given explicitly so the two generated
+# The manual is no longer a GResource compiled into the binary. It is a Mallard set that the
-# sources cannot collide on symbol names.
+# desktop help viewer (Yelp on GNOME) reads off disk, because that is the only way `F1` can
-set(UDPSCOPE_HELP_DIR ${CMAKE_CURRENT_SOURCE_DIR}/src/help)
+# open a real, searchable, translatable document and the only way the freedesktop Help System
-file(GLOB UDPSCOPE_HELP_FILES CONFIGURE_DEPENDS ${UDPSCOPE_HELP_DIR}/*.txt)
+# Specification's `help:` URI resolves it. The user documentation is then *files*, checked and
-add_custom_command(
+# installed rather than compiled in.
-  OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/udpscope_help_resources.c
+#
-  COMMAND ${GLIB_COMPILE_RESOURCES}
+# The document identifier -- the `<name>` in `help:<name>` -- is derived from the desktop
-          --target=${CMAKE_CURRENT_BINARY_DIR}/udpscope_help_resources.c
+# file's own basename (its desktop-file id), not written out twice: the same string is the
-          --sourcedir=${UDPSCOPE_HELP_DIR}
+# `.desktop` file, the GApplication id and the installed directory. The specification installs
-          --c-name=udpscope_help
+# a document at `<datadir>/help/<lang>/<document>/` and resolves `help:<document>` to the first
-          --generate-source
+# match under $XDG_DATA_HOME/$XDG_DATA_DIRS, so the directory name *is* the identifier.
-          ${UDPSCOPE_HELP_DIR}/udpscope-help.gresource.xml
+# NAME_WE is not used: it strips the *longest* extension, so it would cut `org.udpscope.app`
-  DEPENDS ${UDPSCOPE_HELP_DIR}/udpscope-help.gresource.xml ${UDPSCOPE_HELP_FILES}
+# down to `org`. Strip the two suffixes this one file actually carries, in order.
-  COMMENT "Compiling udpscope help resources"
+get_filename_component(_udpscope_desktop
+  ${CMAKE_CURRENT_SOURCE_DIR}/data/org.udpscope.app.desktop.in NAME)
+string(REGEX REPLACE "\\.desktop\\.in$" "" UDPSCOPE_HELP_NAME "${_udpscope_desktop}")
+unset(_udpscope_desktop)
+set(UDPSCOPE_HELP_SRC ${CMAKE_CURRENT_SOURCE_DIR}/help/C/${UDPSCOPE_HELP_NAME})
+file(GLOB UDPSCOPE_HELP_FILES CONFIGURE_DEPENDS
+     ${UDPSCOPE_HELP_SRC}/*.page ${UDPSCOPE_HELP_SRC}/figures/*.png)
+
+# The install rule the specification asks for. `CMAKE_INSTALL_DATADIR` is `share` by default,
+# so the set lands at `<prefix>/share/help/C/<document>/`, which is exactly where a viewer
+# looks. There is no install step for the binary itself (see the desktop-entry target below),
+# but the manual is *read from a datadir* by another process, so it has to be installable.
+#
+# `COMPONENT Help` is what lets the opt-in targets below install *only* the manual: it names this
+# rule, and `cmake --install --component Help` runs it and nothing else. The ordinary
+# `cmake --install` installs every component, so its behaviour is unchanged -- the component is a
+# filter a caller may apply, not a change to the default.
+install(DIRECTORY ${UDPSCOPE_HELP_SRC}/
+        DESTINATION ${CMAKE_INSTALL_DATADIR}/help/C/${UDPSCOPE_HELP_NAME}
+        COMPONENT Help
+        FILES_MATCHING PATTERN "*.page" PATTERN "*.png" PATTERN "*.jpg")
+
+# --- installing the manual alone: prefix-wide and user-local, both opt-in -----
+# A user who runs the binary out of a build tree wants *just* the manual where `help:` resolves,
+# and not the `cmake --install` of a whole project. These two targets are that, one per
+# destination; neither is built by default and neither is touched by `cmake --build build`.
+#
+# `install-help` honours `CMAKE_INSTALL_PREFIX`, so a packager or a system-wide user points it at
+# `/usr` with -DCMAKE_INSTALL_PREFIX at configure time. It goes through the install machinery
+# (`cmake --install`) rather than a hand-rolled copy, which is what makes DESTDIR and `--prefix`
+# behave exactly as they do for the ordinary install. It cannot install system-wide on its own:
+# `/usr` is root-owned, so the target writes to the configured prefix and a system-wide caller
+# wraps it in `sudo` -- a build target has no more privilege than the shell that runs it.
+add_custom_target(install-help
+  COMMAND ${CMAKE_COMMAND} --install ${CMAKE_BINARY_DIR} --component Help
+  COMMENT "Installing the manual into ${CMAKE_INSTALL_PREFIX}"
   VERBATIM)
 
+# `install-help-user` is the no-root case the launch-failure alert names. It resolves the user
+# data directory the way `help_installed_path()` does -- `$XDG_DATA_HOME` when it is set,
+# `$HOME/.local/share` otherwise, the XDG Base Directory Specification's own default -- and copies
+# the set there. The copy is done by a script rather than by `cmake --install --prefix` because
+# the destination is the *data directory*, not a prefix: `cmake --install`'s datadir is always
+# `<prefix>/share`, so an arbitrary `$XDG_DATA_HOME` cannot be expressed as a prefix. The script
+# prints every path it wrote; the copy uses the install rule's file filter, so both destinations
+# carry the same tree.
+add_custom_target(install-help-user
+  COMMAND ${CMAKE_COMMAND}
+          -DHELP_SRC=${UDPSCOPE_HELP_SRC}
+          -DHELP_NAME=${UDPSCOPE_HELP_NAME}
+          -P ${CMAKE_CURRENT_SOURCE_DIR}/cmake/install_help_user.cmake
+  COMMENT "Installing the manual into the user's XDG data directory"
+  VERBATIM)
+
+# --- UI files: GtkBuilder XML in a GResource ----------------------------------
+# The third bundle, for the same reason as the other two: `.ui` files are data, so they are compiled
+# in rather than looked for at runtime -- and `preprocess="xml-stripblanks"` makes a malformed one a
+# build failure with a file and line number, instead of a window that silently refuses to open.
+set(UDPSCOPE_UI_DIR ${CMAKE_CURRENT_SOURCE_DIR}/src/ui)
+file(GLOB UDPSCOPE_UI_FILES CONFIGURE_DEPENDS ${UDPSCOPE_UI_DIR}/*.ui)
+add_custom_command(
+  OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/udpscope_ui_resources.c
+  COMMAND ${GLIB_COMPILE_RESOURCES}
+          --target=${CMAKE_CURRENT_BINARY_DIR}/udpscope_ui_resources.c
+          --sourcedir=${UDPSCOPE_UI_DIR}
+          --c-name=udpscope_ui
+          --generate-source
+          ${UDPSCOPE_UI_DIR}/udpscope-ui.gresource.xml
+  DEPENDS ${UDPSCOPE_UI_DIR}/udpscope-ui.gresource.xml ${UDPSCOPE_UI_FILES}
+  COMMENT "Compiling udpscope UI resources"
+  VERBATIM)
+# The generated source carries each file as one C string literal, and a `.ui` is big enough to pass the
+# 4095-character minimum the standard requires a compiler to support: `-Woverlength-strings` fires on
+# generated *data*, not on anything anyone wrote. Silenced for this one generated file (the icon bundle
+# is small enough per file never to need it), so the build stays at its one warning. The manual is
+# no longer compiled in, so the help bundle's own warning is gone with it.
+set_source_files_properties(${CMAKE_CURRENT_BINARY_DIR}/udpscope_ui_resources.c
+                            PROPERTIES COMPILE_OPTIONS "-Wno-overlength-strings")
+
+# --- the UI files: an opt-in check, never part of `cmake --build` ---------------
+# The interface is hand-written GtkBuilder XML, and nothing in the build sees a mistake in it: a
+# property a class does not have is a `Gtk-ERROR` when the window is built, and `Gtk-ERROR` *aborts
+# the process* -- so a typo takes the application down rather than failing to open a dialog.
+# `xml-stripblanks` catches malformed XML and nothing else, and the probes catch the rest only for the
+# windows they open.
+#
+# blueprint-compiler type-checks every property and child type against the GIR, and it reads XML as
+# well as blueprint (`decompile` turns one into the other), so `tools/check_ui.py` round-trips each
+# file through it. The XML stays the source of truth and stays hand-written; nothing here is needed to
+# build the application, which is the whole point of not converting the files.
+#
+# No ALL: this runs only when it is named, so `cmake --build build` is unaffected and
+# blueprint-compiler is not a build dependency.
+find_program(UDPSCOPE_PYTHON NAMES python3)
+if(UDPSCOPE_PYTHON)
+  add_custom_target(test-ui
+    COMMAND ${UDPSCOPE_PYTHON} ${CMAKE_CURRENT_SOURCE_DIR}/tools/check_ui.py ${UDPSCOPE_UI_DIR}
+    DEPENDS ${UDPSCOPE_UI_FILES} ${CMAKE_CURRENT_SOURCE_DIR}/tools/check_ui.py
+    COMMENT "Checking the UI files with blueprint-compiler"
+    VERBATIM)
+else()
+  message(WARNING "python3 was not found: the test-ui target is not available")
+endif()
+
+# --- the manual: an opt-in check, never part of `cmake --build` -----------------
+# The manual is hand-written Mallard, and `cmake --build` never reads it -- a broken xref or a
+# missing figure is a page in the viewer with no content or no image, not a build failure.
+# `tools/check_help.sh` runs yelp-check's four offline subcommands over the set (links, media,
+# orphans, ids) and renders the whole set to HTML with yelp-build, so the manual is checked the
+# way the `.ui` files are. `yelp-check validate` is *not* used: it fetches the Mallard RelaxNG
+# schema over the network, which is not available here and would make the check depend on it.
+#
+# No ALL: this runs only when it is named, so `cmake --build build` is unaffected and
+# yelp-tools is not a build dependency.
+find_program(UDPSCOPE_YELP_CHECK NAMES yelp-check)
+find_program(UDPSCOPE_YELP_BUILD NAMES yelp-build)
+if(UDPSCOPE_YELP_CHECK AND UDPSCOPE_YELP_BUILD)
+  add_custom_target(test-help
+    COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/tools/check_help.sh ${UDPSCOPE_HELP_SRC}
+    DEPENDS ${UDPSCOPE_HELP_FILES} ${CMAKE_CURRENT_SOURCE_DIR}/tools/check_help.sh
+    COMMENT "Checking the Mallard help set with yelp-check and yelp-build"
+    VERBATIM)
+else()
+  message(WARNING "yelp-check/yelp-build were not found: the test-help target is not available")
+endif()
+
 # --- build info: version, commit and timestamp compiled into the binary -------
 # Written at configure time so add_executable can name the file, and again on every
 # build so the commit and the timestamp belong to the binary that is running rather
@@ -99,16 +224,35 @@ set_source_files_properties(${UDPSCOPE_BUILD_INFO} PROPERTIES GENERATED TRUE)
 # --- the application ----------------------------------------------------------
 add_executable(udpscope
   ${CMAKE_CURRENT_BINARY_DIR}/udpscope_resources.c
-  ${CMAKE_CURRENT_BINARY_DIR}/udpscope_help_resources.c
+  ${CMAKE_CURRENT_BINARY_DIR}/udpscope_ui_resources.c
   ${UDPSCOPE_BUILD_INFO}
   src/main.cpp
   src/config.cpp
   src/channel.cpp
   src/model.cpp
+  src/condition.cpp
   src/trigger.cpp
+  src/capture.cpp
+  src/waveform.cpp
+  src/event_store.cpp
   src/acquisition.cpp
+  src/source/source_config.cpp
+  src/source/data_source.cpp
+  src/source/registry.cpp
+  src/source/udps_source.cpp
+  src/source/udps_kind.cpp
+  src/source/probe_source.cpp
+  src/source/e1608/e1608_link.cpp
+  src/source/e1608/e1608_device.cpp
+  src/source/e1608/e1608_source.cpp
+  src/source/e1608/e1608_kind.cpp
+  src/source/e1608/e1608_panels.cpp
+  src/source/flatudp/flatudp_signals.cpp
+  src/source/flatudp/flatudp_source.cpp
+  src/source/flatudp/flatudp_kind.cpp
   src/plot_host.cpp
   src/export.cpp
+  src/search.cpp
   src/layout_store.cpp
   src/source_dialog.cpp
   src/measure.cpp
@@ -116,10 +260,31 @@ add_executable(udpscope
   src/status_text.cpp
   src/shortcuts.cpp
   src/help_window.cpp
+  src/settings.cpp
+  src/ui_prefs.cpp
   src/ui.cpp
+  src/ui_probe.cpp
+  src/ui_widgets.cpp
+  src/ui_events.cpp
+  src/ui_status.cpp
+  src/ui_measure.cpp
+  src/ui_cursors.cpp
+  src/ui_math.cpp
+  src/ui_layout.cpp
+  src/ui_source.cpp
+  src/ui_trigger.cpp
+  src/ui_signals.cpp
+  src/ui_context_help.cpp
+  src/ui_tour.cpp
 )
 
 target_include_directories(udpscope PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+# The manual's identifier (`show_help()` builds `help:<id>` from it) and its directory in the
+# source tree (what `help_self_check()` scans). Both come from the block near the top, so the
+# identifier is the desktop file's basename and nothing is written out twice.
+target_compile_definitions(udpscope PRIVATE
+  UDPSCOPE_HELP_NAME="${UDPSCOPE_HELP_NAME}"
+  UDPSCOPE_HELP_DIR="${UDPSCOPE_HELP_SRC}")
 target_link_libraries(udpscope PRIVATE plot::gtk4 udpsclient Threads::Threads
                                       PkgConfig::ADWAITA)
 add_dependencies(udpscope udpscope_build_info)

SPECS.md

@@ -36,3 +36,18 @@
   - the time should be computed from the time associated with the signal (not from the client but from the streamed data)
   - in trigger mode data visualisation should not be refreshed till next event, that's why 2 identical buffer, one is the currently
     viewed event, the other used to acquire live data for next event
+
+## Deviations from the spec
+
+The following were built differently from what was asked for, each for a reason `README.md` states
+in full:
+
+- **`todo.md` item 2 — relative timing.** Implemented as `--relative-time`. The retained history
+  in this mode is **41.943 s** against the default **83.886 s** (measured at 100 kS/s, 4 channels,
+  `--buffer-mb 200`): exactly half, because a second f64 ring for absolute time raises a tick's
+  cost from 24 to 32 bytes — a third more — and `Partition::time_capacity` is floored to a power
+  of two, so a third more weight costs a full halving. The design document and the implementation
+  plan both put the cost at ~22%, which is wrong; the per-byte figure of 75% is wrong for the same
+  reason.
+  Absolute stream time is preserved in a separate ring and used for the export's `abs_seconds`
+  column, exactly as `todo.md` requires.

cmake/install_help_user.cmake

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: MIT
+#
+# The `install-help-user` target's body. Copies the Mallard help set into the user's XDG data
+# directory -- where `help:<id>` resolves without root -- and prints every path it wrote.
+#
+# `$XDG_DATA_HOME` is honoured when it is set, and `$HOME/.local/share` is the fallback when it
+# is not: that is the XDG Base Directory Specification's own stated default for the variable, and
+# it is the default `help_installed_path()` falls back to as well, so the manual lands where the
+# application and the desktop viewer look for it. The variable names a *data directory*, not a
+# prefix -- its `share/` is not appended -- so the set goes to `<data_home>/help/C/<id>/`. An
+# arbitrary `$XDG_DATA_HOME` need not end in `share`, which is exactly why this copies the tree
+# rather than deferring to `cmake --install --prefix`, whose datadir is always `<prefix>/share`.
+#
+# Like the desktop-entry target, this runs only when it is named: `cmake --build build` never
+# touches the user's data directory.
+#
+# Expects -DHELP_SRC= and -DHELP_NAME= on the command line.
+
+if(DEFINED ENV{XDG_DATA_HOME} AND NOT "$ENV{XDG_DATA_HOME}" STREQUAL "")
+  set(data_home "$ENV{XDG_DATA_HOME}")
+elseif(DEFINED ENV{HOME} AND NOT "$ENV{HOME}" STREQUAL "")
+  set(data_home "$ENV{HOME}/.local/share")
+else()
+  message(FATAL_ERROR
+    "XDG_DATA_HOME and HOME are both unset or empty; cannot determine the user data directory")
+endif()
+
+if(NOT DEFINED HELP_SRC OR NOT DEFINED HELP_NAME)
+  message(FATAL_ERROR "HELP_SRC and HELP_NAME are both required")
+endif()
+
+set(dest "${data_home}/help/C/${HELP_NAME}")
+
+# The same filter as the install() rule, so both destinations carry the same tree: the pages and
+# the figures, and nothing an editor left behind.
+file(COPY "${HELP_SRC}/" DESTINATION "${dest}"
+     FILES_MATCHING PATTERN "*.page" PATTERN "*.png" PATTERN "*.jpg")
+
+# Printed because there is no uninstall target: undoing this is these paths.
+file(GLOB_RECURSE installed LIST_DIRECTORIES FALSE RELATIVE "${dest}" "${dest}/*")
+list(SORT installed)
+foreach(path IN LISTS installed)
+  message(STATUS "wrote ${dest}/${path}")
+endforeach()

deps/udpsclient/udps_client.c

@@ -33,6 +33,13 @@
 /*                              Tunable limits                               */
 /*---------------------------------------------------------------------------*/
 
+/** Datagrams held waiting for an earlier counter. */
+#define UDPS_REORDER_SLOTS 64
+/** Total bytes the reorder ring may hold, so a fast stream cannot grow it without bound. */
+#define UDPS_REORDER_BYTES (4u * 1024u * 1024u)
+/** How long a gap is given to resolve before it is committed, by default. */
+#define UDPS_REORDER_WINDOW_S_DEFAULT 0.020
+
 /** Concurrent in-flight reassemblies. The server interleaves at most a couple. */
 #define UDPS_MAX_SLOTS 4
 
@@ -41,7 +48,7 @@
 #define UDPS_FRAG_MASK_BYTES (UDPS_MAX_FRAGMENTS / 8)
 
 /** Largest datagram we can receive, header included. */
-#define UDPS_RX_BUF_BYTES (65535 + 17)
+#define UDPS_RX_BUF_BYTES UDPS_MAX_DATAGRAM_BYTES
 
 /** An incomplete reassembly older than this is abandoned. */
 #define UDPS_SLOT_STALE_S 2.0
@@ -151,6 +158,16 @@ typedef struct {
     double   first_seen;
 } udps_slot_t;
 
+/** One slot in the reorder ring: a raw payload held until its counter is next. */
+typedef struct {
+    uint8_t *buf;       /**< owned; grown on demand to the payload's length */
+    size_t   cap;
+    size_t   len;
+    uint32_t counter;
+    double   recv_time;
+    int      used;
+} udps_held_t;
+
 struct udps_client {
     udps_client_config_t cfg;
     /* Owned copies: the caller's strings need not outlive the create call. */
@@ -181,12 +198,20 @@ struct udps_client {
 
     uint8_t *rxbuf;
 
-    uint32_t last_counter;
+    udps_held_t held[UDPS_REORDER_SLOTS];
+    size_t      held_bytes;    /**< payload bytes currently held */
+    int         held_count;
+    uint32_t    next_counter;  /**< the counter the sequence is waiting for */
+    double      gap_deadline;  /**< wall time the current gap gives up at; 0 = no gap */
+
     int      have_counter;
 
     udps_stats_t stats;
     char         err[256];
 
+    udps_datagram_cb datagram_cb;   /**< NULL until set; fires inside poll(). */
+    void            *datagram_user;
+
     udps_config_cb on_config;
     udps_data_cb   on_data;
     udps_event_cb  on_event;
@@ -475,43 +500,23 @@ static int decode_config(udps_client_t *c, const uint8_t *pl, size_t len) {
     return 0;
 }
 
-static int decode_data(udps_client_t *c, const uint8_t *pl, size_t len,
+/* Decodes and delivers one DATA payload whose ordering has already been resolved
-                       uint32_t counter, double recv_time) {
+ * by the caller.  `lost` counts how many counters the sequence skipped over
+ * before this packet, and `late` marks it as having lost the race past the
+ * reorder window (so the consumer already has a hole where it belongs). */
+static int deliver_data(udps_client_t *c, const uint8_t *pl, size_t len,
+                        uint32_t counter, double recv_time, uint32_t lost, uint8_t late) {
     uint32_t     nsamples = 1u;
     size_t       off      = 8u;
     size_t       total    = 0u;
     size_t       written  = 0u;
     uint32_t     i;
-    uint32_t     lost = 0u;
     udps_frame_t frame;
 
     if (c->num_sigs == 0u) {
         return 0; /* DATA before CONFIG: nothing to decode against. */
     }
 
-    /* Order the sequence before spending anything on the payload.
-     *
-     * Reassembly completes in arrival order, not counter order, so a packet
-     * delayed or duplicated on the wire surfaces after a newer one has already
-     * been delivered.  Its samples carry an older time base: they land on top
-     * of data the consumer already has and leave the span they should have
-     * filled empty.  Nothing in the payload distinguishes such a packet from a
-     * good one, only the counter does.
-     *
-     * The counter is a wrapping uint32, so it is ordered by the signed
-     * difference; comparing the values directly would call the first packet
-     * after the wrap stale and reject the stream from then on. */
-    if (c->have_counter) {
-        int32_t delta = (int32_t)(counter - c->last_counter);
-        if (delta <= 0) {
-            c->stats.stale_packets++;
-            return 0;
-        }
-        lost = (uint32_t)delta - 1u;
-        c->stats.counter_gaps += lost;
-    }
-    c->last_counter = counter;
-    c->have_counter = 1;
     if (len < 8u) {
         return fail(c, "DATA payload too short (%lu bytes)", (unsigned long)len);
     }
@@ -554,10 +559,12 @@ static int decode_data(udps_client_t *c, const uint8_t *pl, size_t len,
     }
 
     c->stats.frames_delivered++;
+    c->stats.counter_gaps += lost;
 
     if (c->on_data != NULL) {
         frame.counter      = counter;
-        frame.lost         = lost;
+        frame.lost         = late ? 0u : lost;
+        frame.late         = late;
         frame.hrt          = rd_u64(pl);
         frame.recv_time    = recv_time;
         frame.publish_mode = c->publish_mode;
@@ -570,6 +577,245 @@ static int decode_data(udps_client_t *c, const uint8_t *pl, size_t len,
     return 0;
 }
 
+/* Finds a free slot in the reorder ring and stores the payload there.
+ *
+ * A duplicate counter (same datagram arriving twice on the wire) replaces the
+ * existing slot so one counter never consumes two slots and both get delivered.
+ * The search for that slot therefore runs *before* the capacity checks, and the
+ * checks are applied only on the path that needs a new slot: a duplicate at a
+ * full ring consumes nothing and must still be accepted.
+ * Returns non-zero and holds nothing when there is no room (ring full or byte
+ * budget exhausted); `order_data` below says what the caller then does. */
+static int hold_packet(udps_client_t *c, const uint8_t *pl, size_t len,
+                       uint32_t counter, double recv_time) {
+    int i;
+    int slot = -1;
+
+    /* Duplicate counter: reuse the existing slot to avoid double delivery. */
+    for (i = 0; i < UDPS_REORDER_SLOTS; i++) {
+        if (c->held[i].used && c->held[i].counter == counter) {
+            slot = i;
+            break;
+        }
+    }
+    if (slot >= 0) {
+        /* The replacement releases the length already held, so the budget is
+         * weighed against what the slot will cost rather than what it adds. */
+        if (c->held_bytes - c->held[slot].len + len > UDPS_REORDER_BYTES) {
+            return -1;
+        }
+    } else {
+        if (c->held_count >= UDPS_REORDER_SLOTS) {
+            return -1;
+        }
+        if (c->held_bytes + len > UDPS_REORDER_BYTES) {
+            return -1;
+        }
+        for (i = 0; i < UDPS_REORDER_SLOTS; i++) {
+            if (!c->held[i].used) {
+                slot = i;
+                break;
+            }
+        }
+        if (slot < 0) {
+            return -1;
+        }
+    }
+
+    if (ensure_cap((void **)&c->held[slot].buf, &c->held[slot].cap, len) != 0) {
+        return -1;
+    }
+    /* If this is a duplicate replacement, subtract the old length first. */
+    if (c->held[slot].used) {
+        c->held_bytes -= c->held[slot].len;
+        c->held_count--;
+    }
+    memcpy(c->held[slot].buf, pl, len);
+    c->held[slot].len       = len;
+    c->held[slot].counter   = counter;
+    c->held[slot].recv_time = recv_time;
+    c->held[slot].used      = 1;
+    c->held_bytes          += len;
+    c->held_count++;
+    return 0;
+}
+
+/* Walks the held ring and delivers every entry whose counter matches the
+ * expected sequence, in order.  The first delivery carries `first_lost` (so
+ * a caller that committed a gap can report the correct count); every
+ * subsequent delivery in the same drain pass carries lost = 0.
+ *
+ * Clears the gap deadline once the ring empties. */
+static int drain_held(udps_client_t *c, uint32_t first_lost) {
+    int      found;
+    int      i;
+    int      rc;
+    uint32_t lost;
+
+    lost = first_lost;
+    do {
+        found = 0;
+        for (i = 0; i < UDPS_REORDER_SLOTS; i++) {
+            if (c->held[i].used &&
+                (int32_t)(c->held[i].counter - c->next_counter) == 0) {
+                uint32_t cnt       = c->held[i].counter;
+                double   rt        = c->held[i].recv_time;
+                const uint8_t *pl  = c->held[i].buf;
+                size_t   len       = c->held[i].len;
+                /* Release the slot before delivering so deliver_data can call
+                 * back into the client without hitting a stale used entry. */
+                c->held_bytes     -= len;
+                c->held_count--;
+                c->held[i].used    = 0;
+                c->next_counter    = cnt + 1u;
+                c->stats.late_resequenced++;
+                rc = deliver_data(c, pl, len, cnt, rt, lost, 0);
+                lost = 0u;
+                if (rc != 0) {
+                    return rc;
+                }
+                found = 1;
+                break;
+            }
+        }
+    } while (found);
+
+    if (c->held_count == 0) {
+        c->gap_deadline = 0.0;
+    }
+    return 0;
+}
+
+/* Gives up on the current gap: finds the lowest held counter (by signed delta,
+ * not raw value, so a wrap mid-gap is handled correctly), advances
+ * next_counter to it, then drains.  The first delivery out of that drain
+ * carries the gap's lost count; the rest carry 0.
+ *
+ * With nothing held it just clears the deadline and returns. */
+static int commit_gap(udps_client_t *c) {
+    int      i;
+    int      best    = -1;
+    uint32_t lost;
+
+    if (c->held_count == 0) {
+        c->gap_deadline = 0.0;
+        return 0;
+    }
+
+    for (i = 0; i < UDPS_REORDER_SLOTS; i++) {
+        if (!c->held[i].used) {
+            continue;
+        }
+        if (best < 0 ||
+            (int32_t)(c->held[i].counter - c->held[best].counter) < 0) {
+            best = i;
+        }
+    }
+
+    lost             = (uint32_t)(int32_t)(c->held[best].counter - c->next_counter);
+    c->next_counter  = c->held[best].counter;
+    return drain_held(c, lost);
+}
+
+/* Orders the sequence before spending anything on the payload.
+ *
+ * The counter is a wrapping uint32, so it is ordered by the signed difference;
+ * comparing the values directly would call the first packet after the wrap stale
+ * and reject the stream from then on.
+ *
+ * Three cases.  A packet that *continues* the sequence is decoded now and costs no
+ * latency at all -- that is the common case and it must stay free.  A packet that
+ * runs ahead of the sequence means an earlier one is missing, so it is held and the
+ * gap is given `reorder_window_s` to resolve; a reorder on the wire resolves in
+ * milliseconds, and holding is what turns it back into order.  A packet behind the
+ * sequence lost that race: the consumer already has a hole where it belongs, so it
+ * is delivered flagged rather than discarded, which is the whole point -- a dropped
+ * packet cannot fill the hole it left.
+ *
+ * The full ring is specified here, in one place.  A packet that needs a slot and
+ * finds none gives up on the current gap -- `commit_gap()` delivers the lowest held
+ * run and so frees at least one slot -- counts the event in
+ * `stats.reorder_overflows`, and the decision is then taken again, once, against
+ * the sequence that commit left behind.  That re-decision is why this is a bounded
+ * loop and not a straight line: the commit advances `next_counter` to the lowest
+ * held counter, which may put it past the arriving packet, and the packet is then
+ * behind the sequence rather than ahead of it.  Whatever happens, the arriving
+ * packet is held or delivered; it is never dropped, because nothing else records it
+ * and the consumer would reserve a hole for it that nothing could ever backfill.
+ * Past the cap it is delivered *in order* and not flagged late: a packet ahead of
+ * the sequence has no reserved hole, the consumer looks a late packet's hole up by
+ * counter and ignores one it cannot place, so advancing `next_counter` to it and
+ * reporting the counters it skipped as `lost` is what reserves their hole. */
+static int order_data(udps_client_t *c, const uint8_t *pl, size_t len,
+                      uint32_t counter, double recv_time) {
+    int32_t delta;
+    int     attempt;
+    int     rc;
+
+    if (c->cfg.reorder_window_s <= 0.0) {
+        /* Resequencing off: byte-for-byte the behaviour before this task. `delta`
+         * is measured against the *next* counter rather than the last, which is the
+         * same test shifted by one -- `delta < 0` here is `delta <= 0` there. */
+        uint32_t lost = 0u;
+        if (c->have_counter) {
+            delta = (int32_t)(counter - c->next_counter);
+            if (delta < 0) {
+                c->stats.stale_packets++;
+                return 0;
+            }
+            lost = (uint32_t)delta;
+        }
+        c->have_counter = 1;
+        c->next_counter = counter + 1u;
+        return deliver_data(c, pl, len, counter, recv_time, lost, 0);
+    }
+    if (!c->have_counter) {
+        c->have_counter = 1;
+        c->next_counter = counter + 1u;
+        return deliver_data(c, pl, len, counter, recv_time, 0u, 0);
+    }
+    for (attempt = 0; attempt < 2; attempt++) {
+        delta = (int32_t)(counter - c->next_counter);
+        if (delta == 0) {
+            rc = deliver_data(c, pl, len, counter, recv_time, 0u, 0);
+            c->next_counter = counter + 1u;
+            if (rc == 0) { rc = drain_held(c, 0u); }
+            return rc;
+        }
+        if (delta < 0) {
+            /* Behind the sequence. */
+            c->stats.late_delivered++;
+            return deliver_data(c, pl, len, counter, recv_time, 0u, 1);
+        }
+        if (hold_packet(c, pl, len, counter, recv_time) == 0) {
+            if (c->gap_deadline == 0.0) {
+                c->gap_deadline = recv_time + c->cfg.reorder_window_s;
+            }
+            return 0;
+        }
+        /* No room: give up on the gap rather than growing the ring, and say so
+         * in a counter, so an undersized window is a reading and not a mystery. */
+        c->stats.reorder_overflows++;
+        rc = commit_gap(c);
+        if (rc != 0) {
+            /* The consumer refused a delivery; nothing is freed and nothing more
+             * may be delivered, so the arriving packet is its caller's problem. */
+            return rc;
+        }
+    }
+    /* The attempt cap is spent and the ring still has no room (the byte budget
+     * cannot fit this one even with a slot free). Deliver it rather than drop it. */
+    delta = (int32_t)(counter - c->next_counter);
+    if (delta < 0) {
+        c->stats.late_delivered++;
+        return deliver_data(c, pl, len, counter, recv_time, 0u, 1);
+    }
+    rc = deliver_data(c, pl, len, counter, recv_time, (uint32_t)delta, 0);
+    c->next_counter = counter + 1u;
+    if (rc == 0) { rc = drain_held(c, 0u); }
+    return rc;
+}
+
 /*---------------------------------------------------------------------------*/
 /*                            Fragment reassembly                            */
 /*---------------------------------------------------------------------------*/
@@ -579,6 +825,14 @@ static void slot_reset_all(udps_client_t *c) {
     for (i = 0; i < UDPS_MAX_SLOTS; i++) {
         c->slots[i].active = 0;
     }
+    /* A reconnect starts a new sequence; payloads held from the previous one
+     * must not be delivered into it. */
+    for (i = 0; i < UDPS_REORDER_SLOTS; i++) {
+        c->held[i].used = 0;
+    }
+    c->held_count   = 0;
+    c->held_bytes   = 0;
+    c->gap_deadline = 0.0;
 }
 
 static void gc_slots(udps_client_t *c, double now) {
@@ -596,7 +850,7 @@ static void deliver_payload(udps_client_t *c, uint8_t type, const uint8_t *pl,
     if (type == UDPS_PKT_CONFIG) {
         (void)decode_config(c, pl, len);
     } else {
-        (void)decode_data(c, pl, len, counter, recv_time);
+        (void)order_data(c, pl, len, counter, recv_time);
     }
 }
 
@@ -906,6 +1160,7 @@ static int do_connect(udps_client_t *c) {
     c->last_data      = now_mono();
     c->last_keepalive = c->last_data;
     c->have_counter   = 0;
+    c->next_counter   = 0u;
     slot_reset_all(c);
     if (c->ever_connected) {
         c->stats.reconnects++;
@@ -981,6 +1236,7 @@ void udps_client_config_init(udps_client_config_t *cfg) {
     cfg->keepalive_interval_s = 15.0; /* server evicts silent clients at 30 s */
     cfg->recv_buffer_bytes    = 4u * 1024u * 1024u;
     cfg->max_packet_bytes     = 1u * 1024u * 1024u;
+    cfg->reorder_window_s     = UDPS_REORDER_WINDOW_S_DEFAULT;
 }
 
 static void copy_str(char *dst, size_t cap, const char *src) {
@@ -992,6 +1248,15 @@ static void copy_str(char *dst, size_t cap, const char *src) {
     dst[cap - 1u] = '\0';
 }
 
+void udps_client_set_datagram_cb(udps_client_t *client,
+                                 udps_datagram_cb cb, void *user) {
+    if (client == NULL) {
+        return;
+    }
+    client->datagram_cb   = cb;
+    client->datagram_user = user;
+}
+
 udps_client_t *udps_client_create(const udps_client_config_t *cfg) {
     udps_client_t *c;
 
@@ -1048,6 +1313,9 @@ void udps_client_destroy(udps_client_t *c) {
     for (i = 0; i < UDPS_MAX_SLOTS; i++) {
         free(c->slots[i].payload);
     }
+    for (i = 0; i < UDPS_REORDER_SLOTS; i++) {
+        free(c->held[i].buf);
+    }
     free(c->sigs);
     free(c->valbuf);
     free(c->vals);
@@ -1151,6 +1419,14 @@ int udps_client_poll(udps_client_t *c, int timeout_ms) {
     }
     budget = clamp_deadline(budget, c->cfg.silence_timeout_s, now - c->last_data);
 
+    /* A held packet must flush on time even when nothing further arrives: at 10 pkt/s
+     * the next arrival is 100 ms away, which is five times the whole budget. */
+    if (c->gap_deadline > 0.0) {
+        double left = c->gap_deadline - now_wall();
+        if (left < 0.0) { left = 0.0; }
+        if (left < budget) { budget = left; }
+    }
+
     FD_ZERO(&rset);
     maxfd = -1;
     if (c->udp_fd >= 0 && c->udp_fd < FD_SETSIZE) {
@@ -1204,6 +1480,11 @@ int udps_client_poll(udps_client_t *c, int timeout_ms) {
             }
             drained++;
             c->last_data = now_mono();
+            /* The raw datagram, before anything reads out of rxbuf: this is the
+             * only place a malformed or duplicate datagram is still visible. */
+            if (c->datagram_cb != NULL) {
+                c->datagram_cb(c->rxbuf, (size_t)n, now_wall(), c->datagram_user);
+            }
             if ((size_t)n >= UDPS_HEADER_SIZE) {
                 handle_packet(c, c->rxbuf, (size_t)n);
             }
@@ -1221,6 +1502,10 @@ int udps_client_poll(udps_client_t *c, int timeout_ms) {
     }
     gc_slots(c, now_wall());
 
+    if (c->gap_deadline > 0.0 && now_wall() >= c->gap_deadline) {
+        (void)commit_gap(c);
+    }
+
     if (c->cfg.silence_timeout_s > 0.0 &&
         (now - c->last_data) >= c->cfg.silence_timeout_s) {
         do_disconnect(c, "server went silent");

deps/udpsclient/udps_client.h

@@ -150,6 +150,13 @@ typedef struct {
      * range the next frame claims.
      */
     uint32_t lost;
+    /**
+     * 1 when this frame's counter is behind the sequence already delivered: it lost
+     * the race past the reorder window and the consumer has a hole where it belongs.
+     * @c lost is 0 for such a frame -- it is not missing anything, it *is* what was
+     * missing -- so a consumer sizes its backfill from @c counter, not from @c lost.
+     */
+    uint8_t  late;
     uint64_t hrt;          /**< Producer's high-resolution timer at send. */
     double   recv_time;    /**< Wall-clock seconds (CLOCK_REALTIME) at arrival. */
     uint8_t  publish_mode; /**< UDPS_PUBLISH_*. */
@@ -180,6 +187,30 @@ typedef struct {
      * time base older than data already handed over.
      */
     uint64_t stale_packets;
+    /**
+     * DATA packets that were held waiting for an earlier counter and subsequently
+     * delivered via @c drain_held().  This includes a packet released by the
+     * reorder window expiring: that packet arrives alongside a non-zero @c lost
+     * and therefore alongside a gap, so @c late_resequenced is not by itself a
+     * count of gaps avoided.  Compare @c late_delivered, which counts packets
+     * that lost the race past an already-expired window entirely.
+     */
+    uint64_t late_resequenced;
+    /**
+     * DATA packets delivered behind the sequence because the reorder window had
+     * already closed on them. The consumer has a hole for these and may fill it;
+     * before the window existed they were counted in @c stale_packets and dropped.
+     */
+    uint64_t late_delivered;
+    /**
+     * Times a DATA packet needed a slot in the reorder ring and found none, so the
+     * current gap was committed early to make room. Every such packet is still held
+     * or delivered -- none is dropped -- but the window it was given was shorter
+     * than @c reorder_window_s asked for. A non-zero reading says the ring is
+     * undersized for the stream's reordering depth, which is a reading and not a
+     * mystery; it is the only place that shows up.
+     */
+    uint64_t reorder_overflows;
     uint64_t reconnects;
 } udps_stats_t;
 
@@ -206,6 +237,20 @@ typedef void (*udps_data_cb)(const udps_frame_t *frame, void *user);
 /** Called on connection state changes and on recoverable errors. */
 typedef void (*udps_event_cb)(udps_event_t event, const char *detail, void *user);
 
+/**
+ * Largest datagram recv() can deliver on the client's socket, and therefore the
+ * most a raw-datagram observer ever sees in one call.
+ */
+#define UDPS_MAX_DATAGRAM_BYTES (65535 + 17)
+
+/** Called for every datagram as recv() returned it, before the magic check,
+ *  reassembly or resequencing: the bytes a capture has to store, and the only
+ *  place malformed or duplicate datagrams are still visible. Runs on the polling
+ *  thread, inside udps_client_poll(), like every other callback. `bytes` is
+ *  valid until the callback returns. */
+typedef void (*udps_datagram_cb)(const uint8_t *bytes, size_t len,
+                                 double recv_time, void *user);
+
 /**
  * @brief Transport configuration.
  *
@@ -226,6 +271,14 @@ typedef struct {
     double      keepalive_interval_s;/**< Unicast ACK period. 0 disables. */
     uint32_t    recv_buffer_bytes;   /**< SO_RCVBUF; large bursts need a large value. */
     uint32_t    max_packet_bytes;    /**< Ceiling on one reassembled payload. */
+    /**
+     * How long a packet may be held waiting for an earlier counter, in seconds.
+     *
+     * A *contiguous* arrival is never held, so this is the latency a gap costs and
+     * not a latency the stream pays. 0 disables resequencing entirely and restores
+     * the drop-on-late behaviour. Default 0.020.
+     */
+    double      reorder_window_s;
 } udps_client_config_t;
 
 /** Fills @p cfg with the defaults documented in Docs/UDPS-C-Client.md. */
@@ -247,6 +300,12 @@ void udps_client_set_callbacks(udps_client_t *client,
                                udps_event_cb  on_event,
                                void          *user);
 
+/** Installs the raw-datagram observer. Separate from
+ *  udps_client_set_callbacks(), whose signature has call sites and which a
+ *  capture hook is no reason to change. May be NULL. */
+void udps_client_set_datagram_cb(udps_client_t *client,
+                                 udps_datagram_cb cb, void *user);
+
 /**
  * @brief Drives the client: connects if needed, then waits for and processes
  *        packets for at most @p timeout_ms milliseconds.

docs/USER-GUIDE.md

@@ -65,6 +65,12 @@ window change moves the trigger with it.
 - **Ctrl+drag** frames x to a box, **Alt+drag** y.
 - **Fit to data** (menu) auto-scales both axes and frames the whole buffered range.
 
+Each plot has its own **right-click menu**, in the same compact row style as the app's menu:
+**Y axis: auto scale**, **Y axis: fixed range...**, **Fit X axis**, **Fit all** (`f`), and
+**Remove signal** — which swaps the menu to one entry per trace on that plot plus *All traces on
+this plot*, with a **Back** row to return. That is how a trace comes off a row without going through
+the layout editor.
+
 The view is bounded by the **time window**, not by the buffer: zooming out stops at the span you set,
 and panning stops where the data starts. When the buffer holds *less* than the window — right after a
 signal is enabled — the window is left empty on its left, which is what a scope that has just started

docs/claude/architecture.md

@@ -0,0 +1,188 @@
+# Architecture: threads, the data path and the layers
+
+The two threads and what they share, the four display modes, the display clock, and the layers to keep straight.
+
+Part of [CLAUDE.md](../../CLAUDE.md).
+
+`SPECS.md` is the requirement document. `README.md` documents what was actually built,
+including deliberate deviations from the spec and known limitations — read it before
+concluding something is a bug.
+
+### Threads
+
+Exactly two: a producer thread in `Acquisition` owns a `DataSource` and calls
+`source->poll(50)`; the GTK main thread owns every widget and GL context. They share
+`ScopeModel` under `ScopeModel::mutex()`, taken once per DATA frame by the producer and
+once per frame by the UI (`tick()` in `src/ui.cpp`) around `RowSet::bind()`/`acquire()`.
+Samples themselves cross via `plot::data::RingBuffer` (single producer, single
+consumer) and never through the lock. Cross-thread scalars are atomics on `ScopeModel`
+(`trigger_enabled_`, `trigger_armed_`, `trigger_latches_`, `trigger_time_`,
+`event_`, `generation_`). Two of them are a pair: the producer writes `capture_edge_`
+before `trigger_pending_` and those two carry release/acquire, so a consumer that sees a
+capture open sees which edge it belongs to.
+
+### Sources
+
+What feeds `Acquisition` is a `DataSource`, one of the registered *kinds*.
+
+- The kinds live in `src/source/`. `register_builtin_sources()` fills the registry explicitly --
+  there is no static-initialiser registration, which a linker may drop -- and a future `dlopen`
+  loader would only call `register_kind()`.
+- A `DataSource` delivers into `Acquisition` (a `SourceSink`) from inside `poll()`. `Frame` is
+  source-neutral, and its pointers are valid **only during `on_data`**: copy what is kept.
+- The GTK thread reaches a source **only** through `DataSource::post(Command)`; the queue is drained
+  at the top of `poll()`. A panel never calls a source directly.
+- `UdpsSource` wraps `deps/udpsclient` unchanged; `udps_*` names appear only in
+  `src/source/udps_*.cpp` (`grep -rn "udps_" src` outside those files is a leak of the old coupling).
+- The frame is **single-timebase**. A multi-timebase source (ABScope) will change the interface and
+  the data path together; do not bend one frame to carry two clocks.
+- A kind's capability panels are pages of `side_stack`, named `source-<id>`. A disconnected source
+  leaves them **insensitive, not hidden** (`apply_source_panels` in `src/ui_source.cpp`).
+- Session file naming for a non-UDPS kind: the pseudo-host is `<kind>-<identity>` (characters outside
+  `[A-Za-z0-9._-]` become `_`) on port **1** (0 is rejected by the session-file parser), the kind is
+  stored as `source_kind` and its settings as `source_opt_<key>`. A UDPS file keeps `<host>_<port>` and
+  has neither key, so a legacy session is read as UDPS and nothing existing moves.
+- **The E-1608 kind has three layers, and only the top one knows the framework.** `e1608_link`
+  (discovery, handshake, framed TCP commands, the scan socket) and `e1608_device` (typed commands,
+  factory calibration, `decode_scans`) are plain POSIX C++ with no GTK or `DataSource` types; discovery is
+  `Scan` (one socket per interface, polled by the caller: the form polls it from a GLib timer on the main
+  thread, the source's lookup goes through `discover_broadcast`);
+  `e1608_source` is the `DataSource`; `e1608_kind` and `e1608_panels` are the UI. A change to the wire
+  never reaches the UI files.
+- The E-1608 source runs **everything inside `poll()`** on the producer thread: posted commands, the
+  connect state machine (Down, Scanning, Halted), the scan read, the 500 ms status check (its not-running restart is skipped when a hardware trigger is configured), the digital
+  input/counter poll and the waveform tick (every `1 / gen_rate` s, 20 ms by default; one synchronous DAC write per running channel, so a slow board lowers the rate it achieves, which the Analog out panel reports). There is no second thread. A connect attempt (discovery,
+  handshake, calibration read, scan start) can block `poll()` for as long as the command timeout allows each
+  step; that delays only the command queue. Every exception is caught inside `poll()`: an escape would end
+  the producer thread, and `drain_commands()` runs inside the same `try` for that reason.
+- Its frames are **fixed-size blocks** of about 10 ms (`round(scan_rate / 100)` scans, 1 to 4096), not
+  whatever one `recv` returned: `build_stamps` warns once when a frame's sample count differs from the
+  first one's. Digital lines and the counter are held across a block (a step trace).
+- The E-1608 panels read the board's state from `E1608Readouts`, a set of atomics the producer writes
+  and a tick callback throttled to 100 ms reads; a panel never touches the source's internals, and writes
+  only through `post()`. `Acquisition::on_event` ignores the detail string and does nothing for `Error`,
+  so the source also writes each new error to stderr as `[e1608] ...` (once per distinct message, not per
+  retry); that line is where a user sees why a connection failed.
+- **The flat UDP kind is three files and no thread.** `flatudp_signals` is the `signals` string codec,
+  the validity rules and the decoders, with no GTK and no sockets (the probe round-trips it);
+  `flatudp_source` is `FlatUdpSettings` plus the `DataSource`; `flatudp_kind` is the form, a signal-row
+  editor (a name, a type, a count and, while the count is above 1, a "Vector as" drop-down per row). The
+  datagram has no description, so a list that is wrong is invisible except as dropped datagrams: the size
+  check is the only defence, and it is why a wrong-size datagram is counted (`stale`) and reported once per
+  size.
+- A vector row is shown one of two ways, chosen per row (`Row::wave`, the `w` suffix in the text). As
+  **channels** it is `count` scalar channels of one sample per cycle, so the list batches like an
+  all-scalar one. As a **waveform** it is one channel with `rows = count` and
+  `sampling_rate = rate * count`, one datagram per `Frame` (`num_samples = 1`). The two cannot share a
+  list because the model spans a frame by its largest element block and `Frame::value` is 0 past a scalar's
+  one value: a scalar beside a vector block would be zero-padded, so `problem()` demands that a list with a
+  waveform row be waveform rows of one count, and the form shows that message in the subtitle. The channel
+  total is capped at 256.
+- Its frames are **fixed-size blocks** like the E-1608's for the same reason (`build_stamps` warns when the
+  sample count varies): `round(rate / 100)` datagrams for a list with no waveform row, a partial block
+  flushed after 100 ms. `rate` is required because `sampling_rate = 0` makes the model size the ring and
+  the ingest decimation for 1 kHz; there is no time-base switch, since `acquisition.cpp` has no stamping
+  path that ignores the declared cadence.
+- `Disconnected` after 2 s without a *valid* datagram (wrong-size ones do not refresh the clock); it resets
+  `Acquisition`'s per-session state, so the next datagram re-anchors rather than reading as a gap, and the
+  history survives (`CONFIG` is sent once, from the first `poll()`).
+- The form's row editor removes a row from inside its own button's `clicked` emission (GTK keeps the emitter
+  alive to the end of the emission, and the handler copies the form and the row out of its context first);
+  every handler tests `Form::alive`, which the groups' `destroy` clears, because the chooser may have
+  destroyed the sibling widgets the handlers reach by raw pointer.
+
+### Data path
+
+`ScopeModel` holds **one `BufferStore`** (`live()`): one shared time-base ring plus one
+value ring per channel, sized by `plan_partition()` to cover `--max-window` seconds
+within the byte budget. The producer always writes it, whatever the trigger is doing —
+that is what guarantees a full pre-trigger history on the *first* latch after arming.
+The spec's second buffer (item 1) is the latched `EventSnapshot`, which is already an
+immutable copy of the captured window; see README for why two live rings were dropped.
+
+What a trace binds to is `ScopeModel::display_mode()`, one of four states, and
+`RowSet::bind()` takes it as an argument rather than recomputing it:
+
+- `Live` — no trigger: the live ring, on the clock of the **newest sample**
+  (`display_epoch() == -newest`), so the axis is a fixed `[-window, 0]` and x reads as an age.
+- `Capturing` — an edge has been accepted (so the pre window was full) and the post
+  window is still filling: the live ring, on the coming event's own clock
+  (`display_epoch() == -edge`), inside an axis already pinned to `[-pre, +post]`. The
+  post side fills in view and the marker sits at x = 0 throughout.
+- `Held` — the frozen `EventSnapshot` of the last event, whose stamps are already edge-relative,
+  so the display epoch is 0.
+- `Waiting` — armed, nothing captured yet: blank, with the live epoch (there is nothing bound,
+  but the axis is still a live one).
+
+**Disarm during a capture publishes what the capture got to**, then disarms: the producer
+cuts the window at the newest sample and that partial snapshot becomes the held event, so
+the picture on screen at the moment of the Disarm stays on screen. `engine.disarm()` clears
+`pending_`, which drops the display out of `Capturing`, and with nothing published the view
+fell back to the *previous* event — or to blank on a first capture. No event fired, so
+`trigger_latches()` is deliberately not bumped; `ScopeModel::event_seq()` counts published
+snapshots instead, and the frame tick keys its event framing on *that*. Keep the two
+distinct: the latch count is what the probes assert "how many events fired" with.
+
+`Capturing` is a **deliberate departure from SPECS:37** ("data visualisation should not
+be refreshed till next event"), asked for explicitly; that reading is what the old "never
+the live ring mid-capture" rule enforced. What survives of the rule is that `Held` binds
+the snapshot *only* — a held event is never quietly replaced by live data — and that the
+*axis* does not move during a capture: it is the event's window from the edge onwards,
+never a sliding live view.
+
+`display_mode()` must be read **once per frame** and passed around (the tick does this,
+and hands it to `bind()`). The producer can open or close a capture between any two
+reads, and two reads in one frame put the bind, the epoch, the pin and the status line on
+different clocks.
+
+**The display clock is not the stream clock, and `ScopeModel::stream_at_x0()` is the only
+conversion.** `display_x = stream_t - stream_at_x0()` in **every** mode, and the offset lives in
+one of two places: a snapshot carries its own (`EventSnapshot::x_offset`, frozen with the
+picture) and a live view carries it as minus `display_epoch()`. Anything crossing between the
+two clocks goes through that one accessor rather than picking the branch itself — the export's
+`abs_seconds` column, the pause handler putting a display window back on the ring to cut it, the
+measurement marks — because there are four modes and picking the branch by hand gets one of them
+wrong. It reads atomics only, so it is safe to call inside an existing `mutex()` guard.
+Three things about the live epoch specifically:
+- **It is written after `bind()` and `acquire_all()`, not before.** It must be minus the newest
+  sample the *traces* can report, and asking before the acquire is one frame of production
+  stale — at 1 MS/s over a 50 ms window that is a third of the screen to the right of the axis.
+- **There is no feedback loop**, even though the newest stamp is read through the epoch that is
+  about to change: `RowSet::live_edge()` reports in the epoch currently in force, so
+  `display_epoch() - live_edge()` is minus the *raw* stamp and the fixed point is reached in one
+  frame rather than converged on.
+- **`Waiting` takes the live epoch too.** Nothing is bound, but the axis is still a live one, and
+  an epoch of 0 there would make the axis jump on the frame a capture closes.
+
+**A measurement mark is glued to its sample; a cursor stays on screen.** The two instruments move
+in opposite directions under a rolling axis and that is deliberate — a bench scope's cursors sit
+where the user put them while the waveform rolls under, and a measurement's mark names the sample
+it measured. The cursors need no code: their x *is* a display coordinate. The marks are stored in
+**stream** seconds and reconverted every frame by `place_measure_marks()`, since a mark left in
+display coordinates would crawl forward at one window per window. `App::measure_window` is
+stream-clocked for the same reason, and that one is load-bearing: the recompute trigger is "the
+window moved by 2 % of its span", and in display coordinates a live window is a fixed
+`[-window, 0]` — it never moves, so the measurements would never be recomputed again.
+
+Layers to keep straight:
+
+- `SignalInfo` — one signal as the CONFIG described it. The unit of enable/disable.
+- `ChannelInfo` / `ChannelBuffer` — the unit of acquisition and plotting. A
+  `ChannelBuffer` is a `plot::data::Series` over a (value, time) ring pair.
+- `SlotSeries` (`src/channel.hpp`) — a trace's stable series object, rebound each frame
+  to either a `ChannelBuffer` or an `EventSeries`.
+- `RowSet` (`src/plot_host.hpp`) — **one `plot::Figure`** of up to `kMaxRows` rows (added
+  and removed one at a time by the layout editor), each a
+  borrowed `plot::Plot*` with `kSlotsPerRow` fixed trace slots. The figure owns
+  everything the rows have to agree on: the x window (one x link group every row joins),
+  the live follow (the *group's* — a member's own axis must be `XFollow::Off`, since
+  `Figure::link_x()` refuses a `Live` member), the left gutter and the crosshair.
+
+- `ExportTable` (`src/export.hpp`) — the visible window as columns, collected from the
+  snapshot or the live rings and handed to the `.npy`/`.csv` writers. Always the stored
+  samples, never the LOD pyramid's buckets.
+
+`src/ui.cpp` is the GTK4 window (toolbar, trigger panel, signal panel, plot box) plus
+the `tick()` frame function that binds, updates the trigger state and rewrites the
+status line. One `plot::gtk4::PlotArea` in figure mode draws the whole figure. It is by
+far the largest file.

docs/claude/build-and-run.md

@@ -0,0 +1,318 @@
+# Build and run
+
+Configuring, building and launching udpscope, the desktop entry target, the command-line options and the two vendored dependencies.
+
+Part of [CLAUDE.md](../../CLAUDE.md).
+
+## Build and run
+
+```sh
+git submodule update --init --recursive          # deps/plotter is a submodule
+cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo
+cmake --build build
+
+./build/udpscope --server 127.0.0.1 --port 8000
+./build/udpscope --server 10.0.0.5 --port 8000 --multicast 239.1.2.3 --interface 10.0.0.9
+./build/udpscope --source udps --source-opt server=127.0.0.1 --source-opt port=8000   # same as --server/--port
+```
+
+`--help` lists the registered source kinds.
+
+The app can be launched from the shell rather than only from a terminal, but only on request:
+
+```sh
+cmake --build build --target desktop-entry
+```
+
+That writes `org.udpscope.app.desktop` plus both app icons under `$XDG_DATA_HOME` (default
+`~/.local/share`), runs `desktop-file-validate` as a **hard failure** (when it is on `PATH`;
+absent, it says so and installs anyway), refreshes `update-desktop-database` and
+`gtk4-update-icon-cache` when they are on `PATH`, and prints the three paths it wrote — which is
+the uninstall instructions, since there is no uninstall target. `cmake --build build` alone never
+touches `$XDG_DATA_HOME`.
+
+The entry's `Exec` is the built binary's **absolute path in the build tree**, so **moving or
+deleting the build directory breaks it.** That is the price of having no install step and it is
+deliberate: the entry then always launches exactly the binary that was last built. No
+`StartupWMClass` is needed — GTK takes the WM class from the application ID, and the desktop
+file's basename is that same string, which is what associates a running window with the entry.
+
+The interface files can be checked without building anything or opening a window:
+
+```sh
+cmake --build build --target test-ui      # or: make -C build test-ui
+```
+
+That round-trips every `.ui` through `blueprint-compiler` — `decompile` turns it into blueprint, and
+compiling *that* type-checks every property and child type against the GIR — printing one line per file.
+It exists because the alternative is what happens otherwise: a property a class does not have is a
+`Gtk-ERROR` when the window is built, and `Gtk-ERROR` **aborts the process**, so a typo in a `.ui` takes
+the application down rather than failing to open a dialog. `preprocess="xml-stripblanks"` catches
+malformed XML and nothing else, and the probes catch the rest only for the windows they open.
+
+The XML stays the source of truth and stays hand-written: this is a check, not a compiler, and nothing
+here is needed to *build* the application. `blueprint-compiler` and `python3` are found at configure
+time; without them the target is absent rather than silently passing. `tools/check_ui.py --lint` also
+prints the linter's advice, which is advice and deliberately not a gate.
+
+The manual has its own check, the same shape:
+
+```sh
+cmake --build build --target test-help
+```
+
+That runs `yelp-check`'s four offline subcommands over `help/C/<id>/` (links, media, orphans, ids)
+and renders the whole set with `yelp-build html` into a temp directory, so the manual is checked the
+way the `.ui` files are. **`yelp-check validate` is deliberately not used**: it fetches the Mallard
+RelaxNG schema over the network, which is absent on a build box, so it would fail for that reason and
+not for a fault in the pages. `yelp-check`/`yelp-build` are found at configure time; without them the
+target is absent rather than silently passing.
+
+The manual is a Mallard set under `help/C/<id>/`, installed by an `install()` rule to
+`<datadir>/help/C/<id>/` — where the freedesktop Help System Specification's `help:` URI resolves
+`help:<id>` — so it is *read from a datadir by another process* even though the binary itself has no
+install step. `F1` opens it in Yelp through that URI. The document identifier is the desktop file's
+basename (`data/org.udpscope.app.desktop.in` → `org.udpscope.app`), so it is the `.desktop` name, the
+GApplication id and the install directory at once. The figures are regenerated by
+`tools/make-help-shots.sh`, which drives the app headlessly against the mock and draws the annotation
+boxes with ImageMagick; Mallard is translatable with `itstool`, but only the `C` set is authored.
+
+Because the manual is the only thing udpscope installs, it can be installed *alone* — where `help:`
+finds it, and without the `cmake --install` of a whole project — by either of two opt-in targets.
+Neither is built by default and `cmake --build build` never touches either:
+
+```sh
+cmake --build build --target install-help-user   # <data-home>/help/C/<id>/, no root
+cmake --build build --target install-help         # <CMAKE_INSTALL_PREFIX>/share/help/C/<id>/
+```
+
+`install-help-user` writes to `$XDG_DATA_HOME` when it is set and to `$HOME/.local/share` when it is
+not — the XDG Base Directory Specification's own default for the variable, and the fallback
+`help_installed_path()` uses — so it needs no root and lands the set exactly
+where `F1` and the alert look for it. `install-help` goes through the install machinery into the
+configured `CMAKE_INSTALL_PREFIX`, so a packager or a system-wide user points it at `/usr` with
+`-DCMAKE_INSTALL_PREFIX` at configure time. Neither target can install system-wide by itself: a build
+target has no more privilege than the shell that ran it, so `install-help` writes to the configured
+prefix and a system-wide caller wraps it in `sudo`. Both print where they wrote. Both land the same
+tree the `install()` rule does — the user-local copy applies that rule's file filter, and the
+prefix-wide target *is* that rule, reached through the `Help` component
+(`cmake --install --component Help`) — and the ordinary `cmake --install` still installs every
+component, so its behaviour is unchanged.
+
+Options: `--source NAME` and the repeatable `--source-opt k=v` (the source kind and its settings;
+`--server`, `--port`, `--multicast` and `--interface` populate the UDPS entries of the same options),
+`--server`, `--port`, `--multicast`, `--interface`, `--buffer-mb` (per
+buffer, default 200), `--max-window`, `--holdoff`, `--recv-buffer`, `--plots` (the row
+count to *start* with, 1..`RowSet::kMaxRows`; the layout editor owns it afterwards),
+`--capture-packets N` (the raw-datagram ring of README's "Packet capture"; 1..100000,
+the value is required, and the popover button uses 1000 when the flag was absent).
+The flag is **not** persisted in the session file: persistence of the enable state
+belongs with `todo.md` item 3, alongside the relative-time toggle.
+`--renderer cairo|gl|vulkan` exports `GSK_RENDERER` **at the top of `main()`** —
+before `choose_source()`'s `adw_init()` and `run_ui()`'s, because GSK reads the variable when
+it creates its renderer and setting it later is a silent no-op. `cairo` is the software preset
+and also exports `LIBGL_ALWAYS_SOFTWARE=1`: the plot is a `GtkGLArea`, so a display with no
+usable GPU fails twice, and this is the pair `tools/make-help-shots.sh` already sets. Nothing
+is exported when the option is absent, so GTK's own choice stands.
+
+`--source e1608` selects the MCC E-1608 Ethernet DAQ; its settings are `--source-opt` keys, all optional
+(`address` or `mac`+`subnet`, `port` 54211, `code` 0, `timeout_ms` 2000, `scan_rate` 1000 per channel,
+`ext_clock`, `trigger` `none|rising|falling|high|low`, `auto_restart` 1, `calibrate` 1, `poll_rate` 10,
+`gen_rate` 50 (Hz, 1 to 200: the waveform generator's DAC update rate), `mode` `se|diff`, `ai0`..`ai7` `BIP10V|BIP5V|BIP2V|BIP1V` (an absent key = off, **and any `aiN` key at all
+drops the default**: only a run with no `aiN` key gets `ai0=BIP10V`, so `ai1=BIP5V` alone is channel 1
+alone, and a value that is not a range name is a channel that is off), `dir0`..`dir7` `i|o`,
+`plot0`..`plot7`, `plot_counter`, `do_init`, `ao0_init`, `ao1_init`). Either `address` or `mac` is
+required; a MAC with no `address` is looked up by a broadcast sent on every interface (`Scan`), or by a sweep of
+`subnet` (`a.b.c`).
+The enabled channels times `scan_rate` must not exceed 250 kS/s. `tools/mock_e1608.py` is a protocol
+mock of the board for development (UDP discovery and handshake, TCP commands, a scan stream with a sine
+per channel, calibration memory, `--port`, `--mac`, `--log FILE`, `--drop-after S` and `--overrun-after S`
+switches, `--code N`); the mock stands in for the board (a real board has been run once, with one channel; see
+the README), and the mock's header lists the items whose layout is unverified. Errors are written to stderr as `[e1608] ...`, once per distinct message.
+
+```sh
+python3 tools/mock_e1608.py --port 54711 &
+./build/udpscope --source e1608 --source-opt address=127.0.0.1 --source-opt port=54711 \
+  --source-opt ai0=BIP10V --source-opt ai1=BIP5V --source-opt plot0=1
+```
+
+`--source flatudp` receives the MARTe2 `UDPSender` datasource (one datagram per cycle: the signals
+concatenated in declaration order, no header, no padding). The datagram carries **no description**, so the
+settings are the whole contract: `port` 44488, `bind`, `multicast` and `iface` (a group to join and the local
+interface for it), `rate` (the sender's cycle rate in Hz; **required**, it sizes the ring and the ingest
+decimation and spaces the samples within a frame), `endian` `little|big`, and `signals`
+`name:type[count][w],...` with types `uint8/16/32/64`, `int8/16/32/64`, `float32`, `float64`, e.g.
+`Trigger:uint8,Ia:float32,Wave:float32[16]`. A count above 1 makes a vector signal, shown one of two ways: by
+default as `count` **channels** `Wave[0]`..`Wave[15]` of one sample per cycle each (batched like any scalar
+list); with a trailing `w` (`Wave:float32[16]w`) as ONE **waveform** channel receiving `count` consecutive
+samples per cycle at `rate * count`, as a UDPStreamer block signal. A waveform row needs a count above 1, a
+list with one holds only waveform rows of one count (no zero-padding of scalars), and a list may make at most
+256 channels (a scalar 1, a `channels` row `count`, a waveform 1). A datagram of any other size than
+the list implies is dropped and counted as stale; each distinct wrong size is reported once on stderr as
+`[flatudp] ...`. Loss is never reported: the stream has no counter. `tools/mock_flatudp.py` is a sender for
+a signal spec (`--rate`, `--signals`, `--big-endian`, `--gap S,D`, `--bad-every S`, `--multicast G --mcast-if A`,
+`--log FILE`).
+
+```sh
+python3 tools/mock_flatudp.py --port 44588 --rate 1000 --signals 'Trigger:uint8,Ia:float32,Wave:int16[4]' &
+./build/udpscope --source flatudp --source-opt port=44588 --source-opt rate=1000 \
+  --source-opt 'signals=Trigger:uint8,Ia:float32,Wave:int16[4]'
+```
+
+(Quote the `signals` value: zsh globs the `[4]`. The mock takes the same text with or without the trailing `w`;
+the datagram is the same, `w` only says how the app shows it.)
+
+`tools/mock_udpstreamer.py` has waveform-injection options used by the probes:
+
+- `--square-harmonics N` shapes `square`: `N` odd harmonics of the ideal step's Fourier
+  series, so each edge overshoots by the Gibbs constant (about 9 % of the 2 V swing at the
+  default 30, i.e. `y = ±1.179`) and then rings — a band-limited edge, which is what a
+  crossing count or a pulse-width test has to survive. The series is deterministic and the
+  odd harmonics keep the ideal wave's edge instants and its polarity, so the level-0 trigger,
+  the search and the glitch's inverted pulse still read where they did on the step; the
+  *extremes* are what move. `0` (or negative) is the ideal ±1 step, which is what a probe
+  asserting an exact extreme or an exact width asks for — the noise probe's group-delay leg is
+  the one that does, because its `want` is the analytic `tau*ln2` of a step
+  (see [verification.md](verification.md)). It costs the producer about 0.5 ms per
+  2000-sample packet on top of the ideal branch, so at the fast mock's 1.3 MS/s the mock
+  delivers at roughly nine tenths of its declared pace — a reading that scales with the
+  retained span reads that much lower, and nothing else does.
+- `--glitch-at S` / `--glitch-width W` invert the `square` signal for `W` seconds at the
+  start of every square period from stream second `S` onwards — a runt pulse of a known
+  width, which is what a `<` pulse-width trigger and a glitch search are checked against.
+- `--quiet-at S` freezes `sine` at its held value from stream second `S` onwards, so it
+  stops crossing zero: the dropout trigger's input.
+- `--spike-every S` / `--spike-amp A` / `--spike-width N` inject an alternating-sign
+  impulse train onto `sine` only — the other four signals (`time`, `square`, `ramp`,
+  `noise`) are untouched, which is what lets a probe compare a spiked channel against a
+  clean one in the same run. Every `S` seconds a spike of `N` samples at amplitude `A` is
+  added to `sine`; the sign alternates per period because a one-signed train is a DC offset
+  a median would partly track rather than reject. `N` is in **samples**, not seconds, so its
+  duration follows `--rate`. `0` (the default for both `S` and `A`) injects nothing, so
+  every existing invocation is unchanged. **`--batch` must stay at or below 1000** with or
+  without these options: 2000 samples × 5 signals × `f64` is 80 kB and exceeds UDP's
+  ~65507-byte payload limit, and the mock dies on its first `sendto` with
+  `OSError: [Errno 90] Message too long` while the run still exits 0.
+
+Run with no `--server` and udpscope asks which source to open: the sessions it has stored, plus a
+form for a new host. Every probe below passes `--server`, so none of them sees it.
+
+`deps/plotter` is built from source with only the GTK4 adapter enabled
+(`PLOT_BUILD_GTK4`); its tests and examples are forced off. `deps/udpsclient` is a
+vendored C99 source pair compiled into a static lib. `deps/udpsclient` gained one
+additive entry point for the packet capture — `udps_client_set_datagram_cb()`, firing
+inside `udps_client_poll()` immediately after the UDP `recv()` returns, before the
+magic check or reassembly — plus the public `UDPS_MAX_DATAGRAM_BYTES` the capture
+sizes its slots from. A separate setter, not a fourth parameter on
+`udps_client_set_callbacks()`: that signature has call sites, and a capture hook is no
+reason to change them.
+
+**libadwaita ≥ 1.8 is a system dependency** (`pkg_check_modules(ADWAITA ... libadwaita-1>=1.8)`),
+for two widgets: the shortcut overview (`AdwShortcutsDialog`) and the About dialog
+(`AdwAboutDialog`). GTK4's own `GtkShortcutsWindow` is deprecated as of 4.18 and
+`AdwShortcutsDialog` is its replacement; `GtkAboutDialog` still exists but
+`adw_about_window_new()` is deprecated in favour of `AdwAboutDialog`, which shows the
+application icon as the page's own header. Two consequences worth knowing before editing.
+`adw_init()` is called — in `run_ui()` and, since the chooser runs first and must be styled
+the same, in `choose_source()` in place of its `gtk_init()` (both are idempotent) — so
+**the whole app is drawn with libadwaita's stylesheet**, not GTK's: a metric change there
+reaches every widget, and `layout over N frames` / `axes.w changes` is what says whether
+the layout still settles. And an `AdwDialog` is **not** a `GtkWindow`: both `show_about()`
+and `show_shortcuts()` keep an `AdwDialog*`, cleared on `::closed` (there is no
+`::close-request`) and closed with `adw_dialog_close()`. They share one `on_dialog_closed()`
+handler keyed by a pointer-to-pointer (`gpointer slot` cast to `AdwDialog**`), so one
+handler clears either pointer without knowing which dialog it is. Presenting either on this
+app's plain `GtkApplicationWindow` is supported and warning-free; it was checked.
+
+`deps/udpsclient` is a vendored C99 source pair and its diff from the upstream source
+is intentional. Five things were changed:
+
+1. **A reorder ring of reassembled payloads.** When a packet arrives with a higher counter
+   than expected, the raw datagram is held in a fixed-size ring rather than decoded immediately.
+   A deadline (`now + reorder_window_s`, default 0.020 s) is set for the gap; the deadline is
+   served by a third `clamp_deadline()` call on the `select()` budget
+   (`udps_client.c:1145-1152`) so a quiet stream does not wait for the next arrival.
+2. **Late delivery replacing the outright discard.** A packet that arrives past the window — or
+   when the ring is drained by the deadline — is delivered to the callback flagged `late` rather
+   than discarded with `stats.stale_packets++; return 0`. That flag is what makes backfill
+   possible at all; without it the samples are gone before udpscope can act.
+3. **The third `clamp_deadline()`.** The existing pair handles the keepalive and the silence
+   timeout; the reorder deadline is a third call to the same helper, which already understood
+   the pattern.
+4. **`reorder_window_s = 0` as the switch.** `udps_client_config_t::reorder_window_s`,
+   defaulted to `UDPS_REORDER_WINDOW_S_DEFAULT` (0.020) in `udps_client_config_init()`,
+   is the only knob. Setting it to zero disables resequencing and restores the previous
+   discard-on-late behaviour exactly — so a reported regression is bisectable without reverting
+   the source. **There is no command-line flag for the reorder window.** It is not surfaced on
+   udpscope's command line; do not document a `--reorder-window-ms`.
+5. **The full ring never drops the arriving packet, and says so in a counter.** A packet that
+   needs a slot and finds none commits the current gap (which frees at least one, since
+   `commit_gap()` always delivers) and the ordering decision is taken once more against the
+   sequence that commit left behind — a bounded retry, because the commit can advance
+   `next_counter` past the arriving counter and turn an ahead-of-sequence packet into a behind-
+   of-sequence one. Past the retry it is delivered *in order*, with the counters it skipped as
+   its `lost`, and never flagged `late`: a packet ahead of the sequence has no reserved hole and
+   `Acquisition::backfill_from()` silently ignores a late packet it cannot place, so flagging it
+   would be the same silent loss by another route. `stats.reorder_overflows` counts the event,
+   so an undersized ring is a reading rather than a mystery; it is surfaced in the exit dump and
+   the `[reseq-probe]` line as `overflows=`.
+
+`deps/plotter` is upstream's own repository and this app's figure support was added
+there rather than worked around here: `Figure::set_min_y_gutter()` (a floor under the
+common left gutter), `Figure::set_right_gutter()` / `Plot::set_right_gutter()` (an empty
+band on the *other* side, which the layout had no concept of — `axes` reached the
+viewport's right edge, so the rightmost x tick label was centred on a line it had half of
+itself outside of; the guard is `figure_rows_share_one_right_gutter`), and in the GTK4
+adapter `PlotArea`'s **figure mode** —
+`set_figure()`, one `input::Controller` per row, nearest-row event routing, a
+figure-wide crosshair — plus `PlotArea::row_at()` for naming the row a pointer is over.
+
+`plot::data::RingBuffer` carries two writes a plain SPSC ring has no use for and this app
+does: `amend(absolute, v)` rewrites a retained slot when a late packet's data finally
+arrives, and `clear_to(absolute)` empties a ring and **resumes its count at a given
+origin**. The second exists because a math channel's ring is recomputed from its inputs'
+*retained* window: `clear()` would restart it at 0 and leave every absolute index —
+`base()`, `produced()`, `copy_from()` — short by that window's base, which is the
+desynchronisation `live_window_locked()` then reads as an empty window (see
+[invariants-math-channels.md](invariants-math-channels.md)). Its guards are
+`ring_clear_to_resumes_the_absolute_count` — a derived ring refilled from a source's retained
+window must come back with the source's own `produced()`/`base()` — and
+`ring_clear_to_zero_is_clear`.
+
+The render-quality work went there for the same reason: `kTextFS` now **filters** the
+glyph atlas (a 2×2 bilinear clamped to the instance's own cell) instead of point-sampling
+it, and `LineProgram::set_snap()` / `u_snap` rounds an axis-aligned segment's ink onto
+whole pixels for the chrome that frames a plot (grid and axis lines), never for anything
+drawn at a data position. `generate_ticks()` also stores the tick at the origin as
+exactly `0.0` — the walk starts at `ceil(min/stride)*stride` and so never lands on zero
+when the stride is not a power of two, which labelled it `-139a`. `format_time()` picks its
+unit rung by the **rounded** mantissa (`t < u.scale * 0.9995`, and the same slack on the
+whole-second branch) — the `>= 999.5` spill guard `format_si()` in the same file always had —
+because a tick a hair under a rung's top rounds to 1000 at three significant figures and
+`%.3g` writes that `1e+03`, which is how a one-second tick read `1e+3ms`. All four carry
+upstream tests — `the_atlas_is_filtered_not_point_sampled`,
+`grid_hairlines_land_on_whole_pixels`, `the_tick_at_the_origin_reads_zero` and
+`format_time_never_lets_a_field_reach_its_radix`. The box-zoom selection was the one gesture with no
+feedback at all: the controller tracked the rect and nothing drew it. The drawing went upstream with
+the rest — `Plot::set_selection_rect()` (the plot carries a rect the host hands it and learns nothing
+about pointers), `Controller::selection_preview()` (the mask decides which axis is *not* zoomed, and
+the preview is widened along it, because the swept sliver of a horizontal Ctrl drag is the gesture and
+the band across the plot is what the release will apply) and `Renderer::draw_selection_frame()` — and
+it carries three tests: `a_ctrl_box_zoom_previews_the_band_it_will_zoom`,
+`the_selection_frame_is_carried_and_taken_off` and `the_box_zoom_frame_lands_exactly_where_it_says`,
+the last of which reads the headless framebuffer back and compares the same pixels with and without
+the frame. The minor
+grid's look is set there too, not here: `grid_minor` carries 50% alpha, `grid_minor_width` is
+0.75 (sub-pixel, expressed as coverage at 1x) and `grid_minor_dash_on`/`_off` are 3/3 — a
+fragment discard, no extra geometry — so the subdivisions read as texture under the labelled
+grid instead of as a second set of ticks (`the_minor_grid_is_thinner_dashed_and_dimmer_than_the_major`).
+README records what they cured.
+
+Changing any of this means committing in the submodule and moving its pin, and running
+the library's own suite as well as the udpscope probes (see
+[verification.md](verification.md)):
+
+```sh
+cmake --build deps/plotter/build/debug
+xvfb-run -a deps/plotter/build/debug/tests/plot_tests     # expect "0 failed"
+```

docs/claude/invariants-data-path.md

@@ -0,0 +1,372 @@
+# Invariants: the data path — buffers, decimation and the rings
+
+What rebuilds a buffer, why decimation is an average, and the two rules the time ring's precision and its first stamp impose.
+
+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.
+
+- **Any structural change rebuilds the buffer and drops history**: a CONFIG, an
+  enable/disable, a calibration change, or a **change of display window that moves the
+  decimation factor**. Calibration is applied at ingest, which is why it re-partitions.
+  `ScopeModel::set_target_span()` is the window's path in, and it re-plans *only* when
+  `time_stride` actually changes, so walking the window inside one decade is free; it asks
+  `plan_partition()` rather than recomputing the factor, because two expressions for that
+  decision is how the buffer and the view end up disagreeing about the stored rate. It
+  takes `mutex()` itself — do not call it holding the lock.
+- **A rebuild that would plan the *same* storage clears the store instead of allocating one.**
+  `rebuild_locked()` compares the new `Partition` against the current one with
+  `Partition::same_storage_as()` — every field that decides an allocation: `time_capacity`,
+  `time_stride`, `abs_time`, `base_dt` and the per-channel `stride`/`value_capacity` vectors — and
+  on a match calls `BufferStore::reset()` rather than constructing a new one. `base_dt` is in the
+  comparison on purpose: it is not a size, but it is what the slots *mean*, and keeping samples
+  under a changed `base_dt` would re-date the whole ring.
+  **Construction is the cost.** A `RingBuffer<T>` holds a `std::vector<std::atomic<T>>`, which is
+  value-initialised, so making a store touches every byte of `--buffer-mb` — about a second per
+  gigabyte, mostly first-touch page faults — while `reset()` is one relaxed store per ring plus an
+  `invalidate()` and an epoch back to zero. It must leave nothing of the old history behind, which
+  is why it clears the time ring, the absolute-time ring, every value ring, and both the published
+  window and the pyramid of every channel: a reused store that kept a stale published window would
+  hand the renderer samples the new plan does not describe.
+  `reset()` runs on the consumer thread under `ScopeModel::mutex()`, which is what makes a
+  `RingBuffer::clear()` safe here at all — the producer holds that same mutex for the whole of
+  `on_data()`.
+  Every allocation that *is* made says so: `[udpscope] buffer allocated: N channels, S s span,
+  T ms` on stderr. A start used to emit fifteen of those; two is a real start, and a count that
+  climbs again is this rule having stopped applying.
+- **Enables are applied in one batch, because each one re-plans.** `set_signals_enabled()` takes
+  the mutex once, moves every signal in the list, and re-plans and bumps the generation **once** —
+  and not at all when nothing actually moved, which is the common case for a restored session
+  re-enabling what is already on. Calling `set_signal_enabled()` in a loop is a buffer rebuild per
+  signal; `apply_layout()` and the waveform loader collect their wanted signals into one vector for
+  that reason, and `apply_layout()` records the session's span **first**, with no channels bound, so
+  the `apply_time_window()` that follows re-plans nothing.
+- **The shared clock is decimated to fit the requested window; channels never are.** A
+  window too long to store at the wire rate used to be refused (the control was capped to
+  `Partition::span_s`), which made a 600 s view of a 1 MS/s stream unreachable.
+  `plan_partition()` now picks `time_stride`, a power of two, **after** the growth loop has
+  bought all the ring the budget allows — deciding it earlier over-decimates by whatever
+  factor growth was about to add. Per-channel `stride[i]` stays 1: a stride of
+  `round(dt_i / dt_fastest)` keeps one sample per stride, and when that equals the signal's
+  own period — a 2 kHz sine on a 1 MHz clock, stride 500 — every kept sample sits at the
+  same phase and the channel plots flat.
+- **Decimation at ingest is an average, never a stride.** `Acquisition::on_data()` reads
+  and accumulates *every* sample and pushes the mean of each group of `time_stride`
+  (`value_acc_`/`value_acc_n_`, and `time_acc_` for the clock). That boxcar's first null is
+  at the stored rate, so content that would fold back is attenuated instead of reappearing
+  as a false low frequency — which is the whole reason decimation was once dropped
+  entirely. Skipping the read for unstored samples re-introduces the aliasing; the
+  `UDPSCOPE_PROBE_WINDOW_MS` run under `--freq 2000` is the guard (the anti-alias check in
+  [probe-readings.md](probe-readings.md)).
+  The stamp pushed is the group's **mean**, not its last member: that is where the boxcar's
+  group delay puts the value, and stamping at the end of the group shifts every trace half
+  a stored sample late. The accumulators are reset whenever `time_stride` or the channel
+  count changes, so a re-plan starts a fresh group rather than finishing one at the wrong
+  length. The LOD min/max pyramid still preserves the extremes *of what is stored*; a spike
+  narrower than a group is now filtered away rather than aliased, which is the correct
+  trade and is why the status line's `rate` field is worth reading.
+- **A file is ingested too, so the loader decimates by the same factor.** `load_waveform_into_model()`
+  sets the target span to the recording's own length and enables every column, and the plan that
+  comes back may well decimate: 20 s of 10 channels at 500 kS/s is 480 MB of rings, and the budget is
+  `--buffer-mb`. The loader therefore reads `partition().time_stride` **after** the enables and pushes
+  one slot per that many rows, carrying the group's mean at the group's mean stamp — the packet path's
+  filter, written a second time because a file does not arrive in packets. Pushing every row instead
+  overruns the ring and leaves the file as **its own tail**, with nothing to say so: a 20 s event
+  opened as its last 4 s, `stored=10000000` against `published=2097152` in the channel dump, and a
+  trace that looks like a short recording rather than a truncated one. The `waveform loaded:` line
+  carries `rows=` and `decim=` beside `samples=` for exactly this reason — `samples * decim == rows`
+  is the arithmetic that says the whole file is in the buffer.
+- **One bad packet is bridged; only a run of them changes the time source.** The stream-time
+  checks in `build_stamps()` reject three things: stamps that are not finite, a packet with no
+  span at all, and a packet whose stamps do not advance past the previous packet's last. A
+  fourth was added because a real device's clock glitches: a packet whose stamps jump **more
+  than 256 packet spans** ahead is a fault, not a gap, and must be rejected — letting it
+  through poisons `last_stamp_`, and the monotonic clamp (`max(stamps[k] - epoch,
+  last_stamp_)`) then pins every later packet flat at the glitched value, so the whole stream
+  freezes at one x and never recovers. A rejected packet is **bridged**: its stamps are
+  replaced by a continuation of the accepted timeline at the declared cadence, so neither the
+  monotonic mark nor `last_stream_anchor_` is poisoned and the next good packet is accepted
+  normally. Believing the glitch instead is what condemned the *next*, perfectly good packet
+  (it now sits below the poisoned anchor, so it fails the advance test) and threw the whole
+  stream onto the arrival clock. Only **four consecutive** rejected packets abandon the
+  declared time signal, because that is what a signal which is not a time base at all looks
+  like; a first packet with nothing to bridge from still falls back immediately. The unit
+  scale ('ns', 'us', 'ms') is therefore resolved **before** these checks rather than after:
+  they weigh the stamps against a cadence in seconds, and on a 'ns' stream an unscaled
+  comparison is off by 1e9, so every packet would read as an implausible jump. The guard is
+  `tools/mock_udpstreamer.py --time-glitch-at`/`--time-glitch-by` (see
+  [verification.md](verification.md)).
+- **A *restarted* client is the other way into the same poisoning, and it is not a glitch.** Going live
+  from a file view starts a new `udps_client`, and the new stream's stamps can sit **behind** the ones the
+  old stream left in `last_stamp_` — the file view's samples are still in the store. The advance test then
+  rejects every packet of a perfectly good stream, four rejections abandon the declared time signal, and
+  the arrival clock derives its epoch from the stale mark: every sample is stamped **flat at the old
+  value**. `trig engine: … ring=[2.5200..2.5200] n=567000 → n=1131000 → n=1689000` is what that looks
+  like — the count climbing at the stream's rate while the retained span is one value — until some later
+  rebuild resets the store, which is where the "few seconds of nothing" came from.
+  `Acquisition::start()` therefore calls `ScopeModel::reset_stream()` and re-bases `last_stamp_` to
+  `-infinity`: a started or restarted client is a *new stream*, so the previous one's history goes (which
+  is what `reset()` is for) and the monotonic guard re-bases on the new clock instead of pinning it.
+  `ring` moving within a stream round-trip of *Go live* is the assertion.
+- **The arrival-clock fallback does not drop history.** `arrival_epoch_` is derived from
+  `last_stamp_`, so the arrival clock *continues* from the monotonic mark and the two
+  timelines share a zero by construction — the recorded stamps are therefore still on one
+  timeline and are kept. The fallback used to call `reset_live_history_locked()` on the
+  reasoning that the old stamps belonged to a dead clock; they do not, and that wipe is what
+  made a single glitching packet look like "the live stream restarted from 0 with no action
+  from the user". The continuity is also what makes a rebase of `TriggerEngine` unnecessary:
+  the engine holds four absolute stamps (`holdoff_until_s_`, `pending_start_s_`,
+  `last_trigger_s_`, `last_t_s_`) and they stay valid across the change. Anything that makes
+  the clock *discontinuous* breaks that and has to reset them.
+- **The trigger sees the stored (filtered) signal, not the wire signal.** `engine.process()`
+  is fed the averaged value, inside the `if` that pushes it. An edge found on a sample that
+  is not in the buffer would be cut from data that does not contain it.
+- **The time ring is `f64` and the value rings are `f32`, and the asymmetry is the point.**
+  A value's precision is a property of the signal (24 bits is plenty for a sample); a
+  timestamp's is a property of *how long the scope has been running*, because the stamps are
+  stored relative to an epoch fixed at the first sample ever seen and so grow without bound
+  while the interval they must resolve stays one sample period. `f32`'s ULP is 1.9 µs at 16 s
+  of uptime, 3.8 µs at 32 s, 7.6 µs at 64 s and 61 µs over a 600 s window — so at 1 MS/s two
+  to four consecutive samples shared a stamp after half a minute, eight after a minute, and
+  the LOD envelope over such a plateau drew a zero-width segment, i.e. a vertical spike where
+  the waveform should be. That is "zoom in to ~10 µs and three to five points share a
+  timestamp, and min/max produces artefacts". **Do not widen the values to match**: they are
+  the memory budget, and nothing about them is magnitude-bound this way. Three consequences:
+  `plan_partition()` can no longer count slots in its growth loop (a time slot and a value
+  sample are different sizes, so it weighs the budget in **bytes** — `sizeof(f64)` for the
+  clock plus `sizeof(f32) / stride[i]` per channel — and `bytes_for()` is also what bounds
+  the doubling against overflow); `live_window_locked()` compares its bounds in the ring's own
+  type with **no rounding step**, the old `f32` round-trip having existed only so that a
+  sample sitting exactly on a bound was kept whatever the stream's absolute time was; and
+  `EventSnapshot::stamps` is `f64` because it is cut from this ring and is therefore in the same
+  units, whatever a given snapshot's own origin is (both kinds are rebased now — an event's
+  stamps are edge-relative, a pause's freeze-relative — so neither is magnitude-bound the way the
+  ring is, and the width is for the cut rather than for the coordinate). `RingBuffer<T>` stores
+  slots as `std::atomic<T>` behind a `static_assert(is_always_lock_free)`, which `double`
+  satisfies on every supported target. The guard is the **export**: over a multi-million-row
+  `.npy`, `np.diff(t)` must hold one step to within a few ULP of the column's magnitude (see
+  the export guard in [probe-readings.md](probe-readings.md) for why it is no longer exactly one
+  value). Three steps at 2, 2.5 and
+  3 ULP of *the stream's uptime* — microseconds, not femtoseconds — is this defect.
+- **Append is not the only write.** A backfill amends slots that a reservation wrote as NaN, and
+  the amend is split across threads for a reason:
+  - **Ring amend — producer thread.** `RingBuffer<T>::amend(absolute, v)` is a single relaxed
+    store, bounds-checked against `[produced_ - capacity, produced_)`. The same race class as a
+    push, and an `f32` cannot tear. Measurements and export read the ring directly, so they see
+    a repair immediately and no second notification is needed.
+  - **Pyramid amend — consumer (GTK main thread), inside `ChannelBuffer::acquire()`.** The
+    producer collects amended values in a plain `std::vector<Amend>` member and the consumer
+    drains it after its own append pass. `acquire()` is called under `model.mutex()`, and the
+    producer holds that same mutex for all of `on_data`, so the vector is correctly serialised
+    with no lock-free queue. The reason the pyramid amend cannot also be on the producer: a
+    bucket is a 32-byte non-atomic aggregate that the renderer reads **unlocked at paint time**,
+    so a producer writing it could be caught mid-bucket — a `count` that does not match its
+    `sum`, producing a wrong mean from a structure whose readers trust `count == 0` to mean
+    *absent*. On the consumer that cannot happen.
+  - **A hole is stamped at reservation; backfill changes values only.** The f64 time ring is
+    never amended. `neighbours()' binary search requires a monotonic array, and `window_x0_`
+    must remain valid; pre-stamping the hole at the declared cadence (exact in relative mode,
+    the bridge mechanism in stream mode) is what keeps both invariants, and it is why a late
+    packet's counter, not its arrival stamp, is what addresses the hole. The reservation cap
+    (`kGlitchPackets`, 256) is counted in **packets, not samples**, so one hole's sample cost
+    is `256 × batch_` and scales with the stream's batch — 25 600 samples at a batch of 100,
+    2.56 M at a batch of 10 000 — which is the number to weigh against the ring, not the 256.
+  - **A reservation is weighed against the wire, and never booked on the counter's word alone.**
+  The counter is a *claim* about the stream; the arrival clock is a *measurement* of it, and only
+  the two together justify writing NaN into the ring (`Acquisition::gap_plausible()`, called
+  before anything is booked *and* before relative mode's own clock advance, because the advance
+  and the reservation are the same claim). Two tests, either one refusing is enough:
+  - **The arrival clock.** `missing` packets would have taken `missing` frame intervals to arrive,
+    so a gap whose elapsed arrival time is under half of that is refused. Half and not one because
+    the socket clock jitters and a drain can compress two frames' arrival times -- and a refused
+    gap costs a *shading*, never data, so the test is deliberately permissive.
+  - **The ring.** `missing × batch_` samples become `missing × batch_ / time_stride` slots, and the
+    hole may not lap `time_capacity`. This is the *sample* form of the rule the 256-packet cap
+    states in packets -- the cap's own comment says 256 packet spans in one go is an outage, and
+    the invariant above says the number to weigh against the ring is `256 × batch_` and not the
+    256 -- and it has to exist in samples because a hole that laps the ring erases the history it
+    is meant to annotate, can never be backfilled (its slots are already overwritten) and is never
+    forgotten (`forget_holes_before()` waits for slots the ring has passed), so it leaves a
+    *permanent* band over a buffer that is all NaN.
+  What its absence looks like, which is why it is written down: a device whose counter counts
+  *samples*, or frames of an inner layer, reports a forward jump on every datagram while the wire
+  delivers on time. Every frame then reserves, and with `relative_time` every frame books NaN
+  slots by construction -- one band over the whole window with the samples washed out,
+  `backfilled=0` (no packet was ever missing, so nothing can repair it), and the status bar reading
+  `live` at the right rate the whole time. The refusal is counted in `StreamStats::gaps_refused`
+  and said once per connection with the numbers, because the status bar's `gaps` climbs either way
+  and the state is otherwise invisible; `tools/mock_udpstreamer.py --counter-step N` is the mock
+  shape (its counter is otherwise always +1, so this is the one wire shape it could not produce),
+  and `gaps_refused` rising while `nan_slots` stays 0 is the reading. A refused gap is not a silent
+  one: the timeline is not stretched over loss that did not happen, so it shows as the x
+  discontinuity it is.
+- **A re-plan drops every hole and restarts the producer's tick.** `rebuild_locked()` replaces
+    the store, so `produced()` restarts at 0 and a hole's `slot_begin`/`tick_begin`/`x_begin`
+    describe a buffer that is gone; it therefore clears `holes_` and bumps
+    `ScopeModel::plan_generation()`, which the producer compares against the value it last saw
+    and resets `tick_` on. That is what keeps `tick_ / period == produced()`, the relation
+    `backfill_from()` derives a slot index from — without it the amend falls outside the ring
+    and repairs nothing while the hole is still marked repaired, a band saying the opposite of
+    the truth. The generation is the signal and the stride/channel-count comparison is not: a
+    reconnect with an identical CONFIG rebuilds the store leaving both unchanged.
+- **The relative clock is accumulated in *seconds*, and a frame is only stamped into a model that has a
+  streamed channel.** Relative time's stamp is the declared interval counted from the stream's own
+  origin — `Acquisition::rel_base_s_`, which is advanced by the frame's own samples and by the samples a
+  reported gap spans. It is deliberately **not** `position × Partition::base_dt`, and the difference is
+  one defect: a plan is rebuilt whenever the channel list changes (a CONFIG, an enable/disable, a
+  session's math channels), and `base_dt` is the **1 kHz fallback** until a *streamed* channel declares a
+  rate. Recomputing from a position made a plan that *shortened* the interval put every later stamp
+  behind the one already written, and the frame loop's monotonic clamp then held the clock there for the
+  rest of the run. What that looks like: `ring=[a..a]` standing still while `n` climbs,
+  `history` never reaching the pre-window (so a trigger never latches and the display stays in `Waiting`,
+  which is blank), and — the reading that names it — `[udpscope] warning: the clock stalled ...`, printed
+  once per connection the first time a whole frame's stamps are all behind the clock. Accumulated, a plan
+  change is only a slope change and the clock cannot go backwards. The entry is the *other* half: the
+  ingest used to accept a frame as soon as `channels()` was non-empty, and a session's math channel
+  applied before the stream's own signals arrive is exactly one channel with a fallback plan. Such a
+  frame has nowhere to go (the value loop skips every derived channel) and its plan's interval is not the
+  stream's rate, so `on_data()` now requires a **streamed** channel and drops the frame otherwise, the
+  same way it always did for an empty list. `rel_base_s_` is **not** reset across a reconnect — the
+  origin survives, it is relative mode's clock origin — while `base_dt`'s *use* is what this rule took
+  away: it is read to *advance* the clock, never to recompute where the clock already was.
+- **The stream's epoch is adopted *once per connection*, and "unset" is a state, not the value zero.**
+  `epoch` is the stream time the display's x = 0 means, taken from the first frame's stamp. The test for
+  "not adopted yet" used to be `model.epoch() == 0.0`, which relative mode breaks by construction: its
+  first frame is stamped exactly `0`, so the *second* frame adopted the origin — and with
+  `rel = max(stamp - epoch, last_stamp_)` that put a whole frame's samples on one stamp and shifted every
+  later x by a frame's span. `Acquisition::epoch_adopted_` is the flag, re-armed by
+  `reset_session_state()` because a new session's clock is a new clock; the warning line above is what
+  caught it.
+
+- **A dropped time slot is clamped, never answered with a sentinel.** `acquire()` pins
+  the published window to the value ring's base and both rings keep sliding afterwards —
+  their capacities are equal, so there is no slack — which means the oldest few samples
+  of a saturated window routinely point at time slots the producer has already
+  overwritten. `ChannelBuffer::time_of()` therefore clamps to the oldest *readable*
+  slot: a stamp of `0` would reach `x_bounds()`, and from there `dx()` and `x0()`, which
+  is the renderer's whole index mapping — one unreadable slot inflated `dx()` by the
+  ratio of elapsed stream time to the retained window and clipped the older part of
+  every live view. The library's `StreamSeries` is immune for a reason worth copying:
+  its x is `x0 + i*dx`, a function of the absolute index, so an overwritten slot costs a
+  *y* value, never the geometry. Clamping buys the same bargain here.
+- **The window's *first* stamp is cached by `acquire()` and never read at paint time.** The
+  clamp above makes an unreadable slot *survivable*; it does not make reading it *safe*, and
+  `absolute(0)` is not an ordinary slot — `acquire()` pins the window to `values_->base()`, so
+  sample 0 is the ring's oldest, the very slot the producer is about to overwrite. `time_of()`
+  checks the bounds and then copies, and when the producer laps the slot in between the stamp it
+  returns is **one whole ring-span too new**. Everything else on a `ChannelBuffer` is read at
+  paint time with no lock, and `x0()` *was* the origin the renderer reconstructed every trace
+  point from (`gather[i] + series.x0()`), read both inside its increasing-suffix filter and again
+  at `stage_xy()` — so one torn read of that one slot produced three pictures, all of them "the
+  waveform is gone while the grid and the axes stay": `neighbours()` tests against `x_at(0)` and
+  refused the whole visible range (the renderer then gathered the *entire* ring at a coarse level
+  and drew it off the axis — `idx=[0..8388608) level=7 cover=320%`); `x0()` changing *during* the
+  filter loop dropped three quarters of the points; and `stage_xy()` shifted the finished polyline
+  a ring-span off its axis. The gather origin is the *view's* minimum now (see the `gather()`
+  invariant), a local of the renderer's, so the second and third of those are structurally
+  impossible — but **the first is not**, `x_at(0)` is still what `neighbours()` tests the visible
+  range against, and that is the one that gathered the whole ring. The cache is load-bearing for
+  that reason; do not read the slot at paint time because two of its three symptoms are gone.
+  That is the "with measurements and cursors active the plot flickers as
+  if there were no data, at no constant frequency" defect. It is **live only** (a snapshot is
+  immutable, so `x0()` is constant for `Held`/`Paused`), it is a race against packet arrival so it
+  is irregular, and the measurements pane makes it both likelier and larger: the pane holds
+  `mutex()` for each `MeasureWindowReader`'s life, so the released producer bursts several packets
+  at once. `acquire()` runs on the consumer under `ScopeModel::mutex()` — the same lock the
+  producer's pushes hold — and the window is pinned on the line above, so that is the one point in
+  the object's life where the slot is safe to read; `window_x0_` is also the *right* answer rather
+  than merely a stable one (it is the stamp sample `window_base` actually carries, where a
+  paint-time clamp answered with whatever slot happened to be oldest *now*). `x_at(0)` is served
+  from it too, for the same reason, and `invalidate()` clears it with the window. The guard is
+  `trace ink:` / `[ink]` (see [probe-readings.md](probe-readings.md)). The same torn read still exists for a small `i > 0`
+  — the oldest frame or so of samples — but there its observable is a *prefix plateau*, which is
+  exactly what the renderer's increasing-suffix filter was written to absorb, so it is a different
+  symptom and deliberately not fixed here.
+
+## The packet capture sits at `recv()`, and its file is reserved, not sparse
+
+Every wire behaviour a forensic capture exists to answer — a counter that skips, a datagram that
+arrives twice, a fragment that never completes, a CONFIG whose header does not parse — is
+invisible by the time a `udps_frame_t` reaches `Acquisition::on_data`: the client has already
+validated, reassembled, resequenced and dropped. The capture therefore hooks
+`udps_client_set_datagram_cb()`, which the client fires immediately after the UDP `recv()`
+returns and before anything reads out of `rxbuf`, and it stores the bytes without interpreting
+them. The capture is of the *UDP socket*: in multicast mode CONFIG arrives over TCP and is out
+of reach.
+
+The ring file is reserved with `posix_fallocate` rather than left sparse because the stores are
+`memcpy`s into an `mmap`: a store into a page the filesystem cannot back raises **SIGBUS**, which
+kills udpscope outright. An out-of-space condition has to be an error at the moment the user
+toggles — reported in the popover row, the button back off — not a crash ten minutes into the
+run the capture was switched on for. Within the reserved file, a slot's trailing `seq` word is
+published with a release store *after* its bytes are down, so a slot carrying a non-zero `seq`
+is complete and no `fsync` is needed for the file to be readable after a crash: the kernel's
+dirty pages are the file, and a half-copied slot still reads `seq == 0`.
+
+## A reconnect with an unchanged CONFIG keeps the buffer
+
+A disconnect -- EMI makes it a silence timeout, not a polite DISCONNECT -- must not cost the
+acquisition. What historically did was the reconnect's CONFIG: `ScopeModel::set_signals()` rebuilt
+the store on *every* CONFIG, and a rebuild is what drops history, resets `tick_`, retires the
+holes and invalidates a held event. Now the incoming CONFIG is compared against the stream the
+model already has -- names, shapes, rates, ranges, time modes, time-signal indices -- and an
+**identical CONFIG returns early**: the ring keeps its history, the trigger keeps its state and
+its held event, and the outage shows as the gap in the data that it was. Only a CONFIG that
+*changes* the stream re-plans.
+
+The producer's own state is per *connection*, and carrying it across a drop makes recovery read
+as failure: `Acquisition::reset_session_state()` (on DISCONNECTED, and again on the next CONFIG)
+clears the counter mark, the stream-time anchor and the smoothed arrival interval, so the first
+frame of the new session re-anchors instead of reading as late, as a glitch or as an outage. The
+arrival clock's *anchor* deliberately stays -- stamps are small seconds the ring's timeline is
+already scaled against, and re-anchoring mid-stream would move x. The clock *choice* is re-derived
+per connection (`time_source_ = 0` on CONFIG) for the same reason: a session that dropped may
+come back with a different answer.
+
+Relative time's clock (`Acquisition::rel_base_s_`, seconds accumulated at the declared interval)
+also survives: it is the user's chosen origin, and must not jump backwards because the link blipped.
+
+## There may be no store at all
+
+`rebuild_locked()` calls `store_.reset()` for a stream with **no channels** — the model's state until the
+first CONFIG arrives — so `store_` is legitimately null, and `ScopeModel::live()` dereferences it. Every
+path reachable without a stream has to ask first: **pausing a scope that is not connected** is one (the
+button works, and freezing a view means taking a window from the rings), and it crashed inside
+`live_window_locked()` on a null store. The guards belong at the entry points the UI can reach
+(`live_window_locked()`, `publish_pause_view()`), not in `live()`, which cannot express "nothing there"
+through a reference. The paths that only run for a *bound* trace — the series' gather, the SlotSeries'
+`shared_channel()` — are safe by construction: a slot with no channel binds no series at all.
+`UDPSCOPE_PROBE_PAUSE_MS` against a port nothing is listening on is the check.
+
+## A waveform is a source that never arrives
+
+`--open FILE` (and the chooser's Waveforms page) puts an exported `.npy` into the model instead of a
+stream: one signal and channel per column, the samples pushed through `push_loaded_slot()` — the
+producer's own order (values, the shared clock, the absolute clock, then the derived channels), under
+the model's lock — and the display epoch pinned to the file's last stamp so the axis reads
+`[-window, 0]` exactly as the export did. Everything downstream is unchanged, which is the point:
+cursors, measurements, math channels and another export work on a file because they work on the
+rings, not on the wire.
+
+Three things follow, and each is a place the live assumptions would otherwise leak:
+
+- **Nothing is ever starved.** There is no socket and no source, so the starvation notice is skipped
+  while a waveform is open, and the popover's Stream row names the file rather than reporting a
+  connection that has not answered.
+- **The loader must not hold the model's mutex.** Every setter it needs (`set_signals`,
+  `set_signal_enabled`, `set_target_span`) takes that same non-recursive lock; the first version
+  wrapped the whole load in it and deadlocked on the first call. The per-slot push is a model method
+  for the same reason.
+- **The signal names come from the file.** A `.npy` written by `write_npy()` is a structured array
+  whose dtype names its fields, so an export is self-describing and there is no sidecar to lose.
+  `.csv` is not read: it carries the names too, but as text, and the item asked for the binary one.
+- **A waveform has no source, and the app must not invent one.** The address the command line
+  *defaults* to (`127.0.0.1:8000`) is not one: leaving it in place made a file-mode run load — and
+  then *save* — that source's session, which overwrote the arrangement the file was opened with
+  (every drop then refused, the row full) and could clobber a real session. `App::source_port` is 0
+  in file mode, which is what makes `save_layout_now()` refuse and the first-CONFIG layout load skip
+  — the same two things that make a source-less run safe.
+- **One row per column.** Four columns to one row fills the default single row and then refuses
+  every drop ("plot 1 already holds four signals"), which is a loaded file the user cannot plot
+  anything *else* on or rearrange. One per row (sized in `main.cpp`, before the UI exists, as
+  `--plots` does) leaves three free slots each, shows a four-signal file as four stacked traces, and
+  keeps the rest of the columns draggable. Sizing the rows from inside the activation instead leaves
+  the panels built for the old count and the app hangs on the first relayout.

docs/claude/invariants-gtk-and-chrome.md

@@ -0,0 +1,670 @@
+# 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::<prop>` 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 *tab* of the sidebar, 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's **tabs have no icons any more**: two 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 are 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"`, `"<Control>e"`, `"<Control>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:<document>` 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<void(bool ok, const std::string& error)>`)
+  — 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/<id>/` holds
+  `index.page`, one `<topic>.page` per subject, and the `figures/*.png` the pages link, and the
+  whole set is installed (the `install()` rule in CMakeLists) to `<datadir>/help/C/<id>/` — the
+  path the freedesktop Help System Specification's `help:` URI resolves `help:<id>` 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:<id>` 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/<lang>/<id>/` then `$XDG_DATA_DIRS/help/<lang>/<id>/` 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 `<media>` 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/<id>/<topic>.page` works; the same set under
+  `~/.local/share/help` does not. Two genuine defects were chased and fixed before the location
+  was found — a `<figure>` with no `<desc>` 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 a tab stack now, and has no `GtkRevealer` left in it**: an `AdwViewSwitcher`
+  above an `AdwViewStack`, each page a `GtkScrolledWindow` of its own (the two pages are different
+  heights, so one shared scroller would leave a switch scrolled where the new page never asked to
+  be). The reason is the one this trap teaches: five sections competing for one 320 px column left
+  every one of them short of room. 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 stack's hidden page measures 0x0 too and is still
+  given the leftover width, so **ask about state, not about size** carries over unchanged. Every
+  allocation read in the sidebar is a debug capture, and each reads 0 on the page that is *not*
+  current -- a change in what the reading means, not a defect, and no functional code may depend on
+  those numbers.
+- **The sidebar's tabs are text: `AdwViewSwitcherPolicy.wide`, a title on every page, no icon.** The
+  built-in pages get their titles in the `.ui` and a source kind's pages from `SourcePanel::title`
+  (`adw_view_stack_add_titled`); the page's *name* still identifies it to `select_side_tab()` and the
+  session file. An icon-only version existed (policy `narrow`, empty titles, the pills named in code by
+  `name_side_tabs()`, because `narrow` still draws a label beside an icon); it was reversed because the
+  glyphs were not understandable. A page added with an empty title is a blank pill, and
+  `switcher: … pills=N labels=N images=0 pages=N` reads it as `labels` below `pills`. **No icon at all**
+  is not what "no `icon-name`" gives you: `AdwViewSwitcherButton` always builds a `GtkImage` and falls
+  back to `image-missing` (the `[x]` placeholder, which also squeezed the title to "Meas..."), and no
+  property turns it off. `keep_tabs_icon_free()` (`src/ui_source.cpp`) hides every image in the switcher,
+  re-hides one that is shown again, and re-runs on the stack's `items-changed` (connected *after* the
+  switcher's own, so the new button exists) and on the switcher's `map`; `images=0` is the reading.
+- **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 switcher 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
+  (`<property name="icon">foo</property>` 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 `<child>`, 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 <file>` 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.
+- **`<child type="end">` 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 `<child>` 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 `<child>`, 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.

docs/claude/invariants-math-channels.md

@@ -0,0 +1,355 @@
+# Invariants: the math channels and the node editor
+
+A derived channel is an ordinary channel; the engine runs on the producer thread, so its cost is measured in packets.
+
+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.
+
+- **A math channel *is* a channel.** `ScopeModel::set_math_channels()` appends one *synthetic*
+  `SignalInfo` (with `math = true`) per math channel after the stream's own, so the panel's switch,
+  the plot binding, the measurements and the export all handle a derived channel without knowing it
+  is derived -- and another math channel is a valid `Source` for exactly the same reason. The
+  *samples* come from the producer: `Acquisition::on_data()` collects each channel's value for the
+  slot and calls `ScopeModel::push_math_sample()` **once per stored slot**, before the deferred
+  latch (`publish_event()` clamps its snapshot to every ring's `produced()`, so a derived sample
+  pushed later would be missing from the capture's newest slot). The math therefore runs on the
+  *stored* (filtered, decimated) samples, which is also why `math_prepare()` gets `slot_dt() *
+  time_stride`: a cutoff the user typed in Hz means the rate the filter will actually run at.
+  `src/math_channel.cpp` is the engine: a graph evaluated as a **list walked in order**, so a node
+  may only read ones *before* it and a cycle is impossible by construction rather than by a check
+  (`math_channel_valid()` states that as a message the dialog shows). `/tmp/check_math.cpp`-style
+  checks verified the biquads against known responses (LP fc=100 Hz: 50 Hz -> 0.97, 2 kHz -> 0.002;
+  BP fc=1 kHz q=2: 200 Hz -> 0.05, 1 kHz -> 0.95, 4 kHz -> 0.05) -- **keep test sines below
+  Nyquist**: at `dt = 1/10000` a "5 kHz" test tone is the Nyquist point itself and says nothing.
+  The editor is the *compact graph*: nodes as boxes on a `GtkDrawingArea`, click to select (its
+  parameters in the form beside it), **drag from an output port to an input port to wire** (the old
+  two-click protocol is gone), drag a box to move it; **wheel zooms about the pointer, background
+  drag pans, `f` fits, `Ctrl+0` resets**.
+  Its widgets are created once and only shown, hidden and set by `math_dialog_sync()`, so no rebuild
+  can invalidate a live callback handle -- the same shape the measurements dialog uses.
+  `UDPSCOPE_PROBE_MATH_MS` defines three graphs -- the third a `Source` of the first channel into a
+  `DeNoise` node, so the editor's median row is built and synced on a baseline run -- and opens the
+  editor (a construction crash test as much as a state check), and the dump prints each derived
+  channel's extremes beside the source's. Read it on the fast mock, where the two assertions that matter are **`gaps=0`** (the
+  math is on the producer thread, so what it can break is packet capture, never the frame rate)
+  and each `math '<name>': ... N samples vs M time slots` being **equal**, with `math x2` at
+  `y=[-2, 2]`, `math lp` at `y=[-0.998, 0.998]` and `math3` at `y=[-2, 2]`. The `0 visible
+  (order breaks 0, first at -1), y=[0, 0]` tail of that line is **not** a failure: it is
+  `visible_samples()` reading row 0's axis after the window was destroyed, and
+  `UDPSCOPE_EXIT_AFTER_MS` arms the trigger first, so the dump can land in `Waiting`. The live
+  `ch N '<name>' ... y=[..]` lines are the race-free reading of the same thing.
+- **A file view has no producer, so a structural change would leave it empty.** `set_math_channels()`
+  rebuilds the channels *and* the buffer, and a rebuild drops the history: right for a stream, whose producer
+  refills it from the next packet, and wrong for a file, which has nothing to refill it with. Adding a math
+  channel to an open waveform therefore emptied *every* channel -- `samples=0` on the sources too, which a user
+  reads as "the plot is broken" -- and the same emptiness follows any structural change in a file view.
+  `reload_file_view()` (in `ui.cpp`) re-reads the file after such a change, which is also what computes the
+  derived channels over it: the load's own pushes run the math once the set is in place. It fires only when the
+  buffer was *really* dropped -- `stored_slots() > 0` means the change found nothing to do -- and it says so
+  on stderr (`reloaded <path> after a structural change`), because a second read of a file is worth
+  accounting for. `set_math_channels()` in turn treats an identical list as no change at all, so a no-op
+  application (the session apply, a re-open) neither rebuilds nor drops nor re-reads; the comparison leaves the
+  nodes' `x`/`y` out on purpose, since those are the canvas's own and no op reads them -- a graph that only
+  *moved* is not a change, and rebuilding for it would drop the buffer to store two numbers. It is why `--open`
+  works at all with a session that defines math channels, since `main()` loads the file *before* the UI (and
+  so before the session's graphs) exists.
+- **Every path that fills a store must skip a derived channel, not just the packet path.**
+  `ChannelInfo::math` states the rule for the ingest; `push_loaded_slot()` broke it, so loading a file pushed
+  its own value into each derived ring and `push_math_sample()` then pushed the computed one: two samples per
+  slot, i.e. a trace at double rate. The reading that catches it is the one already in this file --
+  `math '<name>': N samples vs M time slots` must be **equal** -- and a file view now has to be read as well
+  as a live one (`--open <the file>` with `UDPSCOPE_PROBE_MATH_MS`). An export writes every *plotted* channel,
+  so a file carries the derived ones as ordinary columns: those are real channels and are filled normally,
+  which is why the fix is in the push and not in the loader.
+  `math cost: S slots, N ns/slot (T timed), X ms total est` is the per-slot cost; see the
+  math-cost invariant below for why it is sampled, why it is an upper bound, and why a figure
+  anywhere in 78--101 ns/slot is one reading of the same thing; the three-graph run reads **103**, the
+  de-noise channel's per-sample median being the difference.
+  The probe also asserts the new editor mechanics. `dialog build:` reads the identity row back as well --
+`name='math3' unit=''` -- which is the pair the `.ui` holds the widgets for and the code fills from the
+channel being edited, so a row that stopped being the one the code writes shows there.
+`editor frame:` is the same idea one level down: it reads the canvas's allocation, whether that canvas is
+*mapped*, and whether the canvas and the name entry are inside the dialog at all -- delayed by 500 ms, because
+an allocation only exists after a layout. A canvas that is visible but parentless never maps and stays `0x0`,
+and reading values off the widgets *inside* the editor cannot see that. It is the reading that catches
+`math_body` written as a child of the window instead of the box above it. Each line carries
+`(want ...)` and the reading
+  taken from a real run is the reference:
+  * `[math-probe] hit: inside node=0 which=-1, past-edge node=0 which=-1 (want 0 -1 0 -1)` — the
+    output square straddles the box edge, so a hit test that recovers the node by a box test misses
+    every pixel past it. `past-edge node=-1` is the silent disarm that was "edges cannot be added".
+  * `[math-probe] cancel: dialog=cleared (want cleared)` — Cancel must `gtk_window_close()`, not
+    `gtk_window_destroy()`. The probe clicks the **button**, because the defect was in the button's
+    connection and a direct handler call cannot see it.
+  * `[math-probe] view: zoom scale=1.210 anchor kept dx=0.0000 dy=0.0000 (want 0.0000 0.0000)` —
+    a wheel zoom that does not keep the graph point under the pointer reads as the canvas sliding
+    away from the hand. Both deltas must be `0.0000`.
+  * `[math-probe] view: pan+zoom hit node=0 which=-1 (want 0 -1)` — hit tests go through
+    `math_to_graph()`. At the identity view a test that forgot the inverse passes anyway, so this
+    one is taken after a pan *and* a zoom.
+  * `[math-probe] view: fit scale=1.591 all_inside=1 (want 1)` and
+    `[math-probe] view: reset scale=1.000 offset=(0.0,0.0) (want 1.000 (0.0,0.0))`.
+  * `[math-probe] view: pan mode=3 dview=30.0 dnode=0.0 (want 3 30.0 0.0)` — a background drag
+    pans the view and moves no node.
+  * `[math-probe] wire: connect mode=2 in_a=0 (want 2 0)`,
+    `[math-probe] detach: emptied_at_begin=-1 in_a=-1 (want -1 -1)`,
+    `[math-probe] detach: escape restores in_a=0 (want 0)`.
+  * `[math-probe] wire: pick node=1 which=0 -> in_a=-1 off_sample=8.4 tol=3.0 (want 1 0 -1,
+    off_sample > tol)` — the pick is taken at `t = 0.52`, **between** samples 12 and 13 of the 24 the
+    curve is walked at, on a wire whose two boxes are several rows apart. `off_sample` is the measured
+    distance from the pick to the nearest sample point and `tol` the pick radius in the same units:
+    with `off_sample` the larger, a hit test that measured to the sample *points* rather than to the
+    *segments* between them would miss. Taken at `t = 0.5` — exactly sample 12 — the line passed for
+    both implementations and asserted nothing, the same mistake as a hit test taken at the identity
+    view.
+  * `[math-probe] wire: backwards ok=1 order=[0:-1,1:0,2:1] output=2 valid=1 why=[] (want 1 ... 1 [])` —
+    the re-sort. `valid=1` is the assertion; the `order=` string is the reading that explains it.
+  * `[math-probe] wire: self refused=1 why=[a node cannot read itself]` and
+    `[math-probe] wire: cycle refused=1 why=[that wire would make a loop]` — and **nothing is
+    written** on either. Both call `math_connect()` directly, so both assert its out-parameter and
+    neither says anything about the UI.
+  * `[math-probe] wire: self through drag-end node=1 problem=[a node cannot read itself] (want the
+    refusal text, not empty)` — the other half, and the one that matters: the refusal has to reach
+    the **validation line**. The UI path used to screen the self case out before `math_connect()` and
+    then drop its `why` on the floor, so the user drew a wire, nothing appeared and nothing was said
+    while the two lines above passed. No synthetic GTK gesture is reachable headlessly, so the probe
+    sets `drag_mode`/`wire_from`/`press_cx`/`press_cy` and calls `math_canvas_drag_end()` — which is
+    still the handler under test. An empty `problem=[]` here is also how the sync **re-entrancy** was
+    found: setting the op dropdown emits `notify::selected`, whose handler syncs, so the form's own
+    write re-entered `math_dialog_sync()` and the inner call rewrote the label the outer had just
+    written. `MathDialog::syncing` guards it.
+  * `[math-probe] validate: broken problem=[..] label=[..] apply=0; fixed problem=[] apply=1 (want non-empty 0; empty 1)`,
+    `[math-probe] validate: no-selection label=[..] (want non-empty)` — the label is written
+    **above** `math_dialog_sync()`'s early return; a stale message when there is no selection to
+    show is the failure mode.
+  * `[math-probe] validate: source list=6 acquired=6 signals=7 (want list==acquired)` — the
+    dropdown lists exactly the acquired channels, not all signals.
+  * `[math-probe] op pick: nodes 3->4 op_index=7 q_row=1 (want 4 7 1)` and
+    `[math-probe] op pick: index round trip=1 (want 1)`.
+  * `[math-probe] add node: after a delete cells=[(24,20) (24,78) (184,78) (184,20)] overlaps=0
+    (want 0)` — the boxes are put back on the grid, the middle one deleted and one added. The new box
+    takes cell 1, `(184,20)`, which the deletion freed; placing by `nodes.size()` would have put it on
+    `(184,78)`, which is occupied, and an overlapped box is an unclickable one. `overlaps` is the
+    assertion, `cells` the reading that explains it.
+  * `[math-probe] tidy: xs=[24,24,204,384] overlaps=0 (want 0)` — four nodes in three depth columns
+    (the delete above left two roots), so two share the first column and the x values repeat. Only
+    `overlaps=0` is the assertion.
+  Four rules here were wrong first and are worth keeping:
+  * **A `Source` may only name an *acquired* channel** -- `ScopeModel::channels()`, which is what the
+    dialog's dropdown lists, **and both places that create a node must take one from there**.
+    `signals().front()` is the stream's *timestamp* signal: it is first in every CONFIG, it is not
+    acquired, and a graph sourced from it validates and then reads NaN for ever. The dialog's
+    default was fixed first and the pane's `+` was not, which is what "[ch] -> [gain x2] produces
+    only nan" was. The dropdown also *reconciles*: a node whose source is not in the list is moved
+    to what the form is showing, rather than the form showing one channel while the node holds
+    another, and while a source that is not acquired is in the graph the **live validation line is
+    non-empty and Apply is insensitive** (the engine's validator is about the graph -- an output,
+    every input wired above it -- and cannot see the acquired list).
+  * **The ingest must skip a derived channel.** `Acquisition::on_data()` iterates every channel and
+    reads each one from the packet, so a math channel with no signal read *zero* and pushed it --
+    while `push_math_sample()` pushed the real value on the same slot. Two pushes per slot into a
+    ring whose time ring advances once: the values alternated between the real one and 0, and once
+    both rings wrapped the value ring had drifted a whole window off the time ring, so the derived
+    trace disappeared. `ChannelInfo::math` is the flag (`channel.math`) and the loop `continue`s on
+    it. **A derived channel's `values(c).produced()` must equal `live().time().produced()`** -- one
+    push per stored slot -- and the dump prints both as `N samples vs M time slots` for exactly
+    this: the arithmetic on the plot can look plausible long after the pairing is wrong.
+  * **`gtk_window_destroy()` does not emit `close-request`.** The math dialog's pointer is cleared
+    by a `close-request` handler, so a Cancel that *destroyed* the window left `app.math_dialog`
+    pointing at a dead widget: every later `open_math_dialog()` took the "already open" branch and
+    presented it -- a GTK critical, and nothing on screen, which is "I cannot edit a math channel
+    again". Both paths close (`gtk_window_close()`), which emits the signal, lets the handler clear
+    the pointer, and then destroys. The same lesson as the other GTK traps here: a programmatic
+    destroy is not a user close, and only one of them runs the handlers.
+  * **Boxes must not overlap on the canvas.** The first auto-place staggered nodes by 24 px for a
+    132 px box, so every box sat on the one before it, `math_node_at()`'s topmost-first search always
+    returned the last, and a drag or a click landed on the wrong node -- which reads as the dialog
+    ignoring the pointer. The **add-node grid** places in two columns spaced 160 px apart, rows 58,
+    and `math_add_node()` takes the **first free cell** rather than cell `nodes.size()`: placing by
+    the count reuses an occupied cell as soon as anything has been deleted — delete the middle of
+    three and add one and the new box lands exactly on an existing one. The free-cell search uses the
+    same overlap test the tidy probe asserts with, and falls through to cell `nodes.size()` after 64
+    cells rather than searching for ever. The **tidy layout** uses a column pitch of `kNodeW + 48` =
+    180, which is *wider* than that 160 and is what gives a wire's 40-unit horizontal tread its
+    clearance — at 160 the bezier's control points cross and the wire doubles back on itself. The
+    probe prints the box the drag *began over* for exactly this reason.
+    Offering the whole signal list let a graph name something nobody is acquiring (no data for ever)
+    and put the stream's timestamp signal, which has no samples, in it.
+  * **`prepare_math_locked()` runs from `rebuild_locked()`, so *every* plan change re-prepares the
+    filters**: a CONFIG, an enable/disable, and a window change that moves the decimation (that path
+    is `set_target_span()` -> `rebuild_locked()`). Coefficients are a function of the *stored*
+    interval and the filter's state is the old rate's history, so both are rebuilt together.
+    Preparing only on an edit left the cutoff wrong and the state ringing after any window change --
+    that is what "I tested a low pass and it was a mess" was.
+  * **The graph's output defaults to the *last* node, and a node added to a linear graph becomes
+    it.** The output began at index 0 -- the *source* -- so every operation a user built was
+    computed and then thrown away: a gain of 2 and a low pass both produced a channel equal to its
+    input. The output is drawn as the orange dot and settable explicitly, so an earlier node chosen
+    deliberately is kept; this is the default for a graph that has never been given a choice.
+  * **`gtk_spin_button_new_with_range()` can leave the value at the range's *minimum*.** The offset
+    field began at -1e6, and `on_math_param_changed()` reads the widgets, so `x*2` saved as
+    `x*2 - 2000000`. Every numeric field is seeded with its own identity value; the range-minimum
+    default is never a useful starting point for a gain or a corner frequency.
+  * **The form's rows are grouped per *op*, not per field**: gain and offset are one group because
+    `gain + offset` is one op. The offset was a row of its own that nothing ever hid, which read as
+    a property of every node.
+  * **A `GtkSpinButton` holds zero decimals by default**, so every numeric field sets its digits
+    (4 for gain/offset/clamp, 3 for `fc`/`Q`); without that a 12.5 Hz cutoff was stored as 12 and a
+    gain of 0.25 as 0. And the canvas drag reports the *total* offset from where the gesture began,
+    so adding each update's delta to a value the handler then writes back is a runaway box -- it
+    must record the position at `drag-begin` and ignore a drag that did not begin on a box.
+  * **A port hit must name its own node.** The output square is drawn centred on `n.x + kNodeW`,
+    straddling the box's right edge, with a `±kPort` hit radius against a `±kPort*0.5` drawn
+    half-width — so recovering the node with `math_node_at()`, which matches only inside the box,
+    returns `-1` for every pixel past the edge. `math_port_at()` returns the node directly for
+    that reason.
+  * **Every hit test goes through `math_to_graph()`, and every tolerance is a screen distance
+    divided by `view_scale`.** A tolerance left in graph units makes a port unhittable zoomed out
+    and greedy zoomed in. **A probe that tests a hit at the identity view asserts nothing** — the
+    check has to be taken after a pan and a zoom.
+  * **A drag's mode is decided once, at `drag-begin`, and the precedence is port, box, background.**
+    Asking the box first makes the output square unreachable, which is the same geometry as the
+    bullet above.
+  * **A detach empties the input at `drag-begin`.** That is what makes a release over nothing the
+    detach gesture rather than a second verb, and it is why `Escape` has something to restore.
+  * **A backwards wire re-sorts the list; it is not refused.** The evaluator walks the nodes in
+    order, and until now that made the order the *user's* problem — an earlier node's input was not
+    even drawn as connectable. `math_connect()` runs Kahn's algorithm over the **trial** edge set,
+    so a cycle is found before anything is written, breaks ties by the current list index so a graph
+    already in order is not permuted, and remaps **`output`, `selected`, every `in_a`/`in_b`,
+    `drag_node`, `wire_from`, `wire_detach` and `selected_wire.node`** in one block. A missed index
+    silently renames an operation or re-points a wire. Its `edges_of` masks each input by the op's
+    **arity**: a node changed from binary to unary keeps a stale `in_b`, and counting it makes an
+    indegree that never reaches zero and so reports a loop that is not there.
+  * **The validation line is written above `math_dialog_sync()`'s early return.** An out-of-range
+    selection is exactly the state in which a stale message misleads most: the graph can still be
+    broken and there is no form to read instead.
+  * **The line is written from `math_dialog_sync()` and from nowhere else, it ellipsizes, and its
+    tooltip carries the full text.** Three consequences. (1) A *refusal* — "a node cannot read
+    itself", a cycle — is not a state `math_dialog_problem()` can describe, since it is a thing that
+    did not happen, so `drag-end` leaves it on `MathDialog::refusal`, which the sync shows in
+    preference to the graph's own problem and **consumes as it writes**: the message lasts until the
+    next sync, and every mutation syncs. `Apply`'s sensitivity still follows the graph alone, because
+    a refused wire wrote nothing. (2) The label **ellipsizes rather than wraps**, and the tooltip is
+    set beside the text so the two cannot disagree — layout must not depend on content, and this
+    label sits in a dialog whose canvas is `hexpand`. (3) The sync is **not re-entrant**
+    (`MathDialog::syncing`): writing the op dropdown emits `notify::selected`, whose handler syncs,
+    and the inner call rewrote the label the outer one had just written.
+  * **`math_op_index()`, never a cast.** `math_op_at()`'s order is the dialog's — what a dropdown
+    lists and what a session file stores — and `static_cast<guint>(op)` worked only because the
+    two happen to agree today. The session-file rule in this file already says an op is written as
+    its index through `math_op_at()`; this is the other direction of the same rule.
+  * **A `Delete` key removes the selected *wire* and never falls through to the selected node.**
+    A key whose target depends on an invisible selection state is how a graph gets destroyed by
+    accident; the `delete node` button stays the only way to remove a node.
+- **`MathOp` is append-only, because `math_op_at()` *is* the serialisation.** A session stores a node's op
+  as its index through that accessor, so an op inserted in the middle reinterprets every node in every file
+  written before it; `DeNoise` is therefore index 12, after `Div`, and sits last in the dropdown.
+  `math_op_uses_filter()` keeps its meaning of *a biquad* -- `math_op_uses_fc()` is the wider question
+  ("does this op read `fc` at all") and is what the dialog's corner row asks.
+- **The de-noise node's median window is *pooled* in `MathRuntime::median`, not held in `MathNodeRt`**, so a
+  node's state stays on one cache line; nine doubles per node would push every node in the graph, filter or
+  not, across two. `MathNodeRt::med_at` / `::med_n` / `::med_pos` / `::med_have` are that pool's slice,
+  length, write position and fill, and the pool is sized in `math_prepare()`.
+- **Median *then* pole, and the order is the design.** The median kills an impulse outright -- one shorter
+  than half its window cannot move it at all -- and the pole takes the broadband hash it leaves behind. The
+  other order feeds the pole the impulse, which smears it over the pole's whole settling time and leaves the
+  median a wide bump it cannot reject.
+- **The de-noise pole reuses `b0` and `z1`, deliberately.** `math_prepare()` carries `z1` across a
+  re-prepare, so the pole keeps its history through a decimation change exactly as the biquads do -- while the
+  median window starts from rest, the same choice the biquads' `z2` makes. `median_n()` rounds *up* to odd and
+  caps at 9, and it is what enforces the window rather than the dialog: a session file holding 4 or 40 still
+  loads. The cap is what `double sorted[9]` in the step is sized for.
+- **The math channels' cost is the *producer's*, and the instrument must not be part of it.**
+  `push_math_sample()` runs once per stored slot -- up to the wire rate -- so what a regression
+  here looks like is `gaps`, never a frame time. Three things were taken off that path and must
+  not come back: a `std::vector` *local* (a heap allocation and free per slot; it is the member
+  `math_values_`, `assign()`d), a `Source` node's channel resolved **by name** per sample (a
+  linear scan with a `std::string` compare per candidate, per node, per slot, behind a
+  type-erased call -- `math_prepare()` resolves it once into `MathNodeRt::src`, and every rebuild
+  re-prepares), and a **`fetch_add` on the cost counters**. That last one was 20-25 % of the
+  measured figure: a `lock xadd` costs about what a two-node graph's whole arithmetic does, so
+  counting the slots cost more than the work being counted. The counters are producer-written
+  only, so each is a relaxed `store()` of a value already in hand (`math_slot_count_` and
+  friends). Two things about the figure itself:
+  * **It is sampled, one slot in `kMathCostSample`, and it is an upper bound.** A slot's work is
+    the same order as one `clock_gettime`, so the measured slot carries a clock read. Timing a
+    *run* of consecutive slots to amortise that away **is wrong and was tried**: the producer gets
+    its slots a packet at a time, so a run long enough to be worth timing straddles a packet
+    boundary now and then and charges the measured slots the **wait for the next packet**. At 2000
+    samples a packet a 64-slot run crosses one ~3 % of the time, and a ~1.5 ms gap spread over 64
+    slots reported **799 ns/slot against the true ~80**. One slot is always inside one packet.
+  * **78--101 ns/slot is one reading.** Four identical-config runs spread that far, so the per-slot
+    path is at the noise floor of this harness and a micro-optimisation cannot be shown to work
+    here. Converting `MathRuntime` from eight parallel `std::vector<double>` to one array of
+    `MathNodeRt` was measured and bought **nothing** -- at six nodes the whole runtime is
+    L1-resident either way. It was kept for the shape, not for a number; do not expect a cache
+    argument to pay at this size.
+
+## A gap is a gap in a filter's output, never the end of its state
+
+A reserved hole is NaN in the source channel, and a biquad that integrates it poisons `z1`/`z2`
+for ever: every later sample comes out NaN, so a filtered trace died at the first drop and never
+came back. Relative time made it systematic — a counter gap reserves NaN slots by construction,
+where a stream-time gap is often absorbed by the stamps — but EMI caused it in both modes, and
+the reading was unambiguous: the memoryless channels held 95% finite samples while every
+`LowPass`/`HighPass`/`BandPass` channel held `finite=0`.
+
+`biquad_step()` therefore returns NaN **without touching the state words** when its input is not
+finite. The hole stays visible in the filtered trace (the gap is the truth about the data), the
+filter's history remains the last *real* samples it saw, and the trace resumes after the hole
+with at most the transient a re-start costs. The exit dump's `math '<name>': finite=N/M` line is
+the assertion: `finite` must be about `M` minus the hole share, and `finite=0` beside non-zero
+`hole_slots` is this defect returned.
+
+- **A math channel is a row of the *signal* list, under a `MATH` divider, and there is no math pane.**
+  `append_math_signals_locked()` already puts every channel in `signals()`, so the pane was the same
+  list drawn twice; the divider is what the pane uniquely contributed. It is non-selectable and
+  non-activatable -- a heading that highlighted under the pointer would read as a row you can plot --
+  and it carries the `+` that creates a channel, appended even when there are none, because a `+` that
+  waited for a channel to exist could never create the first one. A math row's menu is *Edit graph…*,
+  *Default colour*, *Delete*: no Information and no Calibrate, because calibration is applied at
+  ingest and a derived channel has no stream to describe, and no rename, because the node editor owns
+  a channel's name and unit and a second place to change them would be a second answer to the same
+  question. A row's tick is the channel's own switch and must reach `App::math` -- the copy the
+  session file is written from -- or the list and the file disagree about what "enabled" was.
+- **A graph *edit* does not move the plan; adding or removing a channel does.** The plan is a partition over
+  the channels, so `set_math_channels()` takes a surgical path whenever the *set* is unchanged -- same channels,
+  names and enables: the store is never touched, every other channel keeps its samples **and** its runtimes, and
+  only the edited graphs are prepared again. `math_apply_locked()` computes the whole list on a recompute
+  (the graphs are walked in order, so a channel's inputs must be there) but writes only the channels in the
+  affected mask; the affected set is the edited channels plus whatever *names* them, since one channel's output
+  is another's input. Before this, every edit rebuilt the store and every channel in the window started again,
+  which is the "modifying one expression invalidates all the others" report.
+  `[math-probe] graph edit: stored_slots N -> M` reads it: M must be at least N -- the store keeps filling
+  while the edit runs -- and never 0.
+
+- **A recompute rewrites a ring *in place*, and both of the ring's counters have to survive it.**
+  `recompute_math_locked()` replays the inputs' **retained** window, which begins at the time ring's
+  `base()` and not at zero, so an emptied derived ring is restarted with `clear_to(base)` and never
+  `clear()`. With `clear()` the refill renumbered the channel from 0 and left its `produced()` short by
+  exactly `base` -- and `live_window_locked()` clamps its window against *every* channel's `produced()`,
+  so that one lagging channel answered `n = 0` for the live view, every pause view **and** every trigger
+  capture, until a whole ring of fresh data had gone by. That is the "a math edit freezes acquisition,
+  and the trigger stops firing on a channel that is not even derived" report, and it is **invisible
+  before the ring first wraps** (`base == 0`, where the two numberings coincide), which is why it reads
+  as intermittent and uptime-dependent. The dump's `math '<name>': N samples vs M time slots` is the
+  reading -- both numbers are `produced()`, so a mismatch *is* this defect -- but only on a run whose
+  ring has wrapped: give it a small `--buffer-mb`. `UDPSCOPE_PROBE_MATHWRAP_MS` is the probe that
+  arranges exactly that, and it exists because **`math_probe` structurally cannot** reach this state:
+  every edit that probe makes follows a structural change, which replans the buffer and restarts every
+  ring at absolute 0, where both halves of this are identities.
+  The published window is the second counter. `acquire()` is incremental, so a rewrite that leaves
+  `produced()` where it was publishes **nothing** and the pyramid -- what the renderer and every
+  measurement read -- goes on describing the samples the edit replaced. `ChannelBuffer::republish_from(base)`
+  is what puts it back, and it takes the ring's base rather than 0 because `invalidate()` would make the
+  next `acquire()` walk every absolute index ever produced (an hour at 1 MS/s is 3.6 G appends) to publish
+  one window.
+
+- **A math channel whose source is switched off is switched off with it.** `Source` resolves to a *channel*, so
+  a derived channel cannot be computed from a signal nobody acquires: left enabled it would silently compute
+  nothing, which is what "all math signals depending on it do not compute anymore" looked like from outside.
+  `on_signal_switch()` disables the channels that read that signal -- **transitively**, since one math channel
+  may name another -- through the same path the pane's own switch uses (`MathChannel::enabled` and
+  `apply_math_channels()`), and takes their traces off the plots along with the signal's. The channels that do
+  not read it are untouched: `[enable-all-probe]`'s `math_on=[…]` is the half that reads this. Re-enabling the
+  signal does **not** switch them back on, for the same reason re-enabling does not restore the traces.

docs/claude/invariants-measurements.md

@@ -0,0 +1,339 @@
+# Invariants: the measurements pane
+
+Why the pane is refreshed on a cadence, why neither pass may read its window raw, how a crossing is counted, and which mean over a split is which.
+
+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 measurements pane is refreshed on a cadence, and its cost is the *window's*, not the
+  frame's.** A measurement is a statistic of the visible window and a live view moves that window
+  every frame, so "recompute when the window moves" is "recompute every frame" at O(visible
+  samples) *per measurement*. With the pane holding four measurements over a 4.7M-sample window
+  that measured **13.66 ms of tick mean** (baseline 0.41 ms) and cost the run a third of its
+  frames. Three things fixed it, and all three matter: `update_measures()` recomputes at most
+  every `kMeasureRefreshUs` (100 ms; 400 ms when a pass costs more than `kMeasureHeavyUs`), once
+  when the window settles and once per mode change -- and reading *that* backwards is what made
+  it worse first, 457 recomputes in one run, because a pinned window then recomputed every
+  frame; the window is materialized in bounded chunks (never two whole-window f32 temporaries)
+  and the loop holds it **by reference** (copying both vectors per measurement was 300 MB of
+  memcpy a frame); and `measure_stats()` is one shared pass carrying both extremes with their
+  first positions, the sum and the count, so average/min/max/peak-to-peak need no pass of their
+  own -- `top`/`bottom`/`amplitude` take a second read of that same **bucket** list and never of
+  the window (the flat-level invariant below). **Adding a type must not add a pass** -- that is
+  what `compute_measure()`'s `stats` argument is for.
+  **The window a value is computed over is the *pin* while the view is pinned, and the viewport
+  otherwise.** A pinned view -- a held event, a paused stream, an opened file -- is a *still
+  frame*: the data behind it does not change, so a pan or a zoom only looks closer. Measuring the
+  pin (`RowSet::pinned_range()`, the same accessor `hold_pinned_window()` clamps into, so "what
+  frames this view" has one expression) is what makes a gesture change **no value at all** --
+  and it is decided in `update_measures()`, at the call site, rather than inside
+  `MeasureWindowReader`, because the decision is also *booked*: the window
+  `MeasureWindowReader` is handed is the same one the "it moved" test compares against
+  `App::measure_window`, so a gesture inside the pin spends no recompute either. A reader that
+  chose its own window would leave a pinned view recomputing on every gesture frame for a number
+  that cannot change (457 passes in one run is the shape that mistake took).
+  This test has been wrong in both directions and the reasoning is worth keeping. Suppressing it
+  while held (`moved = ... && !held`) left the pane describing the whole 2 s event
+  (`for=[0.47..2.47]`) while a 50 ms slice of it was on screen; *removing* the exemption was the
+  opposite mistake, and it is the reported "when measuring a still frame (a triggered event, or a
+  paused stream) moving the zoom makes measurements such as average or top change, which should
+  never happen". The two are one question asked of two different windows: **which window is this
+  pane about** (the pin, while pinned) and **has it moved** (asked of that window in every mode).
+  Answers: a pinned view still recomputes when it should -- a fresh latch, a re-stated pin, a new
+  snapshot, the held/live change -- and a settled one satisfies `swin == measure_window` exactly
+  and so reads `moved == false` on its own.
+  `[measurepin-probe]` is the reading: on a latched event zoomed to a quarter of itself,
+  `same=4/4 for_same=1 pass_delta=0` with the values bit-identical and `for=` still at the pin;
+  the same on a pause taken from a held event. Live is the case that must **not** be swallowed,
+  and it reads `same=0/4 for_same=0` with a positive `pass_delta`, `span_before=2.000000`,
+  `span_after=0.125000` and `follows=1` -- the results window narrowed with the viewport and the
+  values moved with it. The
+  one path that is *not* this rule is the window control: `apply_time_window()` unpins
+  (`set_time_window()` clears `pinned_`), so for the frames before the held branch re-states the
+  pin the view really is live-framed and the pane measures the viewport -- `[measure-trace]`
+  prints `pin=off` for exactly those frames, which is what makes them legible rather than looking
+  like the defect again.
+  The marks' *ink* is set where they are created (`install()` in `plot_host.cpp`): 0.75 px and
+  dashed 4/4 through `Plot::set_cursor_stroke()`, which is per cursor because the trigger marker
+  (also a cursor) keeps the solid `line_width_px` stroke. A new measure mark must take that
+  stroke -- it is created in the same loop, so it does; a new *instrument* should not.
+  The **marks** the pane draws (`set_measure_marks()` -- full-width `h_ruler`s and full-height
+  cursors, i.e. the "lines across the plot") are re-placed every frame from the result, so a
+  throttled pass is a *stepped* ruler: acceptable, because the ruler and the number beside it
+  come from the same pass and agree. What is *not* acceptable is a ruler that appears and
+  disappears, so an invalid pass falls back to the last valid result for its **level** marks and
+  only drops its **time** marks: a level is a property of the signal (a mean, a top, an
+  amplitude) and outlives the window it was measured in, while a time mark is a position *inside*
+  that window and may not. Both are emitted in **one pass after the numbers, never inside the
+  loop that computes them**: that loop has three `continue`s (an unresolvable signal, a channel
+  with no window) and each one was a way for the rulers to blink off and back. Fixing one and not
+  the others is how that bug survived a round of "fixes". `clamp fires: N` in the dump is the other half of this: `clamp_to_data()`
+  compares with a relative tolerance, because clamping to exactly `window_s_` can leave the
+  group's span an ULP above it and a clamp that fires every frame is a re-frame loop, not a
+  clamp.
+- **A measurement must not read its window raw.** Both passes go through
+  `plot::data::MinMaxPyramid`, which the producer already maintains at amortised O(1) -- so the
+  pane inherits the summary of the new samples rather than computing one, which is what the
+  "evaluate only on new samples" ask comes to here. Throttling the cadence (above) bounded *how
+  often*; this bounds *how much*, and it is the larger factor: 19.7 ms per recompute to 1.2--1.6
+  ms, reading **0.1 %** of a 2 M-sample window. Pass one (`measure_scan_buckets()`) adds whole
+  level-0 buckets -- 64 samples each, carrying min, max an **exact** sum and a finite count -- and
+  locates each extreme to a *bucket*; one raw `measure_scan()` of that bucket alone then pins it
+  to a sample, two buckets at most whatever the window's size. Pass two
+  (`measure_accumulate_bucket()`) folds a bucket's **sums** only when it lies **strictly** on one
+  side of its level (`k.lo > level` or `k.hi < level`): then every sample falls in the same bin and
+  none is *at* the level, so the fold is exact and not an approximation. It asks **separately**
+  whether the bucket enters a side of the hysteresis band (see the invariant below), because a
+  single test against `level ± h` refuses exactly the buckets a crossing passes through. A bucket
+  wholly past a threshold holds that crossing at its first sample, exactly -- which is where the raw
+  walk would have found it. It refuses a bucket that straddles the level, one that enters a side
+  somewhere inside itself, and one holding a non-finite sample (the raw walk takes the first
+  *finite* sample of the new side and an aggregate cannot say which that is); the caller then opens
+  that bucket. **Nothing may be folded before a refusal** -- a refused bucket goes to
+  `measure_accumulate()`, which adds the same samples again, and sums added above the `return false`
+  double-counted every opened bucket. That read as `top=0.614304` on a unit sine against the 2/pi a
+  mean over a half then gave; a *bucketed* window no longer reports `top` from those sums at all
+  (see the flat-level invariant below), which makes the rule easier to break silently rather than
+  less binding -- the sums are the fallback a window with no histogram reads, so a wrong one is a
+  wrong answer waiting for that window. Four things this rests on, each of which breaks it silently:
+  * **Exactness is the point, so nothing may stride or decimate.** `peak to peak` must still read
+    exactly `2` on a unit sine, and it and `average` still come straight out of the one shared
+    `measure_stats()` pass. A bucket's sum is a sum. (`top` has no *exact* reading to protect any
+    more: it is a density estimate and not a mean, so the assertion that used to be
+    `top == 0.636620` on a sine now belongs to `above 50`, which *is* a mean over a side and reads
+    exactly 2/pi again -- see the band-average invariant below, and the flat-level one for what
+    `top` reads instead. Everything above is about the *bucket* path being a fast path and not an
+    approximation, and that is unchanged.)
+  * **The bucket index space must be the window's.** `ChannelBuffer::acquire()` calls
+    `pyramid_.drop_before(values_->base())`, so a channel's pyramid is in the value ring's
+    absolute index space -- the same space `live_window_locked()` answers in, since a channel's
+    stride is always 1. The snapshot's pyramid is built from sample 0 and never dropped from, so
+    its space is the snapshot's own. `MeasureWindowReader::origin_` is what turns one into a
+    window offset, and a mismatch there measures the wrong samples rather than failing.
+  * **The raw path stays, and stays exact**, for the window's partial edge buckets, for the
+    samples produced since this frame's `acquire_all()` (one frame of production, so bounded), and
+    for the straddling buckets. A window shorter than a bucket degrades to O(window) and must
+    still be right.
+  * **Both passes walk the same fetched bucket list** (`App::measure_bucket_scratch`, reused
+    across recomputes -- a 2 M-sample window is 32 k buckets). Fetching twice is a second walk of
+    the pyramid for nothing.
+  `measure cost:`'s `covered`/`buckets`/`raw` is the guard, and it needs the fast mock to say
+  anything.
+- **A pass costs the window's buckets times the pane's *measured channels* and its *distinct
+  levels*, and the window's own size multiplies all of it.** The cadence above bounds *how
+  often*; this is *how much*, and it is the term a big time scale buys. Measured on the mock at
+  the user's scale -- a **15 s** window, `--buffer-mb 4000` (so `time_stride` stays 1 and the
+  window is 11.8 M samples, 184 k level-0 buckets), four signals, one row -- with
+  `[levels-probe]` (see [verification.md](verification.md)), `measure cost:` reading
+  `recomputes`/`each`/`covered`/`buckets`/`raw`:
+
+  | pane | `each` | `raw` | tick mean |
+  |---|---|---|---|
+  | empty | -- | -- | 1.34 ms |
+  | 1 measurement, 1 level | 6.58 ms | 0.1 % | 1.99 ms |
+  | 4 measurements, 4 shares on **one** channel | 10.28 ms | 0.4 % | 2.38 ms |
+  | 16 measurements, 16 shares on one channel | 24.55 ms | 1.2 % | 3.86 ms |
+  | 4 measurements, 1 share each on **four** channels | 35.69 ms | 2.6 % | 4.58 ms |
+
+  So a pane is priced per measured **channel** (one `MeasureWindowReader`, one fetch, one scan)
+  and per **distinct share** (one accumulator), and the window's samples are the multiplier on
+  both: the same pane over a 2 M-sample window is the 1.2--1.6 ms a recompute this pane's
+  budget was fixed at, and a machine's ten noisy channels at a 15 s window is **tens of ms a
+  pass**, several times a second. That lands on the **tick** -- `update_measures()` runs inside
+  it -- so `frame cost:`'s tick mean is where a pane's cost shows (1.34 -> 4.58 ms above), and
+  it is *not* an ingest problem: `gaps=`/`packets=` stay exactly clean even though each
+  `MeasureWindowReader` holds `model->mutex()` for its whole life, because a socket buffer
+  absorbs a few tens of ms of producer. Read the tick mean and `each` before blaming the
+  producer.
+  Inside a pass the terms are, instrumented per window at that scale: the **fetch** 3.3 ms
+  (three out-of-line `MinMaxPyramid` accessors and a 48-byte `MeasureBucket` per bucket),
+  `measure_scan_buckets()` 0.8 ms, and **pass two** 7.5 ms -- dominated by the per-(bucket,
+  level) fold. That fold is why `measure_accumulate_bucket()` is `inline` in `measure.hpp`: it
+  is the innermost loop of a walk whose iteration count is the window's buckets *times* the
+  pane's levels, and as an out-of-line call in its own translation unit it cost **30 % of the
+  pass** (sixteen shares on one channel: `24.55 -> 17.25 ms` a recompute). A caller adding a
+  per-bucket type keeps it in the header, and a caller adding a bulk one may not let it grow a
+  call per bucket either.
+  The third term is `raw`, and it is the **signal's**: a level that falls inside a bucket's
+  `[lo, hi]` has to be walked sample by sample (the fold cannot split a bucket), so a signal
+  whose local range covers the level everywhere -- white noise, a noisy machine channel --
+  degrades the pass to O(window) *per level*: measured `raw=4.6 %` on the mock's `noise` channel
+  against `0.1 %` on its `sine` at the same window. It is the field to read before blaming the
+  pane for a slow run, and no cheaper walk fixes it.
+- **`Top`/`Bottom`/`Amplitude` read a *flat* level, and the density that finds it is the buckets',
+  not the samples'.** A band-limited edge overshoots and rings -- the mock's `square` at 30
+  harmonics reaches ±1.179 where its plateau is ±1 -- so a measurement that reads the extremes, or
+  a mean over a side of a level, reports the ringing rather than the level the signal dwells at:
+  that is what made this change (`amplitude` read `1.179350` and `top` `0.986496` on the rippled
+  square, against `1.179350` of overshoot where the plateau is `1`). A flat level is a *density*
+  question: the plateau holds most of the samples and the ringing a few percent. So
+  `measure_scan_buckets()` folds a 64-bin histogram of the whole buckets' *midpoints* while it has
+  the list in hand -- one observation per bucket, each bin carrying its buckets' **exact** sum and
+  finite count -- and `measure_flat_levels()` takes, either side of the split, the densest bin that
+  holds at least half the densest one's buckets, **the outermost of those**, and the exact mean of
+  the samples of the buckets within **5 % of the window's peak-to-peak** of it. 5 % is *under* the
+  ~9 %-of-swing Gibbs overshoot, so the ringing's excursion falls outside the band while a
+  plateau's own ripple stays inside it; the outermost-of-the-equally-dense rule is what makes a
+  waveform with *no* plateau -- a sine, a ramp -- read its peak instead of an arbitrary mid-range
+  bin that a shifted window would move. `Amplitude` is then `top - bottom`, a bench scope's
+  `Vamplitude`, and **not** the half-swing it used to be, nor the peak-to-peak swing.
+  The readings, fast mock, 2 s window, `[measure-trace]`, harmonics `0` → `30`: `top` `1.000000` →
+  `0.999983`, `bottom` `-1.000000` → `-0.999983`, `amplitude` `2.000000` → `1.999966`, against
+  `peak to peak` `2.000000` → `2.358701` -- the extremes keep the overshoot, and that separation
+  *is* the measurement. On the probe's 1 Hz ±1 sine: `top` `0.957988` (it was `0.636620`, the
+  half-wave mean), `amplitude` `1.915983`, and `peak to peak` still **exactly `2`**; `[stats-probe]`
+  reads `top` `mean=0.957905 sd=0.0014 lo=0.951967 hi=0.962348` over a scrolling window, which is
+  the stability the value band buys -- the answer does not follow the window's alignment.
+  Five things this rests on, each of which breaks something silently:
+  * **Nothing may be read raw for it.** The histogram is the *same* fetched bucket list, walked a
+    second time inside `measure_scan_buckets()`; a histogram of the window's *samples* would be a
+    second O(window) walk, which is exactly what the pyramid path exists to avoid. `measure cost:`
+    is the guard and its `raw` does not move: the probe's pane reads
+    `covered=59684972 buckets=932446 raw=47640 (0.1%)` against the baseline's
+    `covered=61183221 buckets=955856 raw=47402 (0.1%)` -- the same `raw`, 0.44 → 0.50 ms a pass
+    (and `--noise 0.1`, `2.1%` both sides, 0.52 → 0.65 ms).
+  * **It is gated, and the gate is what keeps an unrelated pane free.** `measure_scan_buckets()`'s
+    `flat_hist` comes from `App::MeasureWindow::flat_wanted`, set by the first loop over the pane
+    and only for one of the three types. A pane of means and extremes pays nothing.
+  * **The bin range is the *buckets'*, not the window's.** The window's partial edge buckets and the
+    samples produced since `acquire_all()` are read raw and are not in the list, so
+    `measure_scan_buckets()` tracks its own `blo`/`bhi` over the **non-empty** buckets only -- an
+    all-non-finite bucket is an empty aggregate whose `lo`/`hi` say nothing, and taking them would
+    put a bucket at some arbitrary value. A degenerate range (`bhi == blo`) leaves `folded` at 0,
+    which is the caller's "no histogram at all".
+  * **The *window's* peak-to-peak is what the band is a share of**, and the *split* is sized exactly
+    as `measure_set_level()` sizes a level, so "the top" and "the level a period is counted about"
+    are placed by one rule. The band is a *value* band, which is why the reading does not move when
+    the window does.
+  * **The fallback is the split, and it is what a filtered or sub-bucket window reads.** `hf_fc > 0`
+    disables the pyramid (above) and a window shorter than a bucket has no bucket to fold, so
+    `top`/`bottom` fall back to the mean of each side of the split -- and `amplitude` to the
+    window's own peak to peak, which is the same number on a waveform with nothing to exclude.
+    There is no flat level in that mode to subtract, so `amplitude == top - bottom` is *not* an
+    invariant to lean on there. Measured on the rippled `square` at `hf_fc=100`:
+    `top=0.973824 bottom=-0.991731 amplitude=2.354173 peak to peak=2.354173`, `buckets=0
+    raw=200.0%` -- two raw walks and no density estimate, which is the honest reading of a window
+    the pyramid cannot summarize.
+- **`Above`/`Below`/`Between` are the *means over a side of a share*, and they are the readings
+  `Top`/`Bottom` gave before a flat level replaced them.** That change kept the split's two means as
+  its *internal fallback* for a window the pyramid cannot summarize (above); these three types are
+  that fallback, exposed and named, which is what lets the two different questions about one split be
+  asked side by side -- on a unit sine `above 50` reads `0.636620` (2/pi) where `top` reads
+  `0.957988`, and on the mock's band-limited square `above 50` reads `0.986496` where the plateau is
+  `1.000000` and `top` `0.999983`: the edge's ring is *inside* this mean and not inside that level.
+  Five rules, and the first two are what a reader is most likely to assume wrongly:
+  * **A band is not a wider split, and needs no walk of its own.** `Above`/`Below` are
+    `MeasureLevel::sum[1]`/`count[1]` and `sum[0]`/`count[0]` at the measurement's own share.
+    `Between` is the **difference of two levels' upper sides** -- `sum[1](lo) - sum[1](hi)` over
+    `count[1](lo) - count[1](hi)`, i.e. the samples above the lower edge and *not* above the upper
+    one -- and no single level's two sums can bound a band, because a band's two edges are two
+    thresholds. Both accumulators come out of one pass two over one window (the pane registers one
+    level per edge, `w.pct`, and both are deduplicated into it), so the difference is exact rather
+    than approximate. `v == level` is the below side, as everywhere, so the band is `(lo, hi]`.
+  * **It rides the bucket fast path unchanged.** A bucket wholly inside the band is strictly above
+    the lower level *and* strictly below the upper one, so both accumulators fold it whole; only the
+    buckets that straddle either edge are opened, exactly as for one level. `measure cost:` is the
+    guard: adding all three types to a pane of every type left `raw` at `0.1%` of `covered`
+    (`113966` of `240719031` with the ten types, `134978` of `255372033` with the thirteen), and a
+    band is *two entries of the level list*, not a second pass.
+  * **`measure_level_pcts()` is the only place the shares are read**, and it clamps both to `[0,100]`
+    and puts `Between`'s pair **in order**: "between 80 % and 20 %" is the band between 20 % and
+    80 %. Normalized rather than refused because the shares name two *edges*, and the band does not
+    depend on which the user typed first; the pane's dedup key and both accumulators are keyed on the
+    ordered pair, so one band is one walk however it was written.
+  * **Nothing to measure reads `--`**, exactly as for every other type: a side holding no sample (a
+    share at `100 %`, whose level is the window's own maximum) and an *interior* holding none are
+    both `invalid`/`--` and never `0`. The ideal `--square-harmonics 0` square is where the second
+    shows -- every sample is exactly +/-1, so the band `(0, 0.5]` holds nothing -- against the same
+    band on the band-limited square, which holds the edges' transitions (`between 50 75` =
+    `0.302744`, `between 25 75` = `0.000000`: the symmetric band's two halves cancel, the transition
+    being odd about its own midpoint).
+  * **The reading is a mean over the window's *samples*, so its sixth decimal follows the window's
+    boundary.** A live window is closed at both ends, so its oldest and newest sample share a phase
+    and the mean carries one sample that is not in an open interval -- about one unit in the sixth
+    decimal out of 2.6 M samples. Measured over one fast-mock run, `[measure-trace]`: `above 50` on
+    the sine printed `0.636620` on 48 lines and `0.636621` on 2, `below 50` `-0.636620` on 37 and
+    `-0.636619` on 18, `above 50` on the square `0.986496` on 32 and `0.986495` on 18, and
+    `between 50 75` on the ramp `0.250000`/`0.250001`/`0.249999`. The old `Top`/`Bottom` spread the
+    same way -- it is a property of a mean over a finite window, not of these types, and a reading
+    that has to be exact to six figures is read off `[bandavg-probe]`'s nine.
+  Measured on the fast mock, 2 s window, the mock's default 30-harmonic square, `[bandavg-probe]`
+  (nine significant digits, then what the pane prints):
+  `above 50` on the sine `0.636620262` -> `636.62 mV`; `below 50` on the sine `-0.636619283`;
+  `between 50 75` on the sine `0.255873597` -- the analytic `3(2-sqrt 3)/pi = 0.255873`, which is
+  neither the window's mean (`0`) nor the band's edge (`0.5`); `above 50` on the square
+  `0.986494746` / `0.986495505` (one or two samples at the window's end); `between 50 75` on the
+  `ramp` `0.250000385` and `above 50` `0.500000` -- a uniform density makes every band's mean that
+  band's own centre, so a quarter and a half of the range are the shape's prediction and not a
+  coincidence; `above 100` on the `ramp` `--`; and the ideal square's `between 50 75` `--`.
+  Editing the sine's band through the dialog to `50/90` takes it to `0.431361697`
+  (`0.8 / (2 asin 0.8)`), which is the check that the second share is the one the engine reads.
+- **`MeasureOptions::noise_pct` is a percentage, clamped in `measure_set_level()` to half the room to the
+  nearer extreme**, so a band can never invert its own thresholds. It moves the **edge decision only**: the
+  sums still split at the bare level, which is the *fallback* `Top`/`Bottom` read on a window with no
+  bucket histogram -- a band that moved that split would change what a filtered or sub-bucket window
+  reports, for no gain to a crossing count.
+- **`measure_accumulate` loops samples outer, levels inner, and that is not backwards.** The filter holds one
+  state for the whole walk, so levels-outer would step it once per level *per sample* and hand every level but
+  the last a different filter state.
+- **A non-zero `hf_fc` disables *both* bucket fast paths**, with the single
+  `if (!filtered && reader.bucket_range(...))`. An empty `buckets` makes `bulk_from == bulk_to == n` *and*
+  leaves `lo_search` / `hi_search` at 0, so `pin()` becomes a no-op -- and that is the right answer, because a
+  bucket is an aggregate of unfiltered samples and cannot be mixed into a filtered walk in either direction.
+- **A crossing is counted with hysteresis, and the band moves the *edge decision* only.**
+  `MeasureLevel::hysteresis` is a Schmitt trigger about `level`: an edge is counted once the signal
+  has passed `level + h` going up or `level - h` going down, and a sample inside the band decides
+  nothing. Without it `period`, `frequency` and `pulse duration` are unusable on anything real --
+  the mid level is exactly where a waveform moves *fastest*, so an interferer faster than the
+  fundamental recrosses a single level several times per true crossing. Measured on a 5 Hz sine with
+  a 500 Hz tone at a tenth of the amplitude (`tools/mock_udpstreamer.py --noise 0.1`): 9 true
+  crossings counted as **79**, `period=0.025622 freq=39.029` for a true 0.2 s / 5 Hz, against
+  `period=0.200188` with the band. Four rules, each of which was wrong first:
+  * **`measure_set_level()` is the only place the band is sized**, and `src/ui.cpp` calls it rather
+    than assigning `.level` itself: two expressions for the width is how the raw walk and the bucket
+    path end up disagreeing about where a crossing was. `h = min(0.10 * (hi - lo), 0.5 * min(hi -
+    level, level - lo))`. The 0.10 is measured -- 5 % reads a 0.1 interferer and fails at 0.2
+    (`period=0.075`), 10 % holds to 0.3 and to white noise at sigma=0.05.
+  * **The clamp is load-bearing.** `PulseDuration` lets the user put the split near an extreme, and
+    a fixed tenth of the span there puts the upper threshold *above every sample*: the walk never
+    decides that side and the measurement reads nothing at all, which is worse than reading
+    something noisy. On a ringing 3.3 V logic signal at a 90 % split: `enters=0` with a fixed band,
+    `enters=4 period=0.200000` with the clamp.
+  * **The `sum`/`count` split stays at the bare `level`.** Four things read it and none may be
+    moved by a band: a crossing's *side* is decided by the sample's own value against the level
+    (`v == level` is the below side, as it always was), `Top`/`Bottom` fall back to the mean of
+    each side on a window with no bucket histogram, and `Above`/`Below`/`Between` read it on
+    *every* window -- their whole definition is that split, so a band folded into it would move a
+    documented exact reading (2/pi on a sine) for no gain to any crossing count. The band is about
+    *deciding a crossing*, not about where a sample lives.
+  * **`h = 0` must reduce exactly to the single-level walk**, including the `v == level` skip, so the
+    band is a parameter of the engine rather than a mode of it.
+  The cost is the noise's, not the band's: the clean fast mock reads `raw=119412 (0.1%)` of 215 M at
+  1.41 ms a recompute and with the 0.1 interferer `raw=2.0%` at 1.96 ms. A
+  `/tmp/check_measure.cpp`-style check is how the walk itself was verified (`g++ -std=c++20 -O2 -I
+  src ... src/measure.cpp`): over a clean sine, sines with 0.1 and 0.3 interferers, 10 %/50 % duty
+  squares and a 90 % threshold, the **bucket walk must equal the raw walk exactly** -- same
+  `enters`, same `count[]`, identical `first_enter`/`last_enter` to 0.0 -- which is the assertion
+  that the fast path is a fast path and not an approximation. The app's reading is
+  `[measures-probe]` against `--noise 0.1`.
+- **A statistic's observation is one *recompute*, not one sample.** The pane already refreshes on
+  a cadence (at most one pass per 100 ms while the window scrolls, exactly once when it
+  settles), and the accumulator is fed from that pass's result — so `n` counts windows measured.
+  Feeding it per sample would make `n` a sample count and the mean a mean of *samples*, which is
+  not what any of these measurements measure: a frequency over a window is not a property of a
+  sample. The reading that names this defect is `[stats-probe]`'s `n` in the thousands rather
+  than the tens.
+- **The accumulator is Welford's, and the reason is the same one the time ring is `f64` for.** A
+  measurement's values are routinely large with a small spread — an absolute stream time is the
+  obvious case — and `Σx²  - (Σx)²/n` cancels to noise there. The standalone check is that the
+  spread of `{2,4,4,4,5,5,7,9}` survives a `+1e9` offset unchanged.
+- **What resets the statistics is "what is being measured changed", not "what is in view
+  changed".** An explicit Reset, an add/edit/delete (all three funnel through
+  `rebuild_measures_pane()`), a CONFIG, and a change of display window each change the
+  *question*, so the history is cleared. A pause, a resume, a trigger latch, a pan and a zoom do
+  not: on a **live** view they change which samples answer it, which is precisely what averaging
+  over many windows is for -- and on a **pinned** one they change *nothing*, not even a value
+  (the window invariant above), so there is nothing for the history to see either way. The rule
+  is about the *accumulator* only; it is not a claim that a gesture leaves a value alone, which is
+  a property of the window a value is computed over and is the other half of this change. The
+  pane-wide toggle does not reset either — it only shows and hides labels that are always created
+  and always fed, so reading the plot for a moment does not cost the history.

docs/claude/invariants-plot-and-layout.md

@@ -0,0 +1,184 @@
+# Invariants: the plot, the figure and the layout
+
+How `plot::Figure`/`plot::Plot` may and may not be driven, what a row's state belongs to, the layout editor's overlay, and the rule that layout must not depend on content.
+
+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.
+
+- **A sidebar's size must be its own, never a divider's position.** `GtkPaned` keeps a child's size in
+  `position`, which is a number of pixels **of the window**: the sidebar's width *was* `window - 940`, so on
+  any window narrower than 940 px — a scaled display, where the logical width is half what the screen looks
+  like, or a window a manager capped — the sidebar came up **0 px wide**, and the only way to see it was to
+  drag the divider back. Every patch that kept the paned failed for the same reason (the position derived
+  from the paned's own width, re-parenting the column, the property form of its children, size requests):
+  the *mechanism* was the fault. It is an **`AdwOverlaySplitView`** now — what a utility sidebar is in
+  GNOME, as against `AdwNavigationSplitView`, which is for navigation lists — with `min-sidebar-width` =
+  `max-sidebar-width` = 320 in **pixels**, so the width is its own at any window size, and `collapsed` (set
+  from the window's width in `tick()`) to *overlay* the plot when there is no room beside it rather than
+  being squeezed. `[sidebar-probe]` reads both states: `window=756 sidebar=320` under a 2x scale is exactly
+  the case that used to be zero.
+- **The sidebar's button is the only input; `AdwOverlaySplitView:show-sidebar` is an output.** The split
+  view writes that property *itself* — at startup, and when it collapses — with no user involved, so reading
+  it back as the user's wish is wrong: doing that made connecting a source leave the sidebar shut, because
+  the widget's own `false` was recorded as the user asking for it. A `GBinding` from the property to the
+  toggle is the same mistake in one line, and it cannot be told from a real change by a "is this our own
+  write" flag either, since the toggle's signal may fire after the write returns. Instead `App::sidebar_wanted`
+  holds the wish (written only by `on_sidebar_toggled`, guarded by `App::sidebar_syncing` around our own
+  `set_active`), `update_side_visibility()` is the single place that turns that wish plus "are there signals"
+  into the panel's *and* the button's state together, and `tick()` re-asserts them when the widget disagrees —
+  which is also why a hide *gesture* does not stick: the panel stays where the button says it is. The
+  no-signals case must leave the wish alone, or a source connecting later finds a sidebar the user never closed.
+- **`AdwOverlaySplitView:sidebar-width-fraction` is a 0..1 fraction of the window, whatever
+  `sidebar-width-unit` says.** Setting a pixel count there (320) is a `GObject` critical, and it silently
+  falls back to 0.25 — which reads as "the sidebar is mysteriously 560 px wide" on a wide window with no
+  error anywhere the build would catch. Pin the width with `min-sidebar-width`/`max-sidebar-width`.
+- **A `GtkPaned`'s position is stated after both its sides are filled**, and that is a fact about the
+  *function's order* rather than about the window's shape, which is why it is the one part of the
+  window skeleton that cannot live in `main-window.ui`. `gtk_paned_set_position()` clamps against what
+  its children ask for *now*: called before the sidebar's panels have been appended it is clamped
+  against an empty pane, and the divider lands wherever that left it. Moving the call into the `.ui`
+  moved the plot column by about 180 px, which the layout probe read as a different `done_box` and a
+  taller figure.
+
+- **`plot::Plot` cannot remove or retarget a trace.** Hence fixed trace slots created
+  up front and rebinding via `SlotSeries`; a *name* change (legend text) is the one
+  thing that forces a rebuild. Cursors are parked outside the axis range instead of
+  removed.
+- **A `Figure`'s row count is fixed at construction**, so `RowSet::rebuild_all()` builds
+  a *new* figure and the area is handed it (`PlotArea::set_figure()`); it costs no GL
+  state. That makes one path for "a row's traces changed" and "the row count changed",
+  and it is why `rebuild_all()` restates a pinned event window (`pinned_pre_`/
+  `pinned_post_`) instead of re-framing on the live edge — a drop during trigger mode
+  would otherwise throw the frozen view onto the stream, where nothing moves it off
+  again until the next latch. `PlotArea::create()` is handed `App::placeholder_plot`,
+  never a row: the area keeps a reference to the plot it was created with, and a rebuild
+  destroys every row.
+- **A trace is a slot with a name *and* a channel; a name alone is not one.** `Row::channel[s]`
+  is re-resolved by `RowSet::bind()` every frame (slots are identified by name, see above), and
+  `-1` means the model built no channel for that name. Some names can *never* bind: the stream's
+  **time signal** is skipped by `build_channels_locked()` however often it is enabled, so a slot
+  holding it has a name for ever and data never. The plot showed nothing for it, which is why it
+  went unnoticed, but the cursors pane's `mix` mode drew one line per *named* slot and so gave
+  each phantom a row that could only read `--` — "the pane shows a lot of empty signals that do
+  not exist", six lines over three real traces. Two halves to the rule. (1) Anything that counts
+  traces counts `channel[s] >= 0`, not `!signal_name[s].empty()` — and a per-frame bind means the
+  cursors pane cannot key its rebuild on `generation()` alone, hence `App::cursors_pane_bound`, a
+  bit per row/slot (`kMaxRows * kSlotsPerRow` is 32, so one `std::uint32_t`): a trace that
+  appears without a structural change still gets its line. (2) `apply_layout()` refuses a name
+  that cannot produce a channel (`ScopeModel::is_time_signal()`), because such a name was
+  **sticky**: `collect_layout()` writes `signal_name` back verbatim, so one that got into a
+  session file was re-saved every session for ever. The refusal also heals an existing file on
+  the next save. How the names first got in is unexplained — the drop path already refuses a
+  signal with no channel — most likely an older build or a CONFIG whose time signal was not yet
+  classified as one; the fix is the stickiness and the counting, not a guess at the origin.
+- **A row's contents are state of the `RowSet`, not of the figure.** `insert_row()` and
+  `remove_row()` shift that state with `carry_row()` and let `rebuild_all()` re-deal the
+  figure handles, so inserting above row 1 moves what row 1 plotted down to row 2 rather
+  than renumbering the rows under the user. `carry_row()` deliberately copies fields
+  instead of assigning a whole `Row`: a `Row` also holds the figure handles (`plot`, the
+  axis and cursor ids) and the `SlotSeries` objects the traces point at, and those belong
+  to the row's *position*. It clears the destination's slot bindings for the same reason —
+  the next `bind()` re-resolves them, and without the clear the frame in between draws the
+  moved row's samples under the new row's legend.
+  Both call `rebuild_all()` themselves, so their callers must re-point the area
+  (`PlotArea::set_figure()`) directly; `relayout_areas()` is no help, since it only acts on
+  a *dirty* row.
+- **The layout editor's buttons are *separate* overlay children, never one transparent
+  child covering the area.** A `GtkOverlay` child is picked wherever its allocation is, and
+  `gtk_widget_set_can_target(FALSE)` takes a widget's children out of picking with it, so a
+  full-area `GtkFixed` would swallow every pan, drop and hover the editor is not interested
+  in. Each button is therefore a small widget aligned to a corner or the centre and placed
+  by its **margins**, and the overlay is only measured from its main child, so moving them
+  cannot reach the plot's layout.
+  They are placed from `FigureLayout::rows` — the rects the frame was *drawn* from —
+  divided by `PlotArea::device_scale()`, because a `Rect` is framebuffer pixels and a GTK
+  margin is logical ones. Reading the figure's own rects rather than dividing the widget
+  height by the row count is what keeps a `×` on the row it names when the rows stop being
+  an equal division. `sync_layout_editor()` runs every frame on purpose:
+  `gtk_widget_set_margin_*()` returns early on an unchanged value, so a settled layout costs
+  the comparisons and nothing else, and a resize needs no notification.
+- **Trace slots are identified by signal name, not channel index.** Enabling a signal
+  or a new CONFIG renumbers the channel list, so an index would silently re-point a
+  trace at another signal.
+- **Layout must not depend on content.** The y gutter is reserved at the widest label
+  `TickFormat::Si` can produce *for an axis with no unit* — a sign, three significant
+  figures and a one-glyph prefix, measured and not counted in characters — and only ever
+  grows; the status label is ellipsized so
+  its text cannot drive the paned divider. Both exist to stop per-frame relayout.
+  The reservation deliberately does **not** cover `format_si()`'s `%.3g` fallback
+  (`-1.23e-45`), which it used to: that form needs a value past 1e24, so it bought a third
+  of the gutter for a label no stream produces, and the floor being a monotone maximum over
+  the *measured* need means one that did appear widens the gutter for good anyway. Erring
+  wide is not free here — it is a third of the plot's width.
+  And **nothing may add slack to the gutter it is told**: `note_y_gutter()`'s argument is
+  `layout().y_axis_width`, which is `max(measured, floor)` — partly our own answer coming
+  back — so a constant added to it compounds. See the ratchet reading under `layout over N frames` in
+  [probe-readings.md](probe-readings.md).
+  The same rule is why the activity badge is one glyph in three colours rather than
+  three glyphs, why the `rate` field collapses to one figure or a range instead of a
+  per-channel list, and why `format_elapsed()` steps to a coarser unit instead of
+  letting the counter grow: each is a status field whose *width* would otherwise depend
+  on the stream, and the status row is directly above the plot.
+  The reservation goes on the **figure** (`Figure::set_min_y_gutter()`, added to the
+  plotter for this), not on the rows: `Figure::layout()` clears every row's
+  `set_min_y_gutter()` to measure what its own labels need, so a floor written onto the
+  rows survives exactly until the next layout.
+- **The right-hand band is a want, and the left gutter is a measurement.** The two sides of
+  the plot are not symmetric in kind: the left holds the y labels, so it is measured and
+  floored; the right holds nothing, so there is nothing to measure and `RowSet` simply asks
+  for half the widest time label plus the label padding (`right_gutter_px_`, reserved in the
+  same one-shot block). Half a label is the figure that matters: an x tick label is
+  *centred* on its tick and a live axis is `[-window, 0]`, so there is always a tick exactly
+  on the axes' right edge, and with `axes` flush to the viewport half of that label was
+  drawn outside the plot. Both go on the **figure** and for the same reason — the rows have
+  to end on one column as well as start on one — which is why `apply_gutters()` applies the
+  pair and `rebuild_all()` calls it: a new `Figure` carries neither.
+- **A trace's colour is indexed by *signal*, not by trace slot.** `Row::color_index`
+  stores it and `signal_color_index()` (ui.cpp) computes it from the signal list, so a
+  signal dropped on two rows is one colour and the signal panel's chip names a trace
+  unambiguously. `plot::Plot` fixes a colour at `add_trace()`, so changing one needs a
+  figure rebuild — which `assign()` already forces. A signal on no plot gets
+  `RowSet::unplotted_color()` (grey) rather than no chip, so the panel's rows stay the
+  same height.
+- **The invalid-span band is data-anchored and reserves no layout space.** `Plot::set_invalid_spans()`
+  draws a tinted quad over the span it names; unlike `Plot::set_x_note()` (the `t0` caption), which
+  is chrome drawn at a fixed corner of the axes regardless of the data, a band pans and zooms with
+  the samples it accuses. The two are the complementary cases: the caption is chrome that data does
+  not move, the band is annotation that data does. Both are alike in the second count: neither
+  reserves layout space and neither can be picked, so a hole cannot move the layout the labels were
+  measured into.
+
+  The band has a **one-device-pixel floor on its width**. A hole of one sample in a window of hundreds
+  of thousands is a hundredth of a column, and a fill rounded to zero would drop exactly the case
+  the band is most needed for — a sub-pixel hole is invisible as a gap in the polyline and would be
+  invisible as a band too without the floor.
+
+  The band carries **three states** and they are a property of the hole, not of the plot: solid
+  (`Style::invalid_fill`) while the hole still lacks packets, faint (`Style::invalid_repaired_fill`)
+  once `Hole::repaired()` is true, absent once the hole's slots age out of the ring and
+  `forget_holes_before()` drops it from the table. A repaired hole is **not** retired early: the band
+  is a record of what the window was missing, and retiring it on repair would erase the report the
+  moment it became explicable — the faint tier is how the display says "this was missing but arrived
+  late". `RowSet` sends one `plot::InvalidSpan` per hole to every row — a gap is in the stream, not
+  in one signal — and only in `Live` and `Capturing`, because a `Held` or `Paused` snapshot carries
+  its own stamps that the live hole table does not address.
+
+- **`RowSet::signal_color()` is the only route to a trace's colour.** The user can override the
+  palette entry per signal (clicking its chip; `set_signal_color()` / `clear_signal_color()`,
+  keyed by **name**, because a palette index is positional and a CONFIG renumbers), and that
+  override is exactly the state in which two routes to a colour disagree. So `install()` builds
+  the trace through this call and all three chip sites — the signal panel, the measures pane and
+  the cursors pane — read it too; none of them may index `palette_color()` itself. An override
+  marks every row holding the signal dirty (`mark_signal_dirty()`, not `assign()`: what the slot
+  *holds* did not change) and the rebuild happens on the frame tick via `relayout_pending`,
+  because `relayout_areas()` is the one place that builds a figure and re-points the area at it.
+  `UDPSCOPE_PROBE_COLOR_MS` reads the result back out of `plot::Plot::trace()` and out of the
+  chip's own markup, since asking the resolver twice would assert nothing.
+
+- **Switching a signal off takes its traces off every plot.** The switch means "do not acquire this", and a
+  trace left behind draws nothing: it holds one of the four slots a plot has, reads `--`, and blocks the drop
+  that would fill it with something live. `on_signal_switch()` clears every slot by the **signal name** the
+  slot remembers -- never the channel index, which is exactly what the enable change renumbers -- and says what
+  it did in a notice, because a trace that vanishes silently is its own kind of confusing. The follow-ups (a
+  relayout, the panels' chips, the layout save) are done once by the caller rather than per slot. Re-enabling
+  does **not** put the traces back: the arrangement is the user's, and guessing where they were is worse than
+  leaving them off.

docs/claude/invariants-readouts-and-cursors.md

@@ -0,0 +1,88 @@
+# Invariants: readouts, cursors and the value formatter
+
+What a readout is allowed to quote, how the cursors are read back, and the one formatter both panes share.
+
+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.
+
+- **A readout quotes a stored sample, never a value between two of them.** The hover
+  crosshair and the cursors pane's `mix` values are one call, `Plot::crosshair_value()`, and it
+  reports the **nearer** of the two samples bracketing the x (a tie reads the earlier). Upstream
+  interpolated linearly, and that is wrong twice over here: ingest decimation is a *boxcar
+  average* over `time_stride` samples, so a number between two stored samples is a second
+  estimate laid over the first that nothing on screen or in an export holds; and past the sample
+  spacing the polyline is a line the renderer drew, so a point on it reports the drawing. The
+  change is in `deps/plotter`, which keeps the blend as `CrosshairValue::Interpolated` for a host
+  whose x is a quantity it is willing to interpolate — the nearest sample is the **default** and
+  **udpscope never states the other**, so a `set_crosshair_value_mode()` call appearing here is a
+  regression, not a feature.
+  **Both the mark and the number come from one call, `Plot::crosshair_point()`**, which returns
+  the quoted sample's own **x** as well as its y — so every mark this app draws for a readout is
+  *snapped to the sample it quotes*. The library's `CrosshairRow::marker` and the cursors pane's
+  `mix` crossing annotations (`place_crossings()`, which must use `crosshair_point()` and not
+  `crosshair_value()`) are both placed from it. Two consequences that look like defects and are
+  not: the mark **sits beside the polyline at a deep zoom** (one y feeding both the number and the
+  dot is what keeps them from disagreeing), and a crossing dot **sits a little off its own
+  vertical cursor line** — up to half a sample period, invisible at a whole-window view and the
+  width of the panel at a few samples across, which is the only zoom at which anyone is asking
+  which point it is. The line says where the *marker* is; the dot says which *datum* is quoted.
+  The hover mark is also deliberately *larger* than a trace's own sample dots
+  (`Style::crosshair_marker_px` 9 against `marker_px` 3), because a snapped mark lands among them
+  and at their size reads as one more sample. The guards are the library's
+  `crosshair_value_is_the_nearest_sample`, `the_crosshair_marker_snaps_to_the_sample_it_reports`,
+  `crosshair_interpolated_mode_blends_the_two_samples` and
+  `the_crosshair_mark_is_bigger_than_a_sample_dot`, plus `[cursors-probe]`'s `first mark at x=..
+  y=..` agreeing with the pane's first value.
+- **A measurement with a non-zero `hf_fc` is the one exception**, and it is inherent rather than a rounding
+  error. Its `min`, `max`, `peak to peak`, `average`, `top` and `bottom` are computed from a one-pole-filtered
+  copy of the window, so the quoted value need not equal any stored sample -- and with `show_on_plot` its
+  ruler sits at a level the drawn trace, which is raw, never reaches. This is what filtering *is*; it must
+  not be "fixed" by snapping the readout to the nearest sample. Every measurement with `hf_fc == 0`, which is
+  the default, still quotes a stored sample exactly as the rule above says. The filter is seeded with the
+  window's **first sample** and never from history before the window, so a measurement never depends on data
+  outside the window it reports on: the left-edge step transient is removed by the seeding, not by priming
+  from earlier samples.
+- **`format_measure()` is the one formatter for both panes, and its SI prefix does not depend on
+  there being a unit.** The cursors pane's values and the measurements pane's `text=` go through
+  it, so a change reaches both. The prefix ladder used to be inside `if (!unit.empty())`, which
+  made two decimals of a small unitless value read `0.00` — the reading gone, not merely coarse —
+  and that is a whole class of channels, not a corner: `measure_unit()` returns `""` for any signal
+  whose CONFIG declares no unit, and a **math channel never has one**. The regression net could not
+  see it because `tools/mock_udpstreamer.py` declared `unit="V"` for every data signal; it now takes
+  **`--unit ''`**, and that is the flag to run the measures and cursors probes under when touching
+  this (`text=[636.62m]`, `● sine=585.24m`). With no unit the prefix is written **tight** against
+  the number — `1.34m`, not `1.34 m` — because the space exists to separate the number from its
+  unit and a spaced `m` alone reads as metres; with one it stays spaced and the prefix joins the
+  unit (`636.62 mV`). Below `1e-12` the ladder runs out, and `%.2f` would print `0.00` again, so
+  that range falls back to `%.3g`.
+- **With the instruments off the readout blanks, and the panel stays on screen.** Cursors-off makes the
+  pane *insensitive* rather than hiding it -- a panel you can still see is a panel you can read, and the
+  settings you are about to switch back on must not vanish while you look for them -- and every cell in
+  it is written `"--"`, the spelling an unavailable cell already uses. A readout quotes a stored sample;
+  with nothing bracketing one there is no sample to quote, and keeping the last values would be quoting
+  a sample the cursors no longer name. Two spellings of one state in one grid would be the defect.
+- **The cursors are read back from the plots only while a gesture is on that row.** `Cursor::x`
+  is the *free* pointer position while a drag runs and the snapped value otherwise -- which is
+  what the app itself wrote a frame earlier, or the snap of it. A tick that reads a row on
+  every frame therefore adopts its own echo back, and -- because the vertical pair is one value
+  shared by every row -- a row that has not been re-written yet hands the *previous* shared
+  time straight back. That is the "drag it and it springs back" defect, and the fix is
+  `RowSet::sync_cursors(int drag_row)`: the tick passes the row whose controller reports
+  `grabbed_cursor() != kInvalid`, and every other frame does nothing. The values are echoed
+  back with `CursorPlacement::Free` for the same reason -- the controller snaps at the end of
+  the gesture (`Controller::end_drag()`), and snapping the echo fights the hand that is still
+  moving the cursor.
+- **The cursors' on/off is one flag on the `RowSet`, never a copy per row.** It is one
+  piece of state (the toolbar toggle) and the mode is one value; a per-row copy is something
+  `insert_row()`'s `clear_row()`, or any rebuild, can clear behind the user's back, which is
+  how a row added while the cursors were already on came up with its instruments parked
+  while every other row showed them. The same goes for the vertical pair's `x`: it is one
+  stream time for the figure, so it lives on the `RowSet` too, and `Row` keeps only what is
+  genuinely per row (the rulers' values, the traces, the colours).
+- **Every instrument this app *computed* is out of the pointer's reach.** The trigger marker and
+  the measurement marks are cursors created with `Plot::add_cursor()`/`add_h_ruler()`, and a cursor
+  is grabbable by default -- so each takes `set_cursor_selectable(id, false)`. **Parking it outside
+  the axis is not enough**: the controller holds a marker for the gesture's life and follows the
+  pointer between frames, so a readout parked at `kParked` could still be dragged. The trigger
+  marker says where the scope put the edge and a measurement mark says what a measurement measured;
+  neither is something a user may move. The dump prints `readout instruments locked: N`, which must
+  be 1 -- a drag is not something a probe can perform, so the state is what is asserted.

docs/claude/invariants-rendering.md

@@ -0,0 +1,160 @@
+# Invariants: rendering — index mapping, gather, LOD and grading
+
+How the renderer maps a visible range onto samples, what `gather()` emits and relative to what, and why a dense trace is drawn one pixel column at a time.
+
+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 renderer maps the visible range onto indices through the series' own x, never the
+  `dx()` grid.** `deps/plotter`'s `Renderer::draw_traces` asks `Series::neighbours()` for the
+  bracketing samples. A grid walk is wrong for exactly the series this app plots: `dx()` here is
+  a nominal spacing (the LOD level, a coarse snap) while the real stamps are the time ring, so
+  the window it computes lands inside the visible range and the two end segments — the ones that
+  draw into the left and right margins — are never emitted. That is the "empty margin when
+  zoomed in" defect. The library test is
+  `a_sparse_window_between_samples_still_inks_both_margins` (a stub whose `dx()` lies, with the
+  window strictly between two samples). It is the guard, not the probe: `[trig-probe/idx]` now
+  computes `got` from the same call the renderer makes, so it cannot catch a renderer that went
+  back to the grid — what it still reports is the drift that made the walk wrong (`dx_ratio`).
+- **`neighbours()` is a binary search over the real stamps in *every* series here, the
+  snapshot's included.** `EventSeries` answered from the `(x - x0()) / dx()` grid — the walk the
+  invariant above condemns: `dx()` is the *mean* spacing of the snapshot's stamps and the stamps
+  are an arrival clock, so grid and clock drift apart by whatever that clock wandered over the
+  capture. The renderer picks its visible index window from this call, so the drift arrived as a
+  **constant offset in seconds** between the axis and the gathered geometry — and a constant
+  number of seconds is a *doubling share of the screen* on every zoom step: 8 ms over a 2 s
+  capture is invisible, and seven halvings later it is 374 px of blank left margin on a 716 px
+  axis, with the ink pushed off the right-hand edge by the same amount. That is the "zooming
+  into a held event clips it more and more from the left while the crosshair still reads the
+  right values" report; the crosshair was right because it reads `x_at()`, a real stamp.
+  `ChannelBuffer` always searched; the two now agree. **A perfectly uniform source cannot show
+  this at all** — three probe runs against the ideal mock were clean — so the guard needs
+  `--clock-jitter` (see `UDPSCOPE_PROBE_EVENTZOOM_MS` above).
+- **The `Series` grid contract does not hold for `ChannelBuffer`.** x is a streamed
+  timestamp, so `dx()`/`x0()` report a nominal grid (LOD level, coarse snap) while
+  `gather()`, `x_at()`, `neighbours()` and `x_bounds()` use the real time ring.
+  Nothing may walk that grid to find *which* samples a range covers — the renderer did,
+  and it lost the two end segments (see the margin invariant above). `gather()` emits x
+  relative to an origin because absolute epoch seconds do not survive `f32`.
+- **`gather()` emits x relative to an origin *the caller names*, in every series here**,
+  `EventSeries` included, and the consumer adds that same origin back in `f64`. Two separate
+  rules live here and both were learned from a defect.
+  (1) **It must be relative at all.** An event's stamps are small (edge relative,
+  `[-pre, +post]`), so emitting them absolute does not overflow anything and does not look
+  like a bug — it just draws the whole capture `x0()` = one pre-trigger window to the left of
+  the axis. That was the "half the plot is empty / the marker sits at the end of the data /
+  nothing is drawn but the crosshair reads values" defect: the crosshair reads `x_at()`, which
+  was right all along. `[trig-probe]`'s `data=` vs `drawn=` is the guard.
+  (2) **The origin is the *view's* minimum, not `x0()`.** `x0()` is the start of the
+  **retained window**, so the f32 had to resolve 2^-24 of the whole ring however little of it
+  was on screen: 1.9 µs over 20 s of retained data, which at a view 10 µs wide across a 716 px
+  axis is over a hundred pixels between where a sample is drawn and the x `x_at()` quotes for
+  it — and it halved on every zoom out, so it read as "zooming in makes the crosshair select a
+  point beside the data". `Renderer::draw_traces` passes `x_range.min`, making the error a fixed
+  4e-5 of a pixel at any zoom. The parameter sits **before** `out_xy` deliberately, so a call
+  site that was not thought about is a compile error rather than silent drift. A caller that has
+  no view in mind may still pass `x0()`, and `[trig-probe]`'s `drawn=`/`data=` does exactly that
+  on purpose: it reads the series' *whole* span, which is the widest relative value a gather can
+  be asked to stage. The two guards are upstream's
+  `a_gather_origin_at_the_view_keeps_a_deep_zoom_on_the_sample_it_quotes` and the
+  `trace ink:` line's `drawn-vs-quoted` figure.
+  **A probe that recomputes what the renderer gathers must pass the same origin the renderer
+  does** (`[ink]` and `[zoom-probe]` both pass the axis minimum), or its reconstruction stops
+  being the renderer's and its pixel readings mean nothing.
+- **Every series bound to a trace must carry a real `MinMaxPyramid`**, including an
+  immutable one. `MinMaxPyramid::level_for()` descends to level 0 — raw samples — on a
+  pyramid with no levels, whatever `n` is, so a series that answers `pyramid()` with an
+  empty one is re-gathered sample by sample on every frame it is bound. That was the
+  "large data is laggy" defect: `EventSeries` had no pyramid, and a held 2 s capture at
+  1 MS/s staged 6 million segments per frame for as long as it stayed on screen. The
+  pyramid lives on `EventSnapshot`, not on `EventSeries`: the snapshot is immutable, so it
+  is built once in `publish_event()` inside the `O(n)` pass that already computes the y
+  bounds, and the same channel on two rows shares it. It costs ≈1 byte per sample per
+  channel. `frame path:`'s `segments` is the guard.
+  **"Every" includes the pause**, and that is the half this invariant was written without and
+  which then went wrong for real: `publish_pause_view()` filled `stamps`, `values` and `y` and
+  left `pyramids` empty, so a *paused* view was re-gathered raw on every frame. Both halves of
+  the cost are readable, and the second is the one a performance line cannot show.
+  `frame path:` read `raw=21 lod=118` over a 1.6 s pause against `raw=1 lod=170` for the same run
+  live, with the draw mean 12.34 → 18.18 ms — and the **trace changed appearance**, which is what
+  gets reported. `stage_trace_density()` grades a column against *its own peak* from a `1/height`
+  deposit per segment, so a column fed ~660 raw inter-sample segments accumulates a far spikier
+  distribution, and a far larger peak to normalise against, than one fed the one or two bucket
+  envelopes the pyramid gives: the paused trace read as a hard bright core with its dwell tail
+  dimmed out. **A pause is not a cheaper case than a capture — it freezes the same rings**, so
+  anything `publish_event()` does to a snapshot, `publish_pause_view()` owes too. Building it is
+  not free (see `publish cost:` below): it took the pause publish from 6.15 ms to 22.31 ms, a
+  one-off producer stall against ~5 ms a frame of draw for the pause's whole length, which at
+  ~60 fps repays about thirty times over on a 1.6 s pause — and the producer absorbs it without
+  losing packets (`gaps=0` with and without a pause, the paused run at an 86 ms publish).
+  **The check that the look is restored is `frame path:` across the pause, not the cost line**:
+  a paused run must read the same path as a live one — measured `raw=1 lod=555 columns=555
+  graded=555` against `raw=0 lod=373 columns=373 graded=373`, same 24711-segment worst frame,
+  segment mean within 5 % — where the defect read `raw=21 lod=118`. A `raw` in the tens over a
+  pause is this returning, and it is the appearance as much as the cost.
+- **`EventSeries::gather()` emits a bucket's envelope, not every `2^level`-th sample.**
+  Point decimation hides exactly the spike the capture was triggered on; a scope has to
+  draw a bucket's extremes. It needs no index rebasing, unlike the ring: the snapshot's
+  pyramid is built from sample 0 and nothing is ever dropped from it, so `window_base()` is
+  0 and a window index *is* the absolute one.
+- **A trace denser than the axis is drawn one pixel column at a time, and that is what keeps
+  the plots free of moiré.** The envelope staged as a polyline banded visibly and *crawled*
+  under a pan on exactly the signals this app is pointed at — a high rate, a high frequency or
+  noise — and three things compound to produce it, none a bug alone: `level_for()` sizes a
+  bucket at one to two pixel columns, `Envelope` emits two points per bucket so each
+  contributes a near-vertical min→max hairline *and* a near-vertical connector (≈3.6 per
+  column per trace), and every one lands at a **fractional** x because a trace is deliberately
+  not snapped. Under src-alpha compositing a column's brightness is then a non-linear function
+  of the sub-pixel phases overlapping it, the pattern repeats at the beat between the bucket
+  pitch and the pixel pitch, and a pan sweeps the beat. `deps/plotter`'s
+  `Renderer::stage_trace_columns()` emits one snapped vertical segment per integer column
+  instead, so the trace has **one** phase and there is nothing left to beat. Four things to
+  know before touching it, all upstream in `docs/data-and-performance.md`: the gate is the
+  gathered **density** (≥2 points per column) and `Envelope`, never the LOD level — the raw
+  path at 1.5–64 spp beats the same way, and the density term is also what keeps the reduction
+  off a *sparse* window whose trace is the two segments entering and leaving the frame; a hole
+  stays a hole; disjoint neighbours are joined so a fast edge keeps its join; and it is the one
+  carve-out in `u_snap`'s "never anything drawn at a data position" rule, because a column *is*
+  a pixel column.
+  **It needs a thin ribbon to be visible at all** — a window whose buckets span several periods
+  paints a saturated block and hides the beat — so a screenshot of a slow sine at a whole-window
+  view says nothing either way. The guards are upstream's
+  `a_dense_trace_is_drawn_as_whole_pixel_columns`, which counts the **distinct coverage levels**
+  in the ink (4 against the polyline's 126; a count of *partially covered* pixels separates
+  nothing, 577 against 652, because a 1.5 px stroke's fringe always spills into the next
+  column), and `frame path:`'s `columns=` field here. `trace ink:` deliberately cannot see this
+  path: it recomputes the **gathered** points, which the reduction is downstream of, so its
+  `drawn-vs-quoted` reads 0.0000 either way and remains the guard for the gather origin alone.
+- **A reduced column is graded by dwell, and the grading may not undo the reduction.** The
+  column above is honest about *where* the signal went and silent about *how long it was there*
+  — a column's min and max are identical whether its samples fill the span or pile at its two
+  ends, so a ramp and a pulse are one flat band. `Style::intensity_grading` grades it instead
+  (bright where the signal sits, faint where it only passes through, the digital-phosphor look),
+  and **udpscope turns it on; the library's default is off**, so other hosts are not restyled by
+  an upgrade. The switch is a one-shot in `tick()` guarded by `App::style_stated`, not a line in
+  the window build: `PlotArea::renderer()` is null until the area is realized, so there is no
+  earlier place to state a style. Three things to know here, the rest upstream in
+  `docs/data-and-performance.md` (the `1/height` dwell weighting, the one-column accumulator, the
+  per-column-peak normalisation, the quantised alpha steps):
+  * **The finer gather level is floored at 1 whenever the flat path would have used the
+    pyramid.** Grading asks for `samples_per_pixel / intensity_sub_columns`, and
+    `MinMaxPyramid::level_for()` answers **0 — raw samples** — as soon as that falls under one
+    bucket (`kBucket` is 64). Unfloored, every moderately dense frame became an O(visible)
+    gather: at 1.3 MS/s over a 2 s window, 172 samples a pixel, `raw=1154 lod=0` against the flat
+    path's `raw=710 lod=453`, and 2.30 → 6.36 ms of draw mean. The floor degrades the *look*
+    (fewer sub-columns than asked for, down to what the coarsest buckets give — still two or
+    three per column at 64 samples a bucket) and never the path. It is also why
+    `intensity_sub_columns` past about 8 buys nothing: the bucket size is the limit.
+  * **`graded=` must equal `columns=`** in `frame path:`, and `UDPSCOPE_NO_PHOSPHOR=1` is the A/B
+    that makes either line readable against the ungraded path (see
+    [probe-readings.md](probe-readings.md)).
+  * **The steps are draw calls, not per-segment alpha.** `LineInstance` is four floats of
+    geometry and the colour is a **uniform** (only `TextInstance` carries `a_colour`), so the
+    gradient is `intensity_steps` `LineBatch`es flushed at different alphas. That is why the
+    segment mean rises from 131 to 1340 on the same frames — the rise is the tiers, not extra
+    geometry per column, and the bound is still `axes.w` (measured 14.5 runs a column in the
+    library's own guard, 8303 segments over a 572 px axis).
+  The guard is upstream's `a_dense_trace_can_be_graded_by_dwell`, which draws one frame both ways
+  and profiles the band's outer fifths against its middle: flat reads **191/191**, graded
+  **191/131**. That 0.69 is a *tier* ratio, not the dwell ratio — `intensity_gamma` (0.45) and
+  `intensity_floor` (0.3) compress it deliberately, the floor so that a fast riser, one
+  sub-bucket deep everywhere, is never dimmed out of existence.

docs/claude/invariants-session-and-export.md

@@ -0,0 +1,164 @@
+# Invariants: the session file, the export and the source chooser
+
+What a session persists and in what order, when a save is refused, and when an export is collected.
+
+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 trigger is persisted, settings and state both.** Its condition, its channel (by *name*), its
+  pre-trigger share, hold-off and mode, and whether trigger mode was on — written even while it is off,
+  because a trigger configured once and switched off is still the trigger you come back to. The two
+  enumerations are stored as the *words the panel's dropdowns show*, not as their indexes: an index ties
+  the file to a declaration order, which is the lesson `math_op_at()` carries, and the words are shared
+  with the panel so the two cannot drift. The channel resolves when the acquired channels exist
+  (`rebuild_trigger_signals()` picks up `App::pending_trigger_channel`, or `apply_trigger_layout()`
+  resolves it itself when they are already there) — a name that resolved to nothing would silently move
+  the trigger to channel 0.
+- **A session that loaded is what locks the two panes.** Locked is the returning user's mode: the
+  trigger pane shows one compact line, the signal list only the signals that are on, and neither offers
+  a control that changes the configuration. A *first run* — no session file for that source — never
+  reaches `apply_layout()` and stays in configuration mode, which is what a first run is for. The mode
+  is a mode and not a setting: it is deliberately not persisted, so a scope reopened tomorrow starts
+  where a returning user expects to start. **Dragging a row onto a plot is not configuration and survives
+  the lock**: filling plots is what the list is *for*, so a locked row keeps its `GtkDragSource` — from
+  anywhere on it, the colour chip included, which in configuration mode has a click gesture that claims
+  the sequence precisely so a drag cannot start there. `drag_sources` on the `signals panel:` line is the
+  reading, and it must be `rows - 1`.
+- **The session is the layout.** `LayoutState` persists what makes a reopened scope look like the
+  one that was closed: the window, the rows and their slot signals, the calibration, **the enabled
+  signals**, **the chosen trace colours** (`[[color]]`, `name` + `rgb = "#RRGGBB"` — only the
+  *overrides*, so a stream's new signals still take the positional palette and a saved session does
+  not freeze a colour that is meant to follow the signal list), **the math channels with their
+  graphs**, **the measurements pane**, and **`measure_stats`** — the measurements statistics
+  toggle; written as a bare top-level boolean (`measure_stats = true/false`), defaults to `false`
+  when absent. Signal identity
+  is the *name* throughout (a CONFIG renumbers channels), 'enabled' is read off the channels the
+  model built -- an enabled signal is exactly one that produced a channel -- and `apply_layout()`
+  installs the graphs **before** assigning the rows, since a row may hold a math channel's name and
+  that name is only a signal once its graph is in. Two format rules, both learned the hard way:
+  write an op or a measure *type* as its index through `math_op_at()`/`measure_type_at()`, never as
+  the raw enum value -- those accessors' orders are the dialog's, not the declaration order, so
+  writing one and reading the other silently renames operations. And a top-level key written after
+  a `[[table]]` belongs to *that table* in TOML: `enabled = [...]` emitted after `[[calibration]]`
+  was parsed into the last calibration record and the enable state was lost without a word.
+  `mkdirs()` used to create only components with a trailing slash, so `~/.config/udpscope` was never
+  made and the *first* save failed silently -- worth knowing when a layout change "does not stick".
+- **Measurement options persist under *named* keys -- `threshold`, `threshold2`, `noise` and `hf` -- so a
+  file written before them loads at the defaults**, which are exactly the behaviour it was written against:
+  `noise = 10` is the
+  hysteresis band the app has always counted with, `hf = 0` is no filter, and a file with no
+  `threshold2` -- every file written before `between` existed -- leaves that measurement at
+  `threshold2 = 75`, which is the value the dialog offers a new one. The *pair* is stored as written
+  rather than as ordered: `measure_level_pcts()` is what puts a reversed pair in order on read, so a
+  file records what the user typed and a measurement file round-trips unchanged.
+- **The math node string is thirteen pipe fields, and the reader accepts twelve *or* thirteen.** `med_n` is
+  the thirteenth, after `y`; a twelve-field node is a file written before the de-noise node existed, and its
+  `med_n` stays at the struct's default -- which is what such a file meant. Field 0 is the op as a
+  `math_op_at()` index, which is why `MathOp` may only be *appended* to.
+- **The export is collected at click time, not in the file-dialog callback.** The live
+  view keeps scrolling while the chooser is up, so a late collection would write a
+  window the user never saw. The writer is picked by the chosen path's extension.
+- **The MDF export is MDF 3.30 written by hand, and its layout is the reader's, not the
+  standard's prose.** No dependency is added: MF4 is HDF5 and would need a library, while MF3 is a
+  handful of fixed-size blocks, so `write_mdf()` spells them out. The field list comes from
+  `asammdf` 8.8.27 (`blocks/v2_v3_blocks.py`, `blocks/mdf_v3.py`, which parses MF3 by explicit
+  offsets) and was confirmed byte for byte against a known-good 3.30 file asammdf wrote (one
+  group, a `time` master and two `V` channels). The shape, in file order: the **ID block** is 64
+  bytes with *no id/length header* (`"MDF     3.30"`, byte order, version `330`) — a writer that
+  emits `ID` + size + links at offset 0 produces something no reader accepts, since the first real
+  block starts at 64; the **HD block** is 208 (164 common + 44 of the 3.2-era time fields) and
+  points at the data group; a **TX** comment follows it; then the **samples**; the **DG** is 28; a
+  **CC** (conversion, 46 — a `NONE` conversion is the common fields alone) then a **CN** (channel,
+  228) precede each channel; and the **CG** (30) is last. Address fields are absolute file offsets
+  written *forward*, so the whole address map is computed before a byte is written, and every
+  block length is checked after it is built: a field at the wrong width does not fail the write, it
+  leaves the reader in the middle of the next block.
+- **The data group's data address holds the raw records, with no `DT` header** — which is what
+  asammdf's *writer* does and what its *reader* assumes (`DataBlock` is documented as "a pseudo
+  block not defined by the MDF 3 standard"). This is the one place the file follows the reader
+  rather than a narrow reading of the standard, and it is the assumption ScryLab compatibility
+  rests on: a file with a `DT` block there would have its header read as sample bytes.
+- **In MDF the master is `abs_seconds`, named `time`, and the relative axis is a channel
+  `time_relative`** — the same two numbers the `.npy`/`.csv` table holds, in the other roles. A
+  master off the relative column is 0 at a different sample in each display mode, so it would put a
+  live export and a held event's export on two timelines, which is the one thing the second column
+  exists to avoid; both carry the unit `s`, and the signal columns follow in the `.npy`/`.csv`
+  order. **The unit** is the client's CONFIG unit (a math channel's own), and it is written into
+  the CC block because that is the only place MDF 3 keeps one — and the place ScryLab reads a
+  signal's unit from. `ExportTable::Column` gained the field for it; the two older writers ignore
+  it, and their bytes are unchanged. **The names** are sanitised and de-duplicated against each
+  other *and* against the two reserved names before being cut to 31 bytes (the CN name field is 32
+  with its NUL): ScryLab imports only the **first** occurrence of a channel name, so a cut made
+  before de-duplication could silently drop a signal. `write_export()` is the one place the
+  extension picks the writer (`.csv`, `.mf3`/`.mdf`, anything else `.npy`), and both the dialog and
+  the self-check's export probe come through it so the two cannot offer different formats.
+- **The chooser runs before `ScopeModel` exists, and `--server` is what decides.** `Config` carries
+  `server_specified`, set only by the `--server` branch, and `main()` asks only when it is false —
+  so declining costs no buffer and no socket, and `ScopeModel`, `Acquisition`, `RowSet` and
+  `run_ui()` need no notion of "no source yet". It is `--server` alone and not "no arguments":
+  `--multicast` still needs a server to fetch CONFIG from. **Every documented probe passes
+  `--server`**, which is what makes the feature invisible to the regression net — a probe added
+  without it would reach the chooser and hang. `gtk_init()` plus a nested `GMainLoop`, and then
+  `run_ui()`'s `GtkApplication` afterwards in the same process, is a verified combination
+  (`gtk_init()` is idempotent; running your own loop is the documented GTK4 replacement for the
+  removed `gtk_dialog_run()`).
+- **A session file's name cannot say how its source was reached, so the file says it.**
+  `<host>_<port>.toml` carries neither the multicast group nor the interface, so a chooser row
+  could not reconnect to a multicast source at all. `LayoutState::multicast`/`interface_addr` are
+  written in the **top block, before the first `[[table]]`** — a bare key after a table header is
+  that table's key in TOML, which is exactly how `enabled` was parsed into the last
+  `[[calibration]]` record and lost without a word. A file from an older build has neither key and
+  loads as unicast on the default route. The chooser's list filters to sessions that **name at
+  least one signal**, because a probe run leaves a file per throwaway port and all of them hold
+  `signals = ["", "", "", ""]`; `known_sources()` splits the filename at the **last** `_`, since
+  `sanitize()` turns anything unsafe in a host into one.
+- **`save_layout_now()` refuses to write while `signals()` is empty.** A run against a source
+  whose streamer was down receives no CONFIG, so every slot name stays empty and the save would
+  overwrite a configured session with `signals = ["", ...]`. The chooser then filters that file
+  out — a source whose streamer was merely down during one run would silently vanish from the
+  only list it can be picked from, for ever. Keeping the old file loses nothing: a run that
+  configured nothing had nothing worth persisting.
+- **It refuses again while `replaying` is set: a file view is not the source's session.** Same
+  argument, different cause — this view configured nothing about the stream. A plain replay leaves
+  the rows where the user put them, so its save would merely be pointless; a **group** rebinds every
+  slot to its own renamed channels and the save wrote `signals = ["square (A)", …]` into the file.
+  Nothing noticed until the way back: *Go live* re-applies the session, those names match no live
+  signal, so nothing was enabled and **the live view came back with no channels at all** — on the
+  window the poisoned file carried, which is also how it swallowed the window restore below it. The
+  reading is `[events] live restored (after a group)`: the symptom was a stuck `pending=1` beside
+  `channels=0`, because the restore waits for a channel list that was never going to arrive. The
+  explicit *Save as* is deliberately **not** guarded: that one is a user's own answer to "save this
+  view", and its dialog reports the outcome.
+
+## A configuration is a named session, and a source may hold several
+
+One source, several arrangements: the same streamer serves different experiments, and retyping a
+layout to look at the second one is how a session gets lost. Storage is therefore a **directory
+per source** — `~/.config/udpscope/<host>_<port>/` — holding one `<name>.toml` per configuration
+plus an `active` file naming the one the source is on. `configuration_path()` is the only
+expression of the scheme, and the name is `sanitize()`d exactly as the host is, so a name typed
+with a slash cannot escape the directory.
+
+A configuration carries the whole session *and* the settings that can only be decided before the
+first socket: `buffer_mb`, `relative_time`, `capture_packets`. The startup chooser applies them
+(`apply_source()`), which works because `choose_source()` runs before `ScopeModel` is constructed
+— the one moment a buffer size can be applied at all. Switching configurations inside a running
+app applies what can change live and says in the status line that the rest takes effect on the
+next start; pretending otherwise would be a configuration that half-applies.
+
+A configuration's *startup* settings reach the model from two directions, and both are needed:
+`apply_source()` for a source picked in the chooser, and `apply_stored_settings()` for a source
+named with `--server`, which never reaches the chooser at all. Without the second, a saved host's
+buffer size, clock and capture ring were silently ignored — the layout still applied, because the
+app loads that separately once a CONFIG names the signals — so an edit to any of the three read as
+one that never took effect. **A flag the user typed wins over the file** (`--buffer-mb`,
+`--relative-time`, `--capture-packets`): the file fills in what the command line did not say, and
+`Config::buffer_mb_specified` is what tells "not asked" from "asked for the default".
+
+The `active` file is written on every save and by the chooser's pick, so "which configuration was
+I on" survives a restart. A session written before configurations existed is **imported once** as
+the configuration named `default`, and the old file is renamed to `<host>_<port>.toml.imported`
+rather than deleted: an import that cannot be undone by hand is a migration nobody can back out
+of.
+
+Nothing is lost by switching: the dialog saves the current session *before* loading the picked
+one, which is the only ordering in which a switch cannot lose what it switches from.

docs/claude/invariants-time-axis-and-window.md

@@ -0,0 +1,98 @@
+# Invariants: the time axis and the window control
+
+What may change the time scale (one function, one caller), how the x labels pick their form, and what a fit restores.
+
+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 window control's label is width-locked and ellipsized** (`kWindowLabelChars`), for
+  the same reason as the status label: it sits in the header bar above the plot, so a label
+  that grew from `1 s` to `123.456 ms` would widen the bar and relayout everything under it
+  on a mere change of window. That is also why the window is typed into a popover rather
+  than shown in the bar.
+- **No plot interaction changes the time scale; only the window control does.** The *time scale*
+  is more than the axis: `RowSet::window_s_` also feeds `ScopeModel::set_event_span()` (the
+  trigger's pre-trigger share is a share of *this* window), `ScopeModel::set_target_span()`
+  (which may re-plan the partition, move the decimation and **drop the history**), the window
+  control's readout and the session file. A **zoom or a pan** does not touch it by construction —
+  the controller writes the *member* axis and `clamp_to_data()` caps the span at `window_s_`, so
+  nothing has to be written to keep it that way. **Neither do the two fits**: a fit is the
+  *undo of a zoom*, so `RowSet::fit_x()` restores the window that is already set and reads
+  `window_s_` without ever writing it. Both fits used to frame the *data* instead and move
+  `window_s_` alone, which was wrong twice over — a gesture-triggered re-plan of the rings, and
+  an event span left on the *old* window until the next decade step or unit change applied the
+  fitted value for real (one action, two changes of time scale).
+- **`apply_time_window()` is the only place the time scale changes**, and the window control is
+  its only caller. It clamps to `window_limit()` and moves `set_target_span()`,
+  `set_event_span()`, `RowSet::set_time_window()`, the control and the session save together —
+  the partition **before** the axis, so the axis is framed over the rings that will exist. A fit
+  must not come here for two reasons: it is not entitled to the scale at all, and
+  `set_time_window()` unpins and re-arms the live follow, which would throw a held event or a
+  paused view onto a live edge it has nothing bound to. Paths that change the span for their own
+  reasons (an event pin) call `sync_window_display()` alone, which only restates the control and
+  never moves the plot — calling `apply_time_window()` there would clamp a legitimately short
+  capture up to the requested window.
+- **With nothing bound, `set_time_window()` frames `{-window, 0}` and never `{0, window}`.** Under
+  a following x group a range states two things — its span, and *through its maximum* where the
+  window sits behind the live edge — so a maximum **at** the edge is what makes the offset zero.
+  When there is a live edge to read that is `{newest - window, newest}`; when there is not, the
+  edge the live view would put at x = 0 is 0, so the equivalent statement is `{-window, 0}`.
+  Asking for `{0, window}` there is an offset of a *whole window*. This is not a rare fallback:
+  "no samples bound" is the state every structural change leaves behind, and
+  `apply_time_window()` re-plans the rings and *then* calls this, so it is the axis a mode change
+  is drawn with until the first sample lands. With `{0, window}` the two or three frames after
+  every event or waveform open drew the time base one screen to the left of where the following
+  frames drew it — a trace that jumps a screen sideways and comes back, which is what "opening
+  events or even waveform sometime result in data flickering (like time base) and is unusable"
+  was. The reading is the dump's traceless paint counts: `mode=live` 38 → 0 and `mode=waiting`
+  2 → 40, the latter being the point — a waiting view now paints its empty axis in the *same*
+  place every frame instead of twitching into a framed one.
+- **The x labels go relative on the tick *step against the label resolution at the axis'
+  magnitude*, never on the span.** `RowSet::update_time_labels()`'s question is only ever "can
+  this step be written at this magnitude": `TickFormat::Time` carries three significant figures
+  below a minute, **whole seconds** through `m:ss`/`h:mm:ss` up to a day, and three figures of
+  days above — so the resolution is a step function of the magnitude, which `time_label_resolution()`
+  states and nothing else may re-derive. The old test was `span < 1.0` and it was wrong in both
+  directions: a 2 s window at twenty minutes of uptime reads `20:00` on every tick and stayed
+  absolute, and a **triggered** sub-second window — whose axis is already `[-25ms, +25ms]` about
+  the edge — went relative and so re-anchored its ticks *away from the trigger*, with a `t0`
+  caption that had nothing to explain. Three details hold it up. The step is read back from the
+  majors the **last layout** produced, which is not a feedback loop (a tick's value depends on the
+  range and the axis' pixel width, never on the label form) but *is* absent before the first
+  layout — and with no ticks the form must be **left alone**, because a step guessed from the span
+  would be latched by the hysteresis below. The hysteresis is a 1.05 band on *leaving* the relative
+  form. And *entering* it needs a ULP of slack (`1 - 1e-9`): a step differenced from two tick
+  values and a resolution from `pow(10, n)` differ in their last bits when they are the same
+  number, and `step == res` is a readable axis (`1.73s`, `1.74s`, `1.75s` — one in the last digit
+  is exactly enough), so the bare comparison picked a different form from one frame to the next.
+  The guard is `[timelabels-probe]`'s `distinct=1`, which asserts what the form is *for* rather
+  than which form a given window gets.
+- **The `t0 = …` caption is chrome, never an annotation.** It is `Plot::set_x_note()` (added to
+  `deps/plotter` for this), drawn by `Renderer::draw_x_note()` on the legend's own
+  `draw_readout_panel()` backplate in the bottom-left corner of the axes, in **pixels**. It was an
+  `Annotation` first, and an annotation's anchor is a *data* coordinate: the caption therefore
+  crawled across the plot under a pan and drifted under a zoom, which is what "[t0=...s] move
+  slightly around when user zoom/pan" was. Three things follow. The **text is the host's**, because
+  the caption has to name the anchor precisely enough that label + caption is the exact absolute
+  time and `format_time()` would round it to three figures (`"t0 = %.6g s"`); only the **bottom
+  row** of the figure carries one, every other row being set to `""`; and the renderer measures it
+  rather than `Plot::layout()` — it reserves no space and nothing can be picked on it, so there is
+  no rect to read back, and a caption explaining the x labels must not be able to move the layout
+  those labels were measured into. The guards are the library's
+  `the_x_note_is_chrome_that_a_pan_or_a_zoom_does_not_move` (the footprint is the pixels a frame
+  with the caption differs from one without, and a pan plus a 64× zoom must give the same box to
+  the pixel) and `[timelabels-probe]`'s `note=`, which reads `Plot::x_note()` back.
+- **`fit_x()` restores the *whole of what the view may show*, which is not always `window_s_`.**
+  Live, that is the newest `window_s_` at the live edge (`set_time_window(window_s_)`, the same
+  path a resume takes). Pinned — a held event, a filling capture or a paused view — it is the
+  **pin's** full range, which is the snapshot's own stamps and may be legitimately *narrower*
+  than the requested window. It must write the per-row **member** axes as well as the link group:
+  `hold_pinned_window()` prefers a member that differs from `pinned_stated_`, which is how it
+  tells a real gesture from its own echo, so writing the group alone is reverted to the zoomed
+  range on the next frame. `fit_all()` is the y fit plus this, shared rather than duplicated so
+  the two cannot drift apart.
+- **Relative time is decided by the newest statement, not by the default.** `Config::relative_time_specified`
+  is set by `--relative-time` and by the preferences — which the source chooser can reach before the run
+  is planned, so that is the one place a preference still changes *this* run. Both the list's own copy
+  (`apply_source()`) and a source's stored configuration (`apply_stored_settings()`) only fill in when
+  nothing newer was said. Without the marker, clicking a source row after applying the preference
+  silently reverted it — `[sources] picked ... relative=0`, with the dialog having just written `1`.

docs/claude/invariants-trigger-and-pinning.md

@@ -0,0 +1,622 @@
+# Invariants: the trigger, the capture and a pinned view
+
+The four display modes' framing rules: what the event window is counted in, what pins an axis, and what each pin is measured from.
+
+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.
+
+- **`clamp_to_data()` caps the span at the *requested window*, never at the retained
+  span.** It runs every frame and cannot distinguish "the user zoomed out past the data"
+  from "the ring has only just started filling", so `window_s_` — what the window control
+  states, capped by `--max-window` — is the bound. Clamping to `retained` alone turned a
+  requested 2 s window into the ~0.02 s the first frames held, permanently: nothing there
+  grows a span back. Loosening it to `max(retained, window_s_)` fixed that and broke the
+  other state instead — while the ring is filling the two are equal, but once it holds
+  more than the window the bound becomes the whole ring, and a wheel zoom-out walked the
+  view into data the window was never set to show. `window_s_` is right in both: it never
+  shrinks a window a caller asked for, and a partly filled buffer is left empty on its
+  left, which is what a scope that just started should look like. `UDPSCOPE_PROBE_PAN_MS`
+  reports it as `zoom ... span=.. window=.. limited=1`.
+  Its pan clamping is likewise gated on the data being wider than the view, or the empty
+  left-hand side drags the live edge off the right-hand edge.
+- **The compact pane's arm control is built in the heading, and *one* function states both arm
+  buttons.** Arming is a runtime decision and the locked pane is exactly where it is made, so the
+  control cannot live in the body — that is the part which goes away. `sync_arm_buttons()` is what
+  states the label, the sensitivity and the visibility of both buttons, and it is called from the four
+  places any of its three inputs can change (the click, the toolbar toggle, the curator's re-read,
+  `apply_pane_lock()`). Visibility is `enabled && locked`: with trigger mode off the line beside it
+  already says "stream (trigger off)" and there is no engine to arm, and with the pane open the body's
+  button is the one on screen — **two arm buttons at once would be two controls for one state**, which
+  is why the probe reads the body's allocation as `-1` while the compact one is up.
+  **The same function states the Force button beside the arm one, and the Force button is in the body
+  only.** Its sensitivity is the same `enabled` (a trigger that is off has no engine to force) and it
+  is stated in `sync_arm_buttons()` for the same reason the pair above is stated there — one place, so
+  nothing can drift — but it is *not* armed-gated: in Single mode the previous acquisition leaves the
+  engine disarmed, which is exactly when a user reaches for Force again, so a button that greyed out
+  with the engine's armed state would be unavailable for the one thing it is for. It stays in the body
+  because the heading's single control is the runtime *state* a locked pane exists to change, while a
+  force is an action whose subject — the condition, the level, the pre/post split and the mode that
+  decides whether one acquisition is all of it — is in the body; a second Force in the heading would
+  be a second control for one action whose settings are off screen.
+- **A widget's allocation is not readable in the tick it is first shown.** The compact arm control is
+  created hidden and shown for the first time inside a signal handler, so `gtk_widget_get_width()` in
+  that same tick reads `0` while `gtk_widget_is_visible()` already says `1` — and its sibling's stale
+  allocation (270 px, from when the *body* was still on screen) reads as a live one, because
+  `gtk_widget_get_visible()` is the widget's *own* flag and stays true under a hidden parent. The width
+  only becomes the proof that a control is on the surface **one frame later**, which is why the probe
+  has a `compact_arm_step()` of its own; and the control to compare against must be measured with
+  `is_visible()` or not at all.
+- **Signals start disabled** — enabling is what starts acquisition. A trigger on a
+  signal nobody acquires can never fire, so selecting/arming enables it. **And the signal is resolved
+  *through* the channel, never taken as one.** `TriggerConfig::channel` indexes `channels()` (the
+  acquired ones) while `ScopeModel::set_signal_enabled()` indexes the stream's `signals()`, and the
+  two are not the same index: with one signal acquired, channel 0 *is* that signal while signal 0 is
+  the stream's own clock. Passing one for the other switched on the time base, left the signal the
+  trigger watches exactly as it was — and, because a signal the panel was not showing *is* a change,
+  rebuilt the buffer under the click and dropped its history, which is precisely the pre-trigger
+  window an arming, and now a force, was about to capture. `trigger_signal_index()` is the one
+  resolution and both buttons go through it.
+- **The trigger's event window is separate from the display window**, and
+  `pretrigger_pct` is a share of the *event* span, not of the ring.
+- **The event window is counted in stream seconds end to end; nothing converts it to
+  a sample count.** `TriggerEngine` latches once the stamps it is fed have advanced
+  past the post window, and `ScopeModel::publish_event()` cuts the snapshot by binary
+  search over the time ring. There used to be a measured samples-per-second estimate
+  in `Acquisition` doing that conversion, and it is precisely why the post window came
+  out empty: any stream whose time signal advances in large steps drove it to its
+  1 S/s floor, the count came out as 1, and the engine latched on the edge sample
+  itself. **Do not reintroduce a rate estimate on this path.**
+- **The engine identifies its channel by *name*, never by index.** `TriggerEngine::configure()`
+  drops an open capture when the trigger moves to a different channel, and it is re-called from
+  `Acquisition::on_data()` on **every packet** out of `model_.trigger()`. `TriggerConfig::channel`
+  is an index into `channels()`, and that index is not stable: every rebuild of the channel list
+  renumbers it — enabling a signal that sorts before the trigger's own is enough — and
+  **`ScopeModel::rebuild_channels()` re-resolves the trigger by name and writes the *new* index
+  back, for every caller.** It lives there and not at the call sites because the function *is* the
+  renumbering, and a caller that forgot is a trigger that silently stops: the name-based restore
+  used to be in `rebuild_enabled_locked()` alone, so adding or removing a math channel went through
+  `set_math_channels()`'s structural path with no restore at all, `rebuild_locked()` clamped the
+  now-wrong index to `-1`, and `process()` returns at once on a channel of `-1` while the panel went
+  on naming the channel. That is the second half of the "it sometimes does not trigger, even with
+  the trigger on a non-math channel" report. Keying the reset on the index made any such rebuild
+  abandon the capture **and
+  set no hold-off**, so the next edge inside the post window became t0: that is the "the trigger
+  re-triggers during a capture and the hold-off does not apply" defect, and it needed no glitch
+  and no user action beyond enabling a channel. The name changes when the source genuinely
+  changes, so a deliberate re-point still resets. The rebuild also replaces the `BufferStore`, so
+  the surviving capture's pre side is short and the snapshot reports its own `pre_s` — which may
+  be **negative** when the new ring starts after the edge. That is a faithful reading, not a
+  defect: `[-pre_s, post_s]` still describes the samples the snapshot holds. The guard is
+  `UDPSCOPE_PROBE_TRIGRENUM_MS`, whose `t0_held=1` is the assertion.
+- **`EventCondition` carries the trigger's own rejection: `noise_band` and `hf_fc`.** Both are in the
+  struct's `operator==`, so a change to either *is* a change to the condition. `EventDetector::configure()`
+  takes `dt` and early-returns only when the condition **and** the interval are unchanged -- it runs on
+  *every packet*, so a configure that reset unconditionally would restart the machine before any pulse could
+  close. `dt` is `Partition::slot_dt()`, the *stored* interval and not the CONFIG's nominal rate, and comes
+  from exactly three call sites (`acquisition.cpp`, `ui_trigger.cpp`, `ui_probe.cpp`); a zero there leaves
+  the reject's coefficient at 1, which is a pass-through.
+- **A crossing is a change between two *decided* sides, never a change from the undecided one.** The band
+  makes each sample decide above / below / undecided, and an edge is counted only when the signal has reached
+  the far threshold of the side it is leaving. Seeding the previous side from `0` -- the undecided code --
+  fires on a signal that starts *inside* the band and leaves it without ever reaching the level, an event the
+  trigger is not supposed to see.
+  **A pinned window is *clamped* into the event every frame, and a zoom in is allowed.**
+  While an event is held, a capture is filling, or the view is paused, `tick()` calls
+  `RowSet::hold_pinned_window()`, which caps the span at `[-pinned_pre_, +pinned_post_]`'s and
+  clamps the position into it (and states `Off`, since a following group would re-derive from a
+  live edge). **A zoom in must keep working** -- "not outside the event" is not "not readable",
+  and this function's first version *re-stated* the pin every frame, which made the wheel a no-op
+  in single trigger mode: an acquired event could not be examined at all.
+  **What a gesture inside the pin may *not* move is a measurement**, and it is not this function
+  that holds that: `pinned_range()` is the one expression of the pin's extent, and
+  `update_measures()` measures *it* rather than the viewport while the view is pinned, so a pan
+  or a zoom on a still frame changes no value and spends no recompute (see
+  [invariants-measurements.md](invariants-measurements.md); `[measurepin-probe]` is the reading,
+  `pin=`/`for=` in `[measure-trace]` the field to watch). The pin is therefore load-bearing twice
+  over, and a change to what `pinned_range()` says changes both the framing and the numbers.
+  **The request is read from the row's own axis, not from the group.** A member's `set_x_range`
+  -- what the controller writes for a gesture -- is *not* adopted into the group while the follow
+  is off, so a clamp that read the group only ever saw its own previous answer (the probe showed
+  `group` and `member` both equal to the pin while the ask was gone). `pinned_stated_` remembers
+  what the clamp last wrote: a member that matches it is our own answer coming back, one that
+  differs is a gesture to honour -- which is also what keeps a *fresh* pin
+  (`pin_event_window()`, `pin_pause_window()`, both of which write the group in the same tick)
+  from being reverted to the member's stale window. Without it nothing bounds a drag or
+  a zoom in those states: the library clamps a *following* group's offset only, and the live
+  clamp is deliberately skipped here — so a gesture walked the frozen view off its axis, over
+  data the scope never had. The two are one branch in `tick()` for that reason. A paused view
+  pins the same way (`pin_pause_window()` sets `pinned_` from the frozen range), so the frozen
+  picture is equally immovable; resuming or leaving trigger mode clears it.
+- **An opened file is a pinned view too, and *how* it is pinned matters as much as that it is.** The
+  file view states its pin from the ring's own stamps every frame, and it used to do that with
+  `pin_event_window()` -- which writes the group's range as well as the pin's numbers -- so a box zoom
+  drew its frame and changed nothing: the controller's `set_x_range` went onto the *member*, the next
+  frame's re-statement put the group's range back, and the branch it fell into (`clamp_to_data()`,
+  because a file is neither `event_held` nor `Paused` nor `capturing`) never adopts a member into a
+  group that is not following. That is the wheel-in-single-trigger defect again, in the one mode nobody
+  re-tested. Two things hold it now: the branch is `Paused || capturing || rows->window_pinned()`, so a
+  pinned view is always clamped by `hold_pinned_window()`; and the file's per-frame statement uses
+  `set_data_pin()` -- the pin's numbers -- unless `pinned_window_is()` says the pin is a *different*
+  window, which is a re-open with a new extent and is a new event, stated in full. `[boxzoom-probe]`'s
+  `zoomed=` is the guard, and it is a reading to take in **both** modes: live and file must both read
+  `1`.
+- **`set_data_pin()` takes a *range*; `pin_event_window()` and `pinned_window_is()` take the pre/post
+  *split*.** The three are used in one breath by the file view's statement and by the held event's, and
+  the two forms are not interchangeable: for data over `[lo, hi]` it is `set_data_pin(lo, hi)` against
+  `pin_event_window(-lo, hi)`. Handing the split to `set_data_pin()` stores the pin as `[lo, -lo]`-ish,
+  so the next frame's `pinned_window_is()` reads false, the pin is stated in full again, and the view
+  alternates between the file's span and the corrupted pin at the frame rate -- the flicker in which no
+  interaction survives, because every second frame rewrites the group's range. It is invisible on a file
+  whose stamps are all positive (the corrupted pin is then *wider* than the data and
+  `hold_pinned_window()` never clamps) and on one that ends at 0 (the pin inverts, and the clamp returns
+  early), which is why it reached a user on a recording spanning `[-4..16]` and nothing before it.
+  `[drop-probe]`'s `repins=` is the reading: **2 for a whole run**, not one per frame.
+- **A pinned view is navigable *within its data*, and that is the bound -- not the request.**
+  Two things had to agree for this, and both were wrong in the same direction:
+  the **pause** pinned on the window it asked for rather than on the snapshot it got (a cut
+  clamped to the ring is shorter), and the **held event** pinned on the snapshot's recorded
+  `pre_s`/`post_s` -- the *request* again -- which a capture shorter than the request exceeds.
+  Either way the shortfall was drawn as an empty margin, and a zoom-in moved the view *into* it,
+  which is what made it look as if zooming caused it. `tick()` now re-states the pin from
+  `RowSet::event_data_window()` (the bound **event series'** own stamps) while an event is held,
+  from the snapshot's stamps on a pause, and `pin_pause_window()`/the pause handler set the axis
+  to it as well; `[pause-probe]` prints `axis=` beside `frozen_x=` and the axis must lie inside.
+  A `Capturing` view is the exception and stays on the *requested* `[-pre, +post]`: its post side
+  is empty on purpose, and that is the capture filling in view, not a margin.
+- **A pause is pinned from its snapshot's own stamps too, not from the window it requested.** The
+  pause freezes the *visible window*, but `publish_pause_view()` cuts that window out of the ring
+  and the cut is clamped to what the ring holds -- so a window reaching back past the oldest
+  retained sample produces a *shorter* snapshot. Pinning the axis to the request left the shortfall
+  as an **empty margin on the left**, visible before any zoom and made worse by one: zooming in
+  moved the view *into* the empty part, which is what made it look as if zooming caused it. The pin
+  is the snapshot's own stamps now. `[pause-probe]` prints `axis=` beside `frozen_x=`, and while
+  paused **the axis must lie inside `frozen_x`** -- equal at the moment of the pause, a subset
+  afterwards if the probe zoomed in. Before the fix the two disagreed outright:
+  `axis=[-1.44..0.56]` over data that started at `0.0`. (The event pin already worked this way; the
+  pause now agrees.)
+- **The pause reads the display offset *before* it sets the pause state, and a pause taken on a
+  held event depends on that order.** `on_pause_toggled()` reads the row's axis and
+  `stream_at_x0()`, cuts `view + offset` out of the ring, and hands the same offset to the
+  snapshot as its `x_offset`. `stream_at_x0()` follows the *display*: the moment `paused` is true
+  with no pause view published yet it answers `-display_epoch()`, which on a `Held` view is **0**
+  -- so the cut searched the ring at the event's edge-relative x, found nothing, and froze an
+  **empty** picture: `ev=0` on the probe's line, every measurement `--` and every ruler gone,
+  which is a much louder symptom than the empty margin above and reaches a user the same way
+  (pause while an event is on screen). Read first, it is the offset the axis is actually
+  displaying, which is what the whole scheme requires. The live case is unchanged -- there the
+  epoch does not depend on `paused()`, which is why the pause probe, which pauses a *live* view,
+  never saw it.
+- **The event axis is pinned from the snapshot's own stamps, not from the request.** A
+  capture may legitimately be shorter than asked for — the ring need not reach back a
+  full pre-trigger share on the first latch after arming, so `snap=[-0.339..1.000]`
+  for a ±1 s request is correct there rather than a defect.
+- **The frame that *frames* a snapshot is the one that consumes its `event_seq()`.** The
+  tick reads `display_mode()` *before* it takes `mutex()`, while the producer publishes
+  inside that mutex and lowers `trigger_pending` only at the end of its packet — so a tick
+  can read `Capturing`, block on the lock through `publish_event()`, and reach the framing
+  step with a new sequence number it is not bound to. (The other case is benign and was
+  always handled: a publication and the *next* edge in one frame, where the capture has
+  framed its own window.) Advancing `seen_event_seq` on such a frame dropped the pin
+  permanently — the axis kept the capture's requested `[-pre, +post]` over a shorter
+  snapshot and `event_held` stayed false, letting `clamp_to_data()` drag the frozen view —
+  so the test is `seq != seen_event_seq && display == Held` and the pin stays owed until a
+  frame is bound to the snapshot. Visible only at high rates, where the publish is long
+  enough to lose the race often; `[disarm-probe]`'s `axis=` against `snap=` is the guard,
+  which means **running the disarm probe at 10 kS/s alone does not check this.**
+- **A capture in progress is the one place the axis is pinned from the *request*.** There
+  is no snapshot to measure yet, so `DisplayMode::Capturing` frames
+  `[-(span - post_span_s(span)), +post_span_s(span)]` — computed with the producer's own
+  `TriggerConfig::post_span_s()`, not a second expression that rounds differently, because
+  the marker at x = 0 has to land where the coming cut will put it. The latch then re-pins
+  from the snapshot, and the two agreeing is why the picture does not jump at the latch.
+- **`clamp_to_data()` must be skipped while `capturing` as well as while `event_held`.**
+  A capture is live data on a pinned axis — the exact combination the clamp was written
+  for and against: it would follow the live edge and drag the frozen window off the event.
+- **`publish_event()` cuts one absolute index range and uses it for the time ring and
+  every value ring.** That is what makes `stamps` and each `values[c]` equal-length
+  and index-aligned by construction instead of by two truncations that can disagree —
+  `EventSeries::gather()` indexes both at the same `i`.
+- **`live_window_locked()` is the one live cut, shared by `publish_event()` and the
+  export.** Both need the same absolute index range over the time ring and every value
+  ring, or an export and a capture of the same window would hold different samples. Call
+  it under `mutex()`.
+- **Force is a synthetic edge, and the latch is still the only publisher.** The trigger panel's
+  Force button opens one capture at the *present* moment through `TriggerEngine::force()`: the
+  newest stored stamp becomes the event's own time and the engine enters the same pending state an
+  edge leaves it in, so the ordinary latch cuts, publishes, counts and frames the acquisition. A
+  forced acquisition therefore obeys every rule a latched one does — the axis pinned from the
+  snapshot's own stamps, a `pre_s` shorter than the request when the ring does not reach back that
+  far, and the frame that frames it being the one that consumes its `event_seq()` — and the button
+  owns no window, no publish and no framing of its own: **the event it publishes is cut by the same
+  code as a latched one.** Two things it deliberately does *not* do, both of them choices:
+  - **It skips the pre-window gate.** `force()` does not test `event_t - oldest_s_ >= pre_seconds_`:
+    "capture now" is a request for the history that *exists*, and refusing it because the ring is
+    young would refuse the one thing the button is for. The snapshot reports its own `pre_s`, and the
+    pin follows it — which is also how the pin gets *read*: with a request the ring cannot satisfy (a
+    100 s window at 99 % pre) the axis must come out a few seconds wide, where a pin stated from the
+    request would come out a hundred.
+  - **It does not restart a capture already filling.** That capture *is* the acquisition being asked
+    for: the display is already showing it fill (`live(capturing)`), and restarting it would throw
+    away the post window it has collected and move the marker to the press. The click is refused, and
+    named on stderr, rather than silently reinterpreted.
+  What the trigger *is* afterwards is still the mode's decision, and it is made where it always was —
+  in the latch: Normal leaves the engine armed with the latch's hold-off, Single disarms it. One
+  acquisition, whether an edge produced it or the button.
+- **The Force request is written under the model lock and consumed at the end of a packet.** It is
+  one atomic flag on `Acquisition` (`request_force()`), read with `exchange` after the channel loop
+  and before the `trigger_pending()`/`capture_edge()` publish — after the loop because the cut
+  `publish_event()` is about to make clamps to every value ring's `produced()`, so the newest sample
+  of every channel has to be in by then, and before the publish so the capture the click opened is
+  reported by the same packet that opened it. The *write* belongs under `ScopeModel::mutex()` and in
+  the same critical section as the `armed` flag the click also sets: the producer holds that lock for
+  a whole packet, reading the panel's `armed` at the top of one and the request at the bottom, so a
+  request written in between would be read by a packet whose engine was still disarmed and then
+  dropped — and dropped is right, because a momentary request must not be replayed later on a trigger
+  the user has stopped watching. With **no channel resolved** (no signal acquired) the click is
+  refused in the handler and not left to the producer: `on_data()` returns at once for a model with
+  no *streamed* channel, so a request parked behind that return would fire on the first signal
+  switched on afterwards.
+- **The trigger engine is not fed a reserved hole's samples.** A NaN comparison is false anyway,
+  so the engine would not latch; but the real reason the samples are withheld is the other one:
+  feeding them would advance the hold-off clock across time nothing was sampled in. The probe
+  asserts `trigger_in_hole=0` rather than relying on NaN's arithmetic properties.
+- **`EventDetector` owns every condition shape and holds no arming state; `TriggerEngine` owns
+  the arming, the hold-off and the post window and holds no condition.** The split is what lets
+  the buffer search ask the trigger's exact question without owning a trigger, and it is only
+  true as long as neither half leaks into the other: a detector that knew about the hold-off
+  would answer a search differently from the live trigger, which is the one thing the
+  `agree=1` cross-check in `[search-probe]` exists to catch.
+- **The detector is fed on *every* sample, including during the hold-off and during a capture.**
+  A pulse width, a window excursion and a dropout timeout are all *stateful over several
+  samples*: skipping the feed while the engine is busy loses the opening edge, and the condition
+  then measures from whatever sample the engine happened to resume on. The hold-off is applied
+  to the detector's *answer*, not to its input — `process()` feeds first and tests
+  `now_s < holdoff_until_s_` afterwards.
+- **An event's time is the detector's, not the sample's.** A pulse-width event is detected at
+  the closing edge but could in principle be timed at the opening one, and a dropout is detected
+  one sample after the timeout expires. `feed()` therefore returns the event's *own* time and
+  `process()` uses that for `last_trigger_s_`, `pending_start_s_` **and** the pre-window gate —
+  all three, or the marker, the cut and the gate would disagree with each other by the width of
+  a pulse.
+- **The trigger's whole input is the stored clock, so a clock that stops is a trigger that never
+  fires — and *that* is what a blank trigger-mode display is.** `Acquisition` feeds
+  `TriggerEngine::process(value, rel)` with the same `rel` it stamps the ring with, and the engine
+  has no other clock: the pre-window gate measures the event against the retained history
+  (`event_t - oldest_s_ >= pre_seconds_`), the post window counts *stream seconds* past the edge,
+  and `holdoff_until_s_` is set from `now_s` at the arm. A timeline that stands still therefore
+  reads as `history=0.0000/1.0000 s` for ever, on every line of `trig engine:`, no matter how many
+  samples arrive — and with no latch, `display_mode()` never leaves `Waiting`, whose bind is
+  *nothing* by design, so the plot is blank and the other traces are blank with it (the renderer's
+  bound window is empty too, so the same emptiness shows with the trigger off). Nothing about that
+  picture says "clock": it is "in trigger mode, with a math channel enabled, the data disappears",
+  which is how it reached a user. The reading is the `trig engine:` line's own pair — **`n` climbing
+  while `ring=[a..a]` stands still** — and the one-shot
+  `[udpscope] warning: the clock stalled ...` that `on_data()` prints at the first whole frame whose
+  stamps are all behind the clock. See
+  [invariants-data-path.md](invariants-data-path.md) for the two entries (a plan whose interval
+  moved under the stream; a frame accepted into a model with no streamed channel) and for why the
+  relative clock is accumulated in seconds.
+
+- **Persistence is the older acquisitions drawn *over* the current one, and "a layer is not a
+  signal" is what keeps them from becoming one.** Trigger mode may keep the last `N`
+  acquisitions -- `TriggerConfig::persist_depth`, the panel's *persistence* spin, 1 = the event
+  on screen alone -- and draw the older ones dimmer, which is the whole feature. The machinery is
+  the layer machinery the accumulate path already has: one **layer** per (signal, age), in the
+  same trace slot the accumulate path puts its own extra events in, named with the same suffix
+  vocabulary (` (A)`, ` (B)`, ` #4`), so `layer_base_name()` gives the base signal back and the
+  signal list, the colour resolver, the measurements and the layout writer all keep seeing **one**
+  signal where the plot draws several traces of it. Four consequences, each of which is a rule:
+  * **A layer slot holds no channel.** `RowSet::bind()` resolves a layer's *base* signal (it must
+    still be acquired -- switching a signal off takes its traces off every plot, layers included)
+    and then finds the channel **by name inside the snapshot** (`EventSnapshot::channel_names`),
+    because the channel list is renumbered by any structural change since that acquisition was
+    cut -- the rule `TriggerEngine` already follows, for the same reason. It leaves
+    `Row::channel[]` at `-1`, which is what makes every reader that asks "is this slot a trace of
+    a signal" skip it: the trace counts, the cursors pane's `mix` mask, the measurement marks, the
+    dump's per-slot lines, `collect_layout()`. A persistence layer is therefore invisible to the
+    signal list, the calibration table and the measurements by construction and not by a check;
+    the *measurements* go on describing the current frame because they resolve a channel from the
+    signal name the user configured, and `sine (A)` is not a signal anybody can configure.
+  * **Its brightness is a property of the slot, and it is applied where the trace is created.**
+    `Row::slot_alpha` is `RowSet::persist_alpha(age)` -- **half per acquisition**, so the schedule
+    is 1, 0.5, 0.25, 0.125, ... and the seventh layer is 0.8 %, i.e. gone; it does *not* depend on
+    the depth, so raising N adds dimmer acquisitions instead of restating the ones already on
+    screen. `install()` mixes `slot_alpha * trace_alpha_` into the trace's colour, because a
+    `Plot` fixes a trace's colour **at `add_trace()`** and a brightness nobody can set later is a
+    brightness that has to be a rebuild. Two things follow: a per-layer alpha is impossible
+    without a per-slot one, and **`set_trace_alpha()` is finally read** -- it was set by the
+    accumulate path and read by nothing, so an accumulation's "translucent, so agreement is
+    brightness" was opaque in fact while the docs claimed otherwise.
+  * **The dimmest trace is created first.** A `Plot` draws its traces in the order they were
+    created and cannot reorder them, so `install()` creates them sorted by brightness and the
+    *newest* acquisition is the ink on top. A layer drawn over the event would take its colour out
+    of the event's own trace wherever the two agree -- the opposite of what a persistence display
+    shows.
+  * **Every slot the plan does not fill is freed, and the plan does not depend on the data.**
+    `RowSet::sync_layers()` (called from the tick, before the frame's `bind()`) re-plans one layer
+    per (signal, age) into the row's free slots, *layer by layer* -- age 1 for every signal first,
+    then age 2, as the accumulate path does -- so a row that runs out of room draws the sharper
+    layer for each of its signals and stops. The plan is a function of the rows, the depth and
+    nothing else, so a **latch costs no rebuild**: the slot names and ages stay put and only the
+    snapshot behind them changes.
+- **An older acquisition is *drawn*, and it may not move anything.** The current event is the one
+  the axis is pinned to, and persistence must not disturb that, so `RowSet::event_data_window()`
+  -- the union the pin is re-stated from every frame while an event is held -- **skips layer
+  slots**: a wider older acquisition would otherwise re-pin the axis, and with it the window a
+  pinned measurement reads, which is a *measurement* moving because a display option was turned
+  up. The layers are bound only in `Held` and `Capturing` (a live view has no current event to be
+  the newest of them, a `Waiting` display is blank by design, and a pause view's stamps are on the
+  live window's clock, not on an edge): in `Waiting` and `Live` the layer slots are planned but
+  bound to nothing, and a trace with no series is not drawn and not listed in the legend. The one
+  thing they do share with the signal is the **row's y axis**, so the y auto-fit sees them -- a
+  y axis that ignored the traces it draws would clip the excursion the display exists to show.
+- **A retained acquisition is a whole window copy, so the depth is capped by bytes and by what a
+  row can draw.** `publish_event()` moves the outgoing `event()` into the retention before it
+  publishes the new one: `ScopeModel::persist_event(age)` is the event `age` latches back, one
+  atomic `shared_ptr` slot per age, read by the tick without a lock exactly as `event()` is.
+  `snapshot_bytes()` is the honest cost of one -- both stamp arrays, every channel's `f32` samples
+  and the LOD pyramids built for them, i.e. ~4.5 bytes per sample per channel plus 8 per sample of
+  clock -- and `prune_persist_locked()` cuts the set to **both** bounds: the depth, and
+  `persist_budget_bytes()`, which is the ring's own `--buffer-mb`, because persistence is a copy
+  *of* what the rings hold and holding as much again is the honest ceiling for a display of it.
+  `kMaxPersistDepth` is 8 for the different reason the panel needs one: the layer there is already
+  invisible (0.8 %) and seven is all the free slots a one-signal row has. The depth is not the only
+  thing that limits what is *drawn* -- a row of `S` signals with 8 slots shows
+  `floor((8 - S) / S)` ages of each, so the default four-signal row shows one older acquisition
+  and a row per signal shows all seven. The two shortfalls are **separate readings**, and a caller
+  that conflated them would report a shrunken display as complete: a *slot* shortfall is
+  `placed < want` (what `RowSet::sync_layers()` returns against what the depth asked for), while a
+  *budget* shortfall is a `kept` below the depth plus the count `persist_dropped()` carries -- and in
+  that case the layer slots **exist and draw nothing at all**, so `layers=`/`placed=` alone say
+  nothing is wrong. The panel's notice therefore names both numbers -- `D of W layers fit, K of A
+  older acquisitions retained` -- because a user who asked for eight layers and sees two has no other
+  way to tell "the display is deliberately shallower" from "the feature is broken".
+- **Depth 1 is not a mode, it is the *absence* of one.** `persist_depth = 1` retains nothing at
+  all -- no copy, no layer, no rebuild -- and `set_persist_depth()` prunes the set **at once**
+  rather than at the next latch, because lowering the depth is a user asking to stop paying, and a
+  trigger that has stopped firing never reaches another publish. A depth change is therefore also
+  how the memory comes back.
+
+- **The phosphor density is the *trace*, and that is a different display from the layers above, not a
+  mode of them.** The trigger panel's `Advanced` block offers both, and the words matter: *multiple
+  events* is `persist_depth` (N retained acquisitions, N traces, dimmer with age) while *persistence*
+  is `TriggerConfig::density` -- the plotter's `Plot::set_density()`, an intensity grid
+  **per trace, drawn in that trace's own colour**, every acquisition deposited into it, which fades
+  either by a time constant or by a per-acquisition factor. There is **no depth** on the density and
+  no per-acquisition memory: the image is `traces * columns * rows * 4` bytes, and both factors are
+  bounded -- the grid is the row's axes rect in device pixels **up to the plotter's
+  `kDensityCellCap`**, and there is one grid a trace the row draws. Four traces in a row
+  therefore hold at most 4 MiB between them, whoever dragged the window where (the probe's
+  one-signal-per-row run reads `cells=1044714`, 4 178 856 bytes), so a thousand acquisitions cost
+  what one costs and *neither* a wide window nor a long run can make the image grow. A cell's value
+  is a number of *sweeps*: the library
+  deposits a cell once per trace per sweep however many of that trace's own samples crossed it
+  (`[density-probe] on` reads `peak=1.0000` for one sweep; a per-hit deposit read 18) -- dwell is
+  `Style::intensity_grading`'s question, not this one's. The colour is the trace's own
+  (`RowSet::signal_color()`, the same source the trace was built with and never a second one), so a
+  saturated cell is that signal's colour at full strength and two signals agreeing in a cell are two
+  quads of two colours rather than a blend.
+  Five things hold it together, each of which is a rule:
+  * **It is a trigger-mode display.** `apply_density()` (the tick) states `Held` and `Capturing` as
+    the states it is on in; `Live`, `Waiting`, `Paused` and a file are not, and turning it off drops
+    the grids **at once** rather than at an acquisition a quiet trigger never sends (the rule
+    `set_persist_depth()` follows). So it goes away with the trigger, and a re-enable starts from an
+    empty image rather than a stale one at another scale.
+  * **One deposit per acquisition, one frame *after* the frame that frames it.** `Plot::accumulate_density()`
+    deposits what the plot currently holds through the transforms of its **last** layout, because the
+    frame's own layout is computed inside the paint that follows the tick: `density_pending` is set
+    where a snapshot is *framed* -- beside `record_pending` -- and consumed by the next tick, so the
+    deposit is of the new acquisition drawn at the axis that acquisition is pinned to. Doing it in the
+    same tick was right on the common Held-to-Held transition and wrong on the first latch, whose axis
+    was still the live ring's.
+  * **The switch deposits what is already on screen.** `on && !density_was_on` sets the same pending
+    flag, so a user who turns persistence on while an event is held sees it instead of waiting for a
+    latch that `single` mode may never send.
+  * **No trace is drawn over it, and the newest acquisition is inside it.** `Renderer::draw_traces()`
+    returns at once while a density is on: the trace ink *is* the image, so the acquisition just
+    deposited is a sweep in it and fades with the rest. Drawing the polyline too put a solid,
+    unfading stroke over its own faint ghost -- the reported "persistent image + last acquisition",
+    where the last acquisition never faded in time mode -- and the assertion is a **framebuffer** one:
+    `a_phosphor_density_is_the_trace_in_its_own_colour` reads the same pixel before and after one
+    time constant and requires it dimmer (`full=224 -> faded=115`, the trace's own `0xE0` green),
+    which a stroke over the density could not do.
+  * **The brightness ceiling is the trace's own brightness, and the ramp is linear in sweeps.** The
+    app leaves `DensityConfig::full_scale` at the library's default of **one sweep** and `gamma` at
+    1.0, so the acquisition just deposited reads as the trace it is a picture of and a signal crossing
+    the same place every acquisition settles *at* the trace's colour (the ceiling clamps), rather than
+    a fraction of a brighter steady state. The old ceiling -- the fade's steady state, `1/(1-factor)`
+    for the acquisition fade -- is the gain offset a user reported between the latest acquisition and
+    the persistent image, and the "dimmer by design" headroom that made the ramp visible is reversed
+    here.
+  * **It is the plot's, so a figure rebuild resets it** -- the grids live on each `Plot`, and
+    `rebuild_all()` builds new ones. That is the one state a structural change (a row added, a signal
+    switched off, a trace recoloured) does not carry: it costs the accumulated image and nothing else,
+    and the alternative -- keeping the grids in the `RowSet` -- is what would make it not a plot
+    feature. The layout is unaffected either way: the density reserves no space and nothing on it can
+    be picked, exactly as `set_invalid_spans()` does.
+  * **The session carries it.** `trigger_density`, `trigger_density_decay`, `trigger_density_tau` and
+    `trigger_density_factor` in the layout file, written whether or not it is on -- a display set up
+    once and switched off is still the display you come back to. The decay is the *word* the panel's
+    dropdown shows ("acquisitions"/"time"), for the reason the condition's shapes are text.
+
+## A latch is also a file
+
+The pane that lists the cache is **on demand**: the toolbar's event-history button and the pane are
+collapsed until it is asked for, because a column of stale events beside a live plot is what a user
+who has stopped looking at events does not want. What makes it *available* -- (recording is on) or
+(an event is on screen) -- is decided in one place, `sync_events_availability()`, so the button and
+the pane cannot disagree; a disabled cache with nothing being examined takes the button away *and*
+collapses the pane, because a visible empty column is what "off" must not look like. Trigger mode is
+deliberately **not** one of the conditions: a stored event being examined is a file, which has no
+trigger, and tying the pane to the trigger would close the list under the click that opened an event.
+The recording switch lives in the trigger panel, not in the pane it empties.
+
+## Opening a file is a detour, so *Go live* is a restore
+
+A file view overwrites the live view's settings and every overwrite has a reason: the window becomes
+the event's own span because that is what *framing* an event means, and the trigger goes off because
+a file has no edge to wait for (leaving it on kept a frozen capture on screen *instead* of the file,
+so the click looked like it did nothing at all). None of those reasons survive the way back. What
+the user had set is theirs, and "going back to live loses the trigger I spent a minute setting up"
+is the complaint this answers.
+
+- **`snapshot_live_state()` on the way in, `restore_live_state()` on the way out.** The snapshot is
+  taken by both ways into a file view -- `replay_event()` and `build_event_group()` -- *before* the
+  acquisition is stopped, and is a **no-op while `replaying`**: a second event opened from the first,
+  or a group opened from a replay, would otherwise snapshot a file's settings as "live", which are
+  the very values the restore exists to undo. The group takes it after its argument checks, because a
+  group that is refused leaves the live view alone.
+- **The trigger channel is stored by *name*.** Same reason `TriggerEngine::configure()` takes one: the
+  index is a position in a channel list that a file view rebuilds, and a group **renames** its
+  channels outright (`square (A)`). Putting an index back would select a different signal.
+- **`enabled` and `armed` are deliberately not restored from the snapshot.** They belong to the
+  toolbar toggle, which owns an atomic mirror of `enabled` (`set_trigger_enabled()`) that a plain
+  field write under the lock would leave stale. The restore writes the rest of the `TriggerConfig`
+  and then moves the *toggle*, whose handler states both.
+- **The restore runs from the tick, not from `go_live_again()`, and *after* the deferred layout
+  block.** Two writers would otherwise beat it:
+  - `apply_layout()` ends in `apply_time_window(st.window_s)` -- the window the **session file**
+    holds, not the one the live view had. `go_live_again()` clears `layout_loaded`, so that block
+    fires on the next tick; a restore done inside `go_live_again()` is overwritten by the saved value
+    a frame later. Being the next statement after it in `tick()` is the fix.
+  - `rebuild_trigger_signals()`, finding a `channel` of `-1` after the rebuild renumbered the
+    channels, silently settles on the first signal *and* re-defaults the level -- which is why
+    `trigger_level_touched` is restored with the configuration.
+- **It waits for the trigger's channel *name* to resolve again, not for `generation()` to move.** The
+  restored name has to be resolved against the live channels, and a file view that renamed its channels
+  (`square (A)`) must be gone first or the name selects the wrong signal. `App::live_restore_pending`
+  stays set until `channels()` is non-empty **and** a channel carries the snapshot's name (or the
+  snapshot named none). Gating that on the generation was wrong in the common case: a *single* event
+  keeps the stream's own channel names, and the restarted client's CONFIG is identical, which the model
+  treats as **no change on purpose** (`same_stream_signals()`) -- so the generation never moved and the
+  restore waited for something that could not happen. What shook it loose was toggling the trigger,
+  which *is* a structural change: "click live, then toggle the trigger a couple of times" was the
+  symptom. A `pending=1` that never clears is a reading about the *stream* (no channels yet), not about
+  the restore -- see `invariants-session-and-export.md` for the save that made it stick at
+  `channels=0`.
+- **Only the two controls a file view actually moved are restated** -- the signal dropdown and the
+  level spin. The rest of the trigger panel was never touched, and writing to a control fires its
+  handler, so the ones with nothing to put back are left alone. Both writes are inside
+  `updating_panels`.
+- **`pinned` is not a pass/fail reading on the way back.** `apply_time_window()` drops the file's pin
+  and re-arms the live follow, but if the restored trigger was *on* it can latch again within the
+  frame or two before the probe reads -- and a held capture is pinned, correctly. That is what
+  `held=` and `mode=` are beside it for.
+
+## A comparison is two plots of one model
+
+*Compare* and *accumulate* are still one model -- the buffers cannot hold two independent loads -- but a
+comparison is **two plots** over it, and which plot draws what is only a matter of which channel *names*
+its rows bind. `App::rows` is the primary (`RowSet`, area, gestures); `App::rows_b` is the second, with
+its own `RowSet` and its own hidden `PlotArea` in a paned, deliberately without the drop target, the
+right-click menu or the frame counter: those act on the primary's rows, and a menu on the second plot
+that rearranged the first plot's rows would be a menu lying about its subject.
+
+Rules that cost a defect each:
+
+- **The layout is the user's and is mirrored, never reinvented.** The group build must not call
+  `set_row_count()`; it reads the rows' slot names and re-names the same slots for each layer
+  (`… (A)`, `… (B)` for a comparison; a bare name for layer 0 and `… #2`, `… #3` for the extra layers of
+  an accumulation). An *accumulation* puts its extra layers into free slots -- the row that holds the
+  signal first, then any row with room -- so the user's traces never move. The default layout is four
+  signals in one row, which is why `kSlotsPerRow` is 8: with four, "accumulate these two events" had
+  nowhere to put the second copy and silently did nothing.
+- **A layer is not a signal.** A comparison's model holds one channel per (signal, layer), and the
+  *panel* must not treat the copies as signals of their own: the signal list shows one row per signal
+  (`layer_base_name()`, the shared rule that takes `(A)`, `(B)` and `#N` back off), `signal_color_index()`
+  counts *signals* and not channels -- counting channels spread one signal's colour across the palette
+  -- and both plots of a comparison bind their signal's layers to the *same* colour index, because two
+  colours would say they were different signals. The reading is `list=4` in `[events] compare plots`
+  for a two-event comparison of four signals.
+- **A slot name carries the last group's suffix, so it must be stripped before it is re-derived**:
+  after a comparison the rows are named `sine (A)`, and a following accumulation that mapped that name
+  again bound to no channel at all (`traces0=0`, a plot with nothing in it). `base_name()` takes
+  `(A)`, `(B)` and `#N` back off.
+- **The axes are mirrored from the ranges, once per frame.** The plotter owns its window and a gesture
+  reaches it through the plot's own setter with nothing announcing it, so the frame compares each row's
+  signature with the previous frame's: whichever side moved is the side the user touched, and the other
+  is set to match. The signature is `{span, y.min, y.max}` when the x axis has a **live edge**
+  (`x_live_edge()`, not merely an armed follow: an armed axis with nothing streaming keeps a *stored*
+  window, whose edges a pan moves and whose span never changes) and `{x.min, x.max, y.min, y.max}`
+  otherwise. Comparing the edges under a live edge would read as "both sides moved" on every frame --
+  the window is recomputed as a distance behind the newest sample -- and a zoom in one plot would be
+  overwritten by the other's drift. When both moved the first plot is the reference, which is also what
+  makes the frame after a build converge.
+- **`set_y_range()` clears that axis' auto-scale**, by design: a mirrored zoom is a user decision, and
+  *Fit* re-arms it.
+
+## A group of events is one model, built once
+
+*Compare* and *accumulate* are the same machinery: several event files in **one** model, because the
+buffers cannot hold two independent loads -- `load_waveform_into_model` calls `set_signals()`, which
+rebuilds them, so a second load takes the first with it. So the group is built by hand: one channel per
+(signal, layer) pair, `set_target_span()` to cover the whole group *before* `set_signals()` (or the
+oldest samples are written past the ring's end), then all of the events pushed in one pass. A row is
+one **signal** and its slots are the events, which is what makes a comparison like for like and an
+accumulation a density; the trace alpha (0.35 while accumulating, 1 otherwise) is what turns agreement
+into brightness.
+
+Two things every group must do, both of which cost a defect to learn:
+
+- **Stop the acquisition first.** A live producer keeps pushing into the model it was started with --
+  and it pushes *four* stream signals into the group's *eight* channels, so the group's own samples are
+  the ones that go missing. The reading that catches it is the samples the busy channel holds
+  (`samples0` in the `[events] compare` line): it must be exactly the number of stamps pushed, not
+  that plus whatever the stream added.
+- **Free the slots the group does not fill.** A row carries the previous view's binding, and a trace
+  left in slot 2 of a two-layer row is drawn as if it belonged to the group.
+
+*Compare* shifts the first event so its span *ends* where the second's *begins*, and fills the half a
+sample does not belong to with **NaN** -- the plotter excludes non-finite samples from every series and
+from every pyramid bucket, so a NaN is a gap and not a repeat, and no line is drawn across the join.
+
+**A replay changes the data and frames it once; it never rearranges the layout.** A row plots a signal
+*name*, and an event's export carries the same names the stream does, so loading the event into the
+model leaves every row, slot, colour and the row count pointing at the right signal by itself. So
+`replay_event()` must **not** rebind the rows (`bind_channels_to_rows()`, which is what a freshly opened
+*file* needs) -- that is the user's work, and a click on a list is not a request to rearrange it. The
+window is restated **once, on open** (`apply_time_window(span)`, the only path allowed to change the
+scale), so the whole event is framed the moment it is opened and the user's own zooms are left alone
+afterwards; never per frame. The measurements, the cursors and the readouts then report the stored
+event, because they read the model. What a replay *does* change is the model's contents and the trigger:
+it leaves trigger mode, without which the display stays `Held` and draws the old snapshot.
+
+**A file view has nothing to acquire.** The signal list's acquire tick is *hidden* -- not disabled --
+whenever a file is on screen (`App::waveform_name` non-empty: a replay, a comparison, a `--open`run).
+The samples are stored, "acquire this signal" is a stream's question, and a greyed tick invites the user
+to look for a reason there is none for. Going live rebuilds the panel, so the ticks come back.
+
+**"The same length" is the same count at the same rate, not the same span to the sample.** Two events
+this app recorded itself differ in span by the fraction of a sample the acquisition's window happened to
+fill to (0.9999 s of a 1 s pre-window is normal). Demanding one sample interval made a comparison of two
+just-recorded events refuse to open; the check allows four intervals or a millisecond, whichever is
+larger, and the merged stamp grid carries the difference as a gap.
+
+**A replay must leave trigger mode.** `display_mode()` answers `Held` whenever the model holds a
+snapshot, and a held display draws *the snapshot*, not the live channels -- so replaying an event with
+trigger mode still armed loaded the file into the model and left the old capture on screen: a click
+that looks like it did nothing, with the event sitting in the ring unread. The replay also frames the
+view with `apply_time_window(report.span_s)`, so the click shows the whole event rather than the part
+of it that fell inside the live window.
+
+The switch that decides recording belongs to the **trigger panel**, not to the pane it empties: it
+is a trigger option (it decides whether a latch is written at all), and a pane must not be the only
+place to reach the control that stops it.
+
+
+Every published snapshot is written to the event cache while recording is on: its table (the *export*
+format, so `--open` reads it back), a sidecar of what the list shows, and a preview drawn from the
+samples. Three rules keep that honest:
+
+- **The record happens on the GTK thread, at the end of the tick that framed the snapshot**, not on
+  the producer. The snapshot is taken by `shared_ptr` (a latch landing mid-write cannot pull the data
+  away), and a `record_pending` flag defers the write to the end of the frame so the rows are already
+  bound to the event when the picture is drawn. Recording from the producer would put file I/O
+  between two `recv()` calls, which is the one thing the packet capture's design also refuses.
+- **Nothing a latch does may be expensive.** The write is a `write_npy` of the event's own window and
+  a 480x160 raster; a 2 s, four-channel event is ~230 kB of picture and ~600 kB of samples. The pane
+  is refreshed, not rebuilt, and a failure to write is a line on stderr -- a cache that cannot be
+  written must not stop the scope.
+- **The preview is drawn from the data, never captured from the window.** The plot is a `GtkGLArea`:
+  its ink is not in the widget's paint tree, so `gtk_snapshot_free_to_node()` on a widget paintable of
+  it returns NULL and the "screenshot" would be an empty file. Drawing it in the store also keeps that
+  class GTK-free, which is what makes the cache testable without a window.

docs/claude/verification.md

@@ -0,0 +1,999 @@
+# Verification
+
+How to run the headless self-check, the two baselines every run is read against, and the environment variables that schedule each probe.
+
+Part of [CLAUDE.md](../../CLAUDE.md).
+
+There is no unit test suite. The only automated check is the app's own headless
+self-check, driven by env vars and run under a display (`xvfb-run`, llvmpipe) against
+a live UDPStreamer source:
+
+```sh
+xvfb-run -a env UDPSCOPE_EXIT_AFTER_MS=8000 UDPSCOPE_ENABLE_ALL_MS=1000 \
+  ./build/udpscope --server 127.0.0.1 --port 8000
+```
+
+Two baselines every run is read against. The UDPS runs must be **unchanged by the source-plugin work**:
+a UDPS self-check, number-normalised (`sed 's/[0-9.]\+/N/g'`), diffs empty against one taken before it.
+A clean build emits **one** warning and no more: a `-Woverlength-strings` on the icons'
+generated GResource `.c`, whose blob is **9248** against C99's 4095-byte string-literal limit with
+the five action icons and the two app icons that remain (a note about a generated file, which GCC
+itself supports). History: the help pages' generated `.c` (**516044** bytes) went when the manual
+became a Mallard set installed for Yelp; an unused `output_built` in `math_probe()` was deleted as
+dead code; and the last two, `-Wmissing-field-initializers` on `MathNode::source` in `math_probe()`,
+went when the probe's `MathNode{MathOp::Gain, {}}` / `MathNode{MathOp::LowPass, {}}` named the
+field (a partial brace-initialiser on `MathNode` re-adds one: `source` has no default member
+initialiser). Re-measure by touching `src/icons/udpscope.gresource.xml` and rebuilding; any
+second warning is a finding. And an exit-dump run emits **no** `Gtk-CRITICAL` at all, nor any `Gtk-WARNING`: the dump's
+`gtk warnings:` line counts GTK's own log (through a writer function — GTK is built with structured
+logging, so the handler API never sees its messages) and must read `0`; see
+[probe-readings.md](probe-readings.md).
+
+An *incremental* build reads **zero**: the generated GResource `.c` is not recompiled
+when only `src/` changed, so its `-Woverlength-strings` does not reappear.
+
+A third reading every run offers for free: **how many `[udpscope] buffer allocated:` lines it
+printed.** The line is not behind a probe — it is in every build — and one line is one *real* change
+of buffer plan, each of which blocks the main thread for the time it takes to touch the whole
+`--buffer-mb`. A normal run prints two or three. Fifteen at startup is the defect it was added for;
+see [probe-readings.md](probe-readings.md).
+
+That second baseline used to be "exactly two, `gtk_widget_get_height` and `gtk_widget_get_width`,
+from the dump asking a destroyed widget for its size", and tolerating them was a mistake: the dump
+runs from the destroy handler, so the widget pointer is **freed memory**, and a critical is only
+the lucky reading of it. A run that had built and destroyed other windows first —
+`UDPSCOPE_PROBE_HELP_MS`, which opens the About and shortcut dialogs and then closes them — has had
+that memory reused, and the same two calls
+then **SIGSEGV in the middle of the dump**, which reads as a truncated dump rather than as a
+crash in a debug line. Every size the dump prints is therefore captured on the *tick*, while the
+window is alive (`App::dbg_*`), and **no `gtk_widget_*` call may appear in the dump** — the
+`panel controls:` line was already written that way for the same reason, and that comment is the
+precedent, not an exception.
+
+- `UDPSCOPE_EXIT_AFTER_MS` — run the trigger-on → go-live probe, close the window,
+  then dump the whole pipeline state to stdout (frame/sample counts, per-plot painted
+  frames, trace bindings, panel sizes, status line in both states).
+- `UDPSCOPE_ENABLE_ALL_MS`, `UDPSCOPE_ARM_TRIGGER_MS`, `UDPSCOPE_PROBE_DISARM_MS`,
+  `UDPSCOPE_TRIG_TRACE_MS` — schedule individual probes. `UDPSCOPE_PROBE_DISARM_MS` only
+  *starts* its sequence: it switches the trigger on and then polls for a capture to open,
+  so the Disarm lands ~300 ms into one rather than wherever a fixed delay happened to fall.
+- `UDPSCOPE_PROBE_FORCE_MS` — the trigger panel's **Force** button: one acquisition at the present
+  moment, with the pre/post window the panel is set to, without waiting for the condition. It is a
+  chain, not an instant — `MS` is when it *starts*: it forces trigger mode **off** through the toggle
+  (a session file remembers the trigger, so the off state is stated rather than assumed) and reads the
+  button's stated state 300 ms later; it then sets a level no mock signal reaches (9 V), a 2 s window
+  at 50 % pre, acquires the mock's `sine` and turns the trigger on; it presses Force 2.5 s after that
+  (the window write re-plans the buffer and clears the history, so the ring needs the time to fill
+  past the 1 s leg A asks for); it presses a second time on a 100 s window at 99 % pre — a request no
+  run this short can satisfy — 400 ms after the first latch. **Run it alone, against the plain mock**,
+  with time for both legs:
+
+  ```sh
+  python3 tools/mock_udpstreamer.py --port 8114 --rate 10000 --batch 100 --duration 30 &
+  sleep 1.5
+  xvfb-run -a env UDPSCOPE_EXIT_AFTER_MS=14000 UDPSCOPE_PROBE_FORCE_MS=3000 \
+    ./build/udpscope --server 127.0.0.1 --port 8114 2>&1 | \
+    grep -E 'force-probe|trigger:'
+  ```
+
+  Being alone is load-bearing twice: the level is chosen so the engine *cannot* latch on its own, so
+  a latch count that moves is the force's and nothing else's — any other probe that arms a reachable
+  condition adds latches of its own — and `UDPSCOPE_ENABLE_ALL_MS` before it would acquire four
+  signals, which changes the level's default range and the plan. Two lines per pass are in
+  [probe-readings.md](probe-readings.md); **`latches=P->Q` with `Q == P + 1`, `display=event(frozen)`,
+  `matches_request=1` in leg A, `pin_is_snapshot=1` in both** are the assertions, and leg B's
+  `matches_request=0` is *expected* — a ring that cannot reach back 99 s is the only state where
+  "pinned to the snapshot, not to the request" is a reading rather than a coincidence.
+- `UDPSCOPE_PROBE_PERSIST_MS` (+ `UDPSCOPE_PROBE_PERSIST_DEPTH`, default 4, 1..8) — the **persistence
+  display**: trigger mode keeps the last N acquisitions on screen, each older one drawn at half the
+  previous one's brightness. It enables the signals itself (one call, as a restored session does) and
+  arranges one signal per row — the arrangement the app gives an opened file, and the one with room
+  for every age — sets the depth **through the panel's own spin**, arms the trigger on the mock's
+  `square` and polls until the retention is full: an event on screen and as many older ones kept as
+  the depth asks for. The depth is *left* where it put it, so the run's own tail is the display at
+  that depth:
+
+  ```sh
+  python3 tools/mock_udpstreamer.py --port 9541 --rate 500000 --batch 1000 &
+  PY=$!; sleep 0.5
+  xvfb-run -a env UDPSCOPE_EXIT_AFTER_MS=16000 \
+    UDPSCOPE_PROBE_PERSIST_MS=2500 UDPSCOPE_PROBE_PERSIST_DEPTH=4 \
+    ./build/udpscope --server 127.0.0.1 --port 9541 2>&1 | grep -E 'persist-probe|persistence:|layout:'
+  kill $PY
+  ```
+
+  **Not with `UDPSCOPE_ENABLE_ALL_MS`**: that probe ends by switching a signal off two seconds later,
+  which takes the row that plotted it — and its layers with it — out of the middle of the measurement.
+
+  **Read it as a pair of runs**: the same command at `..._PERSIST_DEPTH=1` is the display *without*
+  the feature, so its `kept=0`, `layers=0`, `bytes=0` and its `layout:` line holding only the signals
+  is the "N = 1 is exactly the old behaviour" reading, and it is also the run the exit dump's
+  `frame cost:` line is compared against — the tick/draw means are means over the whole run, and the
+  depth is raised at `MS`, so the difference is a *lower bound* on what the layers cost. **`ev_is_snap`
+  and `pin_is_snap` must be 1 in both runs**: the older acquisitions are drawn and never pinned, so
+  the axis, the framing and the measurements still describe the current event. `alphas=` is the decay
+  schedule in use, oldest first — halves, and `1/2^age` at that. Both lines and the two exit-dump
+  lines are in [probe-readings.md](probe-readings.md).
+- `UDPSCOPE_PROBE_DENSITY_MS` (+ `UDPSCOPE_PROBE_DENSITY_TAU`, default 1.0 s) — the **phosphor
+  density**: an intensity image **per trace**, in that trace's own colour, the axes rect in device
+  pixels up to the plotter's `kDensityCellCap` (past which it scales the rect down uniformly and
+  magnifies the image back over it with a linear filter), every
+  triggered acquisition accumulated into it (the newest included), drawn *in place of* the traces,
+  fading by a per-acquisition factor or by a time constant. It states the display
+  **off** through the panel's own switch first, so the `off` leg is the run without it, then arms the
+  trigger on the mock's `square` with one signal per row — the arrangement the persistence probe uses
+  — and only then switches it on, so the acquisition already on screen is the first image. Four legs,
+  each a separate `g_timeout`, so whole frames happen between them:
+
+  ```sh
+  python3 tools/mock_udpstreamer.py --port 9551 --rate 500000 --batch 1000 &
+  PY=$!; sleep 0.5
+  xvfb-run -a env UDPSCOPE_EXIT_AFTER_MS=14000 \
+    UDPSCOPE_PROBE_DENSITY_MS=2500 ./build/udpscope --server 127.0.0.1 --port 9551 2>&1 | \
+    grep -E 'density-probe|density:'
+  kill $PY
+  ```
+
+  **The assertions, in order:** `off` reads `rows=0 traces=0 cells=0 ink=0.0 peak=0.0000` (there is no
+  grid at all); `on` reads `rows=4` — every row has its own image, one per trace in its own colour,
+  so `traces=4` with one signal a row — and **`peak=1.0000`**, one sweep's ink
+  being one per cell it covers; `step-acquisitions` reads **`peak=1.5000`**, which is the panel's
+  0.5 applied to the old image plus the new sweep's own pass; and `step-time` reads
+  **`ratio=0.367879`**, one step of `dt = tau` through the plot's own `decay_density()`. A `peak` in
+  the tens for the `on` leg is the *per-hit* deposit -- one sweep counted once per sample that
+  crossed a cell -- which saturates a single acquisition and hides the sweeps behind it. The line
+  also carries the app's own A/B of the frame cost (`tick`/`draw` before and after the switch, in
+  one run), and the exit dump's `density:` line says what the last frame it was on held. Both lines
+  and the dump line are in [probe-readings.md](probe-readings.md).
+
+- `UDPSCOPE_PROBE_NOTRACE` (no value; **not** a scheduled probe, and off unless it is set) — the
+  per-paint detail behind the exit dump's `traceless paints:` counter: one `[notrace]` line for each
+  of the first 40 paints after the first bind that staged no trace, naming the mode, the axis the
+  frame was asked for and every slot's bounds. It is behind a variable because a state that draws
+  nothing lasts as long as it lasts, so an ungated line is one per frame for the whole time -- and it
+  is *not* printed for a frame a phosphor density is drawing, which stages no trace by construction
+  (the frame's ink is the image) and would otherwise be counted as well. The counter itself is in
+  every build; see [probe-readings.md](probe-readings.md).
+
+- `UDPSCOPE_PROBE_HEADER` (no value; **not** a scheduled probe) — the once-a-second
+  `[udpscope] header: window_button_w=… bar_w=…` line. The widths are sampled either way (the
+  exit dump reads them); the line is behind this variable because it is detail behind that
+  reading, not a line every run should print. An unallocated window reads `0` for both.
+- `UDPSCOPE_PROBE_RENDERER` (no value; **not** a scheduled probe) — the renderer pair
+  `--renderer` should have exported, printed from `main()` before GTK initialises
+  (`[renderer] option=… GSK_RENDERER=… LIBGL_ALWAYS_SOFTWARE=…`), then the renderer GTK
+  built (`[renderer] realized=…`) once the window has one. Run it with `--renderer cairo` to
+  check the option reaches the environment before `gtk_init()`/`adw_init()`; run it without
+  the option to check the default is untouched.
+
+- `UDPSCOPE_PROBE_TRIGRENUM_MS` — the trigger's capture must survive a **renumbering of its own
+  channel**. It sets the reported geometry through the real widgets (1 s window, 10 % pre share,
+  hold-off from `--holdoff`) on the mock's *square* alone, polls for a capture to open, and then
+  enables the sine — which sorts before the square and so moves the trigger channel's index under
+  the engine. Its three lines are in [probe-readings.md](probe-readings.md); **`t0_held=1` is the
+  assertion**. Run it with `--holdoff 10`, which makes the stolen-t0 reading unmistakable: a second
+  latch barely a second after the first cannot be a hold-off that applied.
+- `UDPSCOPE_PROBE_FIELDS_MS` — change the trigger panel's edge and Normal/Single
+  dropdowns. As much a crash test as a state check (see the GTK signal-signature invariant
+  below), so time it inside a capture: `[fields-probe] ... capturing=1` followed by no
+  SIGSEGV *is* the assertion.
+- `UDPSCOPE_PROBE_WINDOW_MS` — drive the window control every way a user can: type a
+  number, change the unit under it, step a decade either way.
+- `UDPSCOPE_PROBE_LAYOUT_MS` — drive the layout editor: switch it on, insert above the
+  first row, remove a row, append one at the bottom, switch it off. Its steps are 200 ms
+  apart on purpose — the buttons are placed from the rects the *last frame* was laid out
+  with, so a synchronous sequence would read every position one action stale. It clicks by
+  emitting `::clicked`, never `gtk_widget_activate()`, which holds a `GtkButton` for its
+  250 ms `ACTIVATE_TIMEOUT` and then emits into a button the rebuild has already destroyed.
+- `[levels-probe] N measurement(s) over K channel(s), shares='...' -> W window(s), L level
+  walk(s)` (stderr, `UDPSCOPE_PROBE_LEVELS_MS`) — **prices a measurement pane**, which is what a
+  report of "it is slow with many measurements" has to become before it is a number. It adds one
+  `above` per share in `UDPSCOPE_PROBE_LEVELS` (comma separated, default `50`), spread in turn
+  over the first `UDPSCOPE_PROBE_LEVELS_CHANNELS` channels (default 1), and reports the two
+  things a count does not name: how many **windows** (one `MeasureWindowReader`, one fetch, one
+  scan per measured channel) and how many **level walks** (one accumulator per *distinct* share)
+  the pass then had to take. `50,50,50,50` on one channel is four pane rows and **one** walk;
+  `5,10,15,20` is four rows and **four**; the same four shares over four channels is four
+  windows *and* four walks. Read the `measure cost:` line it leaves in the exit dump and the
+  sweep in [invariants-measurements.md](invariants-measurements.md) — and read it against a run
+  with `UDPSCOPE_PROBE_LEVELS_MS` unset, because the pane's cost is a *difference* between two
+  tick means. **Run it at the scale being asked about**: the cost is the window's, so a 2 s
+  window prices a 15 s one at nothing (four measurements over four channels read `35.69 ms` a
+  recompute and a 4.58 ms tick mean at a 15 s window against `6.58 ms`/1.34 ms for one window at
+  the same window).
+- `[measure-probe] N measurements on 'X'` (stderr, `UDPSCOPE_PROBE_MEASURE_MS`) — adds one
+  measurement of each statistical type (average, top, peak to peak, amplitude) on the first
+  *channel* and forces a recompute. It must name a **channel**, not `signals().front()`: the
+  first signal of a stream is its timestamp, which is not acquired, and naming it adds four
+  measurements that all read `--` *and* makes a performance run look free (each bails before
+  collecting anything -- that is how the first baseline of the stall below read 0.4 ms).
+  The values are in the exit dump as `measurements: <type>=<value>`; on the fast mock
+  (`tools/mock_udpstreamer.py --rate 1300000 --batch 2000`) a unit sine must read
+  `peak to peak=2` **exactly**, `average=0`, and the two flat-level types as their definition
+  says: **`top=0.957988`** and `amplitude=1.915983`. `top` is no longer 2/pi -- it is the *flat*
+  level of the upper side, read from the density of the window's buckets, and a sine has no
+  plateau so the densest band is at its peak; `amplitude` is `top - bottom` (a scope's
+  `Vamplitude`), not the half-swing it once was. The check that the flat levels are *levels* and
+  not extremes is the same probe against the mock's `square` (`--square-harmonics 30`, the
+  control being `0`): `top`/`bottom` `0.999983`/`-0.999983` rippled against `1.000000`/`-1.000000`
+  ideal, `amplitude` `1.999966` against `2.000000`, while `peak to peak` reads `2.358701` rippled
+  against `2.000000` ideal -- the ±1.179 edges'
+  overshoot, kept by the extremes and excluded by the levels. The per-type values, the reason for
+  each, and the cost of the histogram are in
+  [invariants-measurements.md](invariants-measurements.md).
+  `[measure-trace] mode=M view=[..] s0=S swin=[..] pin=[..|off] for=[..] passes=N
+  <type>=<value>... marks=N level:V/time:V...` is a repeating line (250 ms) from the probe: the
+  pane's numbers beside the *current* window and the marks actually placed, which is the only way a
+  stale result or a mark that should not be drawn shows up as a number. `swin` is `view` moved onto
+  the stream's clock by `s0` (`stream_at_x0()`), `pin` is the pin's own extent in that clock (`off`
+  when nothing is pinned) and `for` is the window the printed numbers were computed over -- so a
+  reading that moved while `view` stood still is a change of `s0` (a new snapshot under the same
+  mode) and not a stale pass, and only these fields tell those apart. `passes` beside them says
+  whether a recompute answered the move. **While the view is pinned, `for` must equal `pin` -- and
+  `swin` is free to sit anywhere inside it** -- through any number of zooms and pans: a latched
+  event's numbers are the *frame's*, so a gesture inside the pin changes neither them nor `passes`.
+  Read the other way round it is the defect: `for` following `swin` into the zoom while the values
+  move is the reported "on a still frame the measurements change when I zoom". Neither reading is
+  the old "measurements stand still while the data moves", which was `for=[0.47..2.47]` against a
+  `swin=[1.417..1.467]` with `passes` frozen -- the pane describing a window the plot had left.
+  The line must also never print `marks=0` while measurements with `show_on_plot` are on and the
+  data is there -- that was the rulers blinking off at a mode change. `pin=off` while the mode is
+  `held` is not a stale reading but the window control: `apply_time_window()` unpins, and for those
+  frames the view is live-framed and measuring the viewport is right.
+  `measure cost: N recomputes, X ms total, Y ms each, data D ms (P%), covered=C buckets=B
+  raw=R (F%), N ns/covered sample` follows it: **read it against a run with
+  `UDPSCOPE_PROBE_MEASURE_MS` unset**, because a frame mean cannot attribute a cost. The last
+  three fields are the assertion, and they are a *ratio*, not a time: `covered` is the samples
+  the window spans, `buckets` the LOD buckets the two walks answered from, and `raw` the samples
+  they still had to read. **`raw` must stay at a fraction of a percent of `covered`** on a clean
+  waveform over a window of millions -- 0.1% is what the pyramid-backed walks give (see the
+  measurement-cost invariant in
+  [invariants-measurements.md](invariants-measurements.md)). A `raw` near `covered` means the walks went back to reading
+  the window, which at 1 MS/s is 19.7 ms per recompute and a third of the run's frames. It is
+  *legitimately* higher for a window shorter than a bucket (64 samples) or a signal noisy
+  enough to cross a threshold everywhere, so read it on the fast mock
+  (`tools/mock_udpstreamer.py --rate 1300000 --batch 2000`), where a window is ~2 M samples.
+  `--noise 0.1` there reads **2.0%** at 1.96 ms a recompute against the clean 0.1% at 1.41 ms, and
+  that is the interferer's own cost rather than a regression -- the figure to compare a change
+  against is the **clean** one. `raw` is also the guard on the flat-level types, which are the one
+  thing that reads a second time: `top`/`bottom`/`amplitude` fold a histogram out of the **same**
+  fetched bucket list, so they add buckets and not samples (measured: `raw=0.1%` and `2.1%` with
+  the interferer, against `0.1%`/`2.1%` before those types had a flat level, for 0.44→0.50 ms and
+  0.52→0.65 ms a pass -- the buckets are the budget). It is the guard on the band averages for the
+  same reason: `between` is a *second level in the same walk*, not a second pass, and measured on
+  the fast mock at a 2 s window with the measurements probe adding one of **every** type, `raw`
+  stayed at a fraction of a percent of `covered` —
+  `covered=240719031 buckets=3760828 raw=113966 (0.0%)` for the ten types before, against
+  `covered=255372033 buckets=3989978 raw=134978 (0.1%)` for the thirteen after, at 0.8 → 1.1
+  ns/covered sample (`data` 156.85 → 178.38 ms: the pane holds three more measurements and one more
+  level, and both walk the same fetched bucket list).
+  Note the **final** `measurements:` line and `[measure-trace]`'s last lines may read `--`:
+  `UDPSCOPE_EXIT_AFTER_MS` arms the trigger before it dumps, so the dump can land in `Waiting`
+  with nothing bound and the axis at its default. The race-free reading is an earlier
+  `[measure-trace]` line, which carries its own `view=`; those lines are also where the
+  level-mark fallback is visible (an invalid pass must still print its `level:` marks).
+
+- `[bandavg-probe]` (stderr, `UDPSCOPE_PROBE_BANDAVG_MS`) — the **band averages**:
+  `above`/`below`/`between`, the plain means over one side of a share and over a band, which are
+  *different numbers* from `top`/`bottom`'s flat levels (see the band-average invariant in
+  [invariants-measurements.md](invariants-measurements.md)). It adds seven measurements, on the three
+  shapes whose band means can be computed by hand, and the four figures to read are:
+
+  * the 1 Hz unit sine at a **2 s window**: `above 50` = **`0.636620`** (2/pi) and `below 50` =
+    **`-0.636620`** — the exact figures the old `top`/`bottom` documented, and the reason this type
+    exists at all; `between 50 75` = `0.255873` (`3(2-sqrt 3)/pi`), an interior mean no side and no
+    whole-window statistic reports;
+  * the mock's band-limited `square` (30 harmonics, its default): `above 50` = **`0.986496`**, the
+    reading the commit that made `top` a flat level recorded as the *old* `top`;
+  * the mock's `ramp`, whose density is uniform: `between 50 75` = `0.250000` and `above 50` =
+    `0.500000` — a band's mean *is* that band's centre, so the shape predicts the number;
+  * and the two nothing-to-measure readings: `above 100` on the `ramp` and `between 50 75` on
+    `--square-harmonics 0` (whose samples are all exactly +/-1) must be `invalid`/`--`, never 0.
+
+  **Run it at a 2 s window** (the probe waits for a full one before it reads anything — the mock
+  delivers about 0.5 MS/s of the 1.3 MS/s it declares, so a freshly enabled ring needs seconds of
+  wall clock), and **not** with `UDPSCOPE_PROBE_MEASURE_MS` or `UDPSCOPE_PROBE_MEASURES_MS`: all
+  three add measurements to one pane. `UDPSCOPE_EXIT_AFTER_MS=17000` covers its sequence. The
+  command, both mock flavours and the lines are in [probe-readings.md](probe-readings.md):
+  `--square-harmonics 30` for the `0.986496` and the `0.302744`, `--square-harmonics 0` for the
+  `1.000000` and the empty band.
+
+- `[measurepin-probe]` (stderr, `UDPSCOPE_PROBE_MEASUREPIN_MS`) — **what window a measurement
+  describes**: on a still frame the pane is about the *frame*, so a pan or a zoom changes no
+  number, and on a live view the numbers still follow the window. Three legs — a latched event, a
+  pause taken from it, and a live view after the trigger is switched off — each read the pane
+  before and after a *gesture* written on the row's own axis (never the window control, which
+  calls off the pin). The assertions, in order: the pinned legs read **`same=4/4 for_same=1
+  pass_delta=0`** with `for=` still at the pin (the values bit-identical and no recompute spent on
+  the gesture), and the live leg reads **`follows=1`** with `for_same=0`, `pass_delta>0` and the
+  results window's span narrowed to the axis'. Its sequence is about 12 s, so
+  `UDPSCOPE_EXIT_AFTER_MS=20000`; run it on the fast mock with a batch the datagram limit allows
+  (`--rate 1300000 --batch 1500 --freq 1`, **not** `--batch 2000`, which is 80 kB of payload and
+  dies with `Message too long`). The lines, the fields and the settle wait are in
+  [probe-readings.md](probe-readings.md); the window rule itself is in
+  [invariants-measurements.md](invariants-measurements.md).
+
+- `[pan-probe] asked=[..] was=[..]`, `[pan-probe] after=[..] held=D asked=[..]`, then
+  `[pan-probe] zoom asked=[..] after=[..] span=S window=W limited=L`
+  (stderr, `UDPSCOPE_PROBE_PAN_MS`) — **`held` must be 1**: a gesture must not move a window
+  that is pinned (trigger mode, or a paused view). The probe writes the panned range the way a
+  gesture does — on the *member* axis, which `Figure::layout()` adopts into the group — and
+  reports the axis the frame after it produced. Time it *inside* one pinned state: a pan during
+  a capture whose check lands after the capture has ended is re-framed by the mode change, not
+  by the pin, and reads `held=1` with the hold removed (that is how the first version of this
+  probe fooled me). The pause probe makes a stable pin, so run them together:
+  `UDPSCOPE_PROBE_PAUSE_MS=1500 UDPSCOPE_PROBE_PAN_MS=2200` puts the pan and its check inside
+  the pause. With `hold_pinned_window()` disabled it reads `held=0` and the axis sits at the
+  asked range. It then asks for a **zoom-in** (a window a quarter of what is on screen) and
+  reports `group=`/`member=` beside it: **`allowed` must be 1, with both equal to the ask** --
+  that is the single-trigger-mode case, where the wheel has to keep working, and where reading
+  the wrong one of the two made a working clamp look broken. All three verdicts are read from the
+  *tick*, one frame after the ask: a `g_timeout` was the first version and it drifted past the
+  paused/resumed boundary under load. The probe then asks for a **zoom-out** ten times the current span and reports
+  the span the next frame produced: **`limited` must be 1**, i.e. `span <= window`. Run it with
+  a ring that holds *more* than the window (`--buffer-mb 64` past the window's own seconds) —
+  that is the state the old `max(retained, window_s_)` bound leaked in, and it showed up here as
+  `span=2.502550 window=2.000000 limited=0` against `span=2.000000` after the fix.
+
+- `[zoom-probe] <sweep>/x<step> axis=[..] span=.. n=N idx=[a..b) spp=.. level=L pts=P kept=K
+  back=.. ink=[..] x_at_first=.. gap_px=.. end_px=.. rect=[..]` (stderr,
+  `UDPSCOPE_PROBE_EVENTZOOM_MS`) — arms the trigger in **single** mode, polls for a **held
+  event** (a latch happens when the stream says so; a sweep on a timer has nothing to zoom
+  into), then zooms in eight doublings
+  twice: `ges/` writes the row's own axis the way a gesture does, `win/` drives the window
+  control (`apply_time_window`, which unpins and re-arms the live follow before the pin is
+  restated). Each step's reading is taken in the *tick*, after that frame's pin and clamp — a
+  `g_timeout` would report the ask. It recomputes what `Renderer::draw_traces` is handed, through
+  the same calls: `neighbours()` for `idx`, the 64-spp gate for `level`, then `gather()`.
+  **`gap_px` and `end_px` must stay within a pixel or two at every step** — they are how much of
+  the left and right margin no geometry reaches, and a `gap_px` that *doubles* per step is the
+  "zooming into a held event clips it more and more from the left" defect (374 px of a 716 px
+  axis by `ges/x128`), whose cause is a constant offset in data seconds (see the `neighbours()`
+  invariant in [invariants-rendering.md](invariants-rendering.md)). `kept`/`back` are the renderer's own increasing-suffix filter counted rather
+  than applied: `kept` far below `pts` is a staircase, and a non-zero `back` is a non-monotonic
+  gather. **Run it with `--clock-jitter`** (`tools/mock_udpstreamer.py --rate 1300000 --batch
+  2000 --clock-jitter 0.4`): the ideal mock's stamps sit on a perfect grid, which is exactly
+  what hides this class of bug, and three runs against it reported `gap_px=0.0` throughout while
+  the defect was live. The jitter varies each *packet's* spacing rather than offsetting its
+  start, because the stream's clock has to stay strictly increasing. The `win/` sweep bottoms
+  out at `span=0.05` (`RowSet::set_time_window()`'s floor) and walks to the event's post side,
+  since `set_time_window()` frames the newest span before the pin clamps it — both are expected.
+- `UDPSCOPE_PROBE_PAUSE_MS` — pause acquisition mid-run so layout numbers are
+  measured on a still picture. It now also asserts what a pause *is*
+  (`[pause-probe] <action> paused=D ring_produced=N event_size=M frozen_x=[..] axis=[..]
+  skips=N glance=[..]` on stderr):
+  it presses the **button**, not `Acquisition::set_paused()`, because pausing is a display
+  state as well as an acquisition one and the view snapshot and axis pin live in the
+  handler. Across the three lines **`ring_produced` must grow** (the producer never
+  stops — it fills the live ring exactly as it does with the trigger off), **`event_size`
+  must be non-zero exactly while paused** (the plot is bound to the frozen snapshot, not
+  the ring) and **`frozen_x` must not move between the pause and the resume**; after the
+  resume `event_size` is 0 and the window is back on the newest data. Pausing used to stop
+  the producer, which is why the counts grew by nothing and the resume left a hole.
+  `frozen_x` is the *rebased* snapshot — the pause view's own stamps are relative to the freeze
+  instant now, so the range reads `[-window..0]`-ish rather than stream seconds, and a
+  `frozen_x` in the thousands is the rebase gone.
+  **`glance=` is the assertion for the paused status field**, and this is the only line that can
+  make it: the exit dump's `status bar:` is read live and its two `mode …` lines are the live and
+  triggered states. While paused it must read `paused · <rate> · <window> · for <elapsed>`, with
+  the elapsed figure **growing between the two paused lines** and **absent on the resume line**.
+  It is **wall** time (`g_get_monotonic_time()`), not stream time, because the producer never
+  stops while paused and "how long have I been looking at this" is a question about the user, not
+  about the stream; it is written through `format_elapsed()` so the field steps to a coarser unit
+  instead of growing digits (see the layout rule).
+  **`skips=` is the assertion for the render gate** (the end of `tick()`), cumulative over the
+  session: the `live` line must read **0** and the `paused` line must read **more than 0**. A
+  frozen view is bound to an immutable snapshot on a pinned axis, so a frame whose picture cannot
+  have changed is not drawn again — and this is the only line that can say whether that happened,
+  since a skipped frame is invisible in every other reading by construction. Non-zero on the
+  `live` line is the gate's condition inverted, which would cost dropped samples' worth of
+  picture; 0 on the `paused` line is the gate not engaging and the saving not being made.
+  The gate cannot stall the picture (`kStaticRenderEvery` renders every few ticks regardless),
+  so the renderer's own baselines below are unchanged by it: a measured run read `skips=0`,
+  then 33, then 45, with `columns == graded`, `render blank frames: 0`, and the layout floor
+  still converged (`y-gutter 104..104`).
+- `UDPSCOPE_PROBE_COLOR_MS` — recolour one plotted signal and read the colour back out of the
+  trace and the chip, round-trip it through the session writer, then clear it. Schedule
+  `UDPSCOPE_ENABLE_ALL_MS` before it: with nothing bound it has no trace to recolour and asserts
+  nothing. Its four lines are in
+  [probe-readings.md](probe-readings.md).
+- `UDPSCOPE_EXPORT_MS` (+ optional `UDPSCOPE_EXPORT_PATH`, default
+  `/tmp/udpscope-export`) — collect the export table and write it all three ways (`.npy`,
+  `.csv`, `.mf3`), skipping only the file chooser.
+
+- `UDPSCOPE_PROBE_CONDITION_MS` — arms a qualified trigger against the mock and reports the latched
+  `t0`, the measured pulse or band width, and sample values for the window condition. Schedules its
+  own arm and report stages. `UDPSCOPE_PROBE_CONDITION_SHAPE` picks the leg: `0` pulse width `<`
+  (the glitch, the default, needs `--glitch-at`/`--glitch-width`), `1` pulse width `>` (uses a
+  1.0 s window and 50 % pre so the opening edge of a 0.2 s pulse is captured), `2` window
+  (uses `sine` with a 0.2 s window and 10 % pre), `3` dropout (needs `--quiet-at`; uses `sine`
+  with a 1.0 s window and 50 % pre so the last crossing before the outage is captured).
+- `UDPSCOPE_PROBE_STATS_MS` — reports every measurement's accumulator (`n`, mean, sd, lo, hi),
+  pauses, reports again with `dn=` per measurement, then resets and reports a third time. Three
+  phases: `phase=0`, `phase=1` (after pause) and `phase=2` (after Reset). Needs
+  `UDPSCOPE_ENABLE_ALL_MS` ahead of it and `UDPSCOPE_PROBE_MEASURE_MS` to add measurements first.
+- `UDPSCOPE_PROBE_SIDE_TAB_MS=3000` with `UDPSCOPE_EXIT_AFTER_MS=11000` — the measurements on the
+  Measure tab, a forced pass, then the tab switched away and read again two seconds later. **`advanced=4`
+  is the assertion** (every accumulator gained passes while its page was off screen); `advanced=0` is the
+  defect where the accumulation is gated on the visible tab, which would leave a gap in min/max/avg for
+  exactly as long as the trigger was on screen. It enables *and plots* its own signal, so it needs no other
+  probe ahead of it. The reading's own entry is in `probe-readings.md`.
+- `UDPSCOPE_PROBE_SOURCE_KINDS=2000` with `UDPSCOPE_EXIT_AFTER_MS=5000`, run as `--source probe --source-opt rate=500`
+  -- the source-plugin path end to end. The variable's presence also registers the test-only `probe` kind (a
+  synthetic sine with one panel), so it is the only way a run sees that kind; its value is the delay in ms.
+  Nine `[source-kinds]` lines (one `form` line per registered kind: `udps`, `e1608`, `flatudp`, `probe`); the
+  reading's own entry is in `probe-readings.md`.
+- `UDPSCOPE_PROBE_E1608=1500` with `UDPSCOPE_EXIT_AFTER_MS`, run as `--source e1608` against
+  `tools/mock_e1608.py` -- the MCC E-1608 end to end: panels present and sensitive, a DAC write, a
+  digital-output toggle and a counter reset each reaching the mock, the stream's channels and rate, the
+  factory calibration applied, the capture button disabled, and a hand-computed decode. It enables the
+  signals itself, so do **not** add `UDPSCOPE_ENABLE_ALL_MS` (that probe switches the first signal off
+  after two seconds). Three runs, each short and serial, with the mock killed afterwards:
+  - **no board:** panels `sensitive=0`, `connected=0`, no retry flood on stderr (the one
+    `[e1608] handshake with ...: Connection refused` line is printed once, not per retry);
+  - **the mock:** `--drop-after 3 --log /tmp/e1608-mock.log`, options `scan_rate=1000 ai0=BIP10V
+    ai1=BIP5V plot0=1 plot_counter=1 dir1=o ao0_init=1.5`, with `UDPSCOPE_PROBE_E1608=1500
+    UDPSCOPE_PROBE_E1608_RECONNECT=8000 UDPSCOPE_EXIT_AFTER_MS=10500`; then read the mock's log: the AO
+    levels `1.5, 2.5, 1.5` (the log prints the quantised voltage, so `1.4999, 2.4999, 1.4999` is the
+    expected text), the DOUT bytes `0x00, 0x02, 0x00`, one `COUNTER_RESET`, one `DROP`;
+  - **a rejected code:** mock `--code 1234`, app `code=7`: one error line, the retries stop.
+- `UDPSCOPE_PROBE_E1608_GEN=1500` with `UDPSCOPE_EXIT_AFTER_MS=5500`, run as `--source e1608 --source-opt
+  address=127.0.0.1 --source-opt port=54711 --source-opt ao0_init=0 --source-opt gen_rate=100` against
+  `tools/mock_e1608.py --port 54711 --log /tmp/e1608-gen100.log` -- the generator's update rate: it starts a Sine on
+  DAC 0 through the Analog out panel (and switches the side stack to that page, since the panel refreshes on its
+  frame clock, which does not tick for a page that is off screen), waits 2.5 s, reads the achieved rate and the
+  panel's "Update rate" row, stops the generator and reads both again 400 ms later. Two lines, in
+  `probe-readings.md`. Then count the mock log's `AOUT` lines: about 250 with `gen_rate=100` (the generator ran
+  for about 2.5 s) and about 125 for a run without the option (default 50 Hz). Short and serial, the mock killed
+  afterwards. It enables nothing else, so it can run alone.
+- `UDPSCOPE_PROBE_E1608_RECONNECT=8000` -- reads the source after the mock dropped the link and 500 ms
+  later checks the frame count moved on. The reading's own entry is in `probe-readings.md`.
+- `UDPSCOPE_PROBE_E1608_SCAN=1000` with `UDPSCOPE_EXIT_AFTER_MS=6500`, run as `--source e1608 --source-opt
+  address=127.0.0.1`. Start `tools/mock_e1608.py` first on its default port 54211 (the form scans that port; do
+  not pass `--port`) and kill it afterwards. The value is the delay of phase 1; phase 2 follows 2 s after it and
+  phase 3 (the line) 2 s after that, so phase 3 runs 4 s after phase 1 and the delay must stay below about
+  2500 ms for the line to print before the exit at 6500 ms. It builds
+  the connection form, presses **Scan network**, expects the mock to be listed, clicks the result (address
+  filled, MAC and subnet cleared), presses **Use MAC** (MAC filled, the others cleared), scans again and checks
+  the results were replaced. `UDPSCOPE_PROBE_E1608_SCAN_MAC` names another board (a real one) instead of the
+  mock's `00:80:2f:00:16:08`. One `[e1608] scan:` line. It needs a non-loopback up interface with a broadcast
+  address; when the board did not answer a second line says so, and the run proves nothing about the scan.
+- `UDPSCOPE_PROBE_FLATUDP=2500` with `UDPSCOPE_EXIT_AFTER_MS`, run as `--source flatudp` against
+  `tools/mock_flatudp.py` -- the flat UDP source end to end: a hand-computed codec and decode check and the connect form's validity rules and signal-row editor (both
+  need no source; it covers the `w` suffix, the waveform and 256-channel rules, the channel decode and the
+  float64/uint16/int32/uint32/int64 types in both byte orders), the stream's channel names (`Wave[0]`..
+  for a `channels` vector) and declared rates (`rate * count` for a waveform), the channel count, value
+  continuity per row (and the offset between a vector's elements, or a waveform's block phase), the
+  wrong-size accounting and the capture button. It enables the signals itself, so do **not** add
+  `UDPSCOPE_ENABLE_ALL_MS`. Runs, each short and serial, with the mock killed afterwards (quote the `signals`
+  value: zsh globs the `[4]`):
+  - **mixed list, gap and bad datagrams:** mock `--rate 1000 --signals 'Trigger:uint8,Ia:float32,Cnt:uint64,Wave:int16[4]'
+    --gap 8,4 --bad-every 1` started 1 s before the app, the same `signals` as a `--source-opt`, with
+    `UDPSCOPE_PROBE_FLATUDP=2500 UDPSCOPE_PROBE_FLATUDP_GAP=1500 UDPSCOPE_EXIT_AFTER_MS=14500`; stderr carries
+    exactly one `datagram of 22 bytes, expected 21` line. The silence probe is a 100 ms poll that waits for the
+    stream, then for the 2 s of silence to take the source down, then for it to come back, so it does not
+    depend on when `xvfb-run` finished starting; the only requirement is that the mock's gap begins after
+    the app connected (the mock's clock starts about 4 s before the app's) and ends in time to read the return
+    (`--gap 8,4` with a 14.5 s run does both with several seconds of margin);
+  - **waveform-only list:** mock `--signals 'Wave:int16[4]w'`, app `--source-opt 'signals=Wave:int16[4]w'`,
+    `UDPSCOPE_PROBE_FLATUDP=2500 UDPSCOPE_EXIT_AFTER_MS=5000`: one channel at `rate=4000`;
+  - **big endian (decode of every width through the stream):** mock `--big-endian` on the mixed list, app
+    `--source-opt endian=big`, `UDPSCOPE_PROBE_FLATUDP=2500 UDPSCOPE_EXIT_AFTER_MS=5000`;
+  - **no sender:** `connected=0` throughout, a reading and not a failure.
+- `UDPSCOPE_PROBE_FLATUDP_GAP=1500` -- starts the silence poll described above (2 s after the source's last
+  datagram it must be disconnected; then it must reconnect and the frame count move on).
+- `UDPSCOPE_PROBE_SEARCH_MS` — runs a buffer search for the armed condition, cross-checks the live
+  trigger's own `t0` against the nearest hit (`agree=1` is the load-bearing reading), and jumps to
+  hit 0. Reports the resulting `mode=`, `axis=` and `marks placed=`.
+
+The following mock waveform features are what the qualified-condition probes are checked against,
+as distinct from the fault injection below, which exercises ingest:
+
+- `--glitch-at S` / `--glitch-width W` invert the `square` signal for `W` seconds at the start of
+  every square period from stream second `S` onwards — a runt pulse of a known width, which is
+  what a `<` pulse-width trigger and a glitch search are checked against.
+- `--quiet-at S` freezes `sine` at its held value from stream second `S` onwards, so it stops
+  crossing zero: the dropout trigger's input.
+
+- `UDPSCOPE_PROBE_RESEQ_MS` — one mid-run reading of the resequencing path. Five cases,
+  **run each as its own process** — five back to back starve the mock past its 2 s silence
+  timeout and every case then reads a reconnect instead of what it was testing. Common
+  conditions for the first four: the mock at `--rate 10000 --batch 100 --freq 5`, udpscope with
+  no extra options, under `xvfb-run` with
+  `UDPSCOPE_EXIT_AFTER_MS=8000 UDPSCOPE_ENABLE_ALL_MS=600 UDPSCOPE_EXIT_DUMP=1
+  UDPSCOPE_PROBE_RESEQ_MS=5000`. Move `~/.config/udpscope/127.0.0.1_8000/` aside first (the
+  per-endpoint session is a *directory* now -- `active` plus one `.toml` per named configuration;
+  a bare `127.0.0.1_8000.toml` is a pre-migration leftover): a session left by an earlier run
+  restores its math channel, and five channels instead of four change `channels=`, `span=` and
+  every count derived from them. It restores the **window and the measurements** too, which is
+  the subtler trap: a run after a zoom-sweep probe starts at `window_s = 0.05` with the previous
+  runs' measurements still in the pane, so `measures window:` then reports a short-window
+  sawtooth (144 %, marks off screen) on a run that asked for none of it.
+
+  | case | mock extra flags | key reading |
+  | --- | --- | --- |
+  | **base** | *(none)* | every counter 0; proves the machinery costs nothing |
+  | **reorder** | `--reorder-every 10` | `reseq=51` (mid-run) / `102` (dump); `holes=0`; resequencing inside the window leaves no reservation |
+  | **late** | `--reorder-every 10 --reorder-delay-ms 50` | `bands_repaired` one short of `bands` with `nan_slots=100`; the band still solid is the one hole whose late packet is in flight, and it is the *only* unrepaired one |
+  | **mixed** | `--drop-every 20 --reorder-every 10 --reorder-delay-ms 50` | `bands=43 bands_repaired=20 nan_slots=2200`; all three band states at once |
+  | **re-plan** | `--rate 100000` with the `mixed` flags, and `UDPSCOPE_PROBE_WINDOW_MS=4000 UDPSCOPE_PROBE_RESEQ_MS=6000 UDPSCOPE_EXIT_AFTER_MS=9000` | four `buffer rebuilt` lines before the reading, then `bands=64 bands_repaired=16 nan_slots=7800`: **a band is still only marked repaired when its own slots hold values**. A `bands_repaired == bands` beside a non-zero `nan_slots` here is the hole table and the producer's `tick_` surviving a re-plan that reset `produced()` — a band marked settled over samples that are all still NaN. The non-zero `overflows` is this case too: 100 kS/s with a 50 ms reorder delay keeps about 50 packets in flight against 64 slots |
+
+  The re-plan case needs `--rate 100000`, not the other four's 10 000: at 10 kS/s the ring
+
+- `UDPSCOPE_PROBE_CAPTURE_MS` — toggles the packet capture **through the same handler the
+  status-bar button uses**, waits, then reads the file back off disk and prints one line:
+  `enabled= path= slots= stored= resident= cursor= torn= truncated= header_ok= first_seq=
+  last_seq= payload= file= open_ms= t0=`. `stored` is the datagrams-since-open counter and must
+  equal the dump's datagram count from the toggle's instant; `resident` is what the file holds,
+  which is the slot count once the ring has wrapped; `file` is the reserved size
+  `64 + slot_count * slot_bytes` and is a constant for a given N, so a mismatch against the file
+  on disk is a reading. Two cases, **run each as its own process**:
+
+  1. **enable at runtime** — the mock at `--rate 20000 --batch 200`, udpscope with
+     `UDPSCOPE_ENABLE_ALL_MS=700 UDPSCOPE_PROBE_CAPTURE_MS=1500 UDPSCOPE_EXIT_AFTER_MS=9000`
+     and no capture flag: `enabled=1 header_ok=1 torn=0 truncated=0 first_seq=1`, `stored` equal
+     to the datagrams since the toggle, `open_ms` a few ms.
+  2. **wrap** — the same with `--capture-packets=16` and
+     `UDPSCOPE_PROBE_CAPTURE_MS=7000 UDPSCOPE_EXIT_AFTER_MS=10000`: `stored` (870 in the
+     reference run) exceeds `slot_count`, `resident=16`, `last_seq - first_seq == 15`,
+     `torn=0`, and `cursor` agrees with `seq` (counter mod slot count). A wrap that loses
+     ordering, or a `cursor` that disagrees, shows here and nowhere else.
+
+  Then the converter over the wrap case's file: `tools/capture_to_pcap.py <capture> out.pcap`
+  must exit 0, print a record count equal to `slot_count` with `torn` 0, and the pcap's first
+  and last record timestamps must fall inside the run's wall-clock interval — both checked by a
+  `struct.unpack` of the pcap headers, nothing outside the standard library.
+
+- **A gap must not kill a filtered trace.** `--relative-time` with the mock dropping
+  (`--drop-every 20`) and `UDPSCOPE_PROBE_MATH_MS=2500 UDPSCOPE_ENABLE_ALL_MS=600
+  UDPSCOPE_EXIT_AFTER_MS=9000`: every derived channel's dump line
+  `math '<name>': finite=N/4000` must read about 3800 — the tail minus the reserved holes —
+  and **`finite=0` beside a non-zero `hole_slots` is the defect** (a biquad that integrated the
+  hole's NaN, permanently). The filters' `sd` must stay near the no-drop value; run the same
+  command without `--drop-every` as the control, where every `finite` reads 4000.
+- **A math edit on a ring that has already wrapped.** `UDPSCOPE_PROBE_MATHWRAP_MS` — installs one
+  `Gain` graph over the mock's sine, waits for the ring to **saturate**, and only then edits the gain,
+  which is the one state `UDPSCOPE_PROBE_MATH_MS` cannot reach (each of its edits follows a structural
+  change, and a replan restarts every ring at absolute 0). It therefore needs a **small buffer and a long
+  run**: `--buffer-mb 1` against `--rate 20000 --batch 200`, with
+  `UDPSCOPE_PROBE_MATHWRAP_MS=1500 UDPSCOPE_EXIT_AFTER_MS=25000`. `base > 0` on its second line is the
+  precondition — **`base=0` means the run tested nothing** — and the third line's `produced == slots` and
+  `y=±0.5` are the two assertions; both are in [probe-readings.md](probe-readings.md).
+- `UDPSCOPE_PROBE_CONFIGS_MS` — saves the running session as a configuration named `probe` with a
+  note, through `save_configuration_as()` (the same entry point the dialog's button uses), then
+  reads it back off disk. Reading: `save-as=1`; `names=` gains `probe`; `active=probe`; and the
+  round trip must carry the note **and** the startup settings —
+  `comment='written by the configs probe' buffer_mb=8 relative=0 capture=0`. A `buffer_mb=0` there
+  is the per-source buffer size not being written, which is the one setting a user notices only
+  after a capture has been sized wrong. Run it with a throwaway `XDG_CONFIG_HOME`; the probe
+  deletes its own configuration at the end (`after forget names=…`).
+- `UDPSCOPE_PROBE_ROWMENU_MS` — gives row 0 a trace, opens the plot's context menu with
+  `open_row_menu()` (the one entry point `on_right_click()` wraps) and walks its two views one step
+  at a time (`main` → click **Remove signal** → `remove` → click **Back** → `after-back` → click
+  **Remove signal** again → `second-open` → click a trace), measuring each view's rows:
+  `[rowmenu] <view> N '<label>' h=18 label_x=26 accel_right=R/W ok=1` per row and one
+  `rows=/bad=/labels=` line per view, then `[rowmenu] summary main_rows=5 main_bad=0 remove_rows=6
+  remove_bad=0 after_back_rows=5 after_back_bad=0 second_rows=6 second_bad=0 remove_row_in_main=1
+  remove_row_gone=1 can_open_again=1` and `[rowmenu] remove-clicked 'sine' trace_freed=1`.
+  **Every `bad` must be 0** (the same compact row style as the app's own menu: one label column, a
+  shortcut flush right, 18 px rows — the **Back** row's icon indents its label, which every menu
+  does, so its `label_x` is 52 against the others' 26) and the three booleans must all read 1: the
+  remove view *replaces* the main one (`remove_row_gone`, `remove_row_in_main`), and it can be
+  entered again after leaving it (`can_open_again`) — that last one is the case a
+  `GtkMenuButton`-owned submenu failed, its row going dead on the second click. Each view is
+  measured a step after the click that swapped it in, because a popover allocates its new child on
+  the next layout pass.
+- `UDPSCOPE_PROBE_HELPUI_MS` — the help affordance layer, end to end, in ten steps 300–400 ms apart:
+  the **first-run auto-start** (run it once with a throwaway `XDG_CONFIG_HOME` to see `auto=1`, and
+  again against the same one to see it not repeat), the menu's seven rows and the **four entries of
+  the Help submenu**, the **contextual-help toggle** with the count of "(i)" affordances on either side
+  of it, the tour **started from the probe** and stepped forwards, back and dismissed, and `help
+  figures:` read in both of the trigger pane's modes. Its lines and what each asserts are in
+  [probe-readings.md](probe-readings.md); the two things to read first are **`hints=0`** while the
+  toggle is off (off is *gone*, not greyed) and **`controllers=12 (was 12)`** after the dismissal (no
+  lingering input grab — a tour of ordinary overlay widgets takes none), and **`hint=12x12`** is the
+  size the shrunk "(i)" must keep (the default menu-button mark is 34x34). The `collapsed search:` line
+  is the header hint read on the search block's expander while it is collapsed. The chooser's own tour is
+  the other half and has its own entry points — see the **chooser** bullet below. Give it
+  `UDPSCOPE_EXIT_AFTER_MS=9500 UDPSCOPE_EXIT_DUMP=1` to get the `help layer:`/`help figures:` dump
+  lines as well, and note the tour **auto-starts** in any run whose settings file does not carry
+  `tour_seen` — **in the source chooser when there is one**, in the window otherwise (see the chooser
+  bullet) — so a probe run against a fresh config directory will have it on screen for the first
+  second and a half, and that start *writes* `tour_seen` to whichever config directory the run is
+  using, which is why the second run against the same one reads `auto=0`.
+- `UDPSCOPE_PROBE_TOUR_SURFACE_MS` — the tour's *surface* switch: it puts the sidebar on **Measure**,
+  starts the window's tour, and walks it a stop per tick to the signals stop, reading the sidebar's
+  page and the spotlight/card where the walk arrives. It then puts the sidebar *away* and starts the
+  tour again, which is the same filter's other case (a collapsed pane drops the stops a page switch
+  could have revealed). `[toursurface] signals stop=4/5 … side_tab=signals … contains=1` and
+  `[toursurface] collapsed: side_stack_mapped=0 steps=2 signals_stop=0` are the two assertions; its
+  lines are in [probe-readings.md](probe-readings.md). Run it alone with
+  `UDPSCOPE_EXIT_AFTER_MS=9000 UDPSCOPE_EXIT_DUMP=1` against a live source.
+- `UDPSCOPE_PROBE_DEFAULTS_MS` — opens **Calibrate** and reads every spin button in it and in the
+  trigger panel: `[defaults] calibrate: 1 0 model=1 0 | trigger: 0.001 0.002 0 0.001 0 50 0.01`. A
+  `GtkSpinButton` starts at its range's *minimum*, so a `-1e12` here is an unseeded button the
+  dialog's own reader would then apply — which is exactly what the calibration offset did. It then
+  calibrates signal 0 through `set_calibration()` and reopens the dialog:
+  `[defaults] calibrated: 2.5 -1.25 model=2.5 -1.25` — **the dialog must show the signal's stored
+  calibration**, and the two halves must match.
+- The **chooser**, display-free: `UDPSCOPE_PROBE_SOURCES=1` prints `[sources] N known:` with one
+  entry per configuration (`host:port/name … buffer= relative= note='…'`), and
+  `UDPSCOPE_PROBE_PICK_MS=800` opens the chooser, picks the first row and prints
+  `[sources] picked host:port … buffer=64 relative=0 capture=0 config=… note='…'` — the settings the
+  configuration carried, into the `Config` the model is built from. **With no `--server` and no probe
+  the chooser blocks in its own nested loop** (no frame to end and no dump), so a chooser run is
+  always this probe. It also prints the dialog's frame *and its own help layer*:
+  `[sources] chooser ui: … hints=[2 {chooser_sources chooser_waveform}] hint=12x12` with the setting
+  on, `hints=[0 {}] hint=0x0` with it off. `UDPSCOPE_PROBE_CHOOSER_HELP=1` drives the **Enable
+  contextual help** row and reads the file back; `UDPSCOPE_PROBE_CHOOSER_TOUR=1` drives the **Guided
+  tour** row and walks the chooser's own tour to its last stop, printing `[sources] chooser tour: …`
+  and the handoff (`tour_pending=1`); `UDPSCOPE_PROBE_CHOOSER_TOUR_MS=<ms>` walks it a stop per tick
+  instead, printing the page the stack shows at every stop and stepping **Back** off the stop that
+  stands on the waveforms page — the reading for the surface a stop changes. It starts the walk
+  itself when one is not running, so it does not need a first-run config; pair it with
+  `UDPSCOPE_PROBE_PICK_MS` after the walk so the application's half follows. A working run: seed a
+  source once (`./build/udpscope --server 127.0.0.1 --port N` against a mock, under the throwaway
+  `XDG_CONFIG_HOME`), then run bare with
+  `UDPSCOPE_PROBE_CHOOSER_TOUR_MS=2000 UDPSCOPE_PROBE_PICK_MS=4500 UDPSCOPE_EXIT_AFTER_MS=12000
+  UDPSCOPE_EXIT_DUMP=1`. Its lines and what each asserts are in
+  [probe-readings.md](probe-readings.md). A legacy file
+  (`<host>_<port>.toml`) produces `layout loaded from …/<host>_<port>/default.toml`, an `active`
+  holding `default`, and the old file renamed `.imported`.
+- **The loading window covers the gap, and only on the path that asked.** The same
+  `UDPSCOPE_PROBE_PICK_MS` run must print
+  `[sources] loading: title='Connecting to 127.0.0.1:<port>' detail='planning the N MB sample buffer'`
+  **between** the `picked` line and the stream's `CONFIG:`, and `[sources] loading: closed` **after**
+  it — the window is raised before the buffer is planned and taken down only once the real window has
+  been presented, which is the whole of what it exists for. `UDPSCOPE_PROBE_WAVE=<path>` is the file
+  leg of it (`title='Opening <basename>' detail='reading the recording'`, before `waveform loaded:`).
+  A run that names its source with `--server` prints **no** `loading:` line at all: every other probe
+  here is on that path and must stay on it.
+- **The event cache round-trips, and only where it is available.** `UDPSCOPE_PROBE_EVENTS_MS` reads
+  the pane's availability first, in the state the app starts in -- `[events] live: button_visible=0
+  pane=0 recording=1`, **no pane and no button without trigger mode** -- then turns trigger mode on
+  through the real toggle (`[events] after trigger on: button_visible=1 pane=0`: the button appears,
+  the pane stays collapsed) and clicks the button, waits for a latch, then reads the cache and replays
+  the newest event through the pane's own row:
+  `[events] dir=… n=1 newest: dur=2.000000 pre=1.000000 post=1.000000 edge=… signals=4 samples=20001
+  rate=10000 seq=1 thumb_bytes=230454 recorded=1 pane=1`, then
+  `[events] activated row0: replaying=1 thumbnail=1 thumb_size=108x36 thumb_visible=1` (the size is
+  what says the picture is *on screen*: a paint-able alone is not), `[events] replayed: channels=4
+  samples=20001 replaying=1 waveform=1` and `[events] live again: replaying=0 waveform=0`. It ends on
+  the pane's availability, through the trigger panel's switch: `[events] recording off, trigger off` and
+  `[events] recording off, trigger on` -- once the cache holds events (the probe's own run has written
+  some by this point) both read `button_visible=1 pane=1 recording=0`, because a button that shows the
+  cache must not go away with the switch that wrote it; against an *empty* cache the same two lines read
+  `button_visible=0 pane=0`, which is the empty column the item exists to prevent. **`samples` must equal the
+  export's row count for the same window** (`20001` for a 2 s event at 10 kS/s), `thumb_bytes` must be
+  a real BMP (`54 + 480*160*3`-ish, i.e. hundreds of kB, not 0), `thumbnail` must be 1 (the row loaded
+  the picture) and the last line must read `replaying=0` -- a replay with no way back is a one-way
+  door. It then **waits for a second latch** (bounded: twelve retries) and drives the two group layouts
+  through the buttons: `[events] compare buttons: cached=2 selected=2 compare=1 accumulate=1` (the
+  buttons read the selection), `[events] halve`… `[events] halves a_first=20001 a_second=0 b_first=0
+  b_second=20001` -- **the two halves of the ring, and the reading that says a comparison's gap is a
+  gap: the first event's channel is finite only in the first half and the second's only in the second**
+  -- `[events] compare: kind=1 rows=4 channels=8 samples0=40002 traces0=2 traces1=2 window=4.000
+  recording=1 pane=1` (`samples0` must be exactly the stamps pushed, **not more**: a live producer left
+  running pushes its own four signals into the group's eight channels), `[events] compare plots:
+  area_b=1 rows_a=1 rows_b=1 x_a=[-2.000,0.000] x_b=[-2.000,0.000] same_x=1` (the second plot exists, is
+  on screen, mirrors the row count, and both are on one x window), then the sync -- the probe sets a y
+  range nobody would arrive at by accident on the *first* plot and reads the second a few frames later:
+  `[events] compare sync: y_a=-3.500 y_b=-3.500 mirrored=1` -- and `[events] accumulate: kind=2 rows=1
+  channels=8 samples0=33045 selected=2 traces0=8 window=2.000` (`traces0=8`: the four signals the layout
+  holds plus one layer each for the second event, **in the same row**, which is what an accumulation
+  means). Run it with a throwaway
+  `XDG_CACHE_HOME` and `UDPSCOPE_EXIT_AFTER_MS` long enough for the second latch (20 s).
+- **A waveform round-trips.** Export from a live run (`UDPSCOPE_EXPORT_MS` with
+  `UDPSCOPE_EXPORT_PATH`, against the mock at 10 kS/s), then open that file with `--open` and an
+  exit dump. The load must print
+  `[udpscope] waveform loaded: … signals=4 samples=20001 rows=20001 decim=1 span=2.000000s rate=10000 time=[-2.000000..0.000000]`
+  — **the same row count, column count, span and time range the export probe reported**
+  (`rows=20001 cols=4 time=[-2.000000..0.000000]`) — and the dump must show `channels=4`,
+  `frames=0 packets=0` (no acquisition) and, per channel,
+  `20001 samples vs 20001 time slots … y=[-1.0000, 1.0000]`. A file that loads with fewer samples
+  than it was written with, or with `NaN` slots, is the reader mis-slicing its records.
+- **A recording that does not fit its buffer is *filtered* into it, not truncated.** The case needs a
+  file bigger than the budget, which the mock cannot export in one window, so write one with NumPy —
+  the dtype is the exporter's own, `[('time','<f8'), ('abs_seconds','<f8'), (<signal>,'<f4'), …]` — and
+  open it against a small buffer:
+  ```bash
+  python3 -c "import numpy as np; n=1000000; t=-4.0+np.arange(n)/50000.0; \
+  a=np.zeros(n, dtype=[('time','<f8'),('abs_seconds','<f8'),('a','<f4'),('b','<f4'),('c','<f4'),('d','<f4')]); \
+  a['time']=t; a['abs_seconds']=1000.0+t; a['d']=np.linspace(-1,1,n); np.save('/tmp/long.npy', a)"
+  xvfb-run -a env UDPSCOPE_EXIT_AFTER_MS=4000 ./build/udpscope --open /tmp/long.npy --buffer-mb 1
+  ```
+  must read `samples=31250 rows=1000000 decim=32 span=19.999980s time=[-4.000000..15.999980]` and
+  `stored=31250 … published=31250` per channel — **the whole span, at a thirty-second of the rate**.
+  The ramp column is the assertion that the *head* is there: `y=[-0.999969, 0.999969]` is the file end
+  to end, where the defect this exists for reads a fraction of it. With every row pushed regardless of
+  the plan, this file arrived as its **last 0.9 s** and nothing in the log said so.
+- **A loaded file can be plotted.** `UDPSCOPE_PROBE_DROP_MS` drives the drop handler the way a drag
+  from the signal panel does, on a file opened with `--open`: it must read
+  `[drop-probe] signals=4 channels=4 rows=4 slots0=[sine|||] view=[-3.999690..15.999670] repins=2` —
+  **`rows` equal to the column count**,
+  one trace per row — and each drop must return `1` and add its trace (`dropped signal 1 -> 1
+  slots=[sine|sine|square|]`). `rows=1 slots0=[sine|square|ramp|noise]` with every drop returning `0`
+  is the defect this exists for: rows sized four signals to one row fill the only row, so the app
+  reads as one that cannot plot anything. A file-mode run must also write **no session** for the
+  default `127.0.0.1:8000` (`App::source_port` is 0), or it overwrites that source's saved layout.
+- **A file view states its pin once.** `repins` on the line above must read **2** whenever the probe
+  is scheduled — at one second or at seven — and `view` must be the file's whole span. A file's extent
+  does not change while it is open, so the tick refreshes the pin's *numbers* and writes the group's
+  range only when the view first becomes an event. Reading it against the decimated file above
+  (`/tmp/long.npy`, stamps `[-4..16]`) is the case that matters: with the pin written as a pre/post
+  split where a range belonged it read `view=[3.999690..15.999670] repins=116` at three seconds —
+  the axis alternating between the file's span and a corrupted pin every frame, which on screen is a
+  flicker in which no pan, zoom or click survives to the next frame. A file whose stamps are all
+  positive, or which ends at 0 (an export's own window), hides it: the corrupted pin is then wider
+  than the data, or empty, and the clamp never fires. `UDPSCOPE_PROBE_PAN_MS` on the same run is the
+  other half — `allowed=1` and a `view` that is still the zoomed range when the drop probe reads it
+  later is interaction actually taking.
+- **The chooser's Waveforms page**: `UDPSCOPE_PROBE_WAVEFORMS=1` prints
+  `[sources] waveforms: N recent <path>(ok|missing) … page=waveforms`, and `UDPSCOPE_PROBE_WAVE=<path>` sets
+  the field the file dialog's callback sets and prints `[sources] picked waveform <path>` — then the
+  load line above, with no socket involved.
+- **A `--server` launch reads the stored configuration.** With a throwaway `XDG_CONFIG_HOME`
+  holding `127.0.0.1_8101/bench.toml` (`buffer_mb = 64`, `relative_time = true`,
+  `capture_packets = 500`, `active` = `bench`), `./build/udpscope --server 127.0.0.1 --port 8101`
+  must print `[sources] settings from configuration 'bench': buffer=64 relative=1 capture=500`, the
+  `relative time:` line, and a `span=` of about 209 s (64 MB at 10 kS/s) — **not** the 200 MB
+  default's ~655 s. The same command with `--buffer-mb 8` must read `buffer=8` and `span=26.214s`:
+  **an explicit flag wins over the file**. Without this, the settings a host was edited to have were
+  ignored whenever the address came from the command line.
+- The chooser's **form**, with `UDPSCOPE_PROBE_PICK_MS` scheduling it:
+  `UDPSCOPE_PROBE_NEWHOST=host:port` fills it and prints
+  `[sources] form: name='probe-host' note='…' buffer=32 relative=1 connect_sensitive=1`, then
+  `[sources] configuration created: host:port/probe-host … buffer=32 relative=1` and a
+  `picked … config=probe-host`; a following `UDPSCOPE_PROBE_SOURCES=1` must list it
+  (`buffer=32 relative=1 note='…'`) — a configuration the form wrote that the chooser does not
+  list cannot be edited next time. `UDPSCOPE_PROBE_EDITHOST=host:port` opens the same form on that
+  configuration and prints `[sources] edit form: name='…' note='…' buffer=… relative=… button='Save'`
+  — **the pre-fill is the assertion**: an edit form that opens empty cannot edit anything — then
+  saves and reports the new values. `UDPSCOPE_PROBE_EDITNAME=new-name` renames it as well: one
+  `known:` row afterwards, with the old file gone.
+- `UDPSCOPE_PROBE_RESEQ_MS`'s neighbour for **reconnect**: the mock gains an EMI case,
+  `--blackout-at S --blackout D` — silent from second S for D seconds (D must exceed the
+  client's 2 s silence timeout), resuming from *now* so the link's backlog is what the link
+  ate. One run (`--blackout-at 4 --blackout 3.5`, `UDPSCOPE_EXIT_AFTER_MS=15000`) has to read:
+  every reconnect's `CONFIG:` line followed by `CONFIG unchanged: keeping the buffer and its
+  history` (a reconnect that re-plans wipes history, which is the defect this case exists for),
+  no `buffer rebuilt` line after the first CONFIG, `frames` climbing again after the blackout
+  with `gaps=0`, and a trigger armed *after* recovery (`UDPSCOPE_PROBE_KEYS_MS` past the
+  blackout) latching — the dump's `CAPTURING`/`EVENT HELD` and `publish cost: N events` with
+  N ≥ 1 are that proof.
+  already covers 838 s, so no window the control can reach moves `time_stride`,
+  `set_target_span()` returns without rebuilding, and the window probe reports `decim=1`
+  throughout — it re-plans nothing. At 100 kS/s the ring covers 83.9 s and the probe's
+  500 ms → 500 s → 120 s → 600 s → 60 s walk crosses the boundary four times.
+
+  Full measured readings (probe line first, then exit-dump):
+
+  ```
+  === base   mock: none
+  [reseq-probe] reseq=0 late=0 stale=0 overflows=0 holes=0 hole_slots=0 backfilled=0 open_holes=0
+                bands=0 bands_repaired=0 nan_slots=0 scanned=44200 trigger_in_hole=0
+  [udpscope] frames=1032 packets=1033 gaps=0 channels=4 span=838.861s stride=1 reseq=0 late=0
+             stale=0 overflows=0 holes=0 hole_slots=0 backfilled=0
+  [udpscope]   channel 0 'sine' stored=95700 published=95400
+
+  === reorder   mock: --reorder-every 10
+  [reseq-probe] reseq=51 late=0 stale=0 overflows=0 holes=0 hole_slots=0 backfilled=0
+                open_holes=0 bands=0 bands_repaired=0 nan_slots=0 scanned=44200
+                trigger_in_hole=0
+  [udpscope] frames=1027 packets=1028 gaps=0 channels=4 span=838.861s stride=1 reseq=102 late=0
+             stale=0 overflows=0 holes=0 hole_slots=0 backfilled=0
+  [udpscope]   channel 0 'sine' stored=95300 published=95100
+
+  === late   mock: --reorder-every 10 --reorder-delay-ms 50
+  [reseq-probe] reseq=157 late=46 stale=0 overflows=0 holes=40 hole_slots=4000 backfilled=15600
+                open_holes=40 bands=40 bands_repaired=39 nan_slots=100 scanned=44000
+                trigger_in_hole=0
+  [udpscope] frames=1027 packets=1028 gaps=98 channels=4 span=838.861s stride=1 reseq=296
+             late=98 stale=0 overflows=0 holes=91 hole_slots=9100 backfilled=36400
+  [udpscope]   channel 0 'sine' stored=95300 published=95000
+
+  === mixed   mock: --drop-every 20 --reorder-every 10 --reorder-delay-ms 50
+  [reseq-probe] reseq=159 late=25 stale=0 overflows=0 holes=43 hole_slots=4300 backfilled=8400
+                open_holes=43 bands=43 bands_repaired=20 nan_slots=2200 scanned=44100
+                trigger_in_hole=0
+  [udpscope] frames=978 packets=981 gaps=101 channels=4 span=838.861s stride=1 reseq=309 late=50
+             stale=0 overflows=0 holes=94 hole_slots=9400 backfilled=18400
+  [udpscope]   channel 0 'sine' stored=95400 published=95400
+
+  === re-plan   mock: --rate 100000 --drop-every 20 --reorder-every 10 --reorder-delay-ms 50
+  [reseq-probe] reseq=4374 late=72 stale=0 overflows=36 holes=315 hole_slots=31136
+                backfilled=26800 open_holes=64 bands=64 bands_repaired=16 nan_slots=7800
+                scanned=156600 trigger_in_hole=0
+  [udpscope] frames=8949 packets=8953 gaps=614 channels=4 span=83.886s stride=1 reseq=8028
+             late=144 stale=0 overflows=36 holes=603 hole_slots=59936 backfilled=55600
+  [udpscope]   channel 0 'sine' stored=588600 published=584600
+  ```
+
+  The `late` case's `bands_repaired` is one short of `bands` with `nan_slots=100` — exactly one
+  packet's worth of slots at stride 1 — because the probe fires 50 ms-delayed releases into a
+  window that always has one in flight. An earlier recording of this case read
+  `bands_repaired=42 nan_slots=0`; both are healthy, and which one a run gets is where the
+  probe's instant falls relative to the newest release. A `bands_repaired` *above* the count of
+  holes whose slots hold values is the defect, in either direction.
+
+  `holes` far above `open_holes` in the re-plan case is the two bounds working: a re-plan clears
+  the table (the old entries address a buffer that is gone) and `kMaxHoles` caps what survives
+  at 64. The `mixed` case's `open_holes=43` against `bands=43` has no such spread because
+  nothing re-planned. The per-field reference is in [probe-readings.md](probe-readings.md).
+
+The mock also carries four **fault injections** that no probe schedules, because what they exercise
+is the ingest rather than the UI. The first: `--time-glitch-at <stream seconds> --time-glitch-by <seconds>` makes
+**one** packet's time signal jump ahead and then carries on from where the true timeline was, which
+is what a device whose clock glitches puts on the wire. Run it with the trigger armed, e.g.
+
+```sh
+xvfb-run -a env UDPSCOPE_ENABLE_ALL_MS=400 UDPSCOPE_ARM_TRIGGER_MS=700 UDPSCOPE_EXIT_AFTER_MS=22000 \
+  ./build/udpscope --server 127.0.0.1 --port 8000 --holdoff 10
+# mock: --rate 10000 --batch 100 --freq 5 --time-glitch-at 6.0 --time-glitch-by 10.0
+```
+
+Four readings, all off the once-a-second `[udpscope] trig engine:` line:
+
+- exactly one `warning: ... jumped implausibly far ahead of the previous packet (16.01..16.0199
+  against a previous 6.0099); bridging that packet ...` — the glitch was **caught**;
+- **no** `timing samples by arrival instead` — one bad packet must not change the time source;
+- `now_t` crosses the glitch continuously (`5.040 → 6.050 → 7.050`), and `history` keeps **growing**
+  (`1.01 … 23.15`) instead of collapsing — the ring was not wiped;
+- the latches stay a hold-off apart: `edge at 1.060 / latched at 2.060 / holdoff_until=12.060`, then
+  `edge at 12.260 / latched at 13.260 / holdoff_until=23.260` — **11.2 s** for a 10 s hold-off plus
+  a 0.9 s post window.
+
+Before the fix the same run read a fallback warning, `history` collapsing 4.03 → 0.95, `now_t`
+jumping 5.040 → 16.040, and two latches **1.2 s** apart. Note the window here comes from the saved
+session for that port; the figures above are the default 2 s window (50 % pre), so move
+`~/.config/udpscope/<host>_<port>/` aside to reproduce them.
+
+The other two are **packet loss** (`--drop-every N`, `--drop-burst K`) and **wire inversion**
+(`--reorder-every N`). Loss withholds a datagram the counter and the stream clock have already
+advanced over; the client counts the forward jump as `counter_gaps`. An inversion withholds a
+packet until the one behind it is sent, so the receiver sees a later counter first; a packet that
+arrives within the 20 ms reorder window is resequenced with no hole, and one that arrives past it
+leaves a committed hole that it then backfills (`UDPSCOPE_PROBE_RESEQ_MS` exercises both paths).
+There is **no interpolation** anywhere below the ring.
+
+The fourth is the counter itself: **`--counter-step N`** advances the header counter by `N` per
+datagram instead of one -- a device whose counter counts *samples*, or frames of an inner layer,
+rather than packets. Nothing is withheld and every datagram goes out on schedule, so the link is
+intact and the status bar is right to say `live`; what is wrong is the counter's claim, which the
+client cannot check (it has no clock) and only the app can (it has the arrival times). It is the
+one wire shape the mock could not otherwise produce, and the run that reads it is the reseq probe
+with relative time on (the mode that frames a counter gap as NaN by construction):
+
+```sh
+# mock: --counter-step 10
+xvfb-run -a env UDPSCOPE_EXIT_AFTER_MS=8000 UDPSCOPE_ENABLE_ALL_MS=600 \
+  UDPSCOPE_PROBE_RESEQ_MS=5000 UDPSCOPE_EXIT_DUMP=1 \
+  ./build/udpscope --server 127.0.0.1 --port 8000 --relative-time
+```
+
+```
+# fixed:  [reseq-probe] … holes=1 hole_slots=900 backfilled=0 gaps_refused=419 open_holes=0
+#         bands=0 bands_repaired=0 nan_slots=0 scanned=21700 trigger_in_hole=0
+#         status bar: glance=[● live · 9.97 kS/s · 2 s window]
+# broken: [reseq-probe] … holes=420 hole_slots=378000 backfilled=0 open_holes=64 bands=64
+#         bands_repaired=0 nan_slots=198000 scanned=220000 trigger_in_hole=0
+#         status bar: glance=[● live · 101 kS/s · 2 s window]
+```
+
+**`gaps_refused` above 0 with `nan_slots` at 0 is the assertion** — the gap was refused and the
+samples were kept. The broken reading is `nan_slots` at 90% of `scanned` with `backfilled=0`: a
+reserved hole per datagram, `relative_time` framing each one as NaN, and nothing ever missing to
+backfill it, i.e. one missing-data band over the whole window with no trace in it, under a status
+bar reading `live` at ten times the stream's real rate. The same field
+must be **0** on every honest shape above (`--drop-every`, `--drop-burst 200`,
+`--reorder-delay-ms 50`, at 10 kS/s: `holes=210 hole_slots=21000 nan_slots=11000 scanned=22000
+gaps_refused=0` for `--drop-every 2`, `holes=3 hole_slots=60000 nan_slots=20000` for the 200-packet
+burst at 100 kS/s) — a non-zero reading there means the arrival test is refusing real loss, whose
+only cost is a gap with no shading.
+
+All of the readings below are off `UDPSCOPE_EXIT_DUMP`'s `[udpscope] frames= packets= gaps=` line,
+over an 8 s run against `--rate 10000 --batch 100 --freq 5` (100 packets a second) except where the
+burst needs the faster stream. **`gaps` is the exact reading** and repeats to the packet; `frames`
+and `packets` move by one or two with the run's own timing. Run each of these on its own — four of
+them back to back in one script starved the mock past the 2 s silence timeout and every case,
+including the clean one, then read a reconnect instead of what it was testing:
+
+- **clean**, as the reference: `frames=1029 packets=1030 gaps=0`, no warning.
+- `--drop-every 10`: `frames=925 packets=926 gaps=102`. Every tenth packet never reaches the wire,
+  so `packets` falls with `frames` and `gaps` is the count of them. No warning: a one-packet hole is
+  a one-packet jump in the stamps, far inside the glitch guard.
+- `--reorder-every 10`: `frames=1028 packets=1029 gaps=0`. The inverted packet lands inside the
+  20 ms reorder window and is resequenced: every datagram arrives and `gaps` is 0. The
+  pre-resequencing signature was `frames=925 packets=1028 gaps=102` — an inversion cost a counter
+  gap and a discarded packet, which is exactly what resequencing removes. Adding
+  `--reorder-delay-ms 50` pushes the arrival *past* the window and is the case the
+  `UDPSCOPE_PROBE_RESEQ_MS` readings above cover; it is not this row.
+- `--drop-every 1000 --drop-burst 200` at `--rate 100000 --batch 100` (1000 packets a second):
+  `frames=7000 packets=7001 gaps=1600`, eight bursts of 200, and still no warning.
+- `--drop-every 1000 --drop-burst 300`, same stream: `frames=6203 packets=6204 gaps=2400` **and the
+  guard fires** — `warning: ... jumped implausibly far ahead of the previous packet (1.299..1.29999
+  against a previous 0.99899)`, then `timing samples by arrival instead`. 300 packet spans is past
+  `kGlitchPackets` (256), so real loss is read as a clock glitch; and since each bridge advances the
+  anchor by one packet span while the true timeline is 300 ahead, the next four packets fail too and
+  `kFailureLimit` throws the stream onto the arrival clock. A burst between 256 packets and the 2 s
+  `silence_timeout_s` is the only window in which this is reachable, and it is a finding, not a
+  baseline.
+
+Keep a burst under 2 s of wire time whatever the rate: past that the client reconnects, the mock
+resets its counter and clock on the new CONNECT, and the run reads `gaps=0` with a *backwards* stamp
+warning (`does not advance across packets ... 0..0.0099 against a previous 0.3899`) — the reconnect
+path, not the loss path.
+
+**Run one self-check at a time.** Two concurrent `xvfb-run -a` instances end up on the
+same display and the second gets no GL context — it dumps `layout over 0 frames` and
+`valid=-1`, which looks like a pipeline failure and is not one. `tools/mock_udpstreamer.py`
+also outlives its `--duration`, so kill it after each run or the leftovers pile up and
+hold ports.
+
+The probes are the regression net — when changing UI or plot-host behaviour, extend
+the probe/dump in `src/ui.cpp` rather than adding a separate harness.
+
+## The noise probe needs a spiked mock
+
+Every other probe runs against the plain mock. The noise probe reads what a *band* and an *HF reject* do to
+impulsive interference, so its mock must have some: an alternating-sign impulse train of 2 samples at
+amplitude 0.5 every 5 ms, added to `sine` alone (so a spiked channel can be read against a clean one in the
+same run).
+
+```bash
+cd /home/martino/Projects/tools/udpscope
+python3 tools/mock_udpstreamer.py --port 8108 --rate 1300000 --batch 1000 --duration 20 \
+  --spike-every 0.005 --spike-amp 0.5 --spike-width 2 --square-harmonics 0 \
+  > /tmp/noise-mock.log 2>&1 &
+sleep 1.5
+xvfb-run -a env UDPSCOPE_EXIT_AFTER_MS=18000 UDPSCOPE_ENABLE_ALL_MS=1000 \
+  UDPSCOPE_PROBE_NOISE_MS=4000 \
+  ./build/udpscope --server 127.0.0.1 --port 8108 2>&1 | grep -E 'noise-probe|CRITICAL'
+```
+
+`--square-harmonics 0` is the one flag in that command that is not about the sine, and it is what keeps the
+probe's last reading exact: the group-delay leg measures a one-pole's *step* response on `square`, and the
+mock's square rings by default (see [build-and-run.md](build-and-run.md)). A band-limited edge moves that
+crossing off `tau*ln2` — measured `delay=0.002770 ratio=1.255` against the ideal step's `0.002206 / 1.000`,
+and the same figure on every run, so it is a property of the shape and not of the run. The leg's assertion is
+the `0.7..1.4` band, which the ripple keeps, but the ideal step is what keeps the *number* the line prints
+beside `want` as well. The other legs measure event counts on the sine, which the ripple does not touch; the
+counts do read a few percent lower under the ripple at this rate, for the producer-cost reason
+[build-and-run.md](build-and-run.md) gives.
+
+`UDPSCOPE_PROBE_NOISE_MS` is **not the time its readings are taken**. It times the probe's first stage, which
+installs a math graph through `apply_math_channels()` -- and that is a *structural rebuild* that replaces the
+buffer and drops its history. Every reading the probe takes is over retained history, so the rebuild has to
+happen seconds *before* them, and the chain is what the number is really choosing: `4000` puts the graph in at
+4 s, `noise_probe` at 9 s (it enables the signals it measures itself and waits 2.5 s for the ring to refill
+after *that* change), the legs and the five measurements at about 11.5 s, the de-noise channel enabled at
+14 s, and the de-noise reading at 16.5 s -- hence the 18 s exit and the 20 s mock. **Collapsing the two
+stages into one is the failure mode**: a probe that rebuilt the buffer at 11.5 s and then scanned it
+immediately would read `bare=0` on every search leg, which looks exactly like a broken comparator.
+
+**Why 4 s and not 3.** `enable_all_probe`'s last act is a timeout of its own, `ENABLE_ALL_MS + 2000` -- 3 s
+under this recipe -- which walks `signal_list` for the front channel's acquire tick and clicks it. A probe
+that installs a math graph at that same instant rebuilds the signal panel under it, and the off-step then
+emits `active` on a freed `GtkCheckButton`: `GLib-GObject-CRITICAL: instance with invalid (NULL) class
+pointer`, with the backtrace in `enable_all_probe()::{lambda}`. It is a real fragility of that probe's lookup
+and not of the feature, and it is why every documented probe time is offset from `ENABLE_ALL_MS + 2000`, not
+merely from each other.
+
+The de-noise channel is installed *disabled* and enabled only for its own reading (stage 3). An acquired
+channel is a share of the ring, so a fifth one shortens every channel's retained span -- and the six leg
+counts and `pkpk bare` all scale with that span. The readings above the de-noise line belong to the older
+feature and are the proof it still works, so the new channel stays out of the acquisition plan until they
+have run. `--spike-every`/`--spike-amp`/
+`--spike-width` are the mock's own; `--batch` must stay at or below 1000 (2000 samples x 5 signals x f64 is
+80 kB, past UDP's ~65507-byte payload, and the mock dies on its first `sendto` while the run still exits 0).
+
+The three lines and what each must read are in `probe-readings.md`.
+
+`UDPSCOPE_PROBE_NOISE_MS`, `UDPSCOPE_PROBE_MEASURE_MS`, `UDPSCOPE_PROBE_MEASURES_MS`,
+`UDPSCOPE_PROBE_BANDAVG_MS`, `UDPSCOPE_PROBE_MATH_MS` and `UDPSCOPE_PROBE_MATHWRAP_MS` must **not** be
+scheduled in the same run. The noise, measurement, measurements and band-average probes all push onto
+`app.measures`, and the later one would read
+the earlier one's rows as its own; the noise, math and math-wrap probes all write `app.math`, so the later
+one's graph
+lands on top of the earlier one's and both sets of readings describe a state neither probe set up. The noise probe carries
+its own measurement legs (see `probe-readings.md`), so nothing is lost by keeping them apart.

docs/review-2026-10-13.md

@@ -0,0 +1,217 @@
+# Project review — 2026-10-13
+
+A status review for performance, defects and gaps. Every claim below was read back against the
+current tree; where a candidate finding turned out to be wrong it is listed as dismissed, with the
+reason, rather than dropped — a false alarm that is not written down gets re-raised.
+
+## Summary
+
+The project is in good shape. All ten `todo.md` items are implemented, every deviation from
+`SPECS.md` is documented in README's *Review findings not (yet) implemented* and *Limitations*, there
+is no `TODO`/`FIXME`/`HACK` anywhere in `src/`, no dead command-line option, and no settings field
+that is written but never read. The tree builds clean.
+
+- **Defects: none confirmed.** Four candidates were investigated and all four are correct as
+  written (§2).
+- **Performance: one real win on the ingest hot path** (§1.1) — a 64-bit `div` per sample per
+  channel that the code's own comment believes is already cheap. Then one real win on the idle
+  frame path (§1.2), and three small ones. **§1.1 and §1.2 have since been implemented**; the three
+  small ones (§1.3-§1.5) have not.
+- **Gaps: no missing requirement.** What is missing is only what was never asked for (§4), plus one
+  stale sentence in README (§3).
+
+## 1. Performance
+
+### 1.1 A 64-bit division per sample per channel on the producer hot path
+
+> **Implemented** (2026-10-13), as the fix below describes: `Acquisition::acc_mask_` holds the
+> per-channel masks, built where the accumulators are sized; `reserve_hole()` moved with it; the
+> misleading comment at `src/model.cpp:120-122` now says what the mask actually buys. Written up in
+> README under *What the ingest filter and a still frame cost*.
+
+`src/acquisition.cpp:856-857`, in the innermost loop of `on_data()`:
+
+```cpp
+const u64 period = g * part.stride[i];
+if (tick % period != period - 1) continue;
+```
+
+Three facts make this the most expensive avoidable thing in the application:
+
+1. **`part.stride[i]` is always 1.** `plan_partition()` assigns it (`src/model.cpp:49`) and then
+   explicitly re-asserts it (`src/model.cpp:70`), with the comment above it explaining why
+   per-channel strides were abandoned. So `period == g` for every channel, always — the load and
+   the multiply are provably redundant.
+2. **`tick % period` is a real `div`.** `g` is a runtime `u64`, so the compiler cannot strength-
+   reduce it, whatever its value. A 64-bit integer division is ~20-40 cycles of latency on x86.
+   The intent was otherwise: `src/model.cpp:120-122` says a power-of-two stride "keeps `tick %
+   period` cheap", which would be true of a compile-time constant and is not true of a variable.
+   **`time_stride` being a power of two currently buys nothing here.**
+3. **The same condition is already computed.** `tick % g == g - 1` is evaluated at
+   `src/acquisition.cpp:811` for the time ring, and again at `:881` for the math push — and
+   `:857` is the same test once more per channel.
+
+Cost model: `(n_channels + 2)` divisions per **raw** sample, i.e. per wire sample, not per stored
+one — the decimation filter deliberately reads every sample (`:850-852`). At the fast mock's
+1.3 MS/s with 4 channels that is ~7.8 M divisions a second on the producer thread, which is the
+thread whose budget overrun costs packets rather than frames.
+
+Fix: compute the group boundary **once per sample** and reuse it. `g` is a power of two, so
+`const u64 mask = g - 1;` hoisted out of the packet loop turns all three sites into
+`(tick & mask) == mask`. To keep the per-channel generality the type still carries, precompute a
+per-channel mask vector when the partition is planned rather than per sample.
+
+The same expression appears in the hole path at `src/acquisition.cpp:966` (inside
+`reserve_hole()`'s double loop). That one is cosmetic — it runs only on packet loss — but it should
+move with its twin so the two paths keep matching.
+
+How to verify: the fast mock (`tools/mock_udpstreamer.py --rate 1300000 --batch 2000`), reading the
+exit dump's `gaps=` and the producer's CPU share before and after. Expect the win to show as
+headroom rather than as a changed reading on a stream the producer already keeps up with.
+
+### 1.2 The figure is re-rendered 60 times a second even when the picture cannot change
+
+> **Implemented** (2026-10-13), conservatively: a signature of what a frozen view can be re-framed
+> by, opening the gate for `kSettleRenders` frames, plus a `kStaticRenderEvery` floor that renders
+> anyway every four ticks, and the layout editor excluded outright. `[pause-probe]`'s new `skips=`
+> field reports it: a measured run read 0 live, 33 paused, with `columns == graded`, `render blank
+> frames: 0` and the layout floor still converged.
+
+`src/ui.cpp:3709` queues a GL render unconditionally at the end of every tick, and the tick is a
+fixed 16 ms timeout (`src/ui_app.hpp:1023`). In `Held` and `Paused` the bound data is an immutable
+snapshot and the axis is pinned, so with no pointer interaction the frame is provably identical to
+the last one — and it is still fully re-rendered. On llvmpipe, or on a laptop looking at a latched
+event, that is the whole GPU cost of the application for nothing.
+
+Fix: queue the render only when something that can change the picture did — new samples acquired,
+a mode/epoch/pin change, a mark/cursor/label move, an interaction, a resize. Keep it conservative:
+render unconditionally while the layout is still settling, since the layout editor's buttons are
+placed from the *previous* frame's rects and several probes read a value one frame after the ask.
+
+How to verify: the exit dump's per-plot painted-frame counts and `layout over N frames` are exactly
+the two readings that would catch an over-eager skip.
+
+### 1.3 The event publish blocks the UI tick for 69-115 ms
+
+Already documented, with measurements, at `README.md:2189-2191` — listed here only because the
+README prices exactly one remedy (a second live ring) and declines it for good reasons. Two
+options it does not price, both cheaper than a second budget's worth of memory:
+
+- do the snapshot copy on the **producer** side of the handoff, so the stall lands where a stall is
+  already tolerated at a latch (the pause publish already blocks the producer, 22-86 ms);
+- chunk the copy across frames behind a sequence number, publishing only when complete.
+
+Worth a design note before any code — the README's own A/B (`gaps=0` either way) says this buys a
+smoother frame at a latch, not recovered packets, so it is a polish item, not a correctness one.
+
+### 1.4 The status detail string is rebuilt and re-applied every frame
+
+`src/ui.cpp:4063` calls `format_detail(snap)` every tick and `:4082` pushes the result into
+`gtk_widget_set_tooltip_text()` every tick. The popover is already guarded by its own visibility
+(`:4083-4087`); the tooltip is not, and the string is long enough that the code tracks its maximum
+length. Nothing reads it unless the pointer rests on the status label.
+
+Fix: keep the last applied detail string and skip both the format and the setter when it is
+unchanged. Low risk, no behaviour change.
+
+### 1.5 Search marks are re-filtered and re-sorted every frame
+
+`src/ui.cpp:1760-1768`. Two heap vectors, a pass over every hit and an `std::sort` per frame for as
+long as a search result set exists. Correctly short-circuited when there are no hits
+(`:1753`), and being recomputed every frame is load-bearing for a *live* view (the marks are stored
+in stream seconds and the window rolls under them) — but in `Held`/`Paused` neither the hits nor
+the view range move, so the whole result can be cached and invalidated on a view-range or hit-set
+change.
+
+### 1.6 Noted, not recommended: the model mutex spans all of `on_data()`
+
+`src/acquisition.cpp:558` takes the lock and holds it to the end of the function (~line 913),
+covering the sample loop, the math evaluation, the trigger engine, and hole reserve/backfill. The
+UI tick takes the same mutex (`src/ui.cpp:3285`). This is the documented design ("taken once per
+DATA frame", `docs/claude/architecture.md:15-16`) and it is the right call at today's rates, but it
+is the coupling by which math-channel cost on the producer turns into UI frame jitter. The existing
+`math_timed` per-slot instrumentation is the thing to watch if math graphs get heavier.
+
+## 2. Defect candidates investigated and dismissed
+
+Recorded so they are not re-raised.
+
+- **`capture_edge()` loading `memory_order_relaxed`** (`src/model.hpp:492`) while its partner
+  `trigger_pending()` carries release/acquire. **Correct as written.** The consumer reaches
+  `capture_edge()` at `src/ui.cpp:3275` only *after* `display_mode()` at `:3273` has done the
+  acquire load of `trigger_pending_`; the acquire establishes the happens-before, so a relaxed load
+  afterwards cannot see the stale edge, and an acquire also forbids the later load being reordered
+  ahead of it. The probe path (`src/ui_probe.cpp:1129-1130`) reads the flag first too.
+  *One fragility worth a line of doc:* the correctness is a property of **read order at the call
+  site**, and `src/model.hpp:489-491` says a consumer that sees the flag sees the edge without
+  saying that the consumer must therefore read the flag first. Tightening that comment is the whole
+  of the work.
+- **`math_values_.data()` passed to `math_step()` across a possible reallocation**
+  (`src/model.cpp:409-422`). **Safe.** `push_math_sample()` is only reached from `on_data()`
+  (`src/acquisition.cpp:881`, `:978`), which holds the model mutex for its whole body, and
+  `set_math_channels()` takes the same mutex.
+- **`model_.signals()` indexed by `channels[0].signal` after the lock was released**
+  (`src/acquisition.cpp:593-595`). **Safe** — same reason: the lock is held from `:558` to the end
+  of the function, so no CONFIG can re-shape the signal list underneath it.
+- **`events_thumb` left dangling across a list rebuild** (`src/ui_events.cpp:632`). **Already
+  handled** — nulled before the rows are removed and rebound after, with the old texture unreffed.
+
+Nothing in the trigger/pause/file-view/replay seams, the math-channel dependency handling, the
+measurement and cursor paths, or the export/session writers reproduced a wrong number or a lost
+action on inspection. That is a statement about a code read, not about a test run: README's own
+`Limitations` is right that these paths are checked headless, and the seams between two *user*
+actions are where the probes are thinnest.
+
+## 3. One documentation defect
+
+`README.md:2304-2307` says the interactive paths — "drag and drop, the dialogs, the right-click
+menu" — "were not driven by an automated test". That is now stale in all three particulars:
+`UDPSCOPE_PROBE_DROP_MS` drives the drop handler, `UDPSCOPE_PROBE_ROWMENU_MS` walks the
+right-click menu and clicks through its submenu, and `UDPSCOPE_PROBE_DEFAULTS_MS`,
+`UDPSCOPE_PROBE_CONFIGS_MS`, `UDPSCOPE_PROBE_PREFS_MS` and `UDPSCOPE_PROBE_HELP_MS` all open and
+read back dialogs. What remains genuinely undriven is the *gesture* layer (a real pointer drag, a
+real popover dismissal) rather than the handlers behind it, which is a much narrower claim and the
+one worth making.
+
+## 4. Gaps
+
+### Requirements: complete
+
+`SPECS.md` was walked bullet by bullet. Everything is implemented, and the five places where the
+implementation differs are each documented with a reason at `README.md:2182-2240`: one live buffer
+plus an immutable `EventSnapshot` rather than two live rings; allocation at the first CONFIG rather
+than at startup; no per-channel decimation (the spec's formula aliased a 2 kHz sine on a 1 MHz clock
+to a flat line); pre-trigger % as a share of the event window; and a capture drawn as it fills.
+`todo.md`'s ten items are all really there, including item 9's full preference list — the
+light/dark/auto theme, the reset-to-defaults and the cache controls are all in `src/settings.hpp`
+and `src/ui_prefs.cpp`.
+
+### Not asked for, worth considering
+
+Ranked by value against cost, not by ambition:
+
+1. **Save the current view as an image.** The cheapest of these by a wide margin: the event cache
+   already has a sample-driven image writer (`write_preview()`, `src/event_store.cpp:266`), so a
+   menu item and a file chooser is most of the work. A scope user screenshots constantly.
+2. **A draggable trigger level on the plot.** The trigger marker exists but is a vertical cursor
+   and deliberately non-selectable (`src/plot_host.cpp:250`); the level is reachable only through
+   the panel's spin button. A horizontal handle on the trigger channel's row is the standard
+   gesture on every bench scope.
+3. **Per-trace vertical offset and scale.** Up to eight signals share one row's y axis, so two
+   signals of different magnitudes cannot both be read. This is the gap a user hits soonest.
+4. **An FFT / spectrum row.** The largest of these, and the one a UDPStreamer user is most likely
+   to ask for next; it fits the figure's row model (one row, one derived series) rather than
+   fighting it.
+5. **XY mode**, and **undo for layout edits** — both real scope features, both a poor fit for the
+   current one-x-window figure and the layout file respectively. Mentioned for completeness.
+
+## 5. Suggested order
+
+1. §1.1, the ingest-path division — small, local, the clearest win, and it corrects a comment that
+   is currently misleading about why the power of two matters.
+2. §3, the stale README sentence — minutes, and it is wrong today.
+3. §1.4 and §1.5, the per-frame string and sort — small and safe.
+4. §2's doc tightening on `capture_edge()`.
+5. §1.2, the conditional render — the bigger win of the two performance items, but the one that
+   needs care against the layout-settling probes, so it deserves its own change.
+6. §4.1, the screenshot — the cheapest real feature on the list.

docs/superpowers/plans/2026-10-11-ui-files-and-gtk4-practice.md

@@ -0,0 +1,101 @@
+# UI files and current GTK practice
+
+Where the application's interface should be a `.ui` resource instead of widget construction, what is
+already there, and the order to finish it in. Written 2026-10-11.
+
+## Why
+
+Three reasons, in the order they bite.
+
+1. **Some things can only be said in a UI file.** The shortcut overview is the proof: GTK's
+   `GtkShortcutsShortcut` has exactly one gesture type that draws an `icon`, and libadwaita's
+   `AdwShortcutsItem` has no icon property at all -- so a mouse gesture can only be shown as a glyph
+   from a `.ui`. `src/ui/shortcuts.ui` is that, and it is the reason the file exists.
+2. **Structure is data.** A window's arrangement rewritten in C++ is a hundred lines of
+   `gtk_box_append` that no one can read at a glance, cannot be compared with a diff, and cannot be
+   previewed. A UI file is the same arrangement in the notation the GNOME ecosystem reads.
+3. **Current GTK and libadwaita have better widgets than this app uses.** The forms here are
+   `GtkEntry`/`GtkSpinButton` in hand-built label rows. The modern equivalents -- `AdwEntryRow`,
+   `AdwSpinRow`, `AdwSwitchRow`, `AdwComboRow`, inside `AdwPreferencesPage`/`AdwPreferencesGroup` in an
+   `AdwPreferencesDialog` -- are what the preferences dialog should be, and they come from the same
+   move.
+
+## Conventions (established, and in `docs/claude/invariants-gtk-and-chrome.md`)
+
+- `.ui` files live in `src/ui/` and are compiled by the third GResource (`udpscope-ui.gresource.xml`,
+  `prefix=/org/udpscope/ui`), loaded with `gtk_builder_new_from_resource()`.
+- Every file carries `preprocess="xml-stripblanks"`, which is the only thing that catches a malformed
+  file at build time.
+- A file that is valid XML but wrong for GTK **aborts the process** (`Gtk-ERROR`). The probe that opens
+  every window is what catches that; there is no build-time substitute.
+- A `GIcon` property takes a nested object, not a name.
+- A `.ui` over 4095 characters needs `-Wno-overlength-strings` on its generated source.
+- A window built from a builder is replaced (not reused) on the next opening: it belongs to the
+  builder's object list, and a destroyed `GtkWindow` cannot be presented again.
+- A deprecated *widget* is acceptable when no deprecated *function* is called.
+
+## Acceptance for every slice
+
+The same as any other change here: the build stays at **four warnings**, a run stays at **no
+`Gtk-CRITICAL`**, and the slice's own surface is read back by a probe rather than asserted. A new `.ui`
+needs a probe that proves it *loads* and that its contents match whatever drives it -- `[help]`'s
+`ui=` against `tables=` is the model.
+
+## Already done
+
+- `src/ui/main-window.ui` -- the main window's **skeleton**: the window, its two panes, the plot column
+  with the status line under it, and the sidebar's scroller. The four subtrees that depend on the stream
+  (the events pane, the two plot areas, the sidebar's panels, the status popover) are still built by
+  code and put into the slots by id.
+- `src/ui/source-form.ui` -- the form a source is added or edited with: an `AdwDialog` of
+  `AdwPreferencesGroup` rows, with its action in the header bar where the label says which mode it is in.
+- `src/ui/help.ui` -- the help window's chrome: an `AdwWindow` with a header bar and an
+  `AdwNavigationSplitView` whose sidebar is the page list. The rows stay in C++ because the fourteen
+  pages are data, not template.
+- `src/ui/preferences.ui` -- the preferences, as an `AdwPreferencesDialog` with `AdwEntryRow`,
+  `AdwSpinRow`, `AdwSwitchRow`, `AdwComboRow` and `AdwButtonRow` rows. The Apply button is gone: a row
+  applies as it changes, which is what those widgets are designed around, and `[prefs-probe]` reads the
+  file back after every change.
+- `src/ui/shortcuts.ui` -- the shortcut overview, with the mouse rows drawn as an icon cell.
+- The `src/ui/` GResource and its build block.
+- `[help]`'s `ui=`/`ui_accel=`/`ui_icon=`/`ui_bare=` reading, which checks the file against the tables
+  and asserts that no row is left without a visual.
+
+## Remaining, smallest first
+
+| where | what | why it is the right next step |
+|---|---|---|
+| `src/source_dialog.cpp` (the chooser's own window) | the chooser: `.ui` for the window, its two pages and its action row. Its **host form is done**; what is left is the list, the notebook and the buttons around it | the last hand-built UI outside `ui.cpp`, and the file is already open |
+| `build_measures_panel` (`src/ui.cpp`, ~82 lines) | the measurements panel: `.ui` + `tools/check_ui.py` after | small, self-contained, and its own probe |
+| `src/ui/ui_trigger.cpp` (~22 kB) | the trigger panel: the `.ui` holds the panel and its groups; the signal chips and the condition rows stay in code because they follow CONFIG | the largest user-visible panel |
+| `src/ui/ui_signals.cpp` (~20 kB) | the signals panel | mostly a list of data-driven rows, so the `.ui` holds the frame |
+| `src/ui/ui_math.cpp` (~48 kB) | the math panel and the node editor's chrome (the canvas itself is drawn, not declared) | the largest file, and the one where least of it is template |
+| `src/ui/ui_events.cpp` (~44 kB) | the events pane | the rows are events, the frame is not |
+| `src/ui/ui_layout.cpp` (~20 kB) | the layout editor's overlay buttons, which are positioned by code | only the buttons are template |
+| `build_toolbar` (`src/ui.cpp`, ~212 lines) | the header bar's layout, with every button still wired in code | delicate: the `[udpscope] header:` probe reads its geometry |
+
+**Every row of the table above is done or accounted for.** The header bar went last and in one change, because
+`gtk_header_bar_pack_start()` appends after whatever a file has already packed -- staging it by group would
+have reordered the bar in an intermediate commit. Its frame is `src/ui/header-bar.ui`; the overflow menu's
+rows, the window control and every handler stayed in code, and the probe's header readings are byte-identical
+before and after.
+
+**The layout editor's buttons are not a `.ui` row, and the note above is wrong about them.** Their count *is*
+the row count (one per row, one per boundary), and `GtkBuilder` instantiates a file's objects once, so a file
+can hold neither the number nor a prototype for the code to copy. What was real in that row was the
+duplication: the shared look is now one function (`layout_overlay_button()`), and the layout probe reads
+byte-identical before and after. See `invariants-gtk-and-chrome.md`.
+
+**Done since, one row per commit:** the source chooser's window (`0a64e9e`), the measurements panel
+(`d344361`, `07fcf61`), the trigger panel (`1ccc70c`), the signals panel (`c37fbdd`), the math panel
+(`90a17eb`) and the math editor's window, identity row and canvas. What is left of that row is the palette
+and the buttons around the canvas, which stay in code for the reason the canvas's *drawing* does.
+
+**Done since:** the sidebar is an `AdwOverlaySplitView` (`src/ui/main-window.ui`) rather than a paned's end
+child, so its width is its own 320 px and it overlays the plot instead of collapsing to zero — see
+`[sidebar-probe]`.
+
+Each of these is one change on the pattern `src/ui/ui_cursors.cpp` now follows: `ui_load()` the file, resolve
+the ids, keep every value, signal and rebuild in code, and run the panel's own probe before committing.
+
+Nothing in this list should be done in one pass. Each row is its own change, verified on its own.

docs/superpowers/plans/2026-11-02-e1608-network-scan.md

@@ -0,0 +1,681 @@
+# E-1608 Network Scan Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** The E-1608 connection form gets a "Scan network" row that finds boards on every local interface and fills the address or the MAC from a click; the MAC lookup in `E1608Source` stops depending on the default route.
+
+**Architecture:** A non-blocking `Scan` class in `e1608_link` opens one UDP socket per up IPv4 broadcast interface (bound to the device, or to its address), sends `D` on each and drains replies on `poll()`. The form drives it with a 50 ms GLib timer on the GTK main thread (the project has exactly two threads, so no worker). `discover_broadcast()` is `Scan` plus a blocking wait and replaces the limited-broadcast `discover()` call in the source's MAC lookup.
+
+**Tech Stack:** C++20, GTK4/libadwaita (`AdwExpanderRow`, `AdwActionRow`), POSIX sockets (`getifaddrs`, `SO_BINDTODEVICE`), `tools/mock_e1608.py`, the in-app headless probe under `xvfb-run`.
+
+## Global Constraints
+
+- Spec: `docs/superpowers/specs/2026-11-02-e1608-network-scan-design.md` (approved 2026-11-02).
+- Exactly two threads: no worker thread for the scan; the form polls with `g_timeout_add*`.
+- Every source file carries the SPDX MIT header (no new source files in this plan).
+- Text buttons only (no theme icons) on the new controls.
+- A `subnet` that is given still uses `sweep_targets` + `discover` unchanged.
+- An interface that cannot be opened or sent on is skipped, never an error; no interfaces is an empty result.
+- Scan results are never persisted: the session reads and writes only the filled fields.
+- Baselines: a clean build has exactly 3 warnings (an incremental build shows the 2 `ui_probe.cpp` MathNode ones); `gtk warnings: 0`; no `Gtk-CRITICAL`.
+- GTK traps (`docs/claude/invariants-gtk-and-chrome.md`): handler signatures are notify `(GObject*, GParamSpec*, gpointer)`, clicked `(GtkButton*, gpointer)`, changed `(GtkEditable*, gpointer)`; handlers behind `Form::alive`; probes use `g_object_ref_sink` + `g_object_unref` on never-parented rows.
+- Probe code must avoid `x({...}).empty() || y({...}).empty()` (GCC `-Wdangling-pointer`).
+- Verification runs are short and serial; kill every mock afterwards. Do not push or merge.
+
+## File Structure
+
+- Modify `src/source/e1608/e1608_link.hpp` / `.cpp`: `class Scan`, `discover_broadcast()`, a shared reply parser used by `discover()` too.
+- Modify `src/source/e1608/e1608_source.cpp`: the MAC lookup with an empty subnet uses `discover_broadcast()`.
+- Modify `src/source/e1608/e1608_kind.cpp`: the scan row, result rows, fills, timer.
+- Modify `src/ui_probe.cpp`, `src/ui_app.hpp`, `src/ui.cpp`: the `UDPSCOPE_PROBE_E1608_SCAN` probe.
+- Modify docs: `README.md`, `docs/claude/{build-and-run,verification,probe-readings,architecture}.md`.
+
+One design note the spec leaves open: `AdwExpanderRow` can only append rows, so "results right after the scan row" is done by making the scan row itself an `AdwExpanderRow` ("Scan network", a text "Scan" suffix button) at the top of the Connection expander, with the results as its child rows. It reads the same: results sit directly under the scan row.
+
+---
+
+### Task 1: The `Scan` class, `discover_broadcast()`, and the MAC lookup
+
+**Files:**
+- Modify: `src/source/e1608/e1608_link.hpp` (after `discover`, line ~77)
+- Modify: `src/source/e1608/e1608_link.cpp` (includes; anonymous namespace; `discover`; new definitions)
+- Modify: `src/source/e1608/e1608_source.cpp:270-293`
+
+**Interfaces:**
+- Produces (used by Task 2):
+  ```cpp
+  class Scan {
+   public:
+    explicit Scan(int port);
+    Scan(const Scan&) = delete;
+    Scan& operator=(const Scan&) = delete;
+    const std::vector<DeviceInfo>& poll();      // drains non-blocking; cumulative, one entry per MAC
+    std::size_t interfaces() const noexcept;    // sockets opened
+  };
+  std::vector<DeviceInfo> discover_broadcast(int port, int wait_ms);
+  ```
+- Consumes: existing `Fd`, `DeviceInfo`, `kProductId`, `Clock`, `ms_left`.
+
+- [ ] **Step 1: Declare the API**
+
+In `e1608_link.hpp`, after the `discover` declaration add:
+
+```cpp
+/// A broadcast discovery that never blocks. The limited broadcast alone leaves through the default
+/// route only, so on a host with several interfaces it can miss a board on another one; this opens
+/// one socket per up, non-loopback IPv4 interface with a broadcast address (bound to the device, or
+/// to the interface address when binding to the device is refused), sends `D` to
+/// 255.255.255.255 on each, and collects the replies as `poll()` is called. The caller owns the
+/// clock. An interface that cannot be opened or sent on is skipped; no interface is an empty scan.
+class Scan {
+ public:
+  explicit Scan(int port);
+  Scan(const Scan&) = delete;
+  Scan& operator=(const Scan&) = delete;
+  /// Drains every socket without blocking. The devices found so far: E-1608s only, one per MAC.
+  const std::vector<DeviceInfo>& poll();
+  /// How many interfaces a probe was sent on.
+  std::size_t interfaces() const noexcept { return socks_.size(); }
+
+ private:
+  std::vector<Fd> socks_;
+  std::vector<DeviceInfo> found_;
+};
+
+/// `Scan` plus a blocking wait of `wait_ms`: what a lookup by MAC with no subnet uses.
+std::vector<DeviceInfo> discover_broadcast(int port, int wait_ms);
+```
+
+- [ ] **Step 2: Share the reply parser**
+
+In `e1608_link.cpp` add includes `#include <ifaddrs.h>`, `#include <net/if.h>`, `#include <thread>` (keep the list alphabetical with the existing ones). Inside the existing anonymous namespace, just before its closing `}  // namespace` (after `tcp_connect`), add:
+
+```cpp
+/// A `D` reply (at least 29 bytes, first byte `D`, our product id). True when it added a board
+/// that `found` did not already hold (one entry per MAC).
+bool take_reply(const std::uint8_t* buf, ssize_t n, const sockaddr_in& from,
+                std::vector<DeviceInfo>& found) {
+  if (n < 29 || buf[0] != 'D') return false;
+  DeviceInfo info;
+  info.product_id = static_cast<std::uint16_t>(buf[7] | (buf[8] << 8));
+  if (info.product_id != kProductId) return false;
+  std::copy(buf + 1, buf + 7, info.mac.begin());
+  for (const DeviceInfo& d : found) {
+    if (d.mac == info.mac) return false;
+  }
+  char ip[INET_ADDRSTRLEN] = {};
+  ::inet_ntop(AF_INET, &from.sin_addr, ip, sizeof ip);
+  info.ip = ip;
+  found.push_back(info);
+  return true;
+}
+```
+
+In `discover()`, replace the block from `if (n < 29 || buf[0] != 'D') continue;` through `found.push_back(info);` (the lines that build `info`, test the MAC for a duplicate and push) with the single call:
+
+```cpp
+    take_reply(buf, n, from, found);
+```
+
+- [ ] **Step 3: Implement `Scan` and `discover_broadcast`**
+
+After `discover()` (before the `// --- Link` banner) add:
+
+```cpp
+Scan::Scan(int port) {
+  ifaddrs* list = nullptr;
+  if (::getifaddrs(&list) != 0) return;
+  sockaddr_in to{};
+  to.sin_family = AF_INET;
+  to.sin_port = htons(static_cast<std::uint16_t>(port));
+  to.sin_addr.s_addr = htonl(INADDR_BROADCAST);
+  const std::uint8_t probe = 'D';
+  std::vector<std::string> done;  // an interface with several addresses needs one probe, not several
+  for (const ifaddrs* a = list; a != nullptr; a = a->ifa_next) {
+    if (a->ifa_addr == nullptr || a->ifa_addr->sa_family != AF_INET) continue;
+    const unsigned fl = a->ifa_flags;
+    if ((fl & IFF_UP) == 0 || (fl & IFF_LOOPBACK) != 0 || (fl & IFF_BROADCAST) == 0) continue;
+    const std::string name = a->ifa_name;
+    if (std::find(done.begin(), done.end(), name) != done.end()) continue;
+    Fd s(::socket(AF_INET, SOCK_DGRAM | SOCK_NONBLOCK, 0));
+    if (!s.valid()) continue;
+    const int one = 1;
+    ::setsockopt(s.get(), SOL_SOCKET, SO_BROADCAST, &one, sizeof one);
+    if (::setsockopt(s.get(), SOL_SOCKET, SO_BINDTODEVICE, name.c_str(),
+                     static_cast<socklen_t>(name.size())) != 0) {
+      sockaddr_in me = *reinterpret_cast<const sockaddr_in*>(a->ifa_addr);
+      me.sin_port = 0;
+      if (::bind(s.get(), reinterpret_cast<const sockaddr*>(&me), sizeof me) != 0) continue;
+    }
+    if (::sendto(s.get(), &probe, 1, MSG_NOSIGNAL, reinterpret_cast<const sockaddr*>(&to),
+                 sizeof to) != 1)
+      continue;
+    done.push_back(name);
+    socks_.push_back(std::move(s));
+  }
+  ::freeifaddrs(list);
+}
+
+const std::vector<DeviceInfo>& Scan::poll() {
+  for (const Fd& s : socks_) {
+    for (;;) {
+      std::uint8_t buf[128];
+      sockaddr_in from{};
+      socklen_t flen = sizeof from;
+      const ssize_t n = ::recvfrom(s.get(), buf, sizeof buf, MSG_DONTWAIT,
+                                   reinterpret_cast<sockaddr*>(&from), &flen);
+      if (n < 0) break;  // nothing more on this socket for now
+      take_reply(buf, n, from, found_);
+    }
+  }
+  return found_;
+}
+
+std::vector<DeviceInfo> discover_broadcast(int port, int wait_ms) {
+  Scan scan(port);
+  const auto deadline = Clock::now() + std::chrono::milliseconds(wait_ms);
+  while (ms_left(deadline) > 0) {
+    scan.poll();
+    std::this_thread::sleep_for(std::chrono::milliseconds(10));
+  }
+  return scan.poll();
+}
+```
+
+- [ ] **Step 4: Use it in the source's lookup**
+
+In `e1608_source.cpp` `connect_and_start()`, replace
+
+```cpp
+    const std::vector<std::string> targets =
+        host.empty() ? sweep_targets(cfg_.subnet) : std::vector<std::string>{host};
+    const std::vector<DeviceInfo> found =
+        discover(targets, cfg_.port, std::min(cfg_.timeout_ms, 1500));
+```
+
+with
+
+```cpp
+    const std::vector<std::string> targets =
+        host.empty() ? sweep_targets(cfg_.subnet) : std::vector<std::string>{host};
+    const int wait_ms = std::min(cfg_.timeout_ms, 1500);
+    // No address and no subnet: the limited broadcast, sent on every interface rather than only
+    // the default route's.
+    const bool broadcast =
+        host.empty() && targets.size() == 1 && targets[0] == "255.255.255.255";
+    const std::vector<DeviceInfo> found =
+        broadcast ? discover_broadcast(cfg_.port, wait_ms) : discover(targets, cfg_.port, wait_ms);
+```
+
+- [ ] **Step 5: Build**
+
+Run: `cmake --build build -j8 2>&1 | grep -E "warning:|error:" ; echo done`
+Expected: no `error:`; only the 2 baseline `ui_probe.cpp` MathNode warnings (incremental) -- nothing new from `e1608_link.cpp` or `e1608_source.cpp`.
+
+- [ ] **Step 6: Verify the MAC lookup end to end against the mock**
+
+The mock answers a broadcast `D` on UDP 54211. A run with only a `mac` option (no address, no subnet) must find it and stream:
+
+```sh
+python3 tools/mock_e1608.py --port 54211 > /tmp/mock-scan.log 2>&1 &
+MOCK=$!
+UDPSCOPE_PROBE_E1608=1500 UDPSCOPE_EXIT_AFTER_MS=4000 xvfb-run -a ./build/udpscope --source e1608 \
+  --source-opt mac=00:80:2f:00:16:08 --source-opt scan_rate=1000 2>&1 | grep -E "^\[e1608\] (stream|state)"
+kill $MOCK
+```
+
+Expected: `[e1608] stream: connected=1 ... ok=1` and `state: connects=1 message=''`.
+If it reads `connected=0` with `no E-1608 with MAC ... answered`: the sandbox did not loop the broadcast back to the mock. Check with `ip -4 -o addr` that an up non-loopback interface with a broadcast address exists. If one does and it still fails, report that to the user as a finding; do not paper over it.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/source/e1608/e1608_link.hpp src/source/e1608/e1608_link.cpp src/source/e1608/e1608_source.cpp
+git commit -m "e1608: discover boards on every interface, not only the default route's"
+```
+
+---
+
+### Task 2: The form's "Scan network" row, results and fills
+
+**Files:**
+- Modify: `src/source/e1608/e1608_kind.cpp`
+
+**Interfaces:**
+- Consumes: `Scan`, `DeviceInfo`, `format_mac` (Task 1 / existing, via `e1608_source.hpp`'s includes of `e1608_link.hpp`; add the include if the build says otherwise).
+- Produces (used by Task 3's probe), by widget name: the scan row `AdwExpanderRow` named `e1608-scan-row`; its suffix `GtkButton` named `e1608-scan`; each result an `AdwActionRow` named `e1608-result` (title IP, subtitle MAC, `activated` fills the address) holding a suffix button named `e1608-use-mac`. Subtitle texts: `Scanning...`, `1 board found`, `N boards found`, `No board found`.
+
+- [ ] **Step 1: Add the state and `fill()` to `Form`**
+
+In `struct Form`, after `bool alive = true;...` add:
+
+```cpp
+  GtkWidget* scan_row = nullptr;       ///< the "Scan network" expander; the results are its rows
+  std::vector<GtkWidget*> results;     ///< the result rows of the current scan
+  std::unique_ptr<Scan> scan;          ///< non-null while a scan is running
+  guint timer = 0;                     ///< the GLib source polling `scan`, 0 when none
+  int scan_ms = 0;                     ///< time spent in the running scan
+```
+
+and, after `write(...)`:
+
+```cpp
+  /// A result click: puts one way of naming the board in and the other two fields out, under the
+  /// `updating` guard so the dialog is told once.
+  void fill(const std::string& addr, const std::string& mac_text) {
+    if (!alive) return;
+    updating = true;
+    gtk_editable_set_text(GTK_EDITABLE(address), addr.c_str());
+    gtk_editable_set_text(GTK_EDITABLE(mac), mac_text.c_str());
+    gtk_editable_set_text(GTK_EDITABLE(subnet), "");
+    updating = false;
+    if (changed && *changed) (*changed)();
+  }
+
+  void stop_scan() {
+    if (timer != 0) g_source_remove(timer);
+    timer = 0;
+    scan.reset();
+  }
+```
+
+Add `#include <vector>` to the includes if absent.
+
+- [ ] **Step 2: Destroy hook stops the timer**
+
+Replace `on_form_destroy` with:
+
+```cpp
+void on_form_destroy(GtkWidget*, gpointer user) {
+  Form& f = **static_cast<FormPtr*>(user);
+  f.alive = false;
+  f.stop_scan();  // the poll must not outlive the rows it writes to
+}
+```
+
+- [ ] **Step 3: The scan functions**
+
+After `hook_entry(...)` and before `class E1608Kind`, add:
+
+```cpp
+constexpr int kScanMs = 1500;  ///< how long a scan listens
+constexpr int kTickMs = 50;    ///< how often it drains the sockets
+
+/// A result row's two ways to name the board, with the form they fill.
+struct Pick {
+  FormPtr form;
+  std::string ip, mac;
+};
+
+void free_pick(gpointer d, GClosure*) { delete static_cast<Pick*>(d); }
+
+void on_pick_address(AdwActionRow*, gpointer user) {
+  Pick& p = *static_cast<Pick*>(user);
+  p.form->fill(p.ip, "");
+}
+
+void on_pick_mac(GtkButton*, gpointer user) {
+  Pick& p = *static_cast<Pick*>(user);
+  p.form->fill("", p.mac);
+}
+
+void add_result(const FormPtr& f, const DeviceInfo& d) {
+  const std::string mac = format_mac(d.mac);
+  GtkWidget* row = adw_action_row_new();
+  gtk_widget_set_name(row, "e1608-result");
+  adw_preferences_row_set_title(ADW_PREFERENCES_ROW(row), d.ip.c_str());
+  adw_action_row_set_subtitle(ADW_ACTION_ROW(row), mac.c_str());
+  gtk_list_box_row_set_activatable(GTK_LIST_BOX_ROW(row), TRUE);
+  GtkWidget* use_mac = gtk_button_new_with_label("Use MAC");
+  gtk_widget_set_name(use_mac, "e1608-use-mac");
+  gtk_widget_set_valign(use_mac, GTK_ALIGN_CENTER);
+  adw_action_row_add_suffix(ADW_ACTION_ROW(row), use_mac);
+  g_signal_connect_data(row, "activated", G_CALLBACK(on_pick_address),
+                        new Pick{f, d.ip, mac}, free_pick, static_cast<GConnectFlags>(0));
+  g_signal_connect_data(use_mac, "clicked", G_CALLBACK(on_pick_mac), new Pick{f, d.ip, mac},
+                        free_pick, static_cast<GConnectFlags>(0));
+  adw_expander_row_add_row(ADW_EXPANDER_ROW(f->scan_row), row);
+  adw_expander_row_set_expanded(ADW_EXPANDER_ROW(f->scan_row), TRUE);
+  f->results.push_back(row);
+}
+
+void set_scan_status(Form& f, const std::string& text) {
+  adw_expander_row_set_subtitle(ADW_EXPANDER_ROW(f.scan_row), text.c_str());
+}
+
+/// 50 ms poll of the running scan. The rows appear as boards answer; at `kScanMs` the status is
+/// settled and the scan (its sockets) is released.
+gboolean on_scan_tick(gpointer user) {
+  const FormPtr& fp = *static_cast<FormPtr*>(user);
+  Form& f = *fp;
+  if (!f.alive || !f.scan) {
+    f.timer = 0;
+    return G_SOURCE_REMOVE;
+  }
+  const std::vector<DeviceInfo> found = f.scan->poll();
+  while (f.results.size() < found.size()) add_result(fp, found[f.results.size()]);
+  f.scan_ms += kTickMs;
+  if (f.scan_ms < kScanMs) return G_SOURCE_CONTINUE;
+  if (found.empty())
+    set_scan_status(f, "No board found");
+  else if (found.size() == 1)
+    set_scan_status(f, "1 board found");
+  else
+    set_scan_status(f, std::to_string(found.size()) + " boards found");
+  f.scan.reset();
+  f.timer = 0;
+  return G_SOURCE_REMOVE;
+}
+
+void free_form_ptr(gpointer d) { delete static_cast<FormPtr*>(d); }
+
+/// A new scan on the Port field's value: the previous results go, a running scan is replaced.
+void start_scan(const FormPtr& fp) {
+  Form& f = *fp;
+  if (!f.alive) return;
+  f.stop_scan();
+  for (GtkWidget* r : f.results) adw_expander_row_remove(ADW_EXPANDER_ROW(f.scan_row), r);
+  f.results.clear();
+  adw_expander_row_set_expanded(ADW_EXPANDER_ROW(f.scan_row), FALSE);
+  f.scan = std::make_unique<Scan>(static_cast<int>(value_of(f.port)));
+  f.scan_ms = 0;
+  set_scan_status(f, "Scanning...");
+  f.timer = g_timeout_add_full(G_PRIORITY_DEFAULT, kTickMs, on_scan_tick, new FormPtr(fp),
+                               free_form_ptr);
+}
+
+void on_scan_clicked(GtkButton*, gpointer user) {
+  start_scan(*static_cast<FormPtr*>(user));
+}
+```
+
+(`f.stop_scan()` removes the timer; `g_source_remove` fires `free_form_ptr`, which only drops one `FormPtr` copy, never the last. `on_scan_tick` never calls `g_source_remove` on itself: it zeroes `timer` and returns `G_SOURCE_REMOVE`.)
+
+- [ ] **Step 4: Build the row in `make_config_form()`**
+
+After the `f->ao_init[1] = ...` line, add:
+
+```cpp
+    f->scan_row = adw_expander_row_new();
+    gtk_widget_set_name(f->scan_row, "e1608-scan-row");
+    adw_preferences_row_set_title(ADW_PREFERENCES_ROW(f->scan_row), "Scan network");
+    GtkWidget* scan_button = gtk_button_new_with_label("Scan");
+    gtk_widget_set_name(scan_button, "e1608-scan");
+    gtk_widget_set_valign(scan_button, GTK_ALIGN_CENTER);
+    adw_expander_row_add_suffix(ADW_EXPANDER_ROW(f->scan_row), scan_button);
+    g_signal_connect_data(scan_button, "clicked", G_CALLBACK(on_scan_clicked), new FormPtr(f),
+                          free_form, static_cast<GConnectFlags>(0));
+```
+
+Change the Connection group to start with the scan row:
+
+```cpp
+    GtkWidget* conn = expander("Connection", {f->scan_row, f->address, f->mac, f->subnet, f->port,
+                                              f->code, f->timeout});
+```
+
+Update the description string to:
+
+```cpp
+    out.description =
+        "Give an address, or a MAC address to look up (optionally with a subnet such as 192.168.1), "
+        "or scan the network for boards";
+```
+
+- [ ] **Step 5: Build, then check the existing form round trip and warnings**
+
+```sh
+cmake --build build -j8 2>&1 | grep -E "warning:|error:" ; echo done
+UDPSCOPE_PROBE_SOURCE_KINDS=1000 UDPSCOPE_EXIT_AFTER_MS=2500 xvfb-run -a ./build/udpscope \
+  --source probe --source-opt rate=500 2>&1 | grep -E "form e1608|gtk warnings|Gtk-CRITICAL"
+```
+
+Expected: no `error:`, only the 2 baseline warnings; `[source-kinds] form e1608: round_trip=1 valid=1`; `gtk warnings: 0`; no `Gtk-CRITICAL`.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/source/e1608/e1608_kind.cpp
+git commit -m "e1608: a Scan network row in the connection form, with click-to-fill results"
+```
+
+---
+
+### Task 3: The scan probe, docs, and final verification
+
+**Files:**
+- Modify: `src/ui_probe.cpp` (after `e1608_probe_reconnect`, ~line 2459)
+- Modify: `src/ui_app.hpp:1874-1875`
+- Modify: `src/ui.cpp:6031-6033`
+- Modify: `README.md` (E-1608 paragraph, lines ~118-146), `docs/claude/build-and-run.md:118-130`, `docs/claude/verification.md` (after the `UDPSCOPE_PROBE_E1608_RECONNECT` bullet, ~line 443), `docs/claude/probe-readings.md` (`## [e1608]` section, ~line 1848-1890), `docs/claude/architecture.md:45-48`
+
+**Interfaces:**
+- Consumes: the widget names from Task 2; `find_named()`, `find_kind()` in `ui_probe.cpp`.
+- Produces: env var `UDPSCOPE_PROBE_E1608_SCAN=<ms>` and optional `UDPSCOPE_PROBE_E1608_SCAN_MAC` (default `00:80:2f:00:16:08`, the mock's); one stderr line `[e1608] scan: ...`.
+
+- [ ] **Step 1: Declare and register the probe**
+
+In `ui_app.hpp`, after `gboolean e1608_probe_resumed(gpointer user);` add:
+
+```cpp
+/// The E-1608 form's "Scan network" row: presses Scan against the mock, then (phases `_fill`,
+/// `_rescan`) clicks a result to fill the address, "Use MAC" to fill the MAC, scans again and checks
+/// the results were replaced, not added to.
+gboolean e1608_scan_probe(gpointer user);
+gboolean e1608_scan_probe_fill(gpointer user);
+gboolean e1608_scan_probe_rescan(gpointer user);
+```
+
+In `ui.cpp`, after the `UDPSCOPE_PROBE_E1608_RECONNECT` block add:
+
+```cpp
+  if (const char* env = g_getenv("UDPSCOPE_PROBE_E1608_SCAN")) {
+    g_timeout_add(static_cast<guint>(std::atoi(env)), e1608_scan_probe, &app);
+  }
+```
+
+- [ ] **Step 2: Write the probe**
+
+In `ui_probe.cpp`, after `e1608_probe_reconnect`, add (this is outside the file's anonymous namespace, like its neighbours; the helpers it uses, `find_named` and `find_kind`, are visible):
+
+```cpp
+namespace {
+
+/// The scan probe's state, alive from phase 1 to phase 3.
+struct E1608ScanProbe {
+  ConfigForm form;
+  int changes = 0;          ///< how many times the form told the dialog it changed
+  std::string want_mac;     ///< the board the probe expects (the mock's by default)
+  std::string status;       ///< the scan row's subtitle, as read at the end of the first scan
+  std::string ip;           ///< the expected board's address, as listed
+  std::size_t first = 0;    ///< result rows after the first scan
+  bool listed = false;      ///< the expected board was among them
+  bool fill_addr = false;
+  bool fill_mac = false;
+};
+
+E1608ScanProbe* g_scan_probe = nullptr;
+
+void collect_named(GtkWidget* root, const char* name, std::vector<GtkWidget*>& out) {
+  if (root == nullptr) return;
+  if (std::strcmp(gtk_widget_get_name(root), name) == 0) out.push_back(root);
+  for (GtkWidget* c = gtk_widget_get_first_child(root); c != nullptr;
+       c = gtk_widget_get_next_sibling(c))
+    collect_named(c, name, out);
+}
+
+std::string scan_status(E1608ScanProbe& p) {
+  GtkWidget* row = find_named(p.form.rows[0], "e1608-scan-row");
+  const char* t = row != nullptr ? adw_expander_row_get_subtitle(ADW_EXPANDER_ROW(row)) : nullptr;
+  return t != nullptr ? t : "";
+}
+
+/// A form holding stale values in all three naming fields, so a fill is seen to clear the others.
+void scan_probe_stale(E1608ScanProbe& p) {
+  SourceConfig c;
+  c.set("address", "1.2.3.4");
+  c.set("mac", "aa:bb:cc:dd:ee:ff");
+  c.set("subnet", "10.0.0");
+  p.form.write(c);
+  p.changes = 0;
+}
+
+void scan_probe_click(E1608ScanProbe& p) {
+  GtkWidget* button = find_named(p.form.rows[0], "e1608-scan");
+  if (button != nullptr) g_signal_emit_by_name(button, "clicked");
+}
+
+void scan_probe_cleanup() {
+  if (g_scan_probe == nullptr) return;
+  for (GtkWidget* row : g_scan_probe->form.rows) {
+    g_object_ref_sink(row);
+    g_object_unref(row);
+  }
+  delete g_scan_probe;
+  g_scan_probe = nullptr;
+}
+
+}  // namespace
+
+/// Phase 3, 2 s after the second Scan: the results were replaced (same count), and the one line.
+gboolean e1608_scan_probe_rescan(gpointer user) {
+  App* a = static_cast<App*>(user);
+  if (a->window == nullptr || g_scan_probe == nullptr) return G_SOURCE_REMOVE;
+  E1608ScanProbe& p = *g_scan_probe;
+  std::vector<GtkWidget*> rows;
+  collect_named(p.form.rows[0], "e1608-result", rows);
+  const bool replaced = rows.size() == p.first;
+  const std::string status = scan_status(p);
+  const bool status_ok = status.find("found") != std::string::npos && status.rfind("No", 0) != 0;
+  const bool ok = p.listed && p.fill_addr && p.fill_mac && replaced && status_ok;
+  std::fprintf(stderr,
+               "[e1608] scan: found=%zu ip=%s mac=%s status='%s' fill_addr=%d fill_mac=%d "
+               "rescan_replaced=%d ok=%d\n",
+               p.first, p.ip.c_str(), p.want_mac.c_str(), p.status.c_str(), p.fill_addr ? 1 : 0,
+               p.fill_mac ? 1 : 0, replaced ? 1 : 0, ok ? 1 : 0);
+  if (!p.listed)
+    std::fprintf(stderr,
+                 "[e1608] scan: %s did not answer; no up broadcast interface reaches it, or the "
+                 "broadcast was refused (this run proves nothing about the scan)\n",
+                 p.want_mac.c_str());
+  std::fflush(stderr);
+  scan_probe_cleanup();
+  return G_SOURCE_REMOVE;
+}
+
+/// Phase 2, 2 s after the first Scan: the expected board is listed, a result click fills the address
+/// only, "Use MAC" fills the MAC only (each telling the dialog exactly once), then Scan again.
+gboolean e1608_scan_probe_fill(gpointer user) {
+  App* a = static_cast<App*>(user);
+  if (a->window == nullptr || g_scan_probe == nullptr) return G_SOURCE_REMOVE;
+  E1608ScanProbe& p = *g_scan_probe;
+  p.status = scan_status(p);
+  std::vector<GtkWidget*> rows;
+  collect_named(p.form.rows[0], "e1608-result", rows);
+  p.first = rows.size();
+  GtkWidget* mine = nullptr;
+  for (GtkWidget* r : rows) {
+    const char* sub = adw_action_row_get_subtitle(ADW_ACTION_ROW(r));
+    if (sub != nullptr && p.want_mac == sub) mine = r;
+  }
+  p.listed = mine != nullptr;
+  if (mine != nullptr) {
+    const char* title = adw_preferences_row_get_title(ADW_PREFERENCES_ROW(mine));
+    p.ip = title != nullptr ? title : "";
+
+    scan_probe_stale(p);
+    g_signal_emit_by_name(mine, "activated");
+    const SourceConfig by_addr = p.form.read();
+    p.fill_addr = by_addr.get("address") == p.ip && by_addr.get("mac").empty() &&
+                  by_addr.get("subnet").empty() && p.changes == 1;
+
+    scan_probe_stale(p);
+    GtkWidget* use = find_named(mine, "e1608-use-mac");
+    if (use != nullptr) g_signal_emit_by_name(use, "clicked");
+    const SourceConfig by_mac = p.form.read();
+    p.fill_mac = by_mac.get("mac") == p.want_mac && by_mac.get("address").empty() &&
+                 by_mac.get("subnet").empty() && p.changes == 1;
+  }
+  scan_probe_click(p);
+  g_timeout_add(2000, e1608_scan_probe_rescan, a);
+  return G_SOURCE_REMOVE;
+}
+
+/// Phase 1: the form, Scan pressed (the row must read `Scanning...` at once), phase 2 in 2 s.
+gboolean e1608_scan_probe(gpointer user) {
+  App* a = static_cast<App*>(user);
+  if (a->window == nullptr) return G_SOURCE_REMOVE;
+  SourceKind* k = find_kind("e1608");
+  if (k == nullptr) {
+    std::fprintf(stderr, "[e1608] scan: no e1608 kind\n");
+    return G_SOURCE_REMOVE;
+  }
+  g_scan_probe = new E1608ScanProbe;
+  E1608ScanProbe& p = *g_scan_probe;
+  p.form = k->make_config_form();
+  const char* env = g_getenv("UDPSCOPE_PROBE_E1608_SCAN_MAC");
+  p.want_mac = env != nullptr ? env : "00:80:2f:00:16:08";
+  p.form.on_change([]() {
+    if (g_scan_probe != nullptr) ++g_scan_probe->changes;
+  });
+  scan_probe_click(p);
+  const std::string now = scan_status(p);
+  if (now != "Scanning...")
+    std::fprintf(stderr, "[e1608] scan: status right after Scan reads '%s', expected 'Scanning...'\n",
+                 now.c_str());
+  g_timeout_add(2000, e1608_scan_probe_fill, a);
+  return G_SOURCE_REMOVE;
+}
+```
+
+Notes for the implementer: `SourceConfig::get` returns `std::string` (the existing probe calls `f.read().get("signals") == "..."`); `find_kind`, `SourceConfig` and `ConfigForm` are already used in this file. Do not write `x({...}).empty() || y({...}).empty()`.
+
+- [ ] **Step 3: Build and run against the mock**
+
+```sh
+cmake --build build -j8 2>&1 | grep -E "warning:|error:" ; echo done
+python3 tools/mock_e1608.py --port 54211 > /tmp/mock-scan.log 2>&1 &
+MOCK=$!
+UDPSCOPE_PROBE_E1608_SCAN=1000 UDPSCOPE_EXIT_AFTER_MS=6500 xvfb-run -a ./build/udpscope \
+  --source e1608 --source-opt address=127.0.0.1 --source-opt scan_rate=1000 2>&1 \
+  | grep -E "^\[e1608\] scan|gtk warnings|Gtk-CRITICAL"
+kill $MOCK
+```
+
+Expected: `[e1608] scan: found=1 ip=<a local address> mac=00:80:2f:00:16:08 status='1 board found' fill_addr=1 fill_mac=1 rescan_replaced=1 ok=1`; `gtk warnings: 0`; no `Gtk-CRITICAL`. `found=2` or more is fine if a real board is on the network (status then reads `N boards found`; the line still needs `ok=1`).
+If `ok=0` and the second line says the board did not answer, check Task 1 Step 6's loopback note, and tell the user honestly; do not mark this step passed.
+If a flag other than `listed` reads 0, debug that flag (the fill reads the form back; `changes` must be exactly 1 per fill).
+
+- [ ] **Step 4: Clean-build warning count**
+
+```sh
+rm -rf /tmp/scan-clean && cmake -S . -B /tmp/scan-clean >/dev/null && cmake --build /tmp/scan-clean -j8 2>&1 | grep -c "warning:"; rm -rf /tmp/scan-clean
+```
+
+Expected: `3`.
+
+- [ ] **Step 5: Docs**
+
+- `README.md`, E-1608 paragraph (line ~119): after "...(optionally with the subnet to sweep)," add the scan: the sentence "A **Scan network** row at the top of the form probes every network interface of the host for boards (about a second and a half), lists each one by address and MAC, and a click on a result fills the address, or **Use MAC** fills the MAC and leaves the address empty. Results are not saved: only the filled field is." Also add one sentence that a MAC with no subnet is now looked up on every interface, not only the default route's, because a single limited broadcast leaves through the default route alone and missed a board on another interface (found on a real board 2026-11-02, where the board was on `net0` and the default route was `wlan0`).
+- `docs/claude/build-and-run.md` line ~125: change "a MAC with no `address` is looked up by broadcast" to "...looked up by a broadcast sent on every interface (`Scan`), or by a sweep of `subnet`".
+- `docs/claude/verification.md`: after the `UDPSCOPE_PROBE_E1608_RECONNECT=8000` bullet add a bullet for `UDPSCOPE_PROBE_E1608_SCAN=1000` with `UDPSCOPE_EXIT_AFTER_MS=6500`, run as `--source e1608 --source-opt address=127.0.0.1` against the mock on its default port 54211 (the form scans that port), optional `UDPSCOPE_PROBE_E1608_SCAN_MAC` for a real board; one `[e1608] scan:` line; note it needs a non-loopback up interface with a broadcast address, and that the line says so when the board did not answer.
+- `docs/claude/probe-readings.md`, `## [e1608]`: add the sample line `[e1608] scan: found=1 ip=172.21.121.113 mac=00:80:2f:00:16:08 status='1 board found' fill_addr=1 fill_mac=1 rescan_replaced=1 ok=1` to the block, and one bullet per field: `found` (result rows after the first scan; 0 with the "did not answer" second line is an environment without a reachable broadcast interface, not a pass), `status` (the row subtitle; "No board found" with a mock running is the probe sockets not reaching it), `fill_addr=0` (a result click did not set only the address, or told the dialog other than once), `fill_mac=0` (same for Use MAC), `rescan_replaced=0` (the results of the first scan were kept or doubled: `start_scan` did not remove them).
+- `docs/claude/architecture.md` line ~45: in the E-1608 three-layers bullet, add that discovery is `Scan` (one socket per interface, polled by the caller; the form polls it from a GLib timer on the main thread, the source's lookup through `discover_broadcast`).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/ui_probe.cpp src/ui_app.hpp src/ui.cpp README.md docs/claude
+git commit -m "e1608: probe and docs for the network scan"
+```
+
+- [ ] **Step 7: Manual run on the real board (only if it is attached)**
+
+Check `ip -4 -o addr` for the board's interface and `ping`-free: simply run the probe without the mock, naming the board's MAC (the user knows it; the MAC printed by the earlier hardware run was on `net0`, address 169.254.88.75):
+
+```sh
+UDPSCOPE_PROBE_E1608_SCAN=1000 UDPSCOPE_PROBE_E1608_SCAN_MAC=<board mac> UDPSCOPE_EXIT_AFTER_MS=6500 \
+  xvfb-run -a ./build/udpscope --source e1608 --source-opt address=127.0.0.1 2>&1 | grep -E "^\[e1608\] scan"
+```
+
+If it finds the board (`listed`, `ok=1`), add one sentence with the date to the README's E-1608 paragraph ("the network scan was checked against a real board on <date>") and commit `docs: record the scan check on a real board`. If the board is not attached or the MAC is unknown, say so; claim nothing.

docs/superpowers/specs/2026-10-07-scope-features-design.md

@@ -0,0 +1,437 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- SPDX-FileCopyrightText: 2026 Martino Ferrari -->
+
+# Three things a bench scope has and udpscope does not: qualified triggers, measurement statistics, and a search over the buffer
+
+udpscope triggers on one thing — a level crossing — reports each measurement as a single
+number with no sense of how it has varied, and offers no way to ask where in the retained
+buffer something happened. A survey of what bench scopes and the open-source viewers provide
+turned up a longer list than this; it was narrowed deliberately, and what was cut is named in
+**Scope** below.
+
+The three features chosen are not independent. A qualified trigger condition and a search over
+the buffer are the *same question* asked of live data and of recorded data, so they are built
+on one evaluator rather than two, and the probe that proves they agree is part of the work.
+Measurement statistics are separate but cheap: the pane's recompute pass already produces the
+number a statistic accumulates.
+
+## Scope
+
+**In:**
+
+- A shared, allocation-free `EventDetector` extracted out of `TriggerEngine`, carrying four
+  condition types: edge (as now), pulse width (with glitch as a comparison, not a fifth type),
+  window, and dropout.
+- The trigger panel's new type row and the parameter rows each type needs.
+- Per-measurement statistics — count, mean, standard deviation, min, max — accumulated one
+  observation per recompute, with a pane-wide toggle and a Reset.
+- A `Search` section in the trigger panel that scans the retained ring for the trigger's own
+  condition, marks the hits, and navigates them by reusing the existing pause.
+- Four new probes, and the mock waveforms they need.
+- `SPECS.md` is not changed; `README.md` and `docs/claude/` are.
+
+**Out, and deliberately:**
+
+- **Reference waveforms** — declined explicitly.
+- **PNG export** — the `.npy`/`.csv` export covers the need that matters; a screenshot is the
+  window manager's job.
+- **FFT / spectrum** — needs a second `plot::Figure` with its own x units, which is a project
+  of its own and not a feature of this one.
+- **Byte-bounded event history** — a second retention policy beside the ring's, with its own
+  eviction. Out for the same reason.
+- No new measurement types. No change to `measure_scan_buckets()` /
+  `measure_accumulate_bucket()` or to the hysteresis band. No change to the decimation plan, the
+  partition, or the two-thread split.
+
+## Global constraints
+
+These bind every task below and are not restated in each one.
+
+- **Two threads only.** `EventDetector::feed()` runs on the producer inside
+  `Acquisition::on_data()`, under `ScopeModel::mutex()`. It allocates nothing, throws nothing,
+  does no I/O, and is `noexcept`. The statistics accumulator and the search driver run on the
+  GTK main thread.
+- **Every new source file carries the SPDX MIT header**, matching the existing files.
+- **Stream seconds, end to end.** Nothing on the trigger or search path converts a span to a
+  sample count, and nothing introduces a samples-per-second estimate. That conversion is the
+  documented cause of the "the post window is empty" defect
+  (`docs/claude/invariants-trigger-and-pinning.md`).
+- **The detector is fed the stored (decimated, averaged) value**, never the wire value — an
+  event found on a sample the buffer does not hold cannot be cut from it.
+- **A pinned axis is pinned from the snapshot's own stamps, never from the request.** Applies to
+  every pause the search publishes.
+- **There is no unit test suite.** Every assertion is a probe line on stderr, driven through the
+  real widgets, read against the documented baselines: the documented build-warning count and
+  zero `Gtk-CRITICAL`.
+- **No figure is written into a document unless it was measured on this machine.** Costs are
+  printed by probes and quoted from those runs.
+- **Run one probe at a time.** The only exception is the search probe's internal
+  scan-versus-armed pairing, which is one probe.
+
+## File structure
+
+| File | Responsibility |
+| --- | --- |
+| `src/condition.hpp` / `.cpp` | **New.** `EventCondition`, `TriggerType`, `WidthCmp`, and `EventDetector` — the whole per-sample condition state machine and nothing else. No model, no GTK, no allocation. |
+| `src/trigger.hpp` / `.cpp` | `TriggerConfig` grows an `EventCondition`. `TriggerEngine` keeps arming, the hold-off, the pre-window gate, the post window and the mode, and delegates detection to `EventDetector`. |
+| `src/search.hpp` / `.cpp` | **New.** `BufferSearch` — the chunked scan driver over the retained ring, the hit list, the cursor into it, and the staleness state. Owns no widgets. |
+| `src/measure.hpp` / `.cpp` | `MeasureStatsAccum` (Welford) beside the existing result types. |
+| `src/plot_host.hpp` / `.cpp` | `kSearchMarks` cursors per row, created in `install()`, placed by a new `set_search_marks()`. |
+| `src/ui.cpp` | The trigger panel's type and parameter rows, the `Search` expander, the statistics toggle and second line, the chunk pump in the frame tick, and the four probes. |
+| `src/layout_store.hpp` / `.cpp` | One new `LayoutState` field: the statistics toggle. The trigger is not persisted today and is not persisted by this design. |
+| `tools/mock_udpstreamer.py` | `--glitch-at` / `--glitch-width` / `--quiet-at`. |
+| `README.md`, `docs/claude/*` | What was built, and the invariants it adds. |
+
+`src/condition.*` and `src/search.*` are new files rather than additions to `src/trigger.cpp`
+and `src/ui.cpp` for two reasons: the detector must be includable by the search without
+dragging in the engine's arming state, and `src/ui.cpp` is already the largest file in the
+project.
+
+## 1. The shared event condition
+
+### What is extracted
+
+`TriggerEngine::process()` (`src/trigger.cpp:38-106`) currently does three jobs. Lines 78-84
+detect a crossing; line 92 gates it on the pre-trigger window; lines 42-75 run the
+pending/post-window/hold-off/mode machine. Only the first is what a search means by "a
+condition", so only the first moves.
+
+```cpp
+enum class TriggerType { Edge, PulseWidth, Window, Dropout };
+enum class WidthCmp { Less, Greater, Within, Outside };
+
+struct EventCondition {
+  TriggerType type = TriggerType::Edge;
+  double level = 0.0;
+  double level2 = 0.0;          ///< Window: the band's other edge. Ignored otherwise.
+  TriggerEdge edge = TriggerEdge::Rising;
+  WidthCmp cmp = WidthCmp::Greater;   ///< PulseWidth only.
+  double width_s = 1.0e-3;            ///< PulseWidth only.
+  double width2_s = 2.0e-3;           ///< PulseWidth, Within/Outside only.
+  double timeout_s = 1.0e-3;          ///< Dropout only.
+  bool operator==(const EventCondition&) const noexcept;
+};
+
+class EventDetector {
+ public:
+  /// Adopts the condition. Resets the state iff the condition differs.
+  void configure(const EventCondition& c) noexcept;
+  void reset() noexcept;
+  /// One sample, in stream order. Returns the event's own stream time, or NaN for no event.
+  double feed(double value, double t) noexcept;
+};
+```
+
+`feed()` returns a **time** rather than a bool because for two of the four types the event's
+instant is not the sample being looked at: a pulse width is only known at the pulse's closing
+edge, and a dropout fires on an ordinary sample nowhere near an edge.
+
+`TriggerEngine::process()` then reads:
+
+```cpp
+const double event_t = detector_.feed(value, now_s);
+if (!std::isfinite(event_t)) return false;
+if (event_t - oldest_s_ < pre_seconds_) return false;   // the gate, now on the event's own t
+last_trigger_s_ = event_t;
+pending_ = true;
+pending_start_s_ = event_t;
+```
+
+Note the gate and `pending_start_s_` both move from `now_s` to `event_t`. For `Edge` they are
+the same value and the behaviour is bit-identical to today; for a long qualifying pulse they
+differ, and using `now_s` would measure the post window from the wrong instant.
+
+`TriggerEngine::configure()` keeps its name-keyed reset exactly as it is
+(`docs/claude/invariants-trigger-and-pinning.md`) and additionally calls
+`detector_.configure(cfg.condition)`, which resets the detector only when the condition
+actually changed — a condition re-applied every packet must not restart the state machine, or a
+pulse-width condition could never see a pulse end.
+
+### The four types
+
+| Type | Fires when | The instant it calls t0 |
+| --- | --- | --- |
+| `Edge` | `level` is crossed in `edge`'s direction | the crossing sample |
+| `PulseWidth` | a pulse — a crossing in `edge`'s direction, then the crossing back — whose duration satisfies `cmp` against `width_s` (and `width2_s` for `Within`/`Outside`) | **the closing edge**: the width is not known before it |
+| `Window` | the signal enters or leaves `[min(level,level2), max(level,level2)]`; `Rising` = enters, `Falling` = leaves, `Both` = either | the crossing sample |
+| `Dropout` | `level` has not been crossed for longer than `timeout_s` | the first sample at which the timeout is observed |
+
+**Glitch is `PulseWidth` with `cmp = Less`** and is not a separate type. That is how bench
+scopes spell it, and one state machine cannot disagree with itself about where a pulse ended.
+The panel may label the preset "glitch".
+
+`Dropout`'s t0 is the sample at which the expiry is *observed*, not the exact expiry instant,
+for the same reason every readout in this app quotes a stored sample: t0 has to be a sample the
+buffer holds, because the cut is a binary search over the time ring and the axis is pinned to
+what the cut got.
+
+**A zero-width band is refused by the panel, not special-cased in the detector.** The band test
+is `v >= lo && v <= hi` and the event is a change of side, so with `level == level2` the signal
+is "inside" only on exact float equality — which a crossing essentially never lands on, making
+the condition one that silently never fires. That is a worse failure than a refusal, and it
+cannot be fixed by special-casing the detector into an edge trigger: the two state machines
+answer different questions and conflating them is the divergence this design exists to prevent.
+So the second level spin is clamped to differ from the first by at least its own increment, the
+panel says why, and `EventDetector` keeps one unconditional band test.
+
+### Panel and session
+
+The trigger panel gains a **type** combo above the existing rows, and the rows below it change
+with the type: `Edge` shows the level, edge and pre-% rows it shows now; `PulseWidth` adds a
+comparison combo and one or two width spins; `Window` turns the single level spin into two;
+`Dropout` replaces the width with a timeout. Hold-off, pre-% and Normal/Single are common to
+all four and do not move.
+
+No plot instrument is added. The trigger level has never been drawn on the plot — it is a spin
+button (`src/ui.cpp:135`, `:1604`) — so a band needs no second ruler.
+
+`TriggerConfig` gains one `EventCondition` member; its `level` and `edge` replace the
+`TriggerConfig` fields of those names, and every reader moves with them.
+
+**The condition is not persisted, because the trigger is not persisted.** `LayoutState`
+(`src/layout_store.hpp:19-63`) carries the window, rows, calibration, colours, enabled signals,
+the source, the math graphs and the measurements — and no trigger field at all; the trigger is
+built from `--holdoff` and the panel's own defaults on every launch. Adding persistence for it
+is a separate feature nobody asked for, and a session that silently restored an armed
+pulse-width condition would be a surprise rather than a convenience. The only session key this
+design adds is the measurements pane's **statistics toggle**, which belongs beside the
+`measures` it governs.
+
+The level's existing default — the middle of the signal's declared range until the user edits it
+(`src/ui.cpp:2016-2054`) — applies to `Window` as a band about that middle, and `level2`
+defaults with it.
+
+## 2. Measurement statistics
+
+### What is accumulated
+
+Not the samples: `Average` is already the mean of every visible sample. A statistic is of the
+**measurement's own reported value over time** — count, mean, standard deviation, min and max of
+every value that measurement has produced since the last reset.
+
+```cpp
+/// The variation of one measurement's own value over time. Fixed size, no allocation: it is
+/// folded in the pane's existing recompute pass, which must not grow a second pass.
+struct MeasureStatsAccum {
+  std::uint64_t n = 0;
+  double mean = 0.0;   ///< Welford's running mean
+  double m2 = 0.0;     ///< Welford's sum of squared deviations
+  double lo = 0.0;
+  double hi = 0.0;
+  void add(double v) noexcept;
+  void reset() noexcept;
+  double sd() const noexcept;   ///< sqrt(m2 / (n - 1)), 0 for n < 2
+};
+```
+
+Welford rather than `sum` and `sum_of_squares`: on a value with a large offset — a 3.3 V logic
+level whose σ is a few millivolts — the naive form loses the variance entirely to cancellation
+in `Σv²`.
+
+### One observation per recompute
+
+`update_measures()` is throttled deliberately (`src/ui.cpp:3141-3162`): at most one pass per
+`kMeasureRefreshUs` while the window scrolls, four times that when a pass is heavy, and exactly
+**once when the window settles** — the `!changed` early return at `:3153` is what makes a pinned
+window recompute once rather than every frame. The accumulator takes one observation per pass,
+so:
+
+- A scrolling live view contributes on the order of ten observations a second.
+- A paused view, a held event or a pinned window contributes **one**.
+- `n` is therefore a count of *recomputes* — not of samples, frames or seconds. The pane labels
+  it `n` and its tooltip says so. Presenting it as a sample count would be a figure the user
+  acts on and that is false.
+
+Two exclusions, each of which would corrupt the statistic silently:
+
+- An **invalid** result (`--`) contributes nothing, to neither `n` nor the extremes.
+- The **`measure_last_valid` fallback** (`src/ui.cpp:3363`) is **not** accumulated. It exists so
+  a level mark does not blink off and is by construction a repeat of an observation already
+  counted; folding it in pulls the mean toward whatever preceded a dropout and collapses σ.
+
+### Reset
+
+An explicit **Reset** button in the pane clears every accumulator. Three changes clear them
+implicitly, because each one makes the values before and after a different population:
+
+- the measurement is edited (signal, type or options);
+- a CONFIG arrives — the signal list is rebuilt and a name may now resolve elsewhere;
+- the display window changes — a mean over 2 s and a mean over 600 s are different statistics.
+
+Deliberately **not** cleared by a pause, a resume, an event latch, or a pan/zoom within the
+window. Each of those contributes its one settled observation.
+
+Accumulators are not persisted. A statistic over a session that has ended is not a statistic;
+the **toggle's state is** persisted.
+
+### Display
+
+One `Statistics` check button at the top of the measurements pane. Off — the default — the pane
+is exactly as it is now. On, every row grows a second line beneath it, dimmed and smaller:
+
+```
+● ● frequency                    5.0003 Hz   edit
+    x̄ 5.0001  σ 0.0004  ▾ 4.9989  ▴ 5.0012  n 143
+```
+
+Pane-wide rather than per-measurement, so that the second lines align and are comparable, and
+because the per-measurement dialog is already the busiest surface in the app.
+
+The second line is a `GtkLabel` in a vertical box wrapping the existing horizontal row, built in
+`measures_row()` (`src/ui.cpp:2495`) and shown or hidden by the toggle — the toggle must **not**
+call `rebuild_measures_pane()`, which drops and recreates every label including the ones the
+frame tick holds pointers to. All five numbers go through the same `format_measure()` the
+value above them uses, so units and significant figures agree by construction.
+
+## 3. Search and navigate
+
+### What it searches, and with what
+
+A `Search` expander at the bottom of the trigger panel, searching **the trigger's own
+`EventCondition`** read straight off `TriggerConfig`. There is no second condition UI: a
+condition is set up once and can either be armed to capture live or scanned for over the buffer
+already held. That is what the shared evaluator buys, and it gives the search all four types for
+free.
+
+It runs on the **trigger's channel** over the **retained ring** — not the visible window, which
+the user can already read by looking.
+
+### The scan is exact, chunked, and progressive
+
+It feeds the same `EventDetector`, sample by sample, in stream order, raw. No bucket-skipping: a
+level-0 bucket whose `[lo,hi]` does not straddle the level cannot hold a crossing, so skipping
+it is tempting, but the detector is a sequential state machine and synthesising its previous
+value across a skipped span is precisely how the search and the live trigger would come to
+disagree about where an edge was. The shared evaluator exists to make that impossible.
+
+A raw pass over the whole ring cannot be one pass under one lock — that holds
+`ScopeModel::mutex()` long enough to starve the producer. `BufferSearch` therefore advances in
+**bounded chunks pumped from the frame tick**, taking and releasing the lock per chunk, the same
+shape `update_measures()` uses to materialise its window in chunks. The detector's state carries
+across chunks because it is sequential. The panel shows progress and a Cancel.
+
+Two limits, both reported in the panel rather than hidden:
+
+- **The ring keeps filling during the scan** — a pause freezes the view, not the acquisition.
+  Each chunk re-clamps to the ring's current base; if the base has passed the chunk's start the
+  scan stops and the panel says so (`searched 412 s of 600 s — the oldest data was overwritten
+  while scanning`). Reachable only at high rates on a small buffer.
+- **The hit list is capped** at `kSearchHitsMax = 10000`, and the panel says
+  `stopped at 10000 matches`. A condition matching every sample is a mis-set condition; the
+  answer is a message, not millions of doubles.
+
+### The hits, and navigating them
+
+Hits are a `std::vector<double>` of stream times, each the t0 its condition defines. The panel
+shows `147 matches` with `◀ prev`, `next ▶` and `3 / 147`, with key bindings while the panel has
+focus.
+
+Navigation reuses the existing pause. Jumping to hit `t` pauses if not already paused and calls
+the primitive that is already there (`src/ui.cpp:2188-2199`):
+
+```cpp
+model->publish_pause_view(t - w / 2.0, t + w / 2.0, /*x_offset=*/t);
+if (auto snap = model->pause_view(); snap && !snap->stamps.empty())
+  rows->pin_pause_window(snap->stamps.front(), snap->stamps.back());
+```
+
+`w` is the current display window. `x_offset = t` puts the hit at **x = 0**, exactly where a
+held event's edge sits, so the two ways of looking at an event read alike and the x-label logic
+needs no new case. The pin comes off the snapshot's own stamps and never off the request: a hit
+near the oldest retained sample yields a shorter cut, and pinning the request leaves an empty
+left margin that a zoom-in walks into.
+
+Resuming or clearing the search resumes and unpins exactly as the pause button does. The hit
+list survives a resume — it describes data the ring may still hold — but goes stale, so the
+panel marks its age, and any structural rebuild (a CONFIG, an enable/disable, a calibration
+change, or a window change that moves `time_stride`) clears it outright, because those drop the
+history it refers to.
+
+### Marks
+
+Cursors are not dynamic: `RowSet` creates them up front in fixed arrays
+(`kMeasureMarks = 6`, `src/plot_host.hpp:55`) because a `Plot` cannot give one up. So this adds
+`kSearchMarks = 16` cursors per row, created in the same `install()` loop
+(`src/plot_host.cpp:185-188`) and taking the same read-only dashed 0.75 px stroke the measure
+marks take, parked when unused.
+
+Every frame, the hits inside the visible window are placed on them, nearest to the view's centre
+first, with the current hit in a distinct colour. When more hits are in view than there are
+marks the panel reads `16 of 38 marks shown — zoom in to see the rest`, which is a true
+statement about the picture rather than a silent truncation. Like the measure marks they are
+re-placed every frame, which is what makes them read-only: a gesture moves one and this puts it
+back.
+
+## 4. Verification
+
+Four probes, each scheduled by an env var, each driving the real widgets, each printing tagged
+lines to stderr. Added to `docs/claude/verification.md` and `docs/claude/probe-readings.md` with
+the readings a correct run gives — measured, never assumed.
+
+**The numbers in the sample lines below, and in the pane mock-up above, show the line's *shape*
+only.** None of them has been measured; nothing may copy them into a document as a reading. The
+figures that go into `verification.md` come from a run.
+
+**`UDPSCOPE_PROBE_CONDITION_MS`** — for each of `Edge`, `PulseWidth` with `Less`, `PulseWidth`
+with `Greater`, `Window` and `Dropout`: set the type and its parameters through the panel, arm,
+wait for the latch, print
+
+```
+[condition-probe] type=pulsewidth cmp=less width=0.0005 t0=4.3021 want=4.3020 ok=1
+```
+
+`want` comes from the mock's injection schedule. `ok=1` is the reading.
+
+**`UDPSCOPE_PROBE_STATS_MS`** — add a `frequency` measurement on the mock's sine, turn the
+statistics toggle on, let several recomputes land, print
+
+```
+[stats-probe] n=14 mean=5.0001 sd=0.0004 lo=4.9989 hi=5.0012 toggle=1 line2=1
+```
+
+then press Reset and print it again: `n=0` is the assertion. It must also hold a pause for a
+stretch and show `n` advancing by **exactly 1** across it — that is what distinguishes
+accumulating per recompute from accumulating per frame. With the `measure_last_valid` fallback
+wrongly accumulated, `n` climbs through an injected dropout while the value does not change and
+`sd` collapses; that is the second defect this probe exists for.
+
+**`UDPSCOPE_PROBE_SEARCH_MS`** — configure a glitch condition, scan to completion against the
+injected pulse train, print
+
+```
+[search-probe] matches=7 first=1.3020 last=6.8020 scanned=8.21/8.21 s truncated=0 capped=0
+[search-probe] jump 1/7 t=1.3020 axis=[-1.0000..1.0000] snap=[-1.0000..1.0000] inside=1 x0_hit=1
+```
+
+for three successive `next` presses. `matches` is asserted against the injection count,
+`inside=1` is the pause-pin invariant, `x0_hit=1` is the hit sitting at x = 0.
+
+**The cross-check that makes the shared evaluator a claim and not a hope.** The same probe run,
+same condition, same mock, **armed** instead of searched: the first latch's t0 must equal the
+scan's `first` exactly.
+
+```
+[search-probe] armed t0=1.3020 vs scanned first=1.3020 agree=1
+```
+
+A divergence between the live and the offline path appears here and nowhere else.
+
+**Costs are printed, not asserted**, because an unmeasured figure drifts: `scan cost: N chunks,
+X ms total, worst chunk Y ms` — the **worst chunk** is the invariant worth watching, since it is
+what the producer waited on; the total is allowed to be long. Statistics accumulation is folded
+into the existing `measure cost:` line.
+
+**Mock additions:** `--glitch-at <s>` / `--glitch-width <s>` inject a narrow pulse into a pulse
+train at a known instant, and `--quiet-at <s>` stops a signal crossing its level from a known
+instant. Both are permanent regression cases, like `--time-glitch-at`.
+
+## Risks
+
+- **`TriggerConfig`'s `level`/`edge` move into `EventCondition`**, so every reader changes —
+  the panel, the probes and the status line. Mechanical, but wide, and the
+  mitigation is that `Edge` behaviour must be bit-identical afterwards: the existing trigger
+  probes are the regression test and are run before anything new is added.
+- **The scan's worst chunk is a latency the producer pays.** The chunk size is the one knob, it
+  is picked from the measured figure, and the probe prints the worst chunk every run.
+- **`kSearchMarks = 16` is a fixed cost in cursors per row** on every plot whether or not a
+  search is running, as `kMeasureMarks = 6` already is.

docs/superpowers/specs/2026-10-08-resequencing-and-relative-timing-design.md

@@ -0,0 +1,327 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- SPDX-FileCopyrightText: 2026 Martino Ferrari -->
+
+# A late packet leaves a hole it could have filled, and the clock it would be filed under is the wrong one
+
+Two requests, and they are one design.
+
+The first is that a reordered packet currently reads as permanent damage. `udps_client.c:504-514`
+orders the stream by the wrapping `uint32` counter and discards anything that arrives behind the
+newest counter — `stats.stale_packets++; return 0` — *before* spending anything on the payload.
+The samples are gone, the span they should have filled stays empty, and udpscope never learns
+there was a span at all. The asked-for remedy is to leave a hole of
+`<N samples> × <LAST_PACKET_ID − NEW_PACKET_ID − 1>`, mark it invalid, and fill it when the
+missing packets arrive.
+
+The second is `todo.md` item 2: a relative-time mode in which the plot's x comes only from the
+declared sample rate and the packet number, with absolute stream time kept for export.
+
+They are one design because **the counter is what makes a hole addressable**. A reserved hole has
+to be a known number of samples at a known position, and a late packet has to compute which
+position it belongs to. Absolute stamps cannot do either — a lost packet's stamps were never
+received, so its extent in time is a guess, and the guess is what the glitch bridge at
+`src/acquisition.cpp:274-292` is already making. The counter gives the extent exactly. Relative
+timing is not a cosmetic preference that happens to be requested at the same time; it is the
+coordinate system in which resequencing is arithmetic rather than inference.
+
+Two facts from the existing code shape almost every decision below, and both say the work is
+smaller than it looks:
+
+- **`frame->counter` and `frame->lost` are read nowhere in udpscope.** `frame.lost` is set by the
+  client at `udps_client.c:560` and appears in `src/acquisition.cpp` only inside comments
+  (`:309`, `:331`, `:336`). The client has been reporting the exact gap width for the life of the
+  project and nothing has ever consumed it. Neither input needs inventing.
+- **`clamp_deadline()` already exists** (`udps_client.c:1102`), documented as *"Clamps `budget` so
+  a pending deadline is not slept through"* and already used for the keepalive and the silence
+  timeout. The reorder deadline is a third call to it.
+
+## What was decided, and the constraint that decided it
+
+The latency budget is **20 ms**, maximum. That one number settles the shape of the whole receive
+path, because it is a *time* budget and not a packet count: at 1000 pkt/s it is twenty packet
+spans of reorder depth, at 10 pkt/s it is a fifth of one. A hold policy counted in packets would
+either be useless at high rates or add 400 ms at low ones. A policy counted in wall time works at
+every rate, because network reorder is measured in milliseconds regardless of how fast the
+producer sends.
+
+It also means a *contiguous* arrival must be released immediately. The 20 ms is spent only when
+there is a gap to wait on, never on the common case.
+
+Past the window, a committed hole is still **backfilled for values only**. Math channels and the
+trigger are not replayed. A math channel takes NaN in and gives NaN out, so after a repair the
+raw trace is whole and the math trace derived from it keeps its gap. That is a deliberate,
+documented state, not an oversight: the display then says *"this region arrived too late to be
+part of the computation"*, which is true and is cheaper than any mechanism that could make it
+false.
+
+Resequencing and hole reservation run in **both** time modes. In relative mode a hole's stamps
+are exact; in stream mode they are the declared cadence continued from the last good stamp, which
+is the existing bridge mechanism reused. Relative timing is therefore an independent toggle a user
+flips for jitter, not a prerequisite for recovery.
+
+A hole is surfaced two ways: **status-bar counters** and a **shaded band** over the invalid span.
+A NaN run already breaks the polyline, but a one-packet hole at a 10 s window is sub-pixel, and a
+gap nobody can see is not a report.
+
+## Relative timing
+
+`build_stamps()` today picks its clock *by inspection*: `time_source_` latches 1 for the declared
+time signal or 2 for the arrival clock and never flips back (`src/acquisition.cpp:357-367`).
+Relative timing is not a third thing to infer. It is a user-selected mode that bypasses the
+inference: `--relative-time` on the command line, a toggle in the UI, persisted in the session
+file.
+
+### The stamp
+
+```
+stamps_[k] = double(slot_base_ + k) / rate
+```
+
+`slot_base_` is a running `u64` of samples seen. Each packet the counter reports missing advances
+it by `batch`, **before** the frame's own samples are stamped; the delivered frame then advances it
+by its own `n`. The order is what puts the hole ahead of the data that revealed it.
+
+This is the requested `counter × batch + sample_index` with the origin left at counter zero, but
+**accumulated rather than multiplied**, and the difference earns three things:
+
+- `batch` is then only ever needed to size what is *absent*. That is exactly the
+  `<n_samples_per_frame>` of the original formula, and it is the only place the value is load
+  bearing.
+- The `uint32` wrap costs nothing. The counter is consumed only as a signed delta — the same
+  arithmetic `udps_client.c:505` already performs — so no unwrapping bookkeeping is needed.
+- A frame whose `n` disagrees with the established `batch` cannot silently shift the whole
+  timeline, because the timeline is built from the `n` values actually seen.
+
+`batch` is established from the first DATA frame and held for the life of the stream. A later
+frame disagreeing is a genuine inconsistency in the producer, not a loss, so it warns once rather
+than re-deriving.
+
+### The rate is the declared one, and only the declared one
+
+`build_stamps()` currently overrides a declared cadence with the arrival-measured one when the two
+disagree by more than ±25% (`src/acquisition.cpp:152-158`), because a CONFIG declaring 1 MS/s
+while delivering a hundred samples every fifth of a second reads as a staircase in the x column.
+Relative mode must **not** do this. Discarding arrival timing is the entire point of the mode. The
+override stays live in stream mode and is skipped in relative mode.
+
+### The constant offset is already absorbed
+
+`src/acquisition.cpp:555` stamps `rel = stamps_[k] - epoch`, and the `t0 =` caption names the
+epoch. A counter that happens to read 500 000 on connect therefore shows up as an epoch value, not
+as a 50 000 s axis. No origin subtraction is needed in the formula itself.
+
+### The x axis needs no change at all
+
+`RowSet::update_time_labels()` already goes to a relative label form on the tick step against the
+label resolution at the axis' magnitude, with the `t0 =` caption naming the absolute anchor
+(`docs/claude/invariants-time-axis-and-window.md:34`). "Counting backwards, like it is now" is
+what that already does. Relative mode changes *where a stamp comes from* and nothing in the label
+layer.
+
+### What relative mode makes unreachable
+
+The degeneracy guard, the implausible-jump test, `kFailureLimit`, the bridge and the monotonic
+clamp are all dead in relative mode: the stamps are monotone by construction, so there is no bad
+stamp to detect and nothing to clamp. (`kGlitchPackets` itself survives — not as the threshold of
+that test, which is unreachable, but as the reservation cap below, where its value and its
+reasoning carry over unchanged.)
+
+That is not tidiness, it is a fix. Measured last session: a loss burst past `kGlitchPackets` (256)
+is misread as a producer clock glitch; each bridge then advances the anchor by *one* packet span
+while the true timeline is 300 ahead, so the next four packets fail too, `kFailureLimit` trips,
+and the whole stream is thrown onto the arrival clock — the exact failure the bridge was added to
+prevent (`--drop-burst 300` reads
+`jumped implausibly far ahead ... (1.299..1.29999 against a previous 0.99899)` then
+`timing samples by arrival instead`). In relative mode a 300-packet gap is a known quantity and
+cannot be misdiagnosed.
+
+### Absolute time for export
+
+`todo.md` requires absolute stream time to remain available for export. There is exactly one f64
+time ring per `BufferStore`, shared by every channel of that buffer, and relative mode takes it.
+Export therefore needs a **second** f64 ring carrying the absolute stamp under the same group-mean
+rule, written in **relative mode only** and read by export and by nothing else — eight bytes per
+stored slot. The absolute ring is not kept unconditionally; it is budgeted along with the main
+ring and the value rings, which is why it halves the retained span rather than costing a
+proportional fraction (see SPECS.md for the measured figures and the power-of-two explanation).
+
+This cost is paid rather than avoided. Without it, selecting relative mode silently degrades the
+one output `todo.md` says must keep absolute time.
+
+The measured history cost: **83.886 s** in stream mode and **41.943 s** in relative mode, at
+100 kS/s, 4 channels, `--buffer-mb 200`. The plan's ~22% figure and the per-byte 75% figure are
+both wrong because `Partition::time_capacity` is floored to a power of two.
+
+## The receive path
+
+### In the client: a reorder ring of reassembled payloads
+
+Every `udps_frame_t` sets `frame.signals = c->sigs; frame.values = c->vals`
+(`udps_client.c:566-567`) — one client-owned decode buffer, reused for every packet. A frame is
+therefore valid only inside the callback, and holding one requires a copy *wherever* the holding
+happens. The client has no advantage there.
+
+It has a different one: it still holds the **raw datagram**. Resequencing undecoded wire bytes is
+strictly cheaper than resequencing decoded doubles — an `f32` or `i16` payload is two to four
+times smaller than what `c->valbuf` would hold — and the bytes exist nowhere else. That is why
+this sits in the client and not in `Acquisition`.
+
+The hook is the `decode_data()` call site at `udps_client.c:599`: after fragment reassembly, which
+already tolerates arrival order through the slot table, and before decode. Each held entry carries
+the payload bytes, their length, the counter and `recv_time`.
+
+The policy, against `next_counter = last_delivered + 1`:
+
+| arrival | action | added latency |
+| --- | --- | --- |
+| `== next_counter` | decode and deliver now, then drain held entries that became contiguous | **none** |
+| `> next_counter` | copy into the ring; set the gap deadline to `now + 20 ms` if not already set | the newer packet waits |
+| `< next_counter` | the gap is already committed — decode and deliver, flagged **late** | n/a |
+| deadline fires | give up on the missing counters, advance `next_counter` to the lowest held entry, drain in order | capped at 20 ms |
+
+The last row is where `stats.stale_packets++; return 0` at `:506-509` is replaced: a late packet
+is delivered flagged instead of discarded, which is the single change that makes backfill possible
+at all.
+
+The deadline is served by a third `clamp_deadline()` call on the `select()` budget
+(`udps_client.c:1145-1152`). Without it, a held packet on a quiet stream would wait for the next
+arrival — 100 ms at 10 pkt/s — and blow the budget.
+
+Two bounds on the ring, because 20 ms is a different number of packets at every rate: a fixed
+entry count and a fixed byte budget. Overflow commits the gap early rather than growing, and
+increments its own counter, so an undersized window is visible rather than silent.
+
+The window itself is `udps_config_t::reorder_window_s`, defaulting to `0.020`, along
+`recv_buffer_bytes` and `silence_timeout_s` (`udps_client.c:982`). Zero disables resequencing and
+restores today's discard-on-late behaviour exactly, which is what makes the change bisectable
+against a reported regression. The policy value is udpscope's; the mechanism is the client's.
+
+### In `Acquisition`: reservation
+
+On a frame with `lost > 0`, before pushing the frame's own samples, run `lost × batch` NaN samples
+through the **existing** per-sample loop at `src/acquisition.cpp:553`.
+
+That reuse is the design. `tick_` advances, so `tick % g == g - 1` keeps firing on the same phase
+and the decimation grid does not shift; the group mean still lands on the mean stamp; and
+`MinMaxPyramid::append` sees NaN, which its existing non-finite contract already handles as
+*advances the positional count, excluded from every aggregate*. Nothing bespoke is needed for
+decimation, stamping or the pyramid.
+
+Stamps across the hole come from the active time source — exact in relative mode, the declared
+cadence continued from the last good stamp in stream mode, which is the bridge at `:274-292`.
+
+Math channels take NaN and give NaN, so a math trace keeps its gap. The trigger engine's
+comparisons are false on NaN, so it cannot latch inside a hole; this is asserted by the probe
+rather than assumed.
+
+**Reservation is capped at 256 missing packets**, reusing `kGlitchPackets` and its existing
+reasoning verbatim — *256 packet spans in one go is an outage, not loss*. Past the cap there is no
+reservation: log once and continue as today. That cap is also what stops a ten-minute outage from
+pushing billions of NaN samples through the ring and wiping all history to make room for a gap.
+
+## Backfill
+
+`plot::data::RingBuffer` and `MinMaxPyramid` are both strictly append-only today. Backfill needs
+an amend in each, and the two belong on different threads.
+
+`plot_host.hpp:183` calls `acquire(ScopeModel&)` from the frame path, so the **pyramid is mutated
+only on the GTK main thread**, once per frame: the producer pushes into the ring and the main
+thread folds what was pushed into the pyramid. That split carries straight over to the amend.
+
+- **Ring amend — producer thread.** `RingBuffer<T>::amend(absolute, v)`, bounds-checked against
+  `[produced_ - capacity, produced_)`, a single relaxed store. The same race class as a push, and
+  an `f32` cannot tear. Measurements and export read the ring directly, so they see a repair
+  immediately.
+- **Pyramid amend — main thread, inside `acquire()`.** The producer appends amended `(slot, value)`
+  pairs to a plain `std::vector<Amend>` member; `ChannelBuffer::acquire()` drains it **after** its
+  append pass, so every amended index is already published. No SPSC queue is needed: `acquire()` is
+  called under `model.mutex()` and the producer holds that same mutex for all of `on_data`, so the
+  vector is correctly serialised without lock-free machinery.
+
+The thread split is not a stylistic choice. A bucket is 32 bytes and is not atomic, so amending it
+from the producer would let a reader see a half-updated bucket whose `sum` does not match its
+`count` — a wrong mean from a structure whose readers trust `count == 0` to mean *absent*. On the
+main thread that cannot happen and no seqlock is needed.
+
+`MinMaxPyramid::amend(index, v)` folds `v` into every covering bucket: at `count == 0`,
+`min = max = v`, `sum = v`, `sumsq = v²`, `count = 1`; otherwise widen `min`/`max` and accumulate
+`sum`/`sumsq`, `++count`. Its documented precondition is **non-finite → finite only**, which is
+what makes it purely additive and O(log n) with no rebuild. An index already dropped by
+`drop_before` is a no-op.
+
+### The time ring is never amended
+
+The hole was pre-stamped at reservation, so a backfill changes values only. `neighbours()` keeps
+the monotonic array its binary search requires and `window_x0_` stays valid. This is the reason
+reservation pre-stamps rather than leaving the ring short.
+
+### Addressing a late packet
+
+Reservation records `(counter_first, counter_last, tick_start, slot_start, slot_count)` in a
+bounded side table. A late frame's counter indexes straight into it:
+
+```
+tick = tick_start + (counter - counter_first) * batch
+```
+
+Only slots lying **wholly** inside the arrived packet's tick range are amended. A slot straddling
+a hole edge went NaN when its accumulator took a NaN, and its real members were never retained, so
+it stays NaN. A displayed hole is therefore at most one slot wider per edge than the true loss —
+invisible at any hole size worth repairing, and it makes a boundary slot need no special case.
+
+The side table is bounded by the 256-packet reservation cap and a maximum entry count; it is also
+the source the shaded band reads.
+
+## Surfacing
+
+`StreamStats` gains `late_resequenced`, `late_committed` (gave up past 20 ms, or overflowed the
+reorder ring) and `late_backfilled`, and finally exposes `stale_packets` — which the client has
+counted since the beginning and which `src/status_text.cpp:70` has never shown, so an inversion
+today has to be inferred from `packets` and `frames` diverging. All four sit in the status bar's
+second tier.
+
+The band is a new `Plot::set_invalid_spans()` in `deps/plotter`, drawn as a tinted quad behind the
+trace. Unlike the `t0` caption this *is* data-anchored — it must pan and zoom with the data it
+marks — so it is annotation-class, not chrome. The invariant it must respect is that it reserves
+no layout space and cannot be picked, so a hole cannot move the layout the labels were measured
+into.
+
+## Verification
+
+udpscope has no unit test suite; the only automated check is the application's own headless
+self-check (`CLAUDE.md`). This adds exit-dump lines and a `UDPSCOPE_PROBE_RESEQ_MS` probe,
+asserting: a reorder inside the window is resequenced with no hole; a reorder past the window
+leaves a hole and then backfills it; the trigger does not latch inside a hole; a 300-packet burst
+hits the cap and does not throw the stream onto the arrival clock; and relative mode's stamps are
+monotone with the declared spacing.
+
+Runs are serial and short, against the two standing baselines: four build warnings on a clean
+build (two on an incremental build) and zero `Gtk-CRITICAL`. Batching several `xvfb` runs back to
+back starves the mock past its 2 s `silence_timeout_s` and reads as a reconnect, which is a
+measurement artefact and not a defect (`docs/claude/verification.md`).
+
+**One gap in the mock has to be closed first.** `--reorder-every` releases the held packet
+immediately after the one that overtook it, so it is ~0 ms late and would always land inside the
+20 ms window. That exercises resequencing but leaves the **backfill path untestable**. The mock
+needs `--reorder-delay-ms` so a packet can be released deliberately past the window.
+
+## Documentation this lands against
+
+- `docs/claude/invariants-data-path.md` — append-only stops being the whole truth; the amend's
+  precondition and its thread belong here.
+- `docs/claude/invariants-plot-and-layout.md` — the band, and the layout space it must not take.
+- `docs/claude/invariants-trigger-and-pinning.md` — the trigger does not latch inside a hole.
+- `docs/claude/verification.md` — the new probe and dump lines, and `--reorder-delay-ms`.
+- `docs/claude/build-and-run.md` — the vendored `udpsclient` diff: the reorder ring, the late
+  delivery replacing the discard, and the third `clamp_deadline()`.
+- `README.md` and a `SPECS.md` deviation note for relative-time mode.
+
+## Deliberately not in scope
+
+- **Replaying math channels or the trigger over a backfilled region.** Decided against above.
+- **Interpolating across an unrepaired hole.** A hole is reported, not invented. There is no
+  interpolation anywhere in the data path today and this does not add the first.
+- **Making relative mode the default.** It is a toggle. The default stays the declared time
+  signal, so no existing session or run changes what it shows.
+- **The `(min, max, mean, rms)` gather mode** that would fix the separate solid-band degeneration
+  at wide time windows. Related to the pyramid, unrelated to this; still open.

docs/superpowers/specs/2026-10-08-visible-edges-design.md

@@ -0,0 +1,353 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- SPDX-FileCopyrightText: 2026 Martino Ferrari -->
+
+# A square wave's riser is sometimes drawn and sometimes not, and the trace is thinner than the library's own default
+
+The report is that a vertical line — the rising or falling edge of `square` in
+`tools/mock_udpstreamer.py` — is too thin to see, and that it *glitches in and out of
+existence*. Those are two complaints, not one, and they have different causes. The second is a
+defect with a derivable mechanism and a single line of code behind it. The first is a styling
+choice this app made and then never revisited: udpscope asks for a trace **thinner** than
+`deps/plotter`'s own default.
+
+The three remedies named in `todo.md` — grade with more strength, thicken the lines, enlarge the
+sample dots — are all taken. They are not, on their own, enough: the glitch is a row being
+dropped *before* any of those knobs is consulted, so a thicker, brighter trace would glitch in
+and out at a thicker, brighter width.
+
+## The defect: `lit_floor` decides existence, and `intensity_floor` only decides alpha
+
+`Renderer::stage_trace_density()` (`deps/plotter/src/render/renderer.cpp`) accumulates one
+column's dwell into `column_rows_`, where **a segment deposits one unit spread over the rows it
+spans** — `w = 1 / (r1 - r0 + 1)`. It then decides which rows are inked at all:
+
+```cpp
+const f32 lit_floor = 0.01f * peak;
+...
+const bool lit = r < rows && cover > lit_floor;
+```
+
+`peak` is the column's own maximum cover. That makes the existence test a *share of the
+brightest row in the same column*, and for a square wave the brightest row in a column is a
+flat level, whose segments each deposit a full 1.0 into one row.
+
+Take a column that holds both a flat level and the edge. At ~105 samples a column the gather is
+on raw samples, so the column holds ~105 segments: all but one are flat and deposit a full 1.0
+into one row, while the riser is a single segment spread over the whole axis and deposits
+`1/312 = 0.0032` into each of 312 rows. `peak` is then ~50 and `lit_floor` ~0.5 — **over a
+hundred times the riser's own deposit**. Every row of the riser is unlit. The connector at the
+bottom of `emit_column()` does not rescue it either: the top run and the bottom run are both lit,
+so the column's `band_lo…band_hi` already spans the full height, neither gap test fires, and no
+connector is staged. The column is drawn as a bright mark at the top and a bright mark at the
+bottom with nothing between them.
+
+In the phase where the riser lands in a column *by itself*, `peak` is the riser's own deposit,
+the floor is a hundredth of it, every row clears it, and the riser is drawn full height. Which
+case a frame lands in depends on the phase of the bucket grid against the pixel grid, and the
+trace scrolls, so the phase sweeps. That is the whole of "glitches in and out of existence" — not
+a redraw race and not a data gap.
+
+### Measured, before writing any of this down
+
+A true square wave (period 2098 samples, so ~20 columns a period), 60 000 x-units over the 572 px
+axis of `deps/plotter`'s own headless EGL harness — 104.8 samples a column — drawn twice, once
+with `intensity_grading` off and once on, with the pixels read back both times over the **same**
+axes rect. The reading counts the columns the *ungraded* frame inked as a full-amplitude band
+(the riser columns) and then asks how many of exactly those rows the graded frame left dark:
+
+| | riser columns | inked rows over them | intact | gutted | worst dark run | segments |
+| --- | --- | --- | --- | --- | --- | --- |
+| ungraded | 116 | 35 884 | — | — | — | 627 |
+| graded, before | 116 | **2 916** | 10 | **106** | **311 of 312 rows** | 684 |
+| graded, after | 116 | 35 572 | 115 | 1 | — | 732 |
+
+So the graded path was drawing **8 %** of the ungraded path's ink over the riser columns, and 106
+of 116 of them were gutted outright while 10 survived — the 10 being the phase that put a riser
+in a column of its own, which is the flicker, measured. The fix restores 99.1 % of the ink and
+costs 48 segments on a 572 px axis.
+
+Two notes on that table, both of which the committed test must carry rather than smooth over:
+
+- **The one column still gutted after the fix is column 11**, the second column of the window's
+  first riser. The ungraded path inks *two* full-height columns per riser (its per-column min/max
+  plus the connectivity extension, and the gathered window's slack sample) where the graded path
+  inks one, which is also why 116 riser columns appear for ~58 risers. The graded path is the
+  more precise of the two here; the test must assert against the riser's own column rather than
+  against every column the flat path happened to fill.
+- **The existing grading test is unchanged by the fix** — `a_dense_trace_can_be_graded_by_dwell`
+  still reads `flat edge=191 middle=191` against `graded edge=191 middle=131` at `seg=8303`, the
+  documented figures to the digit, and all 376 cases pass. The fix only reaches rows that were
+  below the share floor, which is what makes it a correction and not a restyling.
+
+The app-level A/B this design originally proposed — `UDPSCOPE_NO_PHOSPHOR=1` against the mock's
+`square` — was dropped in favour of the above: udpscope has no probe that can see a dropped row,
+so the app-level run could only have shown that the picture differed, while the library harness
+reads the pixels and names the rows. The mechanism is measured at the layer it lives in.
+
+`Style::intensity_floor`'s own documentation already promised what `lit_floor` broke:
+
+> Not 0: a column the signal merely passed through is still a column the signal *reached*, and a
+> riser dimmed out of existence is a square wave drawn as two disconnected lines.
+
+`intensity_floor` guards a lit row's **alpha**. Nothing guarded its **existence**, and the two
+floors were never reconciled.
+
+### The fix, already applied and measured
+
+`lit_floor` may not exceed the smallest deposit the column actually made, so that **a row one
+segment covers is always lit**. The column's minimum `w` is tracked as the deposits are written
+— one scalar, reset by `emit_column()`, no allocation, one `min` added to the per-segment path —
+and the floor becomes:
+
+```cpp
+const f32 lit_floor = std::min(0.01f * peak, 0.5f * w_min);
+```
+
+The share term stays: it is what stops a row inking on the running-sum reconstruction's residue
+alone. The second term is what makes the test *about a measurement* rather than about a ratio to
+an unrelated row. The half is slack against that reconstruction, not a tuning knob.
+
+This changes no geometry bound — the runs are still maximal stretches of equal tier, O(rows) per
+column at worst — and it touches neither the gather level, the pyramid, nor
+`stage_trace_columns()`. It is in the working tree (`deps/plotter/src/render/renderer.cpp`) with
+the figures above in the comment at its site, which is what Task 2 below is reduced to reviewing.
+
+## The second defect, found by testing the first: grading was gated on the column reduction
+
+The `lit_floor` fix was built and run against the real app, and the report back was that the
+edges are now always visible — and that a new thing is wrong: *"when I zoom in on an edge the
+brightness increases a lot compared to when I am looking at the whole waveform."* Clarified: the
+dimming itself is wanted, **a discontinuity should never be drawn as brightly as a flat top**, at
+any zoom. So the complaint is not about the amount of dimming but about its *inconsistency*.
+
+Measured in the same harness, the riser's own ink at mid-height (the rows neither flat level can
+reach) against the flat level's 191, over a zoom sweep from 101 samples a pixel down to 0.01:
+
+| samples/pixel | 101 | 33.7 | 10.1 | 3.4 | 1.01 | 0.34 | 0.10 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| riser ink, before | 71 | 71 | 71 | 71 | **191** | **191** | **191** |
+| riser ink, after | 71 | 71 | 71 | 71 | 71 | 71 | 68 |
+
+A 2.7× jump in a single step, at `dense_threshold_spp = 1.5`. The cause is a coupling, not a
+constant: grading is staged *inside* `stage_trace_density()`, which only runs when the column
+reduction runs, and the reduction is gated on two gathered points per pixel column. That gate is
+a **density condition whose only purpose is removing the moiré beat** between the bucket pitch
+and the pixel pitch. Dwell has nothing to do with that beat, so zooming past the threshold
+switched the whole phosphor model off — and switched it off exactly where the user is looking at
+an edge closely, which is why it was reported as the edge *lighting up*.
+
+### The fix: grade the polyline by each segment's slope
+
+`Renderer::stage_trace_slopes()` stages the sparse polyline into the same `intensity_steps`
+batches, differing from the dense path only where it must:
+
+- **The measure is `1 / (1 + |Δy_screen|)`** — dwell per row for a single segment. The `1 +` is
+  not a division guard: a flat segment, span 0 and the commonest case in a sparse window, must be
+  the *brightest* tier, and this makes the measure dimensionless and **absolute**. There is no
+  per-column peak down here to normalise against, and that is an improvement — a sparse frame's
+  tiers mean the same thing from frame to frame, so panning does not reshade the trace.
+- **No gather mode is excluded.** `grade` is not reused as the gate: it requires `Envelope`,
+  because turning a bucket's min/max into a band answers a different question from the one a
+  `Nearest` or `Mean` host asked. A segment's slope is a property of the polyline itself.
+- **The geometry is bit-for-bit `stage_xy()`'s**, same `snap = false`; only the batch differs. A
+  segment with one non-finite end is dropped rather than clamped, which is the conclusion
+  `add_polyline_xy()` reaches too.
+- **`FrameStats::slope_traces` is disjoint from `column_traces`**, so a host asserting
+  `graded_traces == column_traces` keeps that reading unchanged.
+
+Tier distribution sanity-checked by hand against the defaults (4 steps, gamma 0.45, floor 0.3):
+span 0 → tier 3, span 1 → 2, span 3 → 2, span 10 → 1, span 312 → 0. A gently sloping sparse sine
+therefore stays near the top tier and is not dimmed into invisibility, which was the risk.
+
+### One false alarm, recorded because the metric was the bug
+
+A first reading of this sweep showed the *frame's brightest pixel* falling from 191 to 167–172 on
+the sparse path whenever grading was on, which the arithmetic said was impossible (a flat segment
+is tier 3, alpha exactly 1.0). It was the measurement: the y range was −1…1, so both flat levels
+sat **on** the boundary rows and were half clipped, and the 191 the ungraded frame reported came
+from pixels near the riser where two segments overlap and double-composite — which grading splits
+across tiers, so they no longer saturate. With the range at −2…2 and the level read well clear of
+the riser, the level is 191 with grading on or off at every zoom. No regression existed. The
+committed test uses −2…2 and reads the level and the riser as two separate figures for this
+reason, stated at the site.
+
+## The styling: the host asked for a thinner trace than the library's default
+
+`RowSet::install()` (`src/plot_host.cpp:175`) builds every trace with `1.2f`. The library's
+`Trace::width` default is `1.5f`, and `Style::crosshair_width`'s documentation treats 1.5 as *the
+trace width a crosshair must read as thinner than*. So the app inverted its own stroke hierarchy
+at the only place it states it, and `1.2f` is also, in both staging paths, the **minimum span a
+short run is stroked at** — the `if (hi - lo < width)` widen — so it sets the floor on how
+visible a one-row run can ever be.
+
+`marker_px` (3.0) and `marker_below_samples` (50) are library defaults udpscope never restated;
+`ui.cpp`'s one-shot style statement sets `intensity_grading` and nothing else.
+
+## Scope
+
+**In:**
+
+- `deps/plotter`: the `lit_floor` correction in `stage_trace_density()`, a library test that fails
+  without it, and the `PLOT_TEST_FILTER` the measurement needed.
+- `deps/plotter`: `Renderer::stage_trace_slopes()` — grading for the sparse polyline — plus
+  `FrameStats::slope_traces` and a library test that fails without it.
+- `deps/plotter`: `Style::line_aa_px` and the grading constants remain *fields* — no new knob is
+  added, and `intensity_grading` stays **one** switch covering both rasterisation paths. The one
+  new field considered and rejected is named under **Out**.
+- udpscope: the trace width at `src/plot_host.cpp:175`, and the style one-shot in `ui.cpp`
+  extended to state `marker_px`, `marker_below_samples`, `intensity_floor` and `line_aa_px`
+  rather than inheriting them.
+- One new probe over the mock's `square`, and the `frame path:` reading extended to report the
+  dropped-row case so a regression is visible rather than merely ugly.
+- `docs/claude/invariants-rendering.md`, `README.md`, and upstream's
+  `docs/data-and-performance.md` + `README.md`.
+- `SPECS.md` is not changed.
+
+**Out, and deliberately:**
+
+- **A `Style` field for "always light a riser".** The dropped row is a bug in a test, not a
+  policy a host should get to choose; a flag would preserve the broken behaviour as an option and
+  oblige every host to know about it.
+- **Changing the connector's tier.** Drawing the inferred bridge at the faintest step is a
+  deliberate honesty claim ("this is not a place the signal was measured to dwell"). Once
+  `lit_floor` is fixed the riser is *real* ink at its own tier and the connector is back to
+  bridging only genuine disjointness, which is what it was written for.
+- **Per-trace or per-row width.** One width for every trace in the app, as now.
+- **A separate switch for sparse grading.** Two switches would let a host reproduce the very
+  inconsistency this fixes, and the user's own framing settles it: the dimming is wanted *at all
+  zooms*, so it is one look and not two.
+- **Normalising the sparse tiers against the frame.** The dense path normalises per column
+  because a frame-wide scale needs the whole image before anything can be drawn; the sparse
+  measure needs no normalisation at all, and leaving it absolute is what makes a pan stop
+  reshading the trace. Matching the dense path here would be matching a compromise.
+- **A user-facing preference for any of these values.** `todo.md` item 9 owns the preferences
+  dialog; this work states defaults in code and leaves hooks for nothing.
+- No change to the gather level, `MinMaxPyramid`, `dense_threshold_spp`,
+  `intensity_sub_columns`, the decimation plan, or the two-thread split.
+
+## Global constraints
+
+These bind every task below and are not restated in each one.
+
+- **Every new source file carries the SPDX MIT header**, matching the existing files.
+- **`stage_trace_density()` stays allocation-free on the frame path.** `column_rows_` is already
+  sized once per call and reused; the minimum-deposit tracking adds a scalar, not a container.
+- **No figure is written into a document unless it was measured on this machine.** The arithmetic
+  above is derived and is labelled as derived; every number that reaches `README.md` or
+  `docs/claude/` comes from a probe run quoted from that run.
+- **There is no unit test suite in udpscope.** Every assertion here is either a `deps/plotter`
+  test (that project has one) or a probe line on stderr driven through the real widgets, read
+  against the documented baselines: the documented build-warning count and zero `Gtk-CRITICAL`.
+- **Run one probe at a time.**
+- **The look is the user's call, the drop is not.** The `lit_floor` fix is correct or incorrect
+  and a test says which. The four style values are judgments; they are stated in one place, with
+  the before-value in a comment, so a second opinion is a one-line change.
+
+## Task 0 — the test harness filter, already applied
+
+`plottest::run_all()` ran all 376 cases unconditionally, so reading one case's output meant
+running the suite. `PLOT_TEST_FILTER` is a substring match honoured in `run_all()`
+(`deps/plotter/tests/harness.hpp`), unset meaning "all", which is what made the A/B above cheap
+enough to iterate on. Documented in upstream's `docs/building-and-testing.md`, including the trap
+that the summary line still counts the whole suite — so a filtered run says `377 cases, 0 failed`
+having run one, and is never evidence that the suite passes.
+
+## Task 1 — the library test that fails now
+
+Upstream, beside `a_dense_trace_can_be_graded_by_dwell`:
+`a_graded_column_keeps_a_riser_it_shares_with_a_flat_level`.
+
+The scratch measurement above is the shape of it, and was deliberately **not** committed: it
+reports numbers rather than asserting, and it leans on the flat path as its reference, which the
+column-11 note shows is not exact. The committed test keeps the construction and replaces the
+reference.
+
+The series and window are the measured ones — a true square of period 2098 over 60 000 x-units,
+~105 samples a column — because that density puts the gather on raw samples and makes a flat
+level's deposit a hundred times the riser's, which is the condition the defect needs. The riser
+must **share** its column, pinned by construction rather than by luck: it is the phase that
+survived in 10 of 116 columns, so a test that lets the phase float passes for the wrong reason
+about one time in twelve.
+
+The assertion is *continuity over the riser's own column*, not a brightness profile — the
+existing grading test already profiles fifths and passes either way. Prefer the staged geometry
+over a pixel readback so the failure names the dropped rows rather than reporting that the
+picture changed, and have the failure print the gap's row range.
+
+It must fail against the pre-fix `lit_floor`; verify that by reverting the one line, not by
+trusting the figures in this document.
+
+**Done.** `a_graded_column_keeps_a_riser_it_shares_with_a_flat_level`, beside the dwell test.
+It chooses its riser columns by the property at stake — a band spanning more than half the axis,
+which on a square wave is a transition and nothing else — from the ungraded frame, then re-reads
+exactly those columns from the graded one and asserts 95 % of them are still tall. Reading
+`kept=115` of `flat=116`, and `kept=10` with `lit_floor` reverted to `0.01f * peak`, which is the
+required failure verified rather than assumed. The column-11 slack is in the assertion's 95 % and
+its reason is in the comment.
+
+## Task 1b — the library test for slope grading
+
+`a_sparse_trace_is_graded_by_slope_like_a_dense_one`: one window either side of
+`dense_threshold_spp` over the same transition at the same place, asserting that the two frames
+took the two paths (`graded_traces` against `slope_traces`), that **neither dims the level**
+(191 either way), that **both dim the riser** to under 55 % of it, and that the two riser
+readings agree to within one tier. Reading 71/191 against 71/191; with the slope staging gated
+off the sparse frame reads 191/191 and the path assertion fails first.
+
+## Task 2 — review the fix
+
+The change is in the tree. What is left is to read the comment at its site against the measured
+numbers it quotes, and to confirm `Style::intensity_floor`'s doc comment now describes reality,
+since it is cited above as having promised what the code did not deliver.
+
+## Task 3 — the four stated values
+
+`src/plot_host.cpp:175` from `1.2f` to at least the library's `1.5f`. The comment records that
+the app had been asking for less than the default and that this width is also the minimum span a
+short run is stroked at.
+
+`ui.cpp`'s style one-shot (`src/ui.cpp:6149`) states, each with the inherited value in a comment:
+
+- `marker_px` — `todo.md` 1.3, "the sample points should be bigger". The dots only appear below
+  `marker_below_samples` raw samples in the window, so this is the deep-zoom reading and is
+  independent of everything above.
+- `marker_below_samples` — raising it brings the dots back at windows that currently show a bare
+  polyline.
+- `intensity_floor` and `line_aa_px` — the two readings of `todo.md` 1.1, "the antialiasing
+  strategy with phosphore effect should be applied with more stregth", and they are different
+  things: `intensity_floor` lifts the *faintest graded tier*, which is what a riser is drawn at
+  even once it is lit; `line_aa_px` widens the anti-aliased fringe on **every** stroke in the
+  library, which is literally more anti-aliasing and makes a thin line read fatter at the cost of
+  a softer grid and axis. Both are stated; the values are the ones to look at on screen and
+  adjust, and the task's report says what each one did on its own.
+
+Nothing here is conditional on Task 2, and nothing in Task 2 is conditional on these.
+
+## Task 4 — the probe
+
+`UDPSCOPE_PROBE_EDGEINK_MS`: plot the mock's `square`, settle on a window dense enough for the
+graded path, and report — per the line reference in `docs/claude/probe-readings.md` — the edge
+column's staged span against the band it should cover, and the count of unlit rows inside it.
+**It must read 0 dropped rows**, and it must be run with and without `UDPSCOPE_NO_PHOSPHOR=1`:
+the ungraded path is the control, and the two must agree about where the trace is.
+
+`frame path:` gains nothing new if the probe above covers the drop; the brief for this task
+decides that from the probe's output, and whichever way it goes,
+`docs/claude/probe-readings.md` gets the per-line entry.
+
+## Task 5 — the documents
+
+`docs/claude/invariants-rendering.md` already carries the grading invariant and the sentence
+"the floor so that a fast riser, one sub-bucket deep everywhere, is never dimmed out of
+existence". That is the claim this defect falsified, so the bullet gains the distinction the code
+was missing — **an alpha floor is not an existence floor** — and names the symptom, the phase
+dependence, and `UDPSCOPE_NO_PHOSPHOR=1` as the A/B that separates the two.
+
+`README.md` records the stroke and marker values as deliberate deviations from the library's
+defaults, under the existing deviations section.
+
+Upstream `docs/data-and-performance.md` and `README.md` carry the `lit_floor` rule and the slope
+path, since both are the library's contract and not this app's. **Done**, together with
+`Style::intensity_grading`'s own doc comment (which described the dense path as the whole of the
+feature), `docs/building-and-testing.md`'s `PLOT_TEST_FILTER` entry, and the case counts in all
+three places that quote them — 350 → 377, and 333 → 360 for the coverage preset.

docs/superpowers/specs/2026-10-09-udp-packet-capture-design.md

@@ -0,0 +1,328 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- SPDX-FileCopyrightText: 2026 Martino Ferrari -->
+
+# UDP packet capture: design
+
+`todo.md` item 4: *optional udp frame storage for debugging of strange behaviours (store last
+`<N>`, default = 1000, udp packets binary content on disk for forensic analysis).*
+
+The strange behaviours worth forensics on are all *wire* behaviours — a counter that skips, a
+datagram that arrives twice, a fragment that never completes, a CONFIG whose header does not parse,
+a burst that outruns the reorder ring. Every one of them is invisible by the time a
+`udps_frame_t` reaches `Acquisition::on_data`: the client has already validated the magic,
+reassembled the fragments, resequenced what it could and dropped what it could not. A capture that
+is to answer *what did the wire actually send* must therefore sit at `recv()`, and must store the
+bytes without interpreting them.
+
+This is a debugging aid, not a feature of the instrument. It is off by default, it adds nothing to
+the glance tier of the status bar, and it must not be able to cost a single packet when it is on.
+
+## The decisions taken, and what each one rules out
+
+| Decision | Alternative rejected |
+| --- | --- |
+| Always-on rolling ring while enabled; the last N are on disk at all times | Keeping the ring in RAM and flushing on an anomaly or on demand — a crash or a `SIGKILL` then leaves nothing, which is the case a forensic capture exists for |
+| A fixed-size file of N slots, plus a converter to pcap in `tools/` | Writing pcap directly (grows, so "last N" needs two rotating files and the newest N is split across both) or one file per datagram (1000 files, an open/write/close per packet in the receive path) |
+| `mmap` once, `memcpy` per datagram | A `pwrite` per datagram (a syscall, and on a busy disk a blocking one, between two `recv()` calls) or a third thread with a queue (a second copy of every datagram, and this application's two-thread property is load-bearing) |
+| One path per source, previous capture kept one deep | A timestamped file per enable (needs the retention policy `todo.md` item 9 defines and this does not build) or a single path overwritten (re-enabling destroys the capture you enabled for) |
+| `--capture-packets[=N]` as well as the popover button | Button only — by the time the window is up and clickable, the first connect and its CONFIG are already history, and those are exactly the "strange behaviours" hardest to reproduce |
+
+## Architecture
+
+Three parts, each with one responsibility and a seam that does not leak the other two.
+
+### 1. The client hands over raw datagrams
+
+`deps/udpsclient` gains **one additive entry point**:
+
+```c
+/** Every datagram as recv() returned it, before the magic check, reassembly or
+ *  resequencing: the bytes a capture has to store, and the only place malformed
+ *  or duplicate datagrams are still visible. Runs on the polling thread, inside
+ *  udps_client_poll(), like every other callback. `bytes` is valid until the
+ *  callback returns. */
+typedef void (*udps_datagram_cb)(const uint8_t *bytes, size_t len,
+                                 double recv_time, void *user);
+
+void udps_client_set_datagram_cb(udps_client_t *client,
+                                 udps_datagram_cb cb, void *user);
+```
+
+A separate setter, **not** a fourth parameter on `udps_client_set_callbacks`
+(`udps_client.h:283`): that signature has call sites, and a capture hook is no reason to change
+them.
+
+The call site is `udps_client.c:1458`, immediately after
+
+```c
+ssize_t n = recv(c->udp_fd, c->rxbuf, UDPS_RX_BUF_BYTES, 0);
+```
+
+returns a positive `n`, and before anything is read out of `rxbuf`. `recv_time` is the same clock
+the client already stamps arrivals with, so a capture's times and the stream statistics agree.
+
+**Boundary, stated rather than discovered later:** in multicast mode CONFIG arrives over TCP
+(`udps_client.c:1142`) and this hook does not see it. The capture is of the UDP socket. A malformed
+*multicast* CONFIG is therefore out of reach, and `README.md` will say so.
+
+### 2. `PacketCapture` owns the file
+
+New unit, `src/capture.hpp` / `src/capture.cpp`. One class, one responsibility — own the ring file
+and store a datagram into it. It includes no GTK, no `ScopeModel`, and no client types beyond
+`<cstdint>`; its whole interface is:
+
+```cpp
+class PacketCapture {
+ public:
+  /// Renames an existing capture to `capture-prev.bin`, creates and reserves the new file,
+  /// maps it. Returns false and leaves the object disabled on any failure, with `error()` set.
+  bool open(const std::string& path, std::uint32_t slot_count);
+  void close();                                   ///< unmap, close; idempotent
+  bool enabled() const noexcept;
+
+  /// One datagram. Called only from the producer thread. Never allocates, never blocks,
+  /// never fails: an over-long datagram is truncated to the slot and counted.
+  void store(const std::uint8_t* bytes, std::size_t len, double recv_time) noexcept;
+
+  std::uint64_t stored() const noexcept;          ///< datagrams since open()
+  std::uint64_t truncated() const noexcept;
+  std::uint32_t slot_count() const noexcept;
+  const std::string& path() const noexcept;
+  /// Copies the last open() failure out, or writes an empty string. Not a
+  /// `const std::string&`: see "What crosses between the threads" below.
+  void error(char* out, std::size_t cap) const noexcept;
+};
+```
+
+#### What crosses between the threads
+
+The producer thread writes this state and the GTK thread reads it every frame for the popover, so
+each field has to be publishable without a lock:
+
+| Field | Type | Why it is safe |
+| --- | --- | --- |
+| `enabled_`, `stored_`, `truncated_` | `std::atomic<…>`, relaxed | counters and a flag, not a consistent set — the same treatment `StreamStats` already gets |
+| `path_` | `std::string` | written **once** by the GTK thread before it ever sets `capture_want_`, and only read afterwards |
+| the open failure | `char error_[128]` plus `std::atomic<bool> error_set_` | the producer fills the buffer and *then* sets the flag with a release store; the GTK thread copies the buffer only when the flag reads true |
+
+The error is deliberately **not** a `std::string` accessor. A `std::string` written by the producer
+inside `open()` and read by the GTK thread on the next frame is a data race with a reallocating
+buffer — the kind that reads correctly for months. The fixed buffer with a flag published after it
+is the same release-store trick the slot's `seq` field uses, for the same reason.
+
+#### The file
+
+```
+offset 0, 64 bytes — header
+  magic        u8[8]  "UDPSCAP\0"
+  version      u32    1
+  slot_count   u32    N
+  slot_bytes   u32    sizeof(record header) + UDPS_RX_BUF_BYTES, 8-byte aligned
+  cursor       u32    next slot index to write (a hint; see below)
+  t0_realtime  f64    CLOCK_REALTIME at open(), the epoch recv_time is relative to
+  peer_addr    u32    the source's IPv4, network order
+  peer_port    u16
+  local_port   u16
+  reserved             to 64 bytes, zeroed
+
+offset 64 + i * slot_bytes, for i in [0, N) — slot i
+  t_arrival    f64    the client's recv_time
+  len          u32    bytes stored (after truncation, if any)
+  orig_len     u32    bytes the wire delivered, so a truncation is visible
+  bytes        u8[len]
+  seq          u64    1-based ordinal since open(); written LAST
+```
+
+`seq` is written last, after the bytes, with a release store. Three things follow, and they are the
+reason the format is this and not simpler:
+
+- **A slot carrying a non-zero `seq` is complete.** No `fsync` is needed for the file to be
+  readable after a crash: the kernel's dirty pages are the file, and a half-copied slot still has
+  `seq == 0`.
+- **`seq`, not `cursor`, is the order.** After the ring wraps, the newest slot is the one with the
+  largest `seq`, and the reader needs no trust in a header field that is updated out of band.
+- **A torn write is detectable, not silent.** The reader reports the count of empty and torn slots
+  rather than averaging over them.
+
+`cursor` is maintained anyway, because a human running `xxd` on the file wants to know where to
+look.
+
+#### Why the file is reserved, not sparse
+
+`posix_fallocate` reserves the whole file at `open()`. The obvious alternative — `ftruncate` and
+let the file stay sparse, so it costs only the bytes actually written — is wrong with `mmap`: a
+store into a page the filesystem cannot back raises **`SIGBUS`**, which kills udpscope outright.
+A capture must not be able to take down the instrument it is observing, and an out-of-space
+condition must be an error at the moment the user clicks, not a crash ten minutes later.
+
+At the default `N = 1000` and `UDPS_RX_BUF_BYTES = 65552`, the file is **~62.6 MiB**. That is
+stated in the help text, in the tooltip and in the popover row, because it is the one cost of
+switching the feature on.
+
+### 3. `Acquisition` drives it, and the GTK thread only ever sets an atomic
+
+`Acquisition` owns the `PacketCapture`, installs the datagram callback next to the three it already
+installs (`src/acquisition.cpp:62`), and does **every** file operation on the producer thread.
+
+```
+GTK thread (the button)              producer thread (the datagram callback)
+---------------------------          --------------------------------------------
+capture_want_.store(true)    ──►     reads capture_want_ at the top of each datagram
+capture_path_ written once           rising edge  → open() : rename, create, fallocate, mmap
+  before the first store               falling edge → close(): munmap, close
+                                     then, if enabled, store(bytes, len, recv_time)
+```
+
+No mutex, no queue, no second copy of any datagram, and the application still has exactly two
+threads.
+
+The one-off cost of a toggle is the `open()`: a rename, a create, a `posix_fallocate` of 62.6 MiB
+and an `mmap`, on the producer thread. It is a user-initiated act that happens once per toggle, and
+`README.md` will say that it can cost the packets in flight during it. Moving it off the producer
+thread would need the lock or the thread this design exists to avoid, for an event that happens
+when a human clicks a button.
+
+The duration is **measured, not asserted**: `open()` records its own wall time and the probe prints
+it as `open_ms`. `posix_fallocate` on a local extent-based filesystem is a metadata operation and
+should be a handful of milliseconds, but that is a claim about the filesystem, not about this code,
+and a reading above ~50 ms is a finding worth putting in `README.md` rather than a number to
+predict here.
+
+### Error handling, and only at this boundary
+
+This is a syscall boundary, so it is validated; nothing else here is.
+
+| Condition | Behaviour |
+| --- | --- |
+| `open`, `posix_fallocate` or `mmap` fails (ENOSPC, EACCES, a read-only cache directory) | capture stays off, `error()` carries `strerror`, one line on stderr, the toggle button returns to off and the popover row shows the reason |
+| the cache directory does not exist | created with `g_mkdir_with_parents`, 0700; a failure there is the row above |
+| `len > UDPS_RX_BUF_BYTES` | impossible — the slot is sized to the client's own receive buffer — but `store()` truncates to the slot, records `orig_len`, and counts it in `truncated()` rather than trusting the impossibility |
+| the previous `capture-prev.bin` cannot be replaced | the capture still opens; the rename failure is reported, the old previous is kept |
+| capture enabled with no connection yet | the button is insensitive until connected, because the path is keyed on the source; `--capture-packets` defers `open()` to the first datagram, which is what arms it before the first CONFIG |
+
+## Surfaces
+
+### The popover button and row
+
+The status bar's detail popover (`src/ui.cpp:7619-7672`) is a two-column grid: four bold headings
+at rows 0, 3, 5, 6 and seven value labels at rows 0..6, in `app->popover_label[11]`. It gains a
+fifth heading, **Capture**, and an eighth value label; the array becomes `[13]` and the
+`kHeadings` / `kHeadingRow` tables gain their entry. `update_status_popover`
+(`src/ui.cpp:6101`) writes the new label like the others — `gtk_label_set_text` only, no rebuild.
+
+The row reads one of:
+
+```
+off
+on · 412/1000 slots · 26.1 MiB · ~/.cache/udpscope/192.168.1.40-5000/capture.bin
+failed: No space left on device
+```
+
+Below the grid, a `GtkToggleButton` labelled **Capture packets** with the
+`media-record-symbolic` icon and a tooltip naming the full path and the file's size. `toggled`
+sets the atomic and nothing else. Insensitive until connected.
+
+Nothing is added to `format_detail()`'s note string: `src/status_text.cpp:86` is a `char
+note[160]` already close to its worst case, and the capture state is not something the exit dump's
+one line needs.
+
+### The command line
+
+```
+  --capture-packets N  store the last N raw datagrams on disk for forensics, in a
+                       ring under the cache directory (1000 slots is ~62.6 MiB);
+                       off unless given, and toggleable from the status bar
+```
+
+Parsed in `src/config.cpp`'s existing style — both `--capture-packets N` and
+`--capture-packets=N`, `N` in 1..100000 — and the value is **required**, not optional.
+`--capture-packets` with an optional value cannot be told apart from `--capture-packets` followed
+by a value in this parser, and every other option in it takes the space-separated form, so a bare
+flag would turn `--capture-packets 500` into `unknown argument: 500`. The 1000 default is the
+slot count the **popover button** uses when the flag was not given; with the flag, the button uses
+the N the flag named.
+
+`Config::capture_packets` is a `std::uint32_t`: 0 means the flag was absent, and the button then
+uses 1000.
+
+The flag arms the ring before the first datagram; it is not persisted in the session file. That
+persistence belongs with `todo.md` item 3's work, alongside the relative-time toggle deferred to
+the same place.
+
+### `tools/capture_to_pcap.py`
+
+```
+$ tools/capture_to_pcap.py ~/.cache/udpscope/192.168.1.40-5000/capture.bin out.pcap
+1000 slots, 412 stored, 0 torn, 0 truncated → 412 packets, 26.1 MiB
+$ wireshark out.pcap
+```
+
+Reads the header, validates the magic and version, walks the slots, orders by `seq`, skips
+`seq == 0`, and emits a classic pcap (`LINKTYPE_ETHERNET`, microsecond timestamps from
+`t0_realtime + t_arrival`) with a synthesised Ethernet/IPv4/UDP header per record built from the
+header's `peer_addr`, `peer_port` and `local_port`. Pure standard library — the mock already
+forces a hard `numpy` dependency on `tools/`, and this script has no reason to add to that.
+
+It also prints the counts above to stderr, which is what makes it a diagnostic in its own right:
+`torn` or `truncated` above zero is a finding about the capture, before anything about the stream.
+
+## Verification
+
+udpscope has no unit test suite; the capture is verified by the application's own headless
+self-check, and the converter by running it.
+
+`UDPSCOPE_PROBE_CAPTURE_MS` toggles capture **through the same handler the button uses**, waits a
+scheduled interval, then reads the file back off disk and prints one line:
+
+```
+[capture-probe] enabled=1 path=… slots=1000 stored=412 cursor=412 torn=0 truncated=0
+                header_ok=1 first_seq=1 last_seq=412 payload=1648000 file=65576064
+                open_ms=3.1 t0=1760000000.123
+```
+
+`payload` is the sum of every stored slot's `len` — the bytes the wire actually delivered, which is
+what tells you whether the ring is holding what you think. `file` is the reserved size,
+`64 + slot_count * slot_bytes`, and is a constant for a given N: it is in the line so that a
+mismatch against the file on disk is a reading rather than something to go and check.
+
+What each field has to read, and the defect a wrong reading names, goes in
+`docs/claude/probe-readings.md` beside the other probes. Two cases in
+`docs/claude/verification.md`:
+
+1. **enable at runtime** — the probe toggles on mid-run; `stored` must equal the datagrams the
+   exit dump counts from that instant, `torn=0`, and `first_seq=1`.
+2. **wrap** — `--capture-packets=16` against the standard mock, run long enough to wrap several
+   times; `stored` exceeds `slot_count`, `last_seq - first_seq == 15`, `torn=0`. A wrap that loses
+   ordering, or a `cursor` that disagrees with `seq`, shows here and nowhere else.
+
+Then the converter, run over the wrap case's file: exit 0, a record count equal to `slot_count`,
+and the pcap's own first and last record timestamps inside the run's wall-clock interval. The
+check is the converter's printed counts plus a `struct.unpack` of the pcap's first and last record
+headers — no Wireshark, no `capinfos`, nothing outside the standard library, so it runs wherever
+the self-check runs.
+
+The standing baselines apply unchanged: a clean build at exactly four warnings, an incremental at
+two, and zero `Gtk-CRITICAL` in any headless run.
+
+## Out of scope
+
+- **Replaying a capture back into udpscope.** That is `todo.md` item 5's territory (opening stored
+  waveforms) and a different feature with a different shape.
+- **Retention beyond one deep.** `capture.bin` and `capture-prev.bin`, nothing more, until item 9
+  defines the cache-size preferences.
+- **Session persistence of the enable state.** Deferred to item 3 with the relative-time toggle,
+  so one piece of work adds the session fields rather than two.
+- **Capturing the multicast TCP CONFIG channel.** Stated as a limitation in `README.md`.
+- **Compression, encryption or rotation of the ring.** A fixed file of raw bytes is what a
+  forensic reader wants, and `gzip` exists.
+
+## Documentation to update
+
+- `README.md` — the feature, the 62.6 MiB cost, the producer stall on toggle, the multicast CONFIG
+  limitation, the converter's usage.
+- `SPECS.md` — nothing: this is a `todo.md` item, not a spec requirement, and not a deviation.
+- `todo.md` — item 4 struck, on one line, with the flag's name (GFM strikethrough is inline and
+  cannot span list items).
+- `docs/claude/build-and-run.md` — the new option; `verification.md` and `probe-readings.md` — the
+  probe and its two cases; `docs/claude/invariants-data-path.md` — one paragraph on why the hook is
+  at `recv()` and why the file is reserved rather than sparse.

docs/superpowers/specs/2026-10-13-noise-rejection-design.md

@@ -0,0 +1,342 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- SPDX-FileCopyrightText: 2026 Martino Ferrari -->
+
+# Noise rejection: design
+
+Noise rejection in three places — the measurements pane, the trigger, and a new math node — aimed
+at one problem: **electromagnetic peaks**. EM interference is *impulsive*. It arrives as a few
+samples of large excursion, not as a raised noise floor, and that distinction decides every choice
+below. An impulse recrosses a threshold several times per true crossing, so it inflates an edge
+count; it moves a `min`, a `max` and a peak-to-peak outright; and it is the one kind of noise a
+low-pass filter handles *badly*, smearing the spike across its settling time instead of removing
+it while rounding the real edge beside it.
+
+Each of the three places therefore gets two independent, optional controls:
+
+| | amplitude qualifier | frequency qualifier |
+| --- | --- | --- |
+| **Trigger** | hysteresis band about the level, in signal units | one-pole HF reject on the comparator's input, `fc` in Hz |
+| **Measurements** | hysteresis band, % of the window's peak-to-peak | one-pole HF reject over the measured window, `fc` in Hz |
+| **Math** | — | the `de-noise` node: median over N samples, then a one-pole at `fc` |
+
+Nothing here changes a default. Every control is off, or set to the value the code already uses,
+so the whole documented reading set must come out of this work unchanged. That is the first
+verification assertion, not an afterthought.
+
+## The decisions taken, and what each one rules out
+
+| Decision | Alternative rejected |
+| --- | --- |
+| The trigger band is **absolute, in the channel's own units** | A percentage of a running peak-to-peak: the producer has no measured span, so it would need per-channel sliding-window state in the hot loop *and* a warm-up during which the band is wrong — which shows up as a missed or early latch, the one failure a trigger must not have |
+| `band == 0` takes today's crossing test **verbatim**, with the latched-side comparator used only when the band is non-zero | One unified latched-side comparator: at `v == level` exactly the two are *not* equivalent (today it fires, a zero-width band decides nothing), and `feed_window`'s own comment records a ±1 square against a `[1, 1]` band firing 19 times on exact float equality. `probe-readings.md`'s `[condition-probe]` table of four exact latch times is a regression suite in disguise; unifying would require re-measuring all of it to prove a change nobody asked for |
+| The band and the filter live **inside `EventDetector`** | Filtering in `Acquisition` before `engine.process()`: the buffer search deliberately runs the same evaluator (`condition.hpp:46-49`), so anything upstream of the detector has to be replicated there, and the live trigger and the search would drift apart |
+| No shared hysteresis primitive extracted | A common `side_of()` header used by `measure.cpp` and `condition.hpp`: the genuinely shared part is about five lines, and the two call sites want different things from it — `measure.cpp` `continue`s on an in-band sample while counting enters, widths and folded buckets, the detector needs a side to feed four state machines. Three similar lines beat a premature abstraction; the *invariant* is stated once and pointed at |
+| The measurement filter is a **real one-pole at a user `fc`**, and it disables the pyramid fast path | Measuring the pyramid's per-bucket means, which would be free and keep the fast path — but its corner is wherever the bucket size puts it (`fs/64`), so it is HF reject at one fixed, rate-dependent frequency rather than a cutoff the user can aim at the interference they actually have |
+| The filter runs **inside each of the two raw walks** | Materializing a filtered copy of the window: `MeasureChunk`'s comment (`measure.hpp:108-115`) records that widening the window cost 60 % of the pane's time before a single statistic had been computed, and 17 MB at a 2.2 M-sample window |
+| One combined `de-noise` node (median **then** pole) | A plain median node chained to the existing `LowPass`: two boxes for one idea, and it lets the user wire them in the wrong order — a pole *before* a median lets one spike contaminate the filter state for its whole settling time, which defeats the purpose |
+| The median window is **N samples, fixed** | A duration converted to N from `dt`: N would then grow with decimation, so a modest duration at a long window becomes a large sort in the producer's hot loop and needs a hidden cap the user did not set |
+| `MathOp::DeNoise` is **appended**, at index 12 | Inserting it beside the filters in `math_op_at()`, where it belongs in the dropdown: a node persists as its *index through that accessor* (`layout_store.cpp:358-365`), so inserting would silently reinterpret every node in every existing session file |
+| The median's ring is **pooled in `MathRuntime`** | A `double[9]` member of `MathNodeRt`: 72 bytes added to *every* node, doubling a struct whose shape README's math-cost section records as a deliberate choice, to serve the one op whose state size is a parameter |
+| A new **impulsive** mock source | Verifying against `--noise` (Gaussian): a median is specifically the wrong tool for a raised noise floor and the right one for impulses, so a Gaussian test would prove nothing about the feature |
+
+## 1. The trigger
+
+### Config
+
+`EventCondition` (`condition.hpp:27`) gains two fields:
+
+```cpp
+double noise_band = 0.0;  ///< hysteresis half-width about `level`, signal units. 0 = off.
+double hf_fc = 0.0;       ///< HF reject corner on the comparator's input, Hz. 0 = off.
+```
+
+Both **must** join `operator==` (`condition.hpp:37-41`). This is not bookkeeping:
+`EventDetector::configure()` returns early when the condition compares equal
+(`condition.cpp:9`) and the producer calls it on every packet, so a field omitted from the
+comparison is a control that silently never takes effect.
+
+The filter needs the sample interval to turn `fc` into a coefficient, and the detector is fed
+`(value, t)` pairs rather than a rate. `configure()` therefore takes `dt` as a second argument and
+keeps it as a `dt_` member, and the early return compares the new `dt` against `dt_` as well as the
+condition against the stored one — a re-plan changes `dt`, and a coefficient left over from the
+previous partition is a filter at the wrong corner.
+
+### Comparator
+
+`EventDetector` gains `int side_ = 0` (0 undecided, ±1 above/below) and one pole state word.
+`crossed_up`/`crossed_down` (`condition.hpp:77-82`) stop being pure functions of `prev_` and
+become flags computed **once per sample** in `feed()`:
+
+- `noise_band == 0` → `prev_ < level && v >= level` and its mirror, bit for bit as today.
+- `noise_band > 0` → `v >= level + band` latches `+1`, `v <= level - band` latches `-1`, anything
+  between decides nothing; a crossing *is* a change of latch.
+
+Computing the pair once also removes a duplicated computation: `feed_edge`, `feed_pulse` and
+`feed_dropout` each call both predicates today.
+
+`feed_window` (`condition.cpp:115`) does not use those predicates, so it takes the band
+explicitly on each edge of its own band: becoming *inside* requires `[lo+band, hi-band]`,
+becoming *outside* requires leaving `[lo-band, hi+band]`. A band wide enough to close that inner
+region is clamped to just under half the window's width — the same shape of clamp
+`measure_set_level()` already applies for the same reason, and it keeps the panel's existing
+refusal of a zero-width window meaningful.
+
+`reset()` (`condition.cpp:14`) clears `side_` and the pole state.
+
+### The filter
+
+One pole on the comparator's input, `y += a·(x − y)`, with `a = 1 − exp(−2π·fc·dt)` built in
+`configure()` and clamped below Nyquist as `biquad()` does (`math_channel.cpp:28`). `fc = 0`
+gives `a = 1`, i.e. `y = x`, so "off" needs no branch in the inner loop.
+
+Two consequences, both stated rather than discovered:
+
+- **The latch moves later** by roughly `1/(2π·fc)` — the pole's group delay. This is inherent,
+  it is what a bench scope's HF reject also does, and it is why the control is off by default.
+- **A NaN stays benign.** `feed()`'s comment (`condition.hpp:68-70`) records that a NaN sample
+  cannot fire because every comparison against it is false, and that *rejecting* one would leave
+  `prev_` stale and let the next sample fire a crossing that today cannot happen. The filter
+  preserves this: a non-finite input returns NaN (which flows into the existing comparisons, all
+  false) and leaves the pole state alone.
+
+`last_value()` (`condition.hpp:73`) comes to report the comparator's input rather than the raw
+sample. Its only consumer is the `v=%.4g` field of the trig-engine diagnostic
+(`acquisition.cpp:918`), whose purpose is to say what the comparator saw.
+
+### Panel
+
+A `trigger_band_spin` and a `trigger_hf_spin` in `build_trigger_panel()` (`ui_trigger.cpp:219`),
+read in `publish_trigger_fields()` (`:56`), shown for all four condition types in
+`sync_trigger_rows()` (`:94`). The band takes the level spin's unit, digits and range, floored at
+0.
+
+### The search gets both for free
+
+`EventDetector` holds no arming state precisely so the buffer search can run the same evaluator
+over retained samples (`condition.hpp:46-49`). A band or a filter set in the panel therefore
+changes what a search finds, consistently, with no second code path and no second thing to keep
+in step.
+
+### Not persisted
+
+The trigger has never been persisted, so neither control is either; a restart comes up with both
+off. That is also what makes every current `[condition-probe]` latch time hold unchanged.
+
+## 2. The measurements
+
+### Config
+
+`MeasureOptions` (`measure.hpp:37`) gains two fields:
+
+```cpp
+double noise_pct = 10.0;  ///< hysteresis half-width, % of the window's peak-to-peak. 0 = off.
+double hf_fc = 0.0;       ///< HF reject corner, Hz. 0 = off.
+```
+
+`noise_pct = 10.0` reproduces today's `kHysteresisFrac = 0.10` (`measure.cpp:36`) exactly, so
+every current reading is identical. `measure_set_level()` (`measure.hpp:195`,
+`measure.cpp:40`) already takes a `pct` — the *threshold* percent — so it gains a second,
+separately named `noise_frac` argument for the band, replacing its read of the file-scope
+`kHysteresisFrac`; the constant stays as `MeasureOptions::noise_pct`'s default so its
+measured-value rationale — 5 % reads a 0.1 interferer correctly and fails at
+0.2, 10 % holds to 0.3 and to white noise at σ=0.05 — does not become an orphan comment. The
+clamp to half the room between the level and the nearer extreme survives untouched: it is what
+keeps a threshold at 90 % measurable instead of reading `enters=0`.
+
+### The band reaches the edge types only
+
+`MeasureLevel::hysteresis`'s comment (`measure.hpp:165-169`) is explicit that the band moves the
+*edge decision* only, and that the `sum`/`count` split stays at the bare level — because that
+split **is** `Top`/`Bottom`, the mean of the samples above or below the threshold, and banding it
+would change the documented exact `top = 2/π` on a unit sine.
+
+So `noise_pct` is meaningful for `PulseDuration`, `Period` and `Frequency`, and does nothing for
+`Top`/`Bottom`. The file's own rule (`measure.hpp:34-36`) is that an option which does nothing
+for a type is left out of the dialog rather than stored and ignored, so this adds a
+`measure_uses_noise()` beside `measure_uses_threshold()` and `measure_uses_side()`
+(`measure.hpp:242-245`), and `measure_dialog_sync()` (`ui_measure.cpp:90`) shows the field for
+those three types only.
+
+A *raised* band also costs reads: `measure_accumulate_bucket()` already refuses a bucket where
+the signal passes `level ± hysteresis` (`measure.hpp:211-216`), so a wider band opens more
+buckets. The existing `measure cost:` line is where that shows up.
+
+### HF reject reaches every type
+
+The filter changes the samples rather than a decision, so `min`, `max`, `average`,
+`peak to peak`, `amplitude`, `top`, `bottom` and every crossing type all read the filtered
+signal. The control is therefore shown for all types.
+
+It is seeded with the window's first sample, so the step transient at the left edge does not read
+as a measurement. (Priming from samples *before* the window is possible — the ring holds the
+history — and is deliberately not done: it would make a measurement depend on data outside the
+window it reports on.)
+
+### What it costs
+
+`hf_fc > 0` disables **both** bucket fast paths, `measure_scan_buckets()` (`measure.hpp:147`) and
+`measure_accumulate_bucket()` (`:217`): a bucket's `lo`/`hi`/`sum` describe raw samples and cannot
+answer for a filtered signal. Both passes walk raw, which is the 1.2–1.6 ms → ~20 ms step at a
+2.2 M-sample window that README's measurement-cost section was written about. Against the pane's
+250 ms cadence that is a few percent of a core and a visible frame hitch.
+
+This is accepted deliberately: the control is per-measurement and off by default, so nothing gets
+slower unasked, and `measure cost:`'s `covered`/`buckets`/`raw` makes the cost a *reading* rather
+than a mystery. `raw ≈ covered` is the signature of a filtered measurement.
+
+The filter runs inside each of the two raw walks — three flops on a sample the walk is already
+reading — rather than materializing a filtered window once. Filtering twice is deterministic and
+free compared with the alternative measured in `MeasureChunk`'s comment.
+
+NaN keeps the existing rule: the walks already skip a non-finite sample, and the filter state is
+left alone, so a hole stays a hole and the filter resumes on real samples.
+
+### Two documented deviations
+
+1. `docs/claude/invariants-readouts-and-cursors.md` holds that a readout quotes a stored sample
+   and never a value between two. A filtered `max` is a value that was never stored, and with
+   `show_on_plot` its ruler sits at a level the drawn — raw — trace never reaches. This is
+   inherent to filtering, so it becomes a stated exception in that invariant rather than a silent
+   violation.
+2. The documented exact baselines (`peak to peak = 2`, `top = 0.636620`) hold with the filter
+   off. With it on they move, correctly; the probe reads both.
+
+### Persistence
+
+Free. A measurement is written as keyed TOML (`layout_store.cpp:659-672`) and read key by key
+(`:544-556`), so two new keys load in an old session at their defaults.
+
+## 3. The `de-noise` math node
+
+### The op, appended
+
+`MathOp::DeNoise` goes last in the enum (`math_channel.hpp:15-28`) and at index 12 in
+`math_op_at()` (`math_channel.cpp:99-114`), with `Div` given an explicit `case 11` so the current
+`default` no longer swallows it; `math_op_count()` becomes 13 and `math_op_name()` gains
+`"de-noise"`.
+
+Indices 0–11 keeping their meaning is exactly what leaves every existing session file reading
+correctly, because a node persists as its index through that accessor. The price is that
+de-noise sits last in the dialog's dropdown rather than beside the filters, which is the right
+side of that trade.
+
+### Parameters
+
+`MathNode` (`math_channel.hpp:48-72`) gains `int med_n = 5;` — odd, 3 to 9, rounded to odd and
+clamped. `fc` is reused for the HF reject; `q` is unused. `fc = 0` means median only, and it
+expresses "off" without a branch: the pole's coefficient `a = 1 − exp(−2π·fc·dt)` is exactly 1 at
+`fc = 0`.
+
+The coefficient is built in `math_prepare()` (`math_channel.cpp:140-165`) where `dt` is known and
+rebuilt on a `dt` change, exactly as the biquads are, with the same sub-Nyquist clamp
+(`:28`).
+
+### Predicates
+
+`math_op_uses_filter()` (`math_channel.cpp:135`) keeps meaning **biquad** — it gates coefficient
+construction at `:162`, and a de-noise node must not be given biquad coefficients. The dialog
+gets a new `math_op_uses_fc()` (filter ‖ de-noise) and a `math_op_uses_median()` for the new spin
+row. `math_dialog_sync_form()` (`ui_math.cpp:889-981`) already shows and hides one widget set per
+op, and `q`'s row being visible for `BandPass` alone is the precedent for a per-op subset of the
+filter row.
+
+### Node text
+
+`math_node_text()` (`layout_store.cpp:358`) emits a 13th pipe field. `math_node_from_text()`
+accepts **12 or 13** fields, defaulting `med_n` when it reads 12, so existing sessions load
+unchanged. A file written by this build and read by an older one is rejected by that build's
+`f.size() != 12u` check (`:385`); there is no forward-compatibility requirement here, but it is
+recorded rather than left as a surprise.
+
+### Runtime state, pooled
+
+`MathRuntime` (`math_channel.hpp:115-120`) gains one `std::vector<double>` holding the median
+rings of whichever nodes need them; `MathNodeRt` gains an offset into it, a ring position and the
+effective N. Not a fixed array member, for the reason in the decisions table. One indirection on
+a path already doing N compares is free, and the choice is reversible if measurement disagrees.
+
+### Evaluation
+
+In `math_step()` (`math_channel.cpp:167-230`), the new case is: push the input into the ring,
+take the median, then one pole step. **Median first** — de-spiking before smoothing is the whole
+point, and the reverse lets one spike contaminate the filter state for its entire settling time.
+
+The median is an insertion sort of at most nine doubles in a local array: ~20 compares worst
+case, ~4 at N=3, against a documented 80–100 ns per slot for a whole three-graph runtime. That
+ratio is measured and reported through the existing math-cost line, not assumed.
+
+**Warm-up:** before the ring holds `med_n` samples the node outputs the median of what it holds,
+which is a correct median of a shorter window. Deliberately not NaN — in this application a NaN
+output *means a hole in the data* (`math_channel.cpp:64-70`), and spending that meaning on a
+start-up transient would make a gap ambiguous.
+
+**NaN** matches `biquad_step` exactly: a non-finite input returns NaN and leaves both the median
+ring and the pole state alone, so the hole stays visible and the node resumes on real samples.
+
+## 4. Verification
+
+There is no unit test suite; the check is the application's own headless self-check under
+`xvfb-run` against `tools/mock_udpstreamer.py`, read against two baselines (an exact warning
+count, and no `Gtk-CRITICAL`).
+
+### The regression assertion, first
+
+Every default is today's behaviour, so the documented reading set must be **unchanged**:
+
+- `[condition-probe]`'s four exact latch times (`t0=1.710000`, `2.160100`, `1.706700`,
+  `4.120200`);
+- `peak to peak=2`, `amplitude=1`, `average=0`, `top=0.636620`;
+- `measure cost:` with `raw ≪ covered`;
+- the build's warning count — adding a field to `MathNode` leaves
+  `ui_probe.cpp:304` and `:313` at one `-Wmissing-field-initializers` each, so four on a clean
+  build and two on an incremental one still holds.
+
+### The mock needs an impulsive source
+
+`tools/mock_udpstreamer.py` offers `--noise` (Gaussian), `--glitch-at`/`--glitch-width` (a single
+glitch at one time) and `--clock-jitter`. None of them is a *stream* of EM-like peaks, and a
+median is the wrong tool for Gaussian noise, so none of the three pieces could be shown to work
+against the mock as it stands.
+
+Add `--spike-every S --spike-amp A --spike-width N`: a recurring impulse of N samples at
+amplitude A, every S seconds. One flag set, and it is what every reading below is measured on.
+
+### The four readings
+
+1. **Trigger band** — a new `[condition-probe]` leg on a slow sine plus spikes. With
+   `noise_band = 0` the latch lands on a spike; with the band above the spike amplitude it lands
+   on the sine's own crossing time. The latched `t0` is the assertion, and the four existing
+   shapes are re-read unchanged in the same run.
+2. **Trigger HF reject** — the same leg with the band off and `hf_fc` set. The latch moves
+   *later* by roughly `1/(2π·fc)`, reported beside the prediction. A latch that does not move is
+   the filter not being in the comparator's path.
+3. **Measurements** — `Frequency` on the spiky mock read three ways: `noise_pct = 0` (counts
+   spikes, frequency far too high), `= 10` (the true frequency), and `hf_fc` set (the true
+   frequency *and* `raw ≈ covered`, which is the fast-path loss as a reading). Plus `peak to
+   peak` with the filter off and on, since that is the number the filter is supposed to move.
+4. **The de-noise node** — `math_probe` (`ui_probe.cpp:304`) gains a de-noise graph on the spiky
+   channel. Its output's peak-to-peak must fall to the clean waveform's while a `LowPass` at the
+   same `fc` does not: that contrast is the entire justification for the node existing. Plus the
+   per-slot cost through the existing math-cost line.
+
+## 5. Documentation
+
+| File | What it gains |
+| --- | --- |
+| `README.md` | A noise-rejection section covering the three places, and the filtered-readout deviation stated rather than quietly taken |
+| `docs/claude/invariants-readouts-and-cursors.md` | The stated exception: a filtered readout is not a stored sample, and its on-plot ruler can sit where the raw trace never goes |
+| `docs/claude/invariants-measurements.md` | A filter on a measurement disables both bucket fast paths, and `raw ≈ covered` is its signature |
+| `docs/claude/invariants-trigger-and-pinning.md` | The band, the `band == 0` verbatim path and why, and the latch delay a filter adds |
+| `docs/claude/invariants-math-channels.md` | Op indices are append-only because the session format stores them; the pooled median state |
+| `docs/claude/verification.md`, `docs/claude/probe-readings.md` | The four readings above and what a wrong value names |
+| `docs/claude/build-and-run.md` | The new mock flags |
+
+## 6. Out of scope
+
+- Persisting the trigger. The trigger has never been persisted; the band and the filter follow
+  that, rather than this change being the one that introduces trigger persistence.
+- Any averaging acquisition mode. Noise rejection here is per-measurement, per-trigger and
+  per-node; nothing changes what the ingest stores, so a raw trace stays raw and every reading
+  remains traceable to stored samples.
+- Noise rejection on the cursors or the search's own UI. The search inherits the trigger's
+  condition and so inherits both controls; nothing further is added.

docs/superpowers/specs/2026-10-14-sidebar-tabs-design.md

@@ -0,0 +1,199 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- SPDX-FileCopyrightText: 2026 Martino Ferrari -->
+
+# A tabbed side panel, and one channel list: design
+
+The side panel stacks five sections in one scrolling column — trigger, cursors, measurements,
+math, signals — each behind a `GtkRevealer` opened by its own toolbar toggle. With trigger,
+measurements, cursors and math all open the column is unusable: every section is short of room,
+and finding one means scrolling past three others.
+
+Two changes, aimed at that one problem:
+
+1. **The column becomes two tabs.** *Measure* holds the cursors readout and the measurements;
+   *Signals* holds the trigger and the channel list. One tab is on screen at a time, so no
+   section competes with four others for height.
+2. **The math list is folded into the signal list.** A math channel already *is* a channel in
+   the model, and the two lists were the same list drawn twice. One list, with a `MATH`
+   divider in it.
+
+A third change falls out of the first. A tab is one-of-N, so it can no longer carry an on/off:
+**no toggle hides a pane any more.** Trigger-off and cursors-off put their pane in a disabled
+state and leave it where it is.
+
+## The decisions taken, and what each one rules out
+
+| Decision | Alternative rejected |
+| --- | --- |
+| `AdwViewStack` + `AdwViewSwitcher` | `GtkStack` + `GtkStackSwitcher`: plain buttons beside an `AdwOverlaySplitView`, which is what the sidebar already is. `GtkNotebook`: draws its own tab strip, which costs width in a 320 px sidebar and reads as off-platform. libadwaita ≥ 1.8 is already a hard requirement (`CMakeLists.txt:22`), so the platform widget costs nothing new |
+| **A scroller per page**, inside the stack | One shared scroller around the stack: the two pages are different heights, so a tab switch would leave the scroll position somewhere the new page did not ask for |
+| The switcher sits **above** the scrolled area | Inside it: the one control that chooses what you are looking at must not be the first thing to scroll away |
+| **Two** tabs, exactly as grouped | A tab per section (five tabs): that is the stack again, laid sideways, and a 320 px sidebar has no room for five switcher pills. Measurements read what the cursors bracket, and the trigger picks a channel from the list beside it — the grouping follows the way the panes are used |
+| Nothing inside a tab collapses | Keeping a revealer per section inside the tab, or a `GtkPaned` between them: the first reintroduces exactly the state-management the tabs remove, two sections at a time instead of five; the second adds a divider position to persist per tab for a column that already scrolls |
+| Trigger-off and cursors-off **disable** their pane | Hiding it, which is today's behaviour: a pane you can see is a pane you can read, and the settings you are about to turn back on should not vanish while you look for them |
+| The `measurements` and `math` toolbar toggles are **deleted** | Keeping them as tab selectors: two buttons that select the same tab, whose pressed state duplicates the switcher's |
+| The switcher shows **titles only**, and the two icons the deleted toggles used are **removed** | Giving each page an `icon-name`: the measurements icon would carry over, but *Signals* has no glyph — reusing the trigger icon for a page that is mostly a channel list misnames it, and drawing a new one is new artwork under the icon authoring rules for a label two words long |
+| One row widget for both kinds of channel, differing **only in its menu** | Inline edit and delete buttons on math rows (today's math pane): math rows then carry visibly more controls than signal rows, and the list stops reading as one column |
+| A `+` on the `MATH` divider **only** | A `+` on the signals header too: a signal comes from CONFIG and cannot be added, so the button would have nothing to do |
+| The statistics accumulator keeps running on the **hidden** page | Gating `update_measures()` on the visible tab: the accumulator is history, so min/max/avg would gain a gap for exactly as long as you looked at the trigger |
+| The probe reads the **page name and sensitivity** | Dropping the two revealer readings: the defect they catch — a panel that is built but not on screen — still exists, it is just spelled differently |
+
+## 1. The container
+
+The sidebar child of `side_view` becomes a vertical `GtkBox`:
+
+```
+AdwOverlaySplitView.side_view
+  sidebar: GtkBox (vertical)
+    AdwViewSwitcher                      <- never scrolls
+    AdwViewStack
+      page "measure"  GtkScrolledWindow -> GtkBox: cursors, separator, measurements
+      page "signals"  GtkScrolledWindow -> GtkBox: trigger, separator, signal list
+```
+
+`side_scroll` moves inside the pages; `App::side_box` becomes the stack, and the five revealer
+fields in `ui_app.hpp` are removed with the code that sets them (`ui.cpp:4728-4767`).
+
+The switcher carries the two page titles and no icons. `udpscope-measure-symbolic` and
+`udpscope-math-symbolic` lose their last user with the toggles that used them, so both leave
+`src/icons/scalable/actions/` and `udpscope.gresource.xml`: the bundled set goes from six
+action icons to four, which `invariants-gtk-and-chrome.md` counts and must be corrected with
+the change.
+
+The pages are built by the functions that build them today — `build_trigger_panel()`,
+`build_cursors_panel()`, `build_measures_panel()`, `build_signal_panel()` — unchanged except
+that they are appended to a page's box instead of to a revealer.
+
+## 2. State instead of visibility
+
+| Control | Today | After |
+| --- | --- | --- |
+| `trigger_toggle` | trigger mode on/off **and** reveals the trigger pane (`ui_trigger.cpp:198`) | trigger mode on/off; the pane's body goes sensitive/insensitive |
+| `cursors_toggle` | cursors on/off **and** reveals the readout (`ui_cursors.cpp:124-126`) | cursors on/off; the readout goes insensitive and its values blank to `—` |
+| `cursors_reset` | hidden while cursors are off (`ui_cursors.cpp:122`) | insensitive while cursors are off |
+| `measures_toggle` | reveals the measurements (`ui.cpp:4541-4550`) | **deleted** |
+| `math_toggle` | reveals the math pane (`ui.cpp:4551-4558`) | **deleted** |
+| `sidebar_toggle`, `events_toggle`, `pause_button` | — | unchanged |
+
+The two deleted toggles leave `src/ui/header-bar.ui` with their handlers, so the bar is
+declared with five controls and no id resolves to a button nothing listens to.
+
+`update_side_visibility()` (`ui.cpp:2830-2850`) keeps its job — the whole sidebar is still the
+split view's to show, still gated on a CONFIG having named a signal — minus the line that showed
+`signal_toggle`, which no longer exists.
+
+Everything else those handlers do is untouched: `tc.armed`, the epoch rule and the
+`set_time_window()` call in `on_trigger_toggled()`, `sync_events_availability()`, the
+Arm/Disarm label, and `rows->set_cursors_visible()` with its `reset_cursors()`.
+
+Blanking the cursor readout to `—` rather than leaving the last values is the readout invariant
+restated: a readout quotes a stored sample, and with the instruments off there is no sample it
+quotes.
+
+## 3. One channel list
+
+**The duplication is literal, and the merge is mostly a deletion.**
+`rebuild_signal_list()` is handed `model.signals()`, and `append_math_signals_locked()`
+(`model.cpp:252-269`) has already appended one synthetic entry per math channel — *"they go
+through the ordinary signal path on purpose: a derived channel is a channel"*, says its own
+comment. Nothing in the list filters `sig.math`, so **every math channel is already a row in
+the signal list**, with its tick, chip, name, unit and menu. The math pane listed the same
+channels a second time.
+
+What the list gains:
+
+- a non-selectable `MATH` divider row before the first math row, carrying the `+` that opens
+  the node editor on a new channel;
+- two items in a math row's menu.
+
+| | signal row | math row |
+| --- | --- | --- |
+| tick | acquire (hidden in a file view) | enabled |
+| colour chip | clickable while plotted | unchanged |
+| unit | from CONFIG | the channel's own |
+| menu | Information, Default colour, Calibrate… | **Edit graph…**, Default colour, **Delete** |
+
+Information and Calibrate… are a *streamed* signal's — calibration is applied at ingest — so a
+math row carries neither. No rename item either: the node editor owns a math channel's name and
+unit (`src/ui/math-editor.ui:37-43`), so *Edit graph…* is where both are changed, and a second
+place to change them would be a second answer to the same question.
+
+Two things already work and must not be rebuilt: the tick is already the right switch —
+`enable_locked()` (`model.cpp:626-639`) mirrors it into the `MathChannel`'s own `enabled` flag —
+and the row's `GtkDragSource` already lets a math channel be dropped onto a plot row, which is
+how `math1` reached row 0 in the session this work started from.
+
+One defect to fix while merging: `App::math` is the copy the session file is written from, so a
+tick on a math row must mirror `enabled` into it before `schedule_layout_save()`. Today the pane's
+checkbox did that (`ui.cpp:2276`) and the list's tick did not, so the two controls disagreed
+about what gets saved.
+
+Deleted: `build_math_panel()` (`ui_math.cpp:1044`), `rebuild_math_pane()` (`ui.cpp:2251-2319`),
+`src/ui/math-panel.ui` and its entry in `src/ui/udpscope-ui.gresource.xml`, `App::math_revealer`,
+`App::math_list`, `App::math_toggle`, `App::measures_toggle`, `App::signal_revealer`, and
+`App::signal_toggle` with `on_signals_toggled()` (`ui_signals.cpp:303-307`) and its overflow-menu
+row (`ui.cpp:4452-4455`) — the list is a page now, so "show or hide the signal list" has nothing
+to hide. The node editor dialog itself is untouched; only the button that opens it moves.
+
+## 4. Persistence
+
+One key, top level in the session file beside `window_s` and `measure_stats`
+(`layout_store.cpp`):
+
+```toml
+side_tab = "signals"   # or "measure"
+```
+
+Written on save; applied once where the rest of the layout is applied, so an unknown or missing
+value leaves the stack on its first page. Nothing else about the panel is persisted today and
+nothing else needs to be: no revealer states remain, and the 320 px width is still the `.ui`'s.
+
+## 5. What runs on a hidden page
+
+`update_cursors_pane()` and `update_measures(force=false, accumulate=true)` are called every
+frame from the tick (`ui.cpp:3275-3276`) and keep being called whichever page is current.
+Writing a label on an unrealized widget is legal; **reading its allocation is not**. Every
+allocation read in the sidebar is a debug capture — `dbg_measures_pane_w/h`
+(`ui.cpp:3237-3239`), `dbg_signal_w/h` and `dbg_trigger_w/h` (`ui_probe.cpp:77-80`) — and each
+reads 0 on the page that is not current. That is a change in what the reading means, which §6
+handles; it is not a defect, and no functional code may start depending on those numbers.
+
+This is the revealer trap in a new widget. `invariants-gtk-and-chrome.md:174-181` records that
+an unrevealed `GtkRevealer` measures 0×0 and is still given the leftover width; a stack's
+hidden page measures 0×0 too, and the rule it teaches — ask about *state*, not about size —
+carries over unchanged.
+
+## 6. Verification
+
+Readings that change, and what each must say instead:
+
+| Reading | Was | Becomes |
+| --- | --- | --- |
+| `dbg_signal_revealed` (`ui_probe.cpp:90`) | the signal revealer's child is revealed | the `signals` page is current **and** its list is non-empty |
+| `dbg_trigger_revealed` (`ui_probe.cpp:92`, `:2190`) | the trigger revealer's child is revealed | the `signals` page is current **and** the trigger body is sensitive |
+| `dbg_measures_pane_w/h` | the pane's size while revealed | the pane's size while its page is current; 0 otherwise, and read as such |
+| the panel-toggle reading (`ui_probe.cpp:104`) | both menu toggles are visible | the switcher is visible, which is the one control those two became |
+
+One new probe, `UDPSCOPE_PROBE_SIDE_TAB_MS`: select the page that is not current, then dump the
+page name, the measurement row count and the accumulator's sample count. The count must have
+advanced across the switch — that is the §5 rule under test, and the defect it names is a
+statistics pane that silently restarts its history every time you look at the trigger.
+
+New reading for the merged list, on the existing signal-panel probe: the row count must be
+signals + 1 + math channels, and the math rows must carry the same widget shape as a signal
+row. A count short by the divider is a list that lost its `+`.
+
+Baselines, unchanged and re-read on every run: exactly four warnings on a clean build, no
+`Gtk-CRITICAL`, `test-ui` 15/15.
+
+Docs to update with the work: `probe-readings.md` (the three changed lines and the two new
+ones), `verification.md` (a bullet for the tab switch), `invariants-gtk-and-chrome.md` (the
+sidebar is a view stack, the hidden-page trap replaces the unrevealed-revealer one for it, the
+bar carries five controls and the bundled set four action icons),
+`invariants-math-channels.md` (the list lives in the signal panel), `invariants-readouts-and-cursors.md`
+(the readout blanks when the instruments are off), and a README note recording the deviation
+from `SPECS.md` where it names the panes.
+
+## Out of scope
+
+The events pane left of the plot, export, the node editor's internals, and the status bar.

docs/superpowers/specs/2026-10-31-e1608-source-design.md

@@ -0,0 +1,153 @@
+# MCC E-1608 source plugin (sub-project 3 of 4)
+
+Date: 2026-10-31
+Branch: `feature/source-e1608` (from `feature/source-plugins`, sub-project 1)
+
+## Context
+
+Sub-project 1 added the `DataSource` / `SourceKind` / `SourceRegistry` framework and ported
+UDPS onto it. This sub-project adds a second kind, `e1608`: the Measurement Computing E-1608
+Ethernet DAQ (8 SE / 4 DIFF 16-bit analog inputs, 2 analog outputs, 8 DIO bits, one 32-bit
+counter), with its own connect form and two side-stack panels.
+
+References for the wire protocol, both written by the user:
+
+- Primary: `~/Projects/marte2_projects/MCC_E1608_DataSource`, a MARTe2 DataSource
+  (`E1608DataSource.{h,cpp}`, `E1608ScanFifo`). Its class comment in the header is the
+  authoritative list of parameters and behaviour. It is bound to MARTe2 (`BasicTCPSocket`,
+  `StreamString`, `SingleThreadService`), so it is **ported** to plain C++, not linked.
+- Cross-check: `~/Projects/uopi/internal/datasource/mcc/{protocol,e1608}.go`, an independent
+  Go implementation of the same protocol.
+
+No board is available. The mock is the only verification until one is attached.
+
+## Decisions
+
+| Question | Decision |
+| --- | --- |
+| DAC / generator | Static level plus a software waveform (sine, square, triangle, ramp), 10 Hz at most. Runs as a timer inside `poll()`; no extra thread. |
+| Hardware | None available. A protocol mock (`tools/mock_e1608.py`) is the contract. Commands whose layout rests on a single reference (or where the two disagree) are listed as unverified. |
+| Analog input config | Full: per-channel enable and range, global SE/DIFF, MAC discovery, external clock, trigger, DI/counter poll rate. |
+| Digital lines and counter | Plot channels the user chooses, off by default, enabled per line in the connect form. |
+| Acquisition modes | Hardware-paced only (scan rate or external clock). Software-paced mode (`ScanRate = 0`) is not ported. |
+| Structure | Three layers: link, device, source. The bottom two have no GTK or `DataSource` types. |
+
+## Design
+
+### 1. Files (new, `src/source/e1608/`, plus the mock)
+
+- `e1608_link.{hpp,cpp}`: UDP discovery (broadcast, or a unicast sweep of a given subnet
+  matched by MAC and the E-1608 product id) and connection-code handshake; TCP command
+  framing with a timeout; the scan socket on `port + 1`. Plain POSIX sockets.
+- `e1608_device.{hpp,cpp}`: typed commands (AI, AO, DIO read/write/direction, counter
+  read/reset, scan queue, scan start/stop, status), the factory calibration read from the board's
+  calibration memory, and `decode()`, which turns raw interleaved `uint16` scans into calibrated
+  volts (`double`).
+- `e1608_source.{hpp,cpp}`: the `DataSource`: the `poll()` state machine, `Frame` building, the
+  DI/counter and generator timers, the atomic readouts for the panels.
+- `e1608_kind.cpp`: the `SourceKind`: the connect form and the two panels.
+- `tools/mock_e1608.py`: the protocol mock.
+- `register_builtin_sources()` registers `e1608` after `udps`.
+
+### 2. Data path and threading
+
+Everything runs inside `poll()` on the producer thread. The GTK thread reaches the board only
+through `post(Command)`.
+
+`poll(timeout)`:
+
+1. Drains the posted commands (DAC writes, DIO toggles, counter reset, generator edits).
+2. Runs the connection state machine: optional MAC lookup, handshake, calibration read, DIO
+   direction and initial outputs, scan queue and scan start take Disconnected to Scanning. A
+   link error fires `on_event(Disconnected)` and retries every 2 s. A connect attempt can block
+   `poll()` for up to the command timeout; that delays only the command queue.
+3. Waits on the scan socket for at most the time to the next timer, reads what arrived, keeps a
+   partial scan for the next call, decodes the complete scans with the calibration and
+   delivers a `Frame`.
+4. Runs the due timers: the DI/counter poll (`DiPollRate`) is a command round trip; the
+   generator tick (at most 10 Hz) is a DAC write.
+
+The frame:
+
+- Signals: the enabled AI channels (unit `V`, `range_min`/`range_max` from the channel's range),
+  the DI lines the user chose (0/1), and the counter if chosen.
+- All signals are scalar; `num_samples` is the number of scans decoded in that read.
+- DI and counter values are held across the block (a step trace).
+- `sampling_rate` is the scan rate on every signal. `counter` is a running frame count.
+- The aggregate rate (enabled channels times scan rate) must stay at or below 250 kS/s. The
+  form refuses a configuration above it.
+
+Overrun: if the board reports a scan overrun the source fires `on_event(Error)` and restarts
+the scan when `AutoRestart` is set; the next frame carries `lost = 1`. This is approximate,
+because the board does not report how many scans it dropped.
+
+Panel readouts: the source keeps the live DIO inputs, the counter, the DAC levels and the
+generator state in atomics. The panels read them from a GTK timer, so no widget touches the
+source's internals.
+
+### 3. Connect form and panels
+
+Connect form: grouped `AdwExpanderRow`s in the chooser's group. `SourceConfig` stays flat; a
+per-channel setting is a key such as `ai0=BIP10V` (absent means off).
+
+- Connection: address, MAC, discovery subnet, port, connection code, timeout. `valid()` needs
+  an address, or a MAC plus a subnet.
+- Acquisition: scan rate, external clock, trigger mode, auto-restart, calibrate (default on),
+  DI/counter poll rate.
+- Analog inputs: global SE or DIFF mode and 8 channel rows (enable, range). In DIFF mode rows
+  4 to 7 are insensitive, not hidden. `valid()` also enforces the 250 kS/s aggregate.
+- Digital I/O: direction per bit (I or O), a "plot" switch per input bit, a "plot counter"
+  switch, the initial DO value and the initial DAC levels.
+
+`identity()` is the address, or the MAC when there is no address. A session file is named
+`e1608-<identity>`, port 1, as sub-project 1 defines for non-UDPS kinds. `has_datagrams()` is
+false, so the capture button is disabled.
+
+Two side-stack panels, both insensitive while disconnected (disabled, not hidden):
+
+- Analog out: per DAC, a mode (Level, Sine, Square, Triangle, Ramp), a level or amplitude plus
+  offset, a frequency of 0.1 to 10 Hz, and an on/off switch. It shows the last voltage written
+  and clamps to ±10 V. The generator stops on disconnect and the DACs return to their initial
+  levels on reconnect.
+- Digital I/O: eight bit rows; an input bit shows a live LED, an output bit has a toggle that
+  posts a write. The counter shows its value and a Reset button. Directions come from the form
+  and are not changed at runtime.
+
+Tab icons are chosen in the plan under the project's bundled-icon rules.
+
+### 4. Verification
+
+Mock (`tools/mock_e1608.py`): UDP discovery with a MAC and the connection-code handshake; TCP
+commands for AI, AO, DIO, the counter, scan queue, scan start/stop, calibration memory and
+status; a scan stream on port+1 at the requested rate with a sine per channel; switches to drop
+the link after N seconds and to report an overrun. Its header lists every command whose layout
+is unverified (single reference, or the references disagree).
+
+Probe `UDPSCOPE_PROBE_E1608=<delay ms>`, run against the mock with `--source e1608`, extends the
+probe/dump in `src/ui.cpp`. It checks:
+
+- Frames arrive with the expected channel count and sample rate.
+- The panels are present and insensitive while disconnected.
+- A DAC write, a DIO toggle and a counter reset each reach the mock.
+- A forced link drop leads to a reconnect and a resumed stream.
+- The calibration is applied (the mock serves non-trivial coefficients).
+
+A decode check needs no mock: a fixed raw buffer decoded against hand-computed volts.
+
+Baselines are unchanged: the UDPS self-check reads as on `main`, exactly three build warnings,
+no `Gtk-CRITICAL`.
+
+Errors: a rejected handshake (bad connection code), no device found, timeouts and scan-socket
+loss surface through `on_event(Error)` with a readable message and follow the reconnect cycle.
+A rejected connection code stops the retries: the source stays in Error with that message until the user reconnects.
+
+Docs: update `architecture.md`, `build-and-run.md`, `verification.md`, `probe-readings.md` and
+`README.md`.
+
+## Out of scope
+
+- Software-paced acquisition (`ScanRate = 0`).
+- A generator faster than 10 Hz, and a dedicated I/O thread.
+- Changing DIO directions at runtime.
+- Per-channel SE/DIFF mixing (one global mode).
+- Verification against a real board.

docs/superpowers/specs/2026-10-31-source-plugins-design.md

@@ -0,0 +1,127 @@
+# Source plugins: framework and UDPS port (sub-project 1 of 4)
+
+Date: 2026-10-31
+Branch: `feature/source-plugins`
+
+## Context
+
+udpscope reads exactly one kind of source, a UDPStreamer stream through `deps/udpsclient`.
+The goal is to accept several kinds of data source as plugins, each with its own config
+dialog and, where the hardware offers it, its own UI (signal generator, digital I/O,
+multiple timebases).
+
+The work is split into four sub-projects, each with its own spec, plan and implementation:
+
+1. **Plugin framework + UDPS client ported onto it** (this document).
+2. Flat UDP plugin (standard MARTe2 UDPWriter stream; the wire format must be supplied or
+   located before that spec is written -- none was found in `~/workspace` or `~/Projects`).
+3. MCC E-1608 plugin. The protocol code in `MCC_E1608_DataSource` is bound to MARTe2
+   (`BasicTCPSocket`, `StreamString`, `SingleThreadService`); it is ported to plain C++, not
+   linked against MARTe2. AI streaming, DIO and DAC/generator panels.
+4. ABScope plugin. Needs a multi-timebase data path and a wire format: the ABScope design
+   only sketches the UDP header and `streamerd` is unwritten.
+
+Sub-project 1 changes no UDPS behaviour. It is a refactor plus the hosting machinery the
+later plugins need.
+
+## Decisions
+
+| Question | Decision |
+| --- | --- |
+| What "plugin" means | Compiled-in registry; the interface is kept clean enough for a `dlopen` loader to be added later (not built now). |
+| Threading | `Acquisition` keeps the single producer thread and calls `source->poll()`. UI actions reach the source through a thread-safe command queue drained inside `poll()`. CLAUDE.md's two-thread rule holds. (A per-source I/O thread was considered and deferred.) |
+| Source UI | Widget factory: a source returns `GtkWidget*` for its config form and each capability panel. |
+| Timebases in the frame | The neutral frame is single-timebase. Sub-project 4 extends interface and data path together; this may break the interface once, accepted. |
+| CLI / sessions | `--server/--port/...` keep meaning UDPS; `--source NAME` and `--source-opt k=v` added. Sessions keyed by kind + identity; legacy `host_port.toml` read as `udps`. |
+
+## Design
+
+### 1. The source interface (new `src/source/`)
+
+- **`SourceConfig`**: ordered string key/value map with typed getters. It is the stored form
+  (a TOML table), the `--source-opt` form, and what a config widget reads and writes.
+- **`Frame`**: source-neutral, mirrors `udps_frame_t`: `counter`, `lost`, `late`,
+  `recv_time`, `publish_mode`, `num_samples`, `signals[]` (the existing `SignalInfo`) and
+  `values[]` (doubles). `signals` and `values` are pointers into the source's own buffers,
+  valid only for the duration of `on_data`; `Acquisition` copies what it keeps. The hole, backfill and time-base logic needs `counter/lost/late`; a
+  source with no counter supplies a running counter and `lost = 0`. `Frame::value(sig, k,
+  col)` replaces `udps_frame_value`.
+- **`DataSource`**: the per-connection object.
+  - `open()`, `poll(timeout_ms)`, `close()`.
+  - `stats()` returns the counters now in `StreamStats`; `connected()` reports link state.
+  - `post(Command)`: thread-safe queue, drained inside `poll()`. `Command` is
+    `std::function<void()>`.
+  - `set_datagram_tap(fn)`: optional; lets UDP-based sources feed the raw-packet capture.
+  - Output goes to a `SourceSink` (`on_config`, `on_data`, `on_event`) called inside
+    `poll()`, as `udps_client` does today.
+- **`SourceKind`**: factory and UI description of one plugin type: `id`, `display_name`,
+  `identity(cfg)`, `make(cfg)`, `make_config_form()` and `make_panels(source)` (each
+  `{id, title, GtkWidget*}`). `make_config_form()` takes no argument: the chooser calls
+  `form.write(cfg)` to fill the form. A `ConfigForm` is a list of `AdwPreferencesRow` widgets
+  plus `write` / `read` / `valid` / `on_change` closures, so the chooser can place the rows in
+  its own group and gate its Connect button on `valid()`.
+- **`SourceRegistry`**: filled by an explicit `register_builtin_sources()` call. No
+  static-init self-registration (linkers can drop it). A future `dlopen` loader would only
+  call `register_kind()`.
+
+### 2. Acquisition and the UDPS plugin
+
+- `Acquisition` takes a `std::unique_ptr<DataSource>` instead of building a `udps_client_t`
+  and implements `SourceSink`; it creates the source lazily in `start()`, from the kind and
+  `SourceConfig` it was given; the four trampolines go away.
+- `on_config` / `on_data` change only in the type they read. Time base, holes, backfill,
+  decimation, trigger and math code are untouched.
+- `run()` calls `source_->poll(50)` and copies `source_->stats()` into
+  `ScopeModel::stats()`. `PacketCapture` stays in `Acquisition`, fed through the datagram
+  tap. Sources without datagrams (E-1608) leave the capture UI disabled, not hidden.
+- `src/source/udps_source.cpp` wraps `deps/udpsclient` unchanged: it maps `udps_signal_t`
+  to `SignalInfo` and `udps_frame_t` to `Frame`, and carries the existing knobs (server,
+  port, multicast, interface, recv buffer). Identity is `host:port`.
+- The `udps_*` types are used only in `acquisition.cpp` today, so no other file changes for
+  this step beyond the `Frame` type.
+
+### 3. UI hosting, config and persistence
+
+- **Connect dialog** (`source_dialog.cpp`): gains a "Source type" dropdown; choosing a kind
+  swaps in that kind's `make_config_form()`. The UDPS form (server, port, multicast,
+  interface) moves into the UDPS plugin. The dialog keeps the known-sources list, buffer
+  size, relative time and capture ring size.
+- **Capability panels**: after the source is created the app calls `make_panels()` and adds
+  each panel as a page of the existing `side_stack` (the side area's page stack, owned by
+  the tab switcher). A panel is insensitive when
+  disconnected (disabled, not hidden; the tab switcher owns visibility). A source with no
+  panels adds no tab; UDPS has none. Panels call `source->post(Command)`, never the source
+  directly, so cross-thread safety lives in one place. A helper kit for common panels (DIO
+  bank, generator form) lives in `src/source/widgets/` but is only added when a plugin uses
+  it, so it arrives with sub-project 3.
+- **Config / CLI**: `Config` gains `source_kind` (default `udps`) and a `SourceConfig`.
+  `--server/--port/--multicast/--interface` populate the UDPS entries. `--source NAME` and
+  repeatable `--source-opt k=v` work for any kind. `--help` lists the registered kinds.
+- **Sessions**: the source's config is stored as top-level TOML keys, `source_kind` and
+  `source_opt_<key>`, written only for non-UDPS kinds (a UDPS session file is unchanged, so
+  legacy `host_port.toml` files read as `udps` with nothing migrated). It is not a `[source]`
+  table. A non-UDPS session file is named by a pseudo-host `<kind>-<identity>` with port 1.
+- **Mocks**: `tools/mock_udpstreamer.py` remains the UDPS mock. Each later plugin ships its
+  own mock under `tools/` so the headless self-check keeps working.
+
+## Verification
+
+- This is a pure refactor for UDPS: the existing headless self-check must read exactly as on
+  `main` -- exactly three build warnings, no `Gtk-CRITICAL` (see `docs/claude/verification.md`).
+- New probe `UDPSCOPE_PROBE_SOURCE_KINDS` (`UDPSCOPE_PROBE_SOURCES` is already the chooser
+  discovery probe). Its value is a delay in ms, and its presence also registers the stub
+  `probe` kind. It extends the probe/dump in `src/ui.cpp` rather than
+  adding a harness. It checks that the registry lists its kinds, that a config form
+  round-trips its `SourceConfig`, and -- with a stub test-only kind carrying one panel --
+  that the panel's tab is built, insensitive while disconnected, and that a posted command is
+  drained by `poll()`.
+- Document the new probe lines in `docs/claude/probe-readings.md`; update `architecture.md`
+  (a `DataSource` replaces the client in the thread description), `build-and-run.md`
+  (new CLI options) and `README.md`.
+
+## Out of scope
+
+- Runtime `.so` loading, and a per-source I/O thread.
+- Multi-timebase data path (sub-project 4).
+- The flat UDP, E-1608 and ABScope plugins (sub-projects 2-4).
+- The DIO / generator helper widgets (arrive with sub-project 3).

docs/superpowers/specs/2026-11-02-e1608-network-scan-design.md

@@ -0,0 +1,63 @@
+# E-1608 network scan -- design
+
+Date: 2026-11-02. Status: approved in conversation, awaiting written-spec review.
+
+## Goal
+
+The E-1608 connection form gets a "Scan network" row that finds boards and fills the address or the
+MAC from a click. Today a user must already know the address, or give a MAC and rely on a lookup.
+
+## Finding (tested on a real board, 2026-11-02)
+
+The board was at 169.254.88.75 on `net0`; the default route is `wlan0`. A `D` probe sent to
+255.255.255.255 with no binding found nothing (it left through `wlan0`). The same probe sent with
+`SO_BINDTODEVICE net0`, or bound to the interface address, or sent to a directed broadcast, or by
+unicast, was answered (64 bytes, first byte `D`). So a single limited broadcast is not enough on a
+host with several interfaces; the existing "find by MAC" lookup has the same flaw.
+
+## Discovery layer (`e1608_link.{hpp,cpp}`)
+
+- `class Scan` (non-blocking, one instance per scan): `Scan(port)` enumerates up, non-loopback IPv4
+  interfaces with `IFF_BROADCAST` (`getifaddrs`), opens one UDP socket per interface bound to it
+  (`SO_BINDTODEVICE`, falling back to binding the interface address if the call is refused), enables
+  `SO_BROADCAST`, and sends `D` to 255.255.255.255 on each. `poll()` drains every socket without
+  blocking and returns the devices found so far (E-1608 product id only, one entry per MAC, the same
+  reply parsing as `discover`). The caller owns the clock.
+- `discover()` keeps its signature. A new overload or helper `discover_broadcast(port, wait_ms)` is
+  `Scan` plus a blocking wait. `E1608Source`'s lookup uses it when the subnet is empty; a given
+  subnet still uses `sweep_targets` + `discover` as today.
+- An interface that cannot be opened or sent on is skipped, never an error; no interfaces is an empty
+  result.
+
+## Form (`e1608_kind.cpp`)
+
+- At the top of the Connection expander, an `AdwActionRow` "Scan network" with a text suffix button
+  "Scan" (widget name `e1608-scan`). The row subtitle reads "Scanning...", "N boards found" or
+  "No board found". No theme icons.
+- A scan starts a `Scan` on the port in the Port field and a 50 ms `g_timeout_add` poll for about
+  1.5 s. There is no thread: the project has exactly two. The timer is removed when the form is
+  destroyed (`Form::alive` guard plus the destroy hook) and when a new scan starts.
+- Each device found becomes an `AdwActionRow` in the Connection expander right after the scan row,
+  replacing the previous results. Title: IP. Subtitle: MAC. Activating the row fills Address and
+  clears MAC and Subnet. A suffix text button "Use MAC" (`e1608-use-mac`) fills MAC and clears
+  Address and Subnet. Fill is done under the form's `updating` guard, then `changed` fires once.
+- Result rows are not read or written by the session: only the filled fields persist.
+- The description line mentions the scan.
+
+## Verification
+
+- A scan probe (env var in the existing pattern): starts against `tools/mock_e1608.py` on a
+  loopback-reachable port, presses the scan button, and prints `[e1608] scan: found=N ip=... mac=...
+  fill_addr=1 fill_mac=1 ok=1`, covering both fills and that the results are replaced on a rescan.
+  If the sandbox refuses the broadcast, the line says so and the limitation is documented, not claimed.
+- A manual run of the scan against the real board, recorded in the README.
+- Baselines unchanged: 3 warnings clean, `gtk warnings: 0`, no `Gtk-CRITICAL`.
+
+## Docs
+
+`README.md` (E-1608 paragraph), `docs/claude/{build-and-run,verification,probe-readings,architecture}.md`.
+
+## Out of scope
+
+Remembering scan results across runs; scanning other subnets than the host's interfaces (the
+`subnet` sweep field remains for that); a worker thread.

docs/superpowers/specs/2026-11-02-flat-udp-source-design.md

@@ -0,0 +1,147 @@
+# Flat UDP source plugin (sub-project 2 of 4)
+
+Date: 2026-11-02
+Branch: to be cut from `feature/source-plugins`
+
+## Context
+
+Sub-project 1 added the `DataSource` / `SourceKind` / `SourceRegistry` framework. Sub-project 3
+added the E-1608. This sub-project adds `flatudp`: a receiver for the MARTe2 `UDPSender`
+datasource (`MARTe2-components/Source/Components/DataSources/UDP/UDPSender.{h,cpp}`).
+
+## The wire format
+
+Read from `UDPSender::Synchronise()` and `MemoryDataSourceI`:
+
+- One `Write` of the datasource memory per `Synchronise()`: **one datagram is one cycle**.
+- The memory is the signals concatenated in declaration order, **no padding**, in the sender's
+  native byte order. `signalOffsets[s]` is the running sum of `size * elements`.
+- There is no header, counter, timestamp or signal description. In IndependentThread mode the
+  first signal is a `uint8` `Trigger`; it is sent like any other signal.
+- The user must therefore enter the exact signal list by hand.
+
+## Decisions
+
+| Question | Decision |
+| --- | --- |
+| Time base | The user declares the nominal cycle rate in Hz (`rate`, required). The existing pipeline stamps the frames: anchored at arrival, samples spaced by the declared cadence, corrected to the measured cadence when the arrivals are more than 25% off it; `--relative-time` gives a purely counted clock. There is no `time_mode` switch: `acquisition.cpp` has no stamping path that ignores the declared cadence, and `sampling_rate = 0` would size the ring and the ingest decimation for 1 kHz (`model.cpp:60`). Loss is never reported (`lost = 0`). |
+| Signal list entry | A row editor: name entry, type dropdown, element count and a remove button per row, plus an "Add signal" row. |
+| Network | Port and optional bind address, plus an optional multicast group and interface. No source-address filter. |
+| Byte order | `little` (default) or `big`. |
+| Out of scope | Auto-detecting the list, importing a MARTe2 `.cfg`, a source filter, loss detection. |
+
+## Config keys
+
+Persisted in the session, settable with `--source-opt`. Kind id: `flatudp`.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `port` | 44488 | UDP port to listen on (the sender's own default). |
+| `bind` | empty | Local address to bind; empty is any. |
+| `multicast` | empty | Group to join; empty is plain unicast. |
+| `iface` | empty | Local interface address for the join. |
+| `rate` | none | Nominal cycle rate in Hz. Required; sizes the ring and the decimation and spaces samples within a frame. |
+| `endian` | `little` | `little` or `big`. |
+| `signals` | none | `name:type[count],...`, e.g. `Trigger:uint8,Ia:float32,Wave:float32[16]`. A persistence format only: the form builds and parses it. |
+
+Types: `uint8/16/32/64`, `int8/16/32/64`, `float32`, `float64`. Count 1 is a scalar signal; N
+is a vector signal. Expected datagram size is the sum of `size * count` over the rows.
+
+Validity (form and `--source-opt` alike): at least one signal; names non-empty and unique;
+count 1-4096; total size at most 65507 bytes; `rate` finite and positive.
+
+## Architecture
+
+New files under `src/source/flatudp/`:
+
+- `flatudp_signals.{hpp,cpp}` -- the `signals` string codec: parse, format, validate, size
+  arithmetic. No GTK, so a probe can round-trip it.
+- `flatudp_source.{hpp,cpp}` -- the `DataSource`.
+- `flatudp_kind.{hpp,cpp}` -- the `SourceKind`, the form, and the registration in
+  `register_builtin_sources()`.
+
+Threading is unchanged: the source lives on the producer thread and `poll()` does all the work.
+
+### Data flow
+
+`poll(timeout_ms)` waits on a non-blocking UDP socket and drains it.
+
+- A datagram of exactly the expected size is decoded row by row to doubles (byte-swapped when
+  `endian=big`).
+- **Batching.** When every row is scalar, decoded datagrams are queued and delivered
+  `block` at a time in one `Frame` (`num_samples = block`), where
+  `block = clamp(round(rate / 100), 1, 1024)`, about 100 frames per second as the E-1608 does. A
+  partial block is flushed after 100 ms so a slow or stopped sender does not hold samples back.
+  When any row is a vector, a vector signal carries one sample per `Frame`, so each datagram is
+  its own frame (`num_samples = 1`).
+- `Frame`: `counter` a running frame count, `lost = 0`, `late = false`, `recv_time` the arrival
+  clock at delivery.
+- `set_datagram_tap` is honoured for every datagram, valid or not, and `has_datagrams()` is
+  true, so packet capture works.
+- `on_config` is called from the first `poll()` with one `SignalInfo` per row (`rows = count`,
+  `cols = 1`, `time_mode = kTimePacket`, `sampling_rate = rate`).
+
+### Errors and state
+
+- A wrong-size datagram is dropped, never decoded. Each distinct size raises one `Error`
+  event ("datagram of N bytes, expected M, check the signal list") and increments `stale`.
+- `Connected` is raised on the first valid datagram and `Disconnected` after 2 s of silence; a
+  later datagram raises `Connected` again.
+- A bind or multicast-join failure raises an `Error` and the source stays disconnected.
+
+### Connect form
+
+Built from `AdwPreferencesRow`s, with the destroy-notify guard used by the E-1608 form.
+
+- Network group: port, bind, multicast, interface.
+- Timing: a rate spin.
+- Byte order combo.
+- Signals group: one row per signal, "Add signal" at the bottom, and a live subtitle with the
+  implied size ("41 bytes per datagram"). `valid()` is false while the list breaks a validity
+  rule.
+- The `signals` string is rebuilt from the rows on every change; `write()` parses it back.
+
+## Verification
+
+No unit suite; the self-check is the contract.
+
+- `tools/mock_flatudp.py`: emits packed structs for a given signal spec and rate; options for
+  big-endian and for one wrong-size datagram.
+- `UDPSCOPE_PROBE_FLATUDP` in `src/ui_probe.cpp`: stream names and count; a hand-computed
+  decode of known values including a vector signal and a `uint64`; the declared rate reaching the model; the
+  wrong-size error reported once and counted in `stale`; disconnect after silence; the form's
+  validity rules; the `signals` codec round trip. A multicast loopback check runs if the
+  sandbox allows it.
+- Baselines unchanged: exactly 3 build warnings, `gtk warnings: 0`, no `Gtk-CRITICAL`.
+
+## Documentation
+
+README (the kind and its limits: no loss detection, the signal list is the user's
+responsibility), `docs/claude/build-and-run.md` (options and mock usage),
+`docs/claude/architecture.md` (source plugins), `docs/claude/probe-readings.md` and
+`docs/claude/verification.md` (the new probe lines).
+
+## Amendment 2026-11-02: how a vector signal is shown (decided with the user during Task 2)
+
+Task 2 found that treating every vector row as one channel of `count` consecutive samples zero-pads
+the scalar channels of a mixed list (the model spans a frame by its largest element block, and
+`Frame::value` is 0 past a scalar's one value) and declares the wrong rate for the vector channel.
+Both readings of a vector are useful depending on the sender, so each vector row picks one:
+
+- **`channels` (default).** `Wave:float32[16]` becomes 16 scalar channels named `Wave[0]` .. `Wave[15]`,
+  one sample per cycle each. All such lists are batched like an all-scalar list.
+- **`waveform`.** `Wave:float32[16]w` is ONE channel receiving a block of `count` consecutive samples per
+  cycle: `SignalInfo{rows=count, cols=1, sampling_rate=rate*count}`, one datagram per `Frame`
+  (`num_samples = 1`).
+
+Rules:
+- The `signals` string takes an optional trailing `w` after the count; `format` emits it only for a waveform row.
+- A waveform row needs `count > 1`.
+- A list with a waveform row must contain only waveform rows, all with the same `count`; otherwise it is
+  invalid, with a message the form shows. (No zero-padding, no holding scalars across a block.)
+- The channel total is capped at 256: scalars count 1, a `channels` row counts `count`, a waveform row counts 1.
+  Over the cap is invalid.
+- `block` batching applies whenever the list has no waveform row; with a waveform row it is 1.
+- The form shows a "Vector as" dropdown (`Channels` / `Waveform`) on rows whose count is above 1, and
+  the channel total in the subtitle.
+- The earlier "Data flow" text saying every vector row forces `num_samples = 1` applies to waveform rows only.

help/C/org.udpscope.app/cursors.page

@@ -0,0 +1,87 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="task"
+      id="cursors">
+
+  <info>
+    <link type="guide" xref="index#analysis"/>
+    <link type="seealso" xref="measurements"/>
+    <desc>The shared vertical cursor pair and the per-row horizontal rulers, their four modes,
+    and how a reading is formatted.</desc>
+    <credit type="author copyright">
+      <name>Martino Ferrari</name>
+    </credit>
+  </info>
+
+  <title>Cursors</title>
+
+  <p>Cursors read values off the traces. There are two kinds: one <em>shared vertical
+  pair</em> that every row carries at the same time, and <em>horizontal rulers</em>, one pair
+  per row, that belong to that row alone.</p>
+
+  <section id="reach">
+    <title>How to reach it</title>
+    <steps>
+      <item>
+        <p>Press the cursors button in the toolbar, or <key>c</key>.</p>
+      </item>
+      <item>
+        <p>The pane below the plot shows the readings and owns a <gui>Reset</gui> button.
+        Drag a marker to move it.</p>
+      </item>
+      <item>
+        <p>The mode dropdown offers four modes: <gui>vertical</gui> (the shared time pair),
+        <gui>horizontal</gui> (the per-row rulers), <gui>both</gui>, and <gui>mix</gui>.</p>
+      </item>
+    </steps>
+  </section>
+
+  <section id="knowing">
+    <title>Worth knowing</title>
+    <list>
+      <item><p>The vertical pair is <em>one</em> time for the whole figure, so moving it on
+      any row moves it on all of them. That is what makes <code>dt</code> meaningful across
+      rows.</p></item>
+      <item><p>A ruler belongs to its row and nothing shares it, so two rows' rulers are
+      independent.</p></item>
+      <item><p><gui>mix</gui> is the reading mode: one line per <em>bound</em> trace, with the
+      trace's own values at each marker and their difference. A slot with a name but no
+      channel behind it is not a trace and gets no line.</p></item>
+      <item><p>A value is the <em>nearest stored sample's</em>, never a number between two
+      samples. Zoom in past the sample spacing and the line between two samples is something
+      the plot drew, not data — so a reading off it would be the drawing. The hover crosshair
+      reads the same way.</p></item>
+      <item><p>Every reading carries a <em>metric prefix</em> so the digits sit in
+      <code>1..999</code>: <code>10.52 mV</code>, not <code>0.01 V</code>. Two decimals is all
+      an instrument landing on an <code>f32</code> sample can claim, so without the prefix a
+      small value would read <code>0.00</code> and the reading would be gone. A stream that
+      declares no unit gets the prefix anyway, written tight against the number
+      (<code>585.24m</code>) — the space separates the number from its unit, and a spaced
+      <code>m</code> with nothing after it would read as metres.</p></item>
+      <item><p>A marker past the newest sample reads <code>--</code>. With only one marker
+      over data the row reads <code>partial</code>: a difference between a number and nothing
+      is not a number.</p></item>
+      <item><p>In <gui>mix</gui> each marker also places a crossing annotation per trace,
+      which is what lets you see on the plot which sample a number came from. It is <em>on
+      that sample</em>, so when the marker falls between two it sits a little off its own
+      line: the line is where you put the marker, the dot is the datum being quoted. The hover
+      crosshair's mark snaps the same way, and is drawn larger than a trace's sample dots so
+      it does not read as one more sample.</p></item>
+      <item><p>The time row exists only in the modes that show the vertical pair.
+      <gui>horizontal</gui> has no time row, by design.</p></item>
+      <item><p>A cursor <em>stays where you put it</em> while a live view rolls under it,
+      which is what a bench scope does: its <code>T0</code> is an age, so a marker left at
+      <code>-1.5s</code> keeps reading the sample a second and a half old as the stream
+      advances. A measurement's marks do the opposite — they travel with the sample they
+      measured — because a cursor is a question you asked and a mark is an answer about one
+      particular sample.</p></item>
+    </list>
+  </section>
+
+  <section id="example">
+    <title>Example</title>
+    <p>Three traces in <gui>mix</gui> mode with both markers over data: 3 lines and 6 crossing
+    marks, each line reading like <code>sine  0.31 V  -0.84 V  -1.15 V</code>. Move the second
+    marker past the newest sample and the third column reads <code>--</code>.</p>
+  </section>
+
+</page>

help/C/org.udpscope.app/export.page

@@ -0,0 +1,78 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="task"
+      id="export">
+
+  <info>
+    <link type="guide" xref="index#output"/>
+    <link type="seealso" xref="sessions"/>
+    <desc>Writing the visible range of every plotted trace to NumPy, CSV or MDF 3.30, and what
+    each format carries.</desc>
+    <credit type="author copyright">
+      <name>Martino Ferrari</name>
+    </credit>
+  </info>
+
+  <title>Saving and export</title>
+
+  <p>Export writes the <em>visible range</em> of every plotted trace to a file: NumPy
+  <file>.npy</file>, <file>.csv</file>, or <gui>MDF 3.30</gui> (<file>.mf3</file> or
+  <file>.mdf</file>), chosen by the extension you type.</p>
+
+  <section id="reach">
+    <title>How to reach it</title>
+    <steps>
+      <item>
+        <p>Pick <gui>Export visible range…</gui> in the overflow menu, or press
+        <keyseq><key>Ctrl</key><key>E</key></keyseq>.</p>
+      </item>
+      <item>
+        <p>A file chooser asks where; the format follows the path's extension.</p>
+      </item>
+    </steps>
+  </section>
+
+  <section id="knowing">
+    <title>Worth knowing</title>
+    <list>
+      <item><p>The table is collected at the moment you click, not when the chooser returns. A
+      live view keeps scrolling while a dialog is up, so a late collection would write a window
+      you never saw.</p></item>
+      <item><p>The rows are the <gui>stored samples</gui>, never the LOD buckets the plot draws
+      from. A row count far below the span times the stored rate means something cut the table
+      from the pyramid.</p></item>
+      <item><p>The stored rate is not always the wire rate. A window long enough to need
+      decimation is stored averaged at a lower rate, and the export carries <em>that</em> —
+      read the status bar's ⓘ popover for the figure before trusting a sample count.</p></item>
+      <item><p>Two time columns. <code>time</code> is the display timeline — negative ages
+      ending at 0 while streaming, offsets from the trigger edge while an event is held — so it
+      is the x you read a value at on screen. <code>abs_seconds</code> is the source's own
+      clock for the same sample, which is what lets two exports taken in different modes line
+      up. Both are strictly increasing and evenly spaced; duplicate or backwards stamps would
+      mean the file held two clocks.</p></item>
+      <item><p>An export taken <em>mid-capture</em> writes the partly filled window that is on
+      screen, which is shorter than the event span. Export outside a capture if you want the
+      whole event.</p></item>
+      <item><p><gui>MDF</gui> exists for handing a window to another tool, and its shape follows
+      the contract that reader uses: one channel group, every channel record-interleaved, the
+      master channel as the x axis and the unit in the channel metadata. So there the
+      <em>master is <code>abs_seconds</code></em>, named <code>time</code> — the clock that is
+      the same in every display mode — and the display axis goes out beside it as an ordinary
+      channel, <code>time_relative</code>. Both are seconds; each signal carries the source's
+      own unit. That is also what <gui>ScryLab</gui> reads: channel name → signal name, master
+      → x axis, unit → the signal's unit.</p></item>
+    </list>
+  </section>
+
+  <section id="example">
+    <title>Example</title>
+    <p>A 2 s window at 10 kS/s over 3 traces writes 20001 rows and 5 columns
+    (<code>time</code>, <code>abs_seconds</code>, three signals). The <file>.npy</file> is
+    <code>64·⌈(10+len(header)+1)/64⌉ + rows·(16 + 4·cols)</code> bytes. Read it back with
+    <code>pd.DataFrame(np.load(path))</code>. The <file>.mf3</file> is bigger — a block per
+    channel plus a comment — <code>272 + comment + rows·record + 28 + channels·274 + 30</code>
+    bytes, with <code>record = 16 + 4·cols</code> and <code>channels = cols + 2</code> for the
+    master and the relative axis. Read that one back with <code>asammdf.MDF(path)</code> or in
+    ScryLab.</p>
+  </section>
+
+</page>

help/C/org.udpscope.app/index.page

@@ -0,0 +1,67 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="guide" style="task"
+      id="index">
+
+  <info>
+    <desc>udpscope plots a live UDPStreamer source as one figure of up to eight stacked
+    plot rows sharing a single time axis, with a trigger, cursors, measurements, math
+    channels and an export. This manual covers connecting, the window and its panels,
+    navigating and pausing the plot, the trigger and its event cache, analysis, and
+    saving and exporting.</desc>
+  </info>
+
+  <title>udpscope</title>
+
+  <section id="main">
+    <title>Getting started</title>
+    <list>
+      <item><p><link xref="overview">Overview</link> — what udpscope is, how it reaches a
+      source, the window and its panels, and a first five minutes.</p></item>
+      <item><p><link xref="source">Choosing a source</link> — the command line, the
+      chooser, and opening an exported waveform instead of a live stream.</p></item>
+      <item><p><link xref="signals">Signals and calibration</link> — how a signal becomes
+      a channel, what starts acquisition, and how a scale and offset are applied.</p></item>
+      <item><p><link xref="layout">Rows, layout and drag &amp; drop</link> — up to eight
+      rows, four traces each, and the layout editor.</p></item>
+    </list>
+  </section>
+
+  <section id="viewing">
+    <title>Viewing</title>
+    <list>
+      <item><p><link xref="window">Time window</link> — the one control that changes the
+      window, and the decimation a long window causes.</p></item>
+      <item><p><link xref="navigate">Navigating the plot</link> — panning, zooming and
+      fitting with the mouse and the keyboard.</p></item>
+      <item><p><link xref="pause">Pause and play</link> — freezing the display without
+      stopping the stream, and how long you have been looking.</p></item>
+      <item><p><link xref="trigger">Trigger</link> — the four trigger shapes, arming,
+      hold-off, the event cache, and searching the buffer.</p></item>
+    </list>
+  </section>
+
+  <section id="analysis">
+    <title>Analysis</title>
+    <list>
+      <item><p><link xref="cursors">Cursors</link> — the shared vertical pair and the
+      per-row horizontal rulers.</p></item>
+      <item><p><link xref="measurements">Measurements</link> — a statistic of the visible
+      window, its on-plot marks, and its statistics line.</p></item>
+      <item><p><link xref="math">Math channels</link> — building a derived channel from a
+      graph of source nodes, operations and one output.</p></item>
+    </list>
+  </section>
+
+  <section id="output">
+    <title>Output and state</title>
+    <list>
+      <item><p><link xref="export">Saving and export</link> — the visible range to
+      <file>.npy</file>, <file>.csv</file> or <file>.mf3</file>.</p></item>
+      <item><p><link xref="sessions">Sessions and settings</link> — the per-source
+      configuration files and what they carry.</p></item>
+      <item><p><link xref="status">Status bar and diagnostics</link> — the glance line, the
+      ⓘ popover, and the activity badge.</p></item>
+    </list>
+  </section>
+
+</page>

help/C/org.udpscope.app/layout.page

@@ -0,0 +1,71 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="task"
+      id="layout">
+
+  <info>
+    <link type="guide" xref="index#main"/>
+    <link type="seealso" xref="signals"/>
+    <desc>How the figure's rows and traces are arranged, how to drop a signal onto a row, and
+    how the layout editor adds and removes rows.</desc>
+    <credit type="author copyright">
+      <name>Martino Ferrari</name>
+    </credit>
+  </info>
+
+  <title>Rows, layout and drag &amp; drop</title>
+
+  <p>The figure is a stack of rows, 1 to 8 of them, each holding up to 4 traces. Rows share
+  one time axis and one pair of side margins, so their y labels line up, their data areas
+  start and end on the same two columns, and their windows cannot drift apart. The left
+  margin holds the y labels; the right one is empty, and is there so the newest tick's label
+  and the newest sample's ink have somewhere to land instead of sitting on the frame.</p>
+
+  <section id="reach">
+    <title>How to reach it</title>
+    <steps>
+      <item>
+        <p>Drag a signal's chip out of the side panel (<key>s</key>) and drop it on a row to
+        add a trace.</p>
+      </item>
+      <item>
+        <p>Press <key>l</key>, or pick <gui>Layout editor</gui> from the overflow menu, to add
+        and remove rows: a <gui>×</gui> appears at the top left of each row and a <gui>+</gui>
+        on each boundary between rows, including above the first and below the last.</p>
+      </item>
+      <item>
+        <p>The editor's own button in the top-right corner leaves it.</p>
+      </item>
+    </steps>
+  </section>
+
+  <section id="knowing">
+    <title>Worth knowing</title>
+    <list>
+      <item><p>A plot's own <gui>right-click menu</gui> (the same compact rows as the app's
+      menu) holds the y-axis scale, the two fits, and <gui>Remove signal</gui>, which swaps
+      the menu to that plot's traces plus <gui>All traces on this plot</gui> — with a
+      <gui>Back</gui> row to return. That is how a trace comes off a row without going through
+      the layout editor.</p></item>
+      <item><p>A drop <em>adds</em> a trace to the row's next free slot; it does not replace
+      one. With four traces already on a row the drop is refused.</p></item>
+      <item><p>Inserting a row moves the rows below it <em>with their contents</em>. Inserting
+      above row 1 puts what row 1 plotted onto row 2 and leaves the new row empty — the rows
+      are not renumbered under you.</p></item>
+      <item><p>A trace is remembered by the signal's <em>name</em>, not by its channel number,
+      because a new CONFIG or an enable renumbers the channels and an index would silently
+      re-point the trace.</p></item>
+      <item><p>Adding or removing a row rebuilds the figure, which is cheap, but it also
+      re-deals every trace. A frozen trigger event survives the rebuild: the pinned window is
+      restated rather than re-framed on the live edge.</p></item>
+    </list>
+  </section>
+
+  <section id="example">
+    <title>Example</title>
+    <p>With three traces on row 1, pressing <key>l</key> shows 3 buttons (one <gui>×</gui>,
+    two <gui>+</gui>). Clicking the <gui>+</gui> above row 1 gives 2 rows and 5 buttons, with
+    the three traces now on row 2 — the layout probe reports exactly this as
+    <code>rows=2 buttons=5 traces=[0:-|1:sine,ramp,noise]</code>.</p>
+  </section>
+
+</page>

help/C/org.udpscope.app/math.page

@@ -0,0 +1,110 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="task"
+      id="math">
+
+  <info>
+    <link type="guide" xref="index#analysis"/>
+    <link type="seealso" xref="signals"/>
+    <desc>Building a derived channel from a graph of source nodes, operations and one output,
+    and how the graph is evaluated.</desc>
+    <credit type="author copyright">
+      <name>Martino Ferrari</name>
+    </credit>
+  </info>
+
+  <title>Math channels</title>
+
+  <p>A math channel is a signal computed from other signals. You build it as a small graph —
+  source nodes, operations, one output — and udpscope then treats the result as an ordinary
+  channel.</p>
+
+  <section id="reach">
+    <title>How to reach it</title>
+    <steps>
+      <item>
+        <p>Press the math button in the toolbar, or <key>g</key>.</p>
+      </item>
+      <item>
+        <p>The pane's <gui>+</gui> adds a channel, and opening one shows the graph editor:
+        nodes as boxes, click a box to select it and edit its parameters beside the canvas.</p>
+      </item>
+      <item>
+        <p>Inside the editor, <gui>add node</gui> is a menu button whose popover picks the op,
+        so the node arrives as the operation you asked for.</p>
+      </item>
+    </steps>
+  </section>
+
+  <section id="gestures">
+    <title>Graph gestures</title>
+    <p><gui>drag</gui> from an output port to an input port to wire them; drag a wired input
+    port off its connection to detach it; click a wire and press <key>Delete</key> to remove
+    it; drag a box to move it. <gui>Wheel</gui> zooms about the pointer. <gui>Drag the
+    background</gui> to pan. <key>f</key> fits all nodes into view;
+    <keyseq><key>Ctrl</key><key>0</key></keyseq> resets the view. <gui>tidy</gui>, the button
+    beside <gui>fit</gui> in the editor, lays the graph out in topological columns and frames
+    it. The orange dot marks the output node; click <gui>set as output</gui> to move it.</p>
+  </section>
+
+  <section id="knowing">
+    <title>Worth knowing</title>
+    <list>
+      <item><p>The graph is evaluated as an ordered list, so a node may only read ones
+      <em>above</em> it. A wire drawn right to left re-sorts the list silently so the graph
+      stays valid. A cycle is unrepresentable: the connection is refused rather than created,
+      and the line beneath the form says why — a loop, or a node asked to read itself.</p></item>
+      <item><p>A derived channel <em>is</em> a channel. It appears in the signal panel, can be
+      plotted, measured, exported, and used as a source for another math channel.</p></item>
+      <item><p>The math runs on the <em>stored</em> samples — decimated and averaged — so a
+      cutoff you type in Hz means the rate the filter will actually run at. Change the window
+      across a decimation boundary and the coefficients are rebuilt for the new rate.</p></item>
+      <item><p>A source may only name an <em>acquired</em> channel. The stream's timestamp
+      signal is not one: a graph sourced from it validates and then reads NaN for ever, so the
+      dropdown does not offer it.</p></item>
+      <item><p>The output defaults to the <em>last</em> node, and a node added to a linear
+      graph becomes the output. Choosing an earlier node explicitly is respected.</p></item>
+      <item><p>Every numeric field starts at its own identity value — gain 1, offset 0 — not
+      at the bottom of its range.</p></item>
+    </list>
+  </section>
+
+  <section id="why">
+    <title>Why an operation sometimes does nothing</title>
+    <p>A graph's <em>output</em> is the node whose value becomes the channel, and it is drawn
+    as the orange dot. A new graph is built source, then operation, and the last node added
+    becomes the output — but a graph whose output is left on the source is valid and simply
+    passes its input through, which is the usual reason a gain or a filter appears to have no
+    effect. <gui>Set as output</gui> moves the dot.</p>
+
+    <p><gui>Apply</gui> is insensitive while the graph is incomplete. A line beneath the form
+    says why: an input that is not connected, no output chosen, or a <em>channel</em> node
+    naming a signal the scope is not acquiring. Only the channels being acquired are offered,
+    because a source that is not acquired reads as no data for ever — and a graph that reads
+    NaN is harder to diagnose than one that would not save.</p>
+
+    <p>The filters are real filters. A math channel's samples are produced as the stream
+    arrives, once per stored slot, so a low pass carries the history a filter needs. A cutoff
+    typed in hertz is against the <em>stored</em> rate, which is the wire rate until a wide
+    window makes the buffer decimate — the status line's rate is that number, and the filters
+    are rebuilt whenever it changes.</p>
+
+    <figure>
+      <title>The math channel editor</title>
+      <desc>Nodes as boxes on a canvas, the orange dot marking the output, and the selected
+      node's parameters beside it.</desc>
+      <media type="image" mime="image/png" src="figures/math-editor.png" width="938" height="420">
+        <p>A sine source wired through a gain into a filter, with the output on the last
+        node.</p>
+      </media>
+    </figure>
+  </section>
+
+  <section id="example">
+    <title>Example</title>
+    <p><code>[sine] → [gain x2]</code> gives a channel reading <code>y=[-2, 2]</code>. A
+    100 Hz low pass on the same source passes 50 Hz at 0.97 and 2 kHz at 0.002; a 1 kHz band
+    pass with Q=2 passes 200 Hz at 0.05, 1 kHz at 0.95 and 4 kHz at 0.05. Each derived channel
+    must hold exactly as many samples as the shared clock has time slots.</p>
+  </section>
+
+</page>

help/C/org.udpscope.app/measurements.page

@@ -0,0 +1,157 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="task"
+      id="measurements">
+
+  <info>
+    <link type="guide" xref="index#analysis"/>
+    <link type="seealso" xref="cursors"/>
+    <desc>A measurement is a statistic of one signal over the window the pane is about — the
+    visible range, or the frozen frame while a view is pinned — with optional
+    on-plot marks and a per-measurement statistics line.</desc>
+    <credit type="author copyright">
+      <name>Martino Ferrari</name>
+    </credit>
+  </info>
+
+  <title>Measurements</title>
+
+  <p>A measurement is a statistic of one signal over the window the pane is about, recomputed as
+  that window moves. The pane lists them with their values; each can also draw its result on
+  the plot.</p>
+
+  <p>That window is the <em>visible range</em> — so on a live view the numbers follow what you
+  pan and zoom to. On a <em>still frame</em> — a held event, a paused stream, an opened file — it
+  is the frame's own extent instead, so panning or zooming inside it changes nothing: the data
+  being measured has not changed and you are only looking closer.</p>
+
+  <section id="reach">
+    <title>How to reach it</title>
+    <steps>
+      <item>
+        <p>Press the measurements button in the toolbar, or <key>m</key>.</p>
+      </item>
+      <item>
+        <p>The pane's <gui>+</gui> adds one; clicking a row opens the dialog where the signal,
+        the type, the threshold share or shares and the on-plot marks are set, with
+        <gui>Save</gui> and <gui>Delete</gui>.</p>
+      </item>
+    </steps>
+  </section>
+
+  <section id="knowing">
+    <title>Worth knowing</title>
+    <list>
+      <item><p>The types are average, top, bottom, min, max, peak to peak, amplitude, above,
+      below, between, pulse duration, period and frequency. <gui>top</gui> and <gui>bottom</gui> are the waveform's
+      <em>flat</em> high and low levels: the level the signal dwells at, taken from the densest
+      band of the window on each side of the split. A band-limited edge overshoots and rings —
+      a nominal 2 V square reaches about ±1.18 at its edges — and a ripple or an overshoot is
+      therefore <em>not</em> what these read. <gui>amplitude</gui> is the delta between those two
+      levels, and <gui>peak to peak</gui> is the swing between the extremes (so on a rippled
+      square <gui>amplitude</gui> reads 2 V where <gui>peak to peak</gui> reads 2.36 V).</p></item>
+      <item><p><gui>above</gui>, <gui>below</gui> and <gui>between</gui> are the opposite kind of
+      number: the plain <em>mean of the samples</em> above a share, below it, or between two
+      shares. That is a different question from <gui>top</gui>/<gui>bottom</gui> even about the
+      same split, and it is the older one — on a unit sine <gui>above 50%</gui> reads 0.64 V
+      (2/π, the mean of a half cycle) where <gui>top</gui> reads 0.96 V (near the peak, which is
+      where a sine dwells most), and on a band-limited square <gui>above 50%</gui> reads 0.99 V
+      where <gui>top</gui> reads the plateau, 1.00 V: the edge's ring is inside the first and not
+      inside the second. <gui>between</gui> takes <em>two</em> shares — <gui>from %</gui> and
+      <gui>to %</gui> — and reports the mean of the samples inside that band, which no single
+      split can answer; the order you type them in does not matter, since a band between 80 % and
+      20 % is the band between 20 % and 80 %.</p></item>
+      <item><p>A mean over a side carries whatever is on that side, so these three are the right
+      numbers when you want the <em>energy</em> or the <em>offset</em> of part of the waveform,
+      and the wrong ones when you want the level a plateau sits at. Like every other measurement,
+      one with nothing to measure reads <code>--</code> rather than a made-up number: a share at
+      100 % has no sample above it, and a band can hold none at all — on an ideal
+      (non-ringing) square every sample is exactly ±1, so a band between 50 % and 75 % is
+      empty.</p></item>
+      <item><p><gui>top</gui> and <gui>bottom</gui> also read <em>near the peak</em> on a
+      waveform that has no flat part, which is the honest reading rather than a failure: a unit
+      sine has no plateau, so the densest band is at its peak and these read about ±0.96 — not
+      the 0.64 a mean over each half would give, and not ±1 either. Only a level the signal
+      actually dwells at is a level.</p></item>
+      <item><p>The <em>split</em> says which side a level is read from, so any share between the
+      two levels reads the same number; it is not a boundary the value depends on. The one case
+      where it is read directly is a window the scope cannot summarize by level — a window
+      shorter than a level's own resolution, or one read through <gui>hf</gui> — where
+      <gui>top</gui>/<gui>bottom</gui> fall back to the mean of each side of the split and
+      <gui>amplitude</gui> to the window's peak to peak.</p></item>
+      <item><p>The on-plot marks come in two kinds and the mix is the reading: a <em>level</em>
+      mark is a ruler at a value, a <em>time</em> mark is a marker at a position. An average
+      draws one level mark; a max draws a level mark <em>and</em> a time mark at the first
+      sample that reached it; <gui>peak to peak</gui> draws a ruler at each extreme and
+      <gui>amplitude</gui> a ruler at each of its two flat levels — the pair is the span, so
+      the two rulers <em>are</em> the measurement.</p></item>
+      <item><p>Marks cannot be dragged. A measurement mark says what the measurement measured,
+      so it is created unselectable — as is the trigger marker.</p></item>
+      <item><p>A pass is throttled to a cadence rather than run every frame, so a ruler over a
+      live view is <em>stepped</em>. The number and the ruler come from the same pass, so they
+      always agree.</p></item>
+      <item><p>An invalid pass keeps its <em>level</em> marks and drops its <em>time</em>
+      marks. A level is a property of the signal and outlives the window; a position inside
+      the window does not. That is what stops the rulers blinking off at a mode change.</p></item>
+      <item><p>A crossing is counted with <em>hysteresis</em>, not on a bare level: the
+      thresholds are a tenth of the window's peak to peak either side of the share, and an
+      edge is counted only once the signal has passed the far one. Period, frequency and pulse
+      duration all depend on it. The mid level is exactly where a waveform moves fastest, so
+      any interferer faster than the fundamental recrosses a single level several times per
+      real crossing — a 5 Hz sine with a 500 Hz tone at a tenth of the amplitude reads 39 Hz
+      without the band and 5 Hz with it. The band holds to an interferer a third of the
+      waveform's own size.</p></item>
+      <item><p>The band is clamped to stay inside the data, which is what keeps a threshold set
+      near an extreme usable: a fixed band there would sit above every sample and the
+      measurement would read nothing. A share near an extreme still leaves the band little
+      room, so it rejects less — which is one reason period and frequency offer no share to
+      set.</p></item>
+      <item><p>A window with too few crossings reads <code>invalid</code> / <code>--</code>
+      rather than a plausible invented number. Frequency over a window holding one edge is the
+      usual case.</p></item>
+      <item><p><gui>frequency</gui> is reported in Hz and <gui>period</gui>/<gui>pulse
+      duration</gui> in seconds; every other type carries the channel's own unit. A value is
+      written with a <em>metric prefix</em> so its digits sit in <code>1..999</code> —
+      <code>636.62 mV</code>, not <code>0.64 V</code> — including when the stream declares no
+      unit at all, which is always the case for a math channel: there the prefix goes tight
+      against the number (<code>636.62m</code>), since two decimals of an unprefixed small
+      value is <code>0.00</code>.</p></item>
+      <item><p>Cost is bounded by reading the summary pyramid the producer already maintains,
+      not the raw window: a bucket's sum is a sum, so the mean, the extremes and a level's own
+      mean are exact. <gui>top</gui>, <gui>bottom</gui> and <gui>amplitude</gui> read the
+      <em>density</em> of the window out of that same summary — which is what tells a flat level
+      from a ripple — so those three cost a second read of the summary and never of a sample, and
+      <gui>between</gui>'s second share is one more level in the same summary walk rather than a
+      walk of its own.</p></item>
+      <item><p><gui>Statistics</gui> adds a second line to every measurement showing
+      <code>n</code>, the mean, the standard deviation and the range. Each observation is one
+      <em>recompute</em> of the pane, so <code>n</code> counts windows measured, not samples —
+      a mean frequency over many windows is what that claims to be. <gui>Reset</gui> clears
+      every accumulator and starts fresh. A change of display window, a CONFIG or a
+      measurement edit also resets; a pause, a resume, a zoom, a pan and the toggle itself do
+      not, so turning the line off to read the plot and back on again keeps the history. On a
+      still frame a pan or a zoom changes nothing for the history to record in the first place —
+      the values do not move there at all.</p></item>
+    </list>
+  </section>
+
+  <section id="example">
+    <title>Example</title>
+    <p>On a 1 Hz ±1 sine: <code>average=0</code>, <code>top=0.957988</code>,
+    <code>bottom=-0.957988</code> (the flat levels, near the peaks — a sine has no plateau),
+    <code>max=1</code>, <code>min=-1</code>,
+    <code>peak to peak=2</code>, <code>amplitude=1.915983</code>, <code>pulse duration=0.5 s</code>
+    (duty 0.5), <code>period=1 s</code>, <code>frequency=1 Hz</code>. On the same stream's
+    band-limited <code>square</code>, whose edges ring out to ±1.179: <code>top=0.999983</code>,
+    <code>bottom=-0.999983</code>, <code>amplitude=1.999966</code> against
+    <code>peak to peak=2.358701</code> — the levels are the plateau's and the extremes are the
+    edges'. Over a 2 M-sample window those passes read about 0.1% of the samples.</p>
+    <p>The mean-over-a-side types on the same two windows: on the sine
+    <code>above 50=0.636620</code>, <code>below 50=-0.636620</code> and
+    <code>between 50 75=0.255873</code>; on the rippled square <code>above 50=0.986496</code> and
+    <code>between 50 75=0.302744</code>, against <code>1.000000</code> for the same
+    <code>above 50</code> on an ideal (non-ringing) square. A <code>ramp</code>, whose density is
+    uniform, is the shape that names what a band mean <em>is</em>: <code>above 50=0.500000</code>
+    and <code>between 50 75=0.250000</code>, each band's own centre.</p>
+  </section>
+
+</page>

help/C/org.udpscope.app/navigate.page

@@ -0,0 +1,104 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="task"
+      id="navigate">
+
+  <info>
+    <link type="guide" xref="index#viewing"/>
+    <link type="seealso" xref="window"/>
+    <desc>Panning, zooming and fitting the plot with the mouse and the keyboard, and what a
+    pinned view refuses to do.</desc>
+    <credit type="author copyright">
+      <name>Martino Ferrari</name>
+    </credit>
+  </info>
+
+  <title>Navigating the plot</title>
+
+  <p>The plot pans and zooms with the mouse and with the keyboard. Every gesture acts on the
+  row the pointer is over, and because the rows share one time axis, an x change moves all of
+  them.</p>
+
+  <section id="reach">
+    <title>How to reach it</title>
+    <terms>
+      <item>
+        <title>Wheel</title>
+        <p><gui>Wheel</gui> zooms both axes · <gui>Shift</gui>+<gui>Wheel</gui> zooms x only ·
+        <gui>Ctrl</gui>+<gui>Wheel</gui> zooms y only.</p>
+      </item>
+      <item>
+        <title>Drag</title>
+        <p><gui>Drag</gui> pans · <gui>Shift</gui>+<gui>Drag</gui> is a box zoom on both axes ·
+        <gui>Ctrl</gui>+<gui>Drag</gui> on x only · <gui>Alt</gui>+<gui>Drag</gui> on values
+        only. The area being chosen is framed while you drag it, so you can see what the
+        release will apply.</p>
+      </item>
+      <item>
+        <title>Keyboard</title>
+        <p><key>+</key> and <key>-</key> zoom both axes; <key>Ctrl</key> with them restricts
+        to x, <key>Alt</key> to y. <gui>Arrow keys</gui> pan, <key>f</key> fits,
+        <key>Escape</key> cancels a gesture in progress.</p>
+      </item>
+    </terms>
+
+    <p>The full table is in the shortcut overview (<keyseq><key>Ctrl</key><key>/</key></keyseq>).</p>
+  </section>
+
+  <section id="knowing">
+    <title>Worth knowing</title>
+    <list>
+      <item><p>The keyboard zoom's modifiers are <em>not</em> the wheel's, and that is
+      deliberate: on common layouts <key>+</key> <em>is</em> <keyseq><key>Shift</key><key>=</key></keyseq>,
+      so a bare zoom-in already arrives with Shift set and Shift could not mean anything.
+      Ctrl/Alt mirror the box-zoom drags instead.</p></item>
+      <item><p>A <em>pinned</em> view is navigable within its own data but cannot leave it.
+      While an event is held, a capture is filling, or the view is paused, a zoom <em>in</em>
+      works normally — "not outside the event" is not "not readable" — but a pan or a zoom out
+      is clamped to the data.</p></item>
+      <item><p>Nothing you do on the plot changes the <em>time window</em> — only the header
+      control does. A zoom or a pan moves the view inside the window; <key>f</key> (and
+      <gui>Fit X axis</gui>) is the <em>undo</em> of a zoom, so a 2 s window zoomed into reads
+      2 s again. The window is more than the axis: it is also the trigger's event span and how
+      the samples are stored, so a wheel notch that redefined it would re-plan the buffer and
+      drop your history.</p></item>
+      <item><p>The axis does not scroll — the <em>data</em> does. A live axis is a fixed
+      <code>[-window .. 0]</code> with the newest sample at 0, so the labels stand still and
+      the trace rolls under them. The cursors stand still with the labels (they are positions
+      on screen, so a cursor you placed stays where you put it, over newer data each frame),
+      while a measurement's marks travel with the sample they measured and leave the view when
+      it does.</p></item>
+      <item><p>A live view is clamped to the window you asked for, not to what the ring
+      happens to hold. That is why a buffer that has only just started filling leaves its
+      left-hand side empty instead of squeezing the window down to the first few
+      samples.</p></item>
+      <item><p>Zooming hard into a held capture is exact. The renderer finds the visible
+      samples by binary search over the real timestamps, never over a nominal sample grid, so
+      a capture whose clock wandered does not drift away from its axis as you zoom.</p></item>
+      <item><p>A trace holding far more samples than the plot has pixels is drawn <em>one
+      pixel column at a time</em>: each column is a single vertical line from the lowest to
+      the highest value that falls in it. Drawn as a polyline instead, such a window puts
+      three or four near-vertical lines in every column at slightly different sub-pixel
+      positions, and how they overlap beats against the pixel grid — which reads as bands of
+      light and dark that <em>crawl</em> as you pan. One line per column removes the beat, and
+      it is also much faster: a 1 MS/s view costs a couple of thousand line segments a frame
+      instead of a couple of hundred thousand.</p></item>
+      <item><p>Those columns are <em>graded by brightness</em>, the way a digital-phosphor
+      scope reads: bright where the signal spent its time, faint where it only passed through.
+      A column's highest and lowest value are the same whether the samples in it are spread
+      evenly or piled at its two ends, so the grading is what tells the two apart — the flat
+      parts of a square wave come out solid and the edges between them faint. It is read from
+      a finer division of each column rather than from the line that is drawn, and it costs
+      about a millisecond a frame.</p></item>
+    </list>
+  </section>
+
+  <section id="example">
+    <title>Example</title>
+    <p>Pause a live view, then press <keyseq><key>Ctrl</key><key>+</key></keyseq>: x narrows
+    and y does not move. Press <keyseq><key>Alt</key><key>+</key></keyseq>: y narrows and x
+    does not. Eight doublings into a held 2 s capture, the trace still reaches both margins —
+    the zoom probe reports <code>gap_px</code> and <code>end_px</code> within a pixel or two
+    at every step.</p>
+  </section>
+
+</page>

help/C/org.udpscope.app/overview.page

@@ -0,0 +1,205 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="task"
+      id="overview">
+
+  <info>
+    <link type="guide" xref="index#main"/>
+    <desc>What udpscope plots, the four parts of the window, and one pass through the
+    application from connecting to saving.</desc>
+    <credit type="author copyright">
+      <name>Martino Ferrari</name>
+    </credit>
+  </info>
+
+  <title>Overview</title>
+
+  <section id="what">
+    <title>What udpscope is</title>
+    <p>udpscope plots a live UDPStreamer source. One window holds up to eight rows of plots,
+    each with up to four traces, and every row shares one time axis, so the whole figure
+    scrolls together. Acquisition runs on its own thread and writes a ring buffer sized from
+    <cmd>--buffer-mb</cmd>; the drawing thread reads whatever that ring holds when a frame
+    starts, which is why a trace never makes the window stutter.</p>
+
+    <p>The stream is the clock. Every interval you read on screen is measured between
+    timestamps the source sent, never your machine's, so a stalled source freezes the view
+    instead of scrolling it — and a source whose clock steps still gets the window you asked
+    for.</p>
+
+    <p>The time axis is <em>relative to now</em>. While streaming it is a fixed
+    <code>[-window .. 0]</code> with the newest sample at 0, so x reads as an age:
+    <code>-1.5s</code> is a sample a second and a half old. In trigger mode 0 is the event's
+    edge instead, and a paused view keeps the ages it was frozen with. The source's own clock
+    is still there when you need it — an export writes it as a second column.</p>
+
+    <figure>
+      <title>The udpscope window</title>
+      <desc>The header bar above the plots, the side panel on the right, and the status bar
+      along the bottom.</desc>
+      <media type="image" mime="image/png" src="figures/main-window.png" width="1280" height="800">
+        <p>One figure of three rows with four signals enabled, the Measure tab open in the
+        side panel, and the status bar reading <gui>live</gui>.</p>
+      </media>
+    </figure>
+  </section>
+
+  <section id="reach">
+    <title>How to reach it</title>
+    <p>Start the app with a source
+    (<cmd>udpscope --server 127.0.0.1 --port 8000</cmd>), or start it with no
+    <cmd>--server</cmd> and pick one from the chooser, which lists the sessions you have
+    opened before. A unicast source serves one client at a time: if a second viewer connects,
+    they take turns and the status bar says so. To watch one source from several instances,
+    use <cmd>--multicast</cmd> with the group and <cmd>--interface</cmd> with the local
+    address.</p>
+
+    <p>The signals arrive <em>disabled</em>. Nothing is acquired until you turn one on in the
+    signal list, and enabling is what starts acquisition — so a freshly opened scope with an
+    idle side panel is working correctly, not failing to connect. For the same reason a start
+    that has enabled nothing prints no <code>buffer allocated:</code> line on stderr.</p>
+
+    <note style="warning">
+      <p>Over SSH with X11 forwarding the window may never appear, and the cure is
+      <cmd>udpscope --renderer cairo</cmd>. Two symptoms tell the two halves apart: a
+      <code>vkCreateSwapchainKHR() ... VK_ERROR_INITIALIZATION_FAILED</code> warning is
+      GTK's default Vulkan renderer failing to make a swapchain and is what the option's
+      <code>GSK_RENDERER=cairo</code> answers; a window whose allocation stays zero
+      (<code>window_button_w=0</code>) means the plot's GL area has no context either, and
+      that is what its <code>LIBGL_ALWAYS_SOFTWARE=1</code> answers. Both variables are
+      exported before GTK initialises, because they are read when the renderer and the GL
+      context are created. <cmd>--renderer gl</cmd> is faster when indirect GL works.</p>
+    </note>
+
+    <note style="tip">
+      <p>See <link xref="source">Choosing a source</link> for the chooser and the multicast
+      options in full.</p>
+    </note>
+  </section>
+
+  <section id="window">
+    <title>The window</title>
+    <terms>
+      <item>
+        <title>The header bar</title>
+        <p>Left to right: the time window (<gui>2 s</gui>), the trigger and the pause, the
+        events, cursors and side-panel switches, and the menu, which holds
+        <gui>Fit to data</gui>, the <gui>Layout editor</gui>, <gui>Export</gui>,
+        <gui>Keyboard shortcuts</gui>, <gui>Help</gui> and <gui>About</gui>.</p>
+      </item>
+      <item>
+        <title>The side panel</title>
+        <p>Two tabs. <gui>Measure</gui> holds the cursors readout and the measurements
+        derived from it; <gui>Signals</gui> holds the trigger and the channel list, where a
+        math channel is a row of that one list under a <gui>MATH</gui> heading whose
+        <gui>+</gui> creates one. One row per channel: its colour, an enable switch, its name
+        and its unit. Channels are dragged from here onto a plot row.</p>
+      </item>
+      <item>
+        <title>The plot</title>
+        <p>Up to eight rows, each with its own y axis and up to four traces, all on one shared
+        time axis. Right-click a row for its own menu (fit, add a signal, remove a trace).</p>
+      </item>
+      <item>
+        <title>The status bar</title>
+        <p>Directly above the plot's bottom edge — the state word, the stored sample rate and
+        the window, and the ⓘ beside it for packets, gaps and the buffer's own figures. The
+        second screenshot below is what a held capture looks like: <gui>event held</gui>, the
+        axis pinned to the event, and the trigger marker at the edge.</p>
+      </item>
+    </terms>
+
+    <figure>
+      <title>A held capture</title>
+      <desc>The trigger has latched, the state reads <gui>event held</gui>, and the axis is
+      pinned to the event rather than to the live edge.</desc>
+      <media type="image" mime="image/png" src="figures/trigger-capture.png" width="1280" height="800">
+        <p>The trigger marker sits at x = 0 and the pre-trigger share of the window is drawn
+        to its left.</p>
+      </media>
+    </figure>
+  </section>
+
+  <section id="first">
+    <title>The first five minutes</title>
+    <steps>
+      <item>
+        <p><em>Connect.</em> With no <cmd>--server</cmd>, pick a stored session or type a host
+        and port.</p>
+      </item>
+      <item>
+        <p><em>Enable a signal</em> in the signal list. The plot stays empty for the first
+        fraction of a second while the first window fills — the buffer holds only what has
+        arrived.</p>
+      </item>
+      <item>
+        <p><em>Drag it onto a row.</em> Drop a second signal on another row, or the same
+        signal again for a second view of it. The colour is per signal, so it is the same one
+        wherever it appears.</p>
+      </item>
+      <item>
+        <p><em>Set the window</em> with the control in the header bar: type a number, pick a
+        unit, or step a decade. The trigger's event window is a share of this span, so a
+        window change moves it.</p>
+      </item>
+      <item>
+        <p><em>Pause</em> (<key>space</key>) to look at a still picture; the producer keeps
+        filling the buffer behind it, and resuming shows what arrived meanwhile rather than a
+        hole.</p>
+      </item>
+      <item>
+        <p><em>Arm the trigger</em> (<key>a</key>) and wait for a latch: the view freezes on
+        one event, and you can zoom in on it. Disarming mid-capture keeps what the capture
+        got.</p>
+      </item>
+      <item>
+        <p><em>Measure it</em> — the measurements pane computes a statistic of the visible
+        window, and <gui>show on plot</gui> marks it as a ruler or a pair of markers.</p>
+      </item>
+      <item>
+        <p><em>Save the data</em> with <gui>Export visible range</gui>, which writes the
+        plotted signals over the window at the stored rate to <file>.npy</file>,
+        <file>.csv</file> or <file>.mf3</file> (MDF 3.30).</p>
+      </item>
+    </steps>
+  </section>
+
+  <section id="knowing">
+    <title>Worth knowing</title>
+    <list>
+      <item><p>A signal nobody enables costs nothing — no buffer, no socket work, no
+      measurements.</p></item>
+      <item><p>The window remembers itself. Rows, traces, the time window, calibration, which
+      signals were enabled, the math channels with their graphs, and the measurements are
+      written per host and port, and reloaded the next time you open that source.</p></item>
+      <item><p>A very wide window on a fast stream is drawn from averaged groups of samples,
+      so the rate in the status bar falls: that is the anti-alias filter, not a fault —
+      striding would fold a fast signal back as a slow one, which looks entirely plausible on
+      screen.</p></item>
+      <item><p>Every instrument the app computed — the trigger marker, the measurement marks
+      — is locked to the pointer's reach. The cursors are yours to drag; those are not.</p></item>
+    </list>
+  </section>
+
+  <section id="installing">
+    <title>Installing this manual</title>
+    <p>The manual is a help set the desktop viewer reads off disk, so <key>F1</key> opens it only
+    once a copy sits where <cmd>help:</cmd> resolves. Either of two targets installs it on its own,
+    without building the application, and each prints where it wrote. Prefer the system-wide one:
+    it is the copy every viewer can read, and the reason is worth knowing before you pick the
+    other:</p>
+    <list>
+      <item><p>For a system-wide or packaged install:
+      <cmd>cmake --build build --target install-help</cmd> writes it under the configured
+      <cmd>CMAKE_INSTALL_PREFIX</cmd>, so point that at <file>/usr</file>
+      (<cmd>cmake -DCMAKE_INSTALL_PREFIX=/usr ..</cmd>) and wrap the target in
+      <cmd>sudo</cmd>. A viewer reads its figures as separate files, and its sandbox exposes the
+      system help directories, so this copy always shows them.</p></item>
+      <item><p>For your own account, needing no root:
+      <cmd>cmake --build build --target install-help-user</cmd> writes it under
+      <file>$XDG_DATA_HOME</file> (default <file>~/.local/share</file>). Be aware that the same
+      sandbox does <em>not</em> expose the user's data directory: those pages open, but a viewer
+      such as Yelp shows them without their figures.</p></item>
+    </list>
+  </section>
+
+</page>

help/C/org.udpscope.app/pause.page

@@ -0,0 +1,63 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="task"
+      id="pause">
+
+  <info>
+    <link type="guide" xref="index#viewing"/>
+    <link type="seealso" xref="trigger"/>
+    <desc>Pausing freezes the display without stopping the stream, and the status bar says how
+    long you have been paused.</desc>
+    <credit type="author copyright">
+      <name>Martino Ferrari</name>
+    </credit>
+  </info>
+
+  <title>Pause and play</title>
+
+  <p>Pause freezes the <em>display</em>, not the acquisition. The producer keeps filling the
+  ring at full rate; the view binds an immutable snapshot of the window that was on screen,
+  and the axis is pinned to it.</p>
+
+  <section id="reach">
+    <title>How to reach it</title>
+    <steps>
+      <item>
+        <p>Press the pause button in the toolbar, or <key>Space</key>.</p>
+      </item>
+      <item>
+        <p>Press it again to resume, which rebinds the live ring and puts the window back on
+        the newest data.</p>
+      </item>
+    </steps>
+  </section>
+
+  <section id="knowing">
+    <title>Worth knowing</title>
+    <list>
+      <item><p>Nothing is lost while paused. Because the producer never stops, resuming shows
+      current data with no hole in the history behind it.</p></item>
+      <item><p>The axis is pinned to the <em>snapshot's own stamps</em>, not to the window that
+      was requested. A window reaching back past the oldest retained sample yields a shorter
+      snapshot, and the pinned axis is that shorter span — so you see a narrower view rather
+      than an empty margin.</p></item>
+      <item><p>A paused view is pinned exactly as a held trigger event is: zoom in freely, but
+      a pan or a zoom out is clamped to the snapshot's data. A measurement goes on describing
+      that frozen frame rather than the part of it you are looking at, so a zoom on a pause
+      changes no reading — see <link xref="measurements"/>.</p></item>
+      <item><p>Pausing is the easiest way to measure a layout or read a cursor precisely,
+      because nothing under the pointer moves between frames.</p></item>
+      <item><p>The status bar says how long you have been paused — wall time, since the stream
+      itself never stopped. It is there so a frozen picture cannot be mistaken for a live one
+      that went quiet.</p></item>
+    </list>
+  </section>
+
+  <section id="example">
+    <title>Example</title>
+    <p>Pause with a 2 s window over a ring holding 1.4 s: the frozen axis reads
+    <code>[-1.40 .. 0.00]</code> rather than <code>[-2.00 .. 0.00]</code> with 0.6 s of blank.
+    The pause probe reports <code>ring_produced</code> still growing across the pause and
+    <code>event_size</code> non-zero exactly while paused.</p>
+  </section>
+
+</page>

help/C/org.udpscope.app/sessions.page

@@ -0,0 +1,93 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="task"
+      id="sessions">
+
+  <info>
+    <link type="guide" xref="index#output"/>
+    <link type="seealso" xref="source"/>
+    <desc>Per-source configuration files: where they live, what they persist, and how the
+    chooser and the Configurations dialog use them.</desc>
+    <credit type="author copyright">
+      <name>Martino Ferrari</name>
+    </credit>
+  </info>
+
+  <title>Sessions and settings</title>
+
+  <p>udpscope stores named sessions — <em>configurations</em> — per source, so reopening a
+  source gives you the scope you closed, and one source can hold several arrangements for
+  different experiments. There is no global preferences file: the session <em>is</em> the
+  settings.</p>
+
+  <section id="reach">
+    <title>How to reach it</title>
+    <p>Nothing to open — the file is written as you work. Its path is in the About dialog, and
+    the directory is <file>$XDG_CONFIG_HOME/udpscope</file>, or <file>~/.config/udpscope</file>
+    when that is unset. Each source has a directory <file>&lt;host&gt;_&lt;port&gt;/</file>
+    holding one <file>&lt;name&gt;.toml</file> per configuration and an <file>active</file>
+    file naming the one it is on.</p>
+  </section>
+
+  <section id="configs">
+    <title>Configurations</title>
+    <p><gui>Configurations…</gui> in the menu lists the running source's configurations: click
+    a row to open it, <gui>×</gui> to delete it, or type a name and a note and press
+    <gui>Save this session</gui> to keep the current arrangement under a new one. Opening a
+    configuration saves the current session first, so switching never loses what it switches
+    from.</p>
+
+    <p>The startup chooser (start with no <cmd>--server</cmd>) lists one row per configuration,
+    with its note and its settings, so two arrangements of one source are told apart before
+    they open.</p>
+
+    <p>A configuration also carries the settings that can only be decided when the buffers are
+    allocated: the <gui>buffer size</gui> (<cmd>--buffer-mb</cmd>), relative time, and the
+    packet capture's ring size. Opening a configuration from the chooser applies all three;
+    switching inside a running app applies the rest and says in the status line that these take
+    effect on the next start.</p>
+
+    <p>The chooser's form sets the first two for a new host, and its pencil button edits them
+    on an existing configuration — along with the name and the note. Renaming a configuration,
+    or editing the address it points at, moves it: the old file is removed rather than left
+    behind.</p>
+  </section>
+
+  <section id="knowing">
+    <title>Worth knowing</title>
+    <list>
+      <item><p>What a configuration persists: the time window, the rows and each row's slot
+      signals, the calibration, the trace colours, which signals were enabled, the math
+      channels with their graphs, the measurements pane — and the startup settings: buffer
+      size, relative time and the packet capture's ring size.</p></item>
+      <item><p>Signal identity is the <em>name</em> throughout, because a new CONFIG renumbers
+      the channels.</p></item>
+      <item><p>A file written by a run against a source whose streamer was down would name no
+      signals at all, so such a run does <em>not</em> write: a configured session is never
+      overwritten by a run that configured nothing. (The chooser hides such a file for the same
+      reason.)</p></item>
+      <item><p>The multicast group and the interface live <em>inside</em> the file, because its
+      name cannot carry them. A file from an older build has neither key and loads as unicast
+      on the default route.</p></item>
+      <item><p>The chooser lists only configurations that name at least one signal, which is
+      what keeps it the sessions you configured rather than every port you have ever tested
+      against.</p></item>
+      <item><p>Deleting a configuration is a supported way to start over; the chooser's
+      <gui>×</gui> and the dialog's do exactly that.</p></item>
+      <item><p>A session from before configurations existed is imported once as the
+      configuration <code>default</code>, and the old file is kept beside the directory as
+      <file>&lt;host&gt;_&lt;port&gt;.toml.imported</file>.</p></item>
+    </list>
+  </section>
+
+  <section id="example">
+    <title>Example</title>
+    <p>Connect to <code>127.0.0.1:8000</code>, drop three signals on row 1, set a 2 s window,
+    and save the session as <code>bench</code> with a note.
+    <file>~/.config/udpscope/127.0.0.1_8000/bench.toml</file> now holds
+    <code>window_s=2 comment="…"</code> with
+    <code>signals = ["sine", "ramp", "noise", ""]</code>, and the next run reports
+    <code>layout loaded from …/127.0.0.1_8000/bench.toml</code> with those signals already
+    acquired.</p>
+  </section>
+
+</page>

help/C/org.udpscope.app/signals.page

@@ -0,0 +1,70 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="task"
+      id="signals">
+
+  <info>
+    <link type="guide" xref="index#main"/>
+    <link type="seealso" xref="layout"/>
+    <desc>How the source's CONFIG becomes channels, what enabling a signal starts, and how a
+    signal's scale and offset are calibrated.</desc>
+    <credit type="author copyright">
+      <name>Martino Ferrari</name>
+    </credit>
+  </info>
+
+  <title>Signals and calibration</title>
+
+  <p>The source's CONFIG message describes its signals: a name, a unit and a type. udpscope
+  turns each enabled signal into a <em>channel</em> — a ring of values beside the shared time
+  ring — and a channel is what a trace plots. Calibration is a scale and an offset applied at
+  ingest.</p>
+
+  <section id="reach">
+    <title>How to reach it</title>
+    <steps>
+      <item>
+        <p>Open the side panel (<key>s</key>), which lists every signal with a switch.</p>
+      </item>
+      <item>
+        <p>The <gui>Signal list</gui> item in the overflow menu opens the editor where the
+        unit and the calibration live.</p>
+      </item>
+    </steps>
+  </section>
+
+  <section id="knowing">
+    <title>Worth knowing</title>
+    <list>
+      <item><p>Signals start disabled, and enabling one is what starts acquiring it. A trigger
+      on a signal nobody acquires can never fire, so arming a trigger enables its signal for
+      you.</p></item>
+      <item><p><gui>Calibrate</gui> in a signal's row menu opens the gain and offset it is
+      <em>currently</em> drawn through, so a trace already scaled by a gain of 2 shows 2 —
+      pressing <gui>Apply</gui> confirms it rather than resetting it. A signal nobody
+      calibrated shows the identity, 1 and 0.</p></item>
+      <item><p>Calibration is applied <em>at ingest</em>, so changing it re-plans the buffer
+      and drops the history. So does enabling or disabling a signal, and so does a new
+      CONFIG. An empty plot for a second after one of those is the ring refilling, not a
+      fault.</p></item>
+      <item><p>The stream's first signal is usually its <em>timestamp</em>, and that one is
+      never acquired. It cannot be plotted, measured or used as a math source, and udpscope
+      refuses to put it in a row rather than binding a trace that would read nothing for
+      ever.</p></item>
+      <item><p>A signal's colour follows the <em>signal</em>, not the slot, so the same signal
+      on two rows is one colour and the side panel's chip identifies it unambiguously. A
+      signal on no row gets a grey chip rather than none, so the panel's rows keep their
+      height.</p></item>
+      <item><p><em>Click a coloured chip to change that signal's colour.</em> A grey chip
+      names no trace, so it is not clickable. The colour is saved with the session;
+      <gui>Default colour</gui> in the signal's ⋯ menu gives the palette entry back.</p></item>
+    </list>
+  </section>
+
+  <section id="example">
+    <title>Example</title>
+    <p>A source declaring <code>time</code>, <code>sine</code>, <code>ramp</code> and
+    <code>noise</code> yields three plottable signals. Enable all three and the exit dump
+    reads <code>3 signals, 3 channels</code>; <code>time</code> is not among them.</p>
+  </section>
+
+</page>

help/C/org.udpscope.app/source.page

@@ -0,0 +1,75 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="task"
+      id="source">
+
+  <info>
+    <link type="guide" xref="index#main"/>
+    <link type="seealso" xref="sessions"/>
+    <desc>How udpscope is pointed at a source: the command line, the startup chooser, and
+    opening an exported waveform instead of a live stream.</desc>
+    <credit type="author copyright">
+      <name>Martino Ferrari</name>
+    </credit>
+  </info>
+
+  <title>Choosing a source</title>
+
+  <p>A source is a host and a port, optionally reached through a multicast group on a named
+  interface. Pass it on the command line, or let udpscope ask.</p>
+
+  <section id="reach">
+    <title>How to reach it</title>
+    <steps>
+      <item>
+        <p>Run with <cmd>--server</cmd> and the app connects straight away.</p>
+      </item>
+      <item>
+        <p>Run <em>without</em> <cmd>--server</cmd> and a chooser appears first: one row per
+        stored <em>configuration</em> (<code>host:port · name</code>, its note, and the
+        settings it carries), newest first, plus a <gui>New host…</gui> form that takes the
+        address <em>and</em> the configuration it belongs to — its name and note, the
+        <gui>buffer size</gui>, and whether time is relative or absolute. A row's pencil
+        button opens the same form on that configuration, pre-filled, and changes to its name
+        or address move it (the old file is deleted).</p>
+      </item>
+      <item>
+        <p>The second page, <gui>Waveforms</gui>, opens an <em>exported</em> run instead of a
+        live source: the files opened before (newest first; one that has since been deleted is
+        marked <em>missing</em>) and an <gui>Open…</gui> button for a new one. The same file
+        can be opened straight from the command line with <cmd>--open FILE</cmd>. A waveform
+        is a source that never arrives — no socket, no acquisition, no starvation notice — and
+        every instrument works on it: cursors, measurements, math channels and another export.
+        Only <file>.npy</file> files are read.</p>
+      </item>
+    </steps>
+
+    <p>The chooser runs before any buffer is allocated and before any socket is opened, so
+    declining it costs nothing.</p>
+  </section>
+
+  <section id="knowing">
+    <title>Worth knowing</title>
+    <list>
+      <item><p>The list is the sessions that <em>named a signal</em>. A session whose streamer
+      was down stores empty slot names and is filtered out, which is what keeps the list the
+      sources you actually configured rather than every port you have ever typed.</p></item>
+      <item><p>A stored row reconnects the way it was reached. The multicast group and the
+      interface are written inside the session file, because the file's name
+      (<file>host_port.toml</file>) cannot carry them.</p></item>
+      <item><p><cmd>--multicast</cmd> still needs <cmd>--server</cmd>: the CONFIG message is
+      fetched from the server, not from the group.</p></item>
+      <item><p>The <gui>×</gui> beside a row deletes that session file. Nothing else is
+      removed.</p></item>
+    </list>
+  </section>
+
+  <section id="example">
+    <title>Example</title>
+    <p><cmd>udpscope</cmd> with two stored sessions lists
+    <code>127.0.0.1:8000  plots=1 signals=3</code> and
+    <code>10.0.0.5:8001  plots=2 signals=4 multicast=239.1.2.3 interface=10.0.0.9</code>.
+    Activating the first reports <code>[sources] picked 127.0.0.1:8000</code> and continues
+    into the scope with that session's layout already loaded.</p>
+  </section>
+
+</page>

help/C/org.udpscope.app/status.page

@@ -0,0 +1,72 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="task"
+      id="status">
+
+  <info>
+    <link type="guide" xref="index#output"/>
+    <desc>The status bar's two tiers, the activity badge, the fixed state words, and the ⓘ
+    detail popover.</desc>
+    <credit type="author copyright">
+      <name>Martino Ferrari</name>
+    </credit>
+  </info>
+
+  <title>Status bar and diagnostics</title>
+
+  <p>The status bar is two tiers. The bar itself is one glance line — the state, the rate and
+  the window — and everything else is behind the ⓘ button at its right-hand end.</p>
+
+  <section id="reach">
+    <title>How to reach it</title>
+    <p>The bar is always visible under the plot. Click <gui>ⓘ</gui> for the detail popover.</p>
+  </section>
+
+  <section id="knowing">
+    <title>Worth knowing</title>
+    <list>
+      <item><p>The badge is one glyph in four colours: green <em>alternating</em> lit and dim
+      means data is arriving, and a steady colour means it is not. A badge that never blinks is
+      not a working badge. Of the two steady colours, <em>grey</em> is no stream at all or a
+      pipeline you stopped (the tooltip says which), and <em>yellow</em> is a source that
+      answered but has sent no configuration.</p></item>
+      <item><p>The state field is one word from a fixed set: <code>connecting</code>,
+      <code>live</code>, <code>paused</code>, <code>armed</code>, <code>capturing</code>,
+      <code>event held</code>, <code>disarmed</code>. Two states add one field each: in trigger
+      mode, how long ago the last event was; while paused, how long you have been paused.</p></item>
+      <item><p><code>connecting</code> means there is no <em>signal list</em> yet — either no
+      session or a session with no configuration behind it. Every other word claims a signal
+      list, so until one arrives there is nothing for them to describe: nothing can be enabled
+      and no data is owed.</p></item>
+      <item><p>The paused figure is <em>wall</em> time, not stream time — the producer never
+      stops while paused, so it answers "how long have I been looking at this picture".</p></item>
+      <item><p>Nothing on the bar may change width with the stream, because the bar sits
+      directly above the plot and a wider label would relayout it. That is why the rate
+      collapses to one figure or a range rather than listing per channel, and why an elapsed
+      time steps to a coarser unit instead of growing digits.</p></item>
+      <item><p><code>gaps</code> counts packets the receiver knows it missed. It is the number
+      that matters: a non-zero count means samples are absent from the buffer, not merely
+      late.</p></item>
+      <item><p><code>reconnects</code> counts sessions re-established with the source. Over
+      unicast a climbing count usually means a second client is taking the source's single
+      session.</p></item>
+      <item><p>The starvation notice — <em>connected, but no data is arriving</em> — is that
+      same situation seen from the other side: the signal list is here, so something took the
+      stream away. A source that has sent <em>no</em> configuration gets a different notice,
+      <em>trying to connect</em>, because nothing was taken away — pointing the app at a port
+      where nothing answers is that case, and the usual cause is a streamer that is not running
+      or is serving another port.</p></item>
+      <item><p><code>stored</code> versus <code>wire</code> in the popover is the decimation.
+      They differ exactly when the window is too long to store at full rate.</p></item>
+    </list>
+  </section>
+
+  <section id="example">
+    <title>Example</title>
+    <p>The bar reads <code>● live · 10 kS/s · 2 s window</code>. Behind ⓘ:
+    <code>Stream  connected, configured / packets 717 · frames 716 · gaps 0 / 3 signals · 3
+    channels</code>, <code>Buffer  200.0 MB · 1677 s span · time x1 / stored 10 kS/s (wire
+    10 kS/s)</code>, <code>Plot 1  3 traces · 195000 samples</code>,
+    <code>Reconnects  0</code>.</p>
+  </section>
+
+</page>

help/C/org.udpscope.app/trigger.page

@@ -0,0 +1,284 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="task"
+      id="trigger">
+
+  <info>
+    <link type="guide" xref="index#viewing"/>
+    <link type="seealso" xref="pause"/>
+    <desc>The trigger's four shapes, arming, forcing an acquisition and hold-off, the event cache with its replay,
+    compare and accumulate, and searching the buffer for a condition.</desc>
+    <credit type="author copyright">
+      <name>Martino Ferrari</name>
+    </credit>
+  </info>
+
+  <title>Trigger</title>
+
+  <p>The trigger watches one signal for a condition and captures a window around it. The
+  <gui>Shape</gui> dropdown chooses what counts as an event; the arming, hold-off, pre/post
+  window and Normal/Single mode are the same for all four shapes. The captured window is
+  frozen on screen until you re-arm.</p>
+
+  <section id="reach">
+    <title>How to reach it</title>
+    <steps>
+      <item>
+        <p>The trigger button in the toolbar (<key>t</key>) reveals the trigger panel: the
+        signal, the level, the shape, the edge (rising, falling, either), the mode (Normal or
+        Single) and the pre-trigger share.</p>
+      </item>
+      <item>
+        <p><gui>Arm</gui> starts watching; <key>a</key> arms and disarms from the keyboard.
+        When the pane is locked with its <gui>[edit]</gui> button — so that it states what the
+        trigger is set to instead of showing the controls — <gui>Arm/Disarm</gui> is in its
+        heading, and the trigger can be armed or disarmed without unfolding the panel. It is
+        offered only while trigger mode is on, because a trigger that is off has no engine to
+        arm.</p>
+      </item>
+      <item>
+        <p><gui>Force</gui> takes one acquisition <em>now</em>, with the event window above,
+        without waiting for the condition to hold — for when the event you are waiting for is not
+        coming and you want to see what the signal is doing this instant. The capture runs out its
+        post-trigger share and then freezes, exactly like a latch: the marker sits at the instant
+        you pressed. In <gui>Normal</gui> mode the trigger goes back to waiting afterwards; in
+        <gui>Single</gui> mode it disarms, because one acquisition is the whole of what that mode
+        means either way. It needs a signal to be acquired — the trigger cannot watch one that is
+        switched off — and pressing it while a capture is already filling leaves that capture
+        alone, since it is the acquisition you asked for.</p>
+      </item>
+      <item>
+        <p><gui>Search the buffer</gui> is at the foot of the same panel.</p>
+      </item>
+    </steps>
+
+    <figure>
+      <title>A held capture</title>
+      <desc><gui>event held</gui> in the status bar, the axis pinned to the event, and the
+      trigger marker at x = 0.</desc>
+      <media type="image" mime="image/png" src="figures/trigger-capture.png" width="1280" height="800">
+        <p>The pre-trigger share is drawn to the left of the marker.</p>
+      </media>
+    </figure>
+  </section>
+
+  <section id="shapes">
+    <title>The four shapes</title>
+    <terms>
+      <item>
+        <title>Edge</title>
+        <p>A crossing of the level in the chosen direction, the classic behaviour.</p>
+      </item>
+      <item>
+        <title>Pulse width</title>
+        <p>A crossing and its return, qualified by how long the excursion lasted: less than,
+        greater than, within or outside a pair of widths; the event is timed at the closing
+        edge.</p>
+      </item>
+      <item>
+        <title>Window</title>
+        <p>The signal entering or leaving a band between two levels; the panel keeps the two
+        levels at least one increment apart, because a zero-width band is not a band: the
+        condition becomes an exact float-equality test against the level, which an ordinary
+        signal never satisfies and a signal sitting at the level satisfies on every
+        transition.</p>
+      </item>
+      <item>
+        <title>Dropout</title>
+        <p>The absence of a crossing for longer than a timeout; one event per outage, re-arms
+        when a crossing returns.</p>
+      </item>
+    </terms>
+
+    <p>The shape's own rows are the only ones shown; the rest are hidden, so the panel never
+    offers a pulse width to a window trigger.</p>
+  </section>
+
+  <section id="multiple-events">
+    <title>Multiple events: keeping the last few acquisitions</title>
+    <p><gui>multiple events</gui> decides how many of the most recent triggered acquisitions stay on
+    screen at once. It is <em>1</em> by default, which is the event alone — the display you get
+    when you ask for no persistence — and it can be raised to 8. Each older acquisition is drawn
+    at half the brightness of the one before it (1, 0.5, 0.25, 0.125, …), and they are all aligned
+    on their own trigger edge, so the pre-trigger part of the event lines up from acquisition to
+    acquisition and whatever changes between them — jitter, ringing, the occasional glitch — shows
+    as a faint ghost behind the current trace. That is what a phosphor display does with
+    successive sweeps.</p>
+
+    <p>The older acquisitions are drawn <em>behind</em> the current one and nothing else changes
+    because of them: the axis still frames the event on screen, the trigger marker still marks
+    <em>its</em> edge, and the measurements still describe the current frame. Lowering
+    <gui>multiple events</gui> back to 1 remembers nothing and frees the retained acquisitions
+    immediately.</p>
+
+    <p>Two things bound how many are drawn, and the panel tells you when one of them bites.</p>
+    <list>
+      <item><p><em>Room in the plot.</em> Each older acquisition is an extra trace in the row that
+      plots its signal, so it needs a free trace slot there. A row holding four signals — the
+      layout the app starts with — has room for one older acquisition of each of them; a row per
+      signal has room for all seven.</p></item>
+      <item><p><em>Memory.</em> A retained acquisition is a whole window copied out of the ring,
+      so persistence may hold at most as much again as the buffer (<gui>--buffer-mb</gui>) does.
+      On a long window at a high sample rate that bound is reached before the eighth layer.</p></item>
+    </list>
+  <section id="persistence">
+    <title>Persistence: how often the trace has been here</title>
+    <p><gui>persistence</gui> — the switch in the trigger panel's <gui>Advanced</gui> block — keeps
+    an <em>image</em> of the last acquisitions instead of their traces. Every acquisition is
+    accumulated into it, the one on screen included, so a cell's brightness means how many of them
+    passed through it: the sweep on screen is the brightest, the ones behind it add on top, and
+    where several agree the ink is brighter still. There is no stroke drawn over the image — the
+    acquisition on screen <em>is</em> its newest ink — so it fades with the rest in both modes. Each
+    signal is kept as its own image in that signal's own colour, so where two signals cross the same
+    place you see both, not one blended line. It is off by default.</p>
+
+    <p>Two things make it different from <gui>multiple events</gui> beside it, and the panel offers
+    both because they answer different questions. <em>It never runs out of room</em>: each signal's
+    image is sized to the plot on screen and capped, so a display of a thousand acquisitions costs
+    what a display of one costs — one image per signal, whatever the plot's trace slots, and a very
+    wide window does not make it grow — and there is no count to choose. <em>And it fades</em>, in
+    one of two ways — <gui>fades by</gui> picks them:</p>
+    <list>
+      <item><p><gui>acquisitions</gui>: every acquisition keeps
+      <gui>per acquisition</gui> of what was there before it (0.5, the default, is the schedule a
+      phosphor's afterglow has: 1, 0.5, 0.25, …). The display then shows the last few sweeps
+      whatever the trigger rate.</p></item>
+      <item><p><gui>time</gui>: the image fades by <gui>time constant s</gui> as the display runs —
+      one constant is the time for it to fall to a third of its ink — so a slow trigger leaves
+      faint sweeps and a fast one leaves bright ones, and the picture is the same whichever the
+      stream is doing.</p></item>
+    </list>
+
+    <p>Persistence is a <em>trigger mode</em> display, like the trigger itself: it is drawn while a
+    captured acquisition is on screen and goes away with the trigger, on a pause, and when you open
+    a stored waveform. Nothing about it moves the framing — the axis is still the current event's,
+    the older sweeps only add ink — and it reserves no space in the plot and cannot be clicked, so
+    it is never in the way of a cursor or a drop.</p>
+
+    <p>Both displays live in the trigger panel's <gui>Advanced</gui> block, together with the
+    trigger's other settings that are set up once and left alone.</p>
+  </section>
+
+
+    <p>If a depth cannot be shown in full, a notice says how many layers fit, and the panel's
+    tooltip carries the same rule. Persistence is a display of what has already been captured: it
+    changes neither what is acquired nor what is measured, and it does nothing while the trigger
+    is off.</p>
+  </section>
+
+  <section id="cache">
+    <title>The event cache, replay and compare</title>
+    <p><em>Every triggered acquisition is kept.</em> Latches are written to the event cache
+    (<file>~/.cache/udpscope/events/&lt;source&gt;/</file>) as a <file>.npy</file> of the
+    event, a <file>.txt</file> of what it was, and a <file>.bmp</file> picture drawn from the
+    samples. The <gui>Events</gui> pane on the left — opened from the toolbar's
+    event-history button, which appears while recording is enabled, and collapsed until you
+    ask for it — lists the last 32 newest first (time, duration, signals, rate), each row with
+    its own picture beside the numbers.</p>
+
+    <p>Clicking a row <em>replays</em> it: the stored event is loaded exactly like an exported
+    file, <em>without changing the layout</em> — the rows, the colours, the window, the
+    cursors and the measurements stay where they are and read the stored data instead. A
+    replay leaves trigger mode, because a file has no edge to wait for, and the pane stays
+    open. Drag the pane's edge to resize it. <gui>Live</gui> goes back to the stream; the
+    status bar names the file until you do.</p>
+
+    <p>Select two or more events in the list and the two buttons under the header act on them:
+    <gui>Compare</gui> puts two events in two plots side by side, keeping the layout you have
+    — one plot per event, the axes synchronised, so zooming a row in one zooms the same row in
+    the other — and <gui>Accumulate</gui> overlays up to four of them in the same traces,
+    translucent, so where they agree the trace is brighter. Your own traces stay where they
+    are in both. They need events with the same signals and the same length. A single click
+    selects, a <em>double</em> click replays.</p>
+
+    <p><gui>Record events</gui>, in the trigger panel with the trigger's other options, is
+    what decides whether anything is kept. It is <em>off by default</em> — nothing is written
+    to disk until you ask — and with it off the history button goes with it.</p>
+  </section>
+
+  <section id="search">
+    <title>Search the buffer</title>
+    <p><gui>Search the buffer</gui>, at the foot of the trigger panel and collapsed until you open
+    it, answers the question the trigger answers — <em>where does this condition hold?</em> — over
+    the <em>whole</em> retained buffer rather than at the live edge. It runs the trigger's own
+    evaluator over the ring in stream order, so a <gui>hit</gui> is not a level you point at: it is
+    an <em>instant</em> the trigger would have fired on, timed the way an acquisition would have
+    timed it. A pulse-width finding, for instance, is the closing edge of a qualifying excursion,
+    not the excursion itself.</p>
+
+    <p>The condition is the one the rest of the panel is set to — the same signal, shape, level and
+    options — so there is no second condition to keep in step: change the panel and the next search
+    asks the new question. Nothing is searched until you ask, and the status line says
+    <gui>not searched</gui>.</p>
+
+    <steps>
+      <item>
+        <p>Set the condition above, then press <gui>Search</gui>. Covering the whole ring takes a
+        moment, and the scan runs in chunks so the stream keeps arriving while it does; the status
+        line counts the ground covered — <gui>scanning 1.2 s of 8.0 s, 40 found</gui>.
+        <gui>Stop</gui> ends a scan early and keeps the hits found so far.</p>
+      </item>
+      <item>
+        <p>Step through the hits with the arrows either side of the position readout
+        (<gui>3 of 40</gui>). The first <gui>next</gui> goes to the first hit, and the ends do not
+        wrap — a wrap from the last hit to the first would look exactly like the view not having
+        moved. Each step <em>pauses</em> on its hit, centred, exactly as the Pause button does, so
+        what you read is the frozen window cut around that instant; press the pause button again to
+        go back to the stream.</p>
+      </item>
+      <item>
+        <p>Every plot row marks the hits that fall in the window, up to sixteen of them. When more
+        are in view the pane says so and suggests zooming in — <gui>16 of 38 marks shown — zoom in
+        to see the rest</gui> — and when the selected hit has scrolled off the window it says that
+        instead. A hit the live stream has since overwritten reads <gui>no longer in the buffer</gui>
+        beside its position.</p>
+      </item>
+    </steps>
+
+    <p>How a scan ended is part of the answer: <gui>N found in 8.0 s</gui> when it covered the whole
+    ring; <gui>N found; the stream overtook the oldest samples</gui> when the producer overwrote
+    samples before the scan reached them, so the count is of what was left; and
+    <gui>N found (the limit) in the newest …</gui> when a condition that holds almost everywhere —
+    an edge on a noisy signal — reached the ten-thousand-hit ceiling. The last is a stop, not a
+    crash: a hit list nobody could navigate is not worth building.</p>
+
+    <p>A result describes the ring it was taken from, so it is <em>dropped</em> when that ring is
+    replaced: a new <gui>CONFIG</gui> from the source, or a change to the signal set, re-describes
+    the stream and clears the hits. The condition above is untouched — only the answer to it
+    is.</p>
+  </section>
+
+  <section id="knowing">
+    <title>Worth knowing</title>
+    <list>
+      <item><p>Arming <em>enables</em> the signal if it was off, because a trigger on a signal
+      nobody acquires can never fire.</p></item>
+      <item><p>The pre-trigger share is a share of the <em>display window</em>, not of the
+      ring. A 2 s window at 50% captures 1 s before the edge and 1 s after.</p></item>
+      <item><p>There are four display states, and the status bar names each: <gui>armed</gui>
+      (watching, nothing drawn yet), <gui>capturing</gui> (the edge was accepted and the post
+      window is filling <em>in view</em>, with the marker at x = 0), <gui>event held</gui>
+      (the frozen capture) and <gui>disarmed</gui>. A held capture is never quietly replaced
+      by live data.</p></item>
+      <item><p>The first edge after arming is only accepted once the history reaches back a
+      full pre-trigger window, so a capture may legitimately be shorter than you asked for.
+      The axis is pinned to what the capture actually got. <gui>Force</gui> is the one
+      acquisition that skips that gate — it captures the history that exists, because "now"
+      is the whole of what you asked for — so on a ring that has just started filling its
+      left side is short even though the axis still shows only what it got.</p></item>
+      <item><p>Disarming <em>during</em> a capture publishes what the capture got to, so the
+      picture on screen at that moment stays on screen. No event fired, so the event count
+      does not move.</p></item>
+      <item><p>The trigger reads the <em>stored</em> signal — decimated and averaged — not the
+      wire signal. A spike narrower than one decimation group is filtered away rather than
+      triggering on data the buffer does not contain.</p></item>
+    </list>
+  </section>
+
+  <section id="example">
+    <title>Example</title>
+    <p>A 1 Hz sine, level 0, rising, 2 s window at 50%, Single. The capture spans
+    <code>[-1.000 .. 1.000]</code> with <code>n=20001</code> samples at 10 kS/s — the span
+    times the real rate, plus one — and the marker sits at x = 0 throughout.</p>
+  </section>
+
+</page>

help/C/org.udpscope.app/window.page

@@ -0,0 +1,66 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="task"
+      id="window">
+
+  <info>
+    <link type="guide" xref="index#viewing"/>
+    <link type="seealso" xref="navigate"/>
+    <desc>The time window control: how to set it, and why a long window is decimated rather
+    than refused.</desc>
+    <credit type="author copyright">
+      <name>Martino Ferrari</name>
+    </credit>
+  </info>
+
+  <title>Time window</title>
+
+  <p>The window is how much time the plot shows. Every row shares one window: the figure has
+  a single x link group, so the rows cannot drift apart. The trigger's event span follows it,
+  and the pre-trigger share is a share of <em>this</em> window.</p>
+
+  <section id="reach">
+    <title>How to reach it</title>
+    <steps>
+      <item>
+        <p>The header bar's window button opens a popover: type a number, pick a unit under
+        it, or step a decade with the arrows.</p>
+      </item>
+      <item>
+        <p>The button's own label is a reading of the current window in a natural unit,
+        width-locked so a change of window cannot widen the header bar.</p>
+      </item>
+    </steps>
+  </section>
+
+  <section id="knowing">
+    <title>Worth knowing</title>
+    <list>
+      <item><p>A window too long to store at the wire rate is <em>decimated, not refused</em>.
+      The shared clock takes a power-of-two stride, and each group of samples is
+      <em>averaged</em> rather than strided, so a tone above the stored Nyquist is attenuated
+      instead of aliasing to a false low frequency.</p></item>
+      <item><p>The stamp stored for a group is the group's <em>mean</em>, which is where the
+      averaging puts the value. Stamping at the end of a group would shift every trace half a
+      stored sample late.</p></item>
+      <item><p>Moving the window across a decimation boundary rebuilds the buffer and drops
+      the history. Walking it inside one decade is free.</p></item>
+      <item><p><em>This control is the only thing that changes the window.</em> A zoom, a pan
+      or a fit moves the view <em>inside</em> it and leaves it alone — which is the point of
+      the previous bullet: a wheel notch that redefined the window could re-plan the buffer
+      and throw your samples away.</p></item>
+      <item><p>The trigger sees the <em>stored</em> (filtered) signal, not the wire signal,
+      because an edge found on a sample that is not in the buffer could not be cut out of
+      it.</p></item>
+    </list>
+  </section>
+
+  <section id="example">
+    <title>Example</title>
+    <p>1 MS/s with 200 MB of buffer. A 2 s window stores every sample
+    (<code>time x1</code>). Widen it to 600 s and the stride becomes <code>x16</code>: 625 S/s
+    stored, anti-aliased at 312.5 Hz. A 2 kHz sine seen through that window reads
+    <code>y=[-0.059, 0.079]</code> — attenuated to about 6%, not folded down to a
+    full-amplitude 125 Hz one.</p>
+  </section>
+
+</page>

src/acquisition.hpp

@@ -3,24 +3,27 @@
 
 #pragma once
 
+#include "capture.hpp"
 #include "config.hpp"
 #include "model.hpp"
 #include "trigger.hpp"
 
-#include <udps_client.h>
+#include "source/data_source.hpp"
 
 #include <atomic>
 #include <chrono>
 #include <cstdint>
+#include <limits>
+#include <memory>
 #include <thread>
 #include <vector>
 
 namespace udpscope {
 
-/// Owns the UDPStreamer client and the producer thread that feeds the model's
+/// Owns the data source and the producer thread that feeds the model's
 /// acquisition buffer. Everything it touches from the thread is serialised on
 /// `ScopeModel::mutex()`, so a UI-side structural change cannot race a frame.
-class Acquisition {
+class Acquisition : private SourceSink {
  public:
   Acquisition(ScopeModel& model, const Config& cfg);
   ~Acquisition();
@@ -28,8 +31,8 @@ class Acquisition {
   Acquisition(const Acquisition&) = delete;
   Acquisition& operator=(const Acquisition&) = delete;
 
-  /// Opens the client (no socket until the first poll) and starts the thread.
+  /// Opens the source (no socket until the first poll) and starts the thread.
-  /// Throws std::runtime_error when the client cannot be created.
+  /// Throws std::runtime_error when the source cannot be created.
   void start();
   /// Stops the thread and destroys the client. Idempotent.
   void stop();
@@ -37,28 +40,95 @@ class Acquisition {
   void set_paused(bool paused) noexcept { paused_.store(paused, std::memory_order_relaxed); }
   bool paused() const noexcept { return paused_.load(std::memory_order_relaxed); }
 
+  /// Turns the packet capture on or off -- the whole GTK side of the feature. The
+  /// path is built here, once, *before* the flag is published, so the producer reads
+  /// a complete string whenever it reads a true flag. `slots` is the ring's size;
+  /// zero means the 1000-slot default. The producer does the open or the close at the
+  /// top of the next datagram, so a toggle costs no lock and no second thread.
+  void set_capture_want(bool want, std::uint32_t slots = 0);
+  bool capture_want() const noexcept {
+    return capture_want_.load(std::memory_order_acquire);
+  }
+
+  /// Asks for one **forced trigger acquisition** -- the trigger panel's Force button. The producer
+  /// consumes the request on its next packet and opens a capture at that packet's newest stamp,
+  /// which the engine's ordinary latch then publishes with the configured pre/post window. The
+  /// request is dropped rather than retried when there is nothing to force: trigger mode off, no
+  /// channel resolved, the engine disarmed, or a capture already filling (a capture in flight *is*
+  /// the acquisition being asked for).
+  ///
+  /// **Write it under `ScopeModel::mutex()`, together with the `armed` flag the click also sets.**
+  /// The producer holds that lock for a whole packet -- it reads the panel's `armed` at the top of
+  /// one and consumes this request at the bottom -- so a request written between the two would be
+  /// read by a packet whose engine was still disarmed, and then dropped.
+  void request_force() noexcept { force_want_.store(true, std::memory_order_release); }
+
+  /// The source this acquisition drives, for the UI's capability panels: it may only call
+  /// `post()` on it. Null until `start()`.
+  DataSource* source() noexcept { return source_.get(); }
+
+  /// The capture, for the popover's row and the probe. Counters and errors are read
+  /// cross-thread through PacketCapture's own published fields.
+  const PacketCapture& capture() const noexcept { return capture_; }
+
  private:
   void run();
-  void on_config(const udps_signal_t* signals, std::uint32_t count, std::uint8_t publish_mode);
+  void on_config(const std::vector<SignalInfo>& signals, std::uint8_t publish_mode) override;
-  void on_data(const udps_frame_t* frame);
+  void on_data(const Frame& frame) override;
-  void on_event(int event, const char* detail);
+  void on_event(SourceEvent event, const char* detail) override;
-
+  /// Drops the producer state that is per *connection*: the counter mark, the time
-  static void config_trampoline(const udps_signal_t* signals, std::uint32_t count,
+  /// anchors and the clock choice. A reconnect re-sends the CONFIG and the stream may
-                                std::uint8_t publish_mode, void* user);
+  /// have restarted its numbering; carrying the old session's marks across makes the
-  static void data_trampoline(const udps_frame_t* frame, void* user);
+  /// first new frames read as late, as glitches or as an outage, which is recovery
-  static void event_trampoline(udps_event_t event, const char* detail, void* user);
+  /// failing exactly when it matters. Called on the producer thread, from on_event().
+  void reset_session_state() noexcept;
+  /// The producer side of the toggle: open on a rising edge, close on a falling one,
+  /// then store if enabled. Every file operation happens here, on this thread.
+  void on_datagram(const std::uint8_t* bytes, std::size_t len, double recv_time);
 
   /// Fills `stamps_` with this frame's base-tick timestamps, in stream seconds,
-  /// and returns how many were written (`frame->num_samples` unless the frame is
+  /// and returns how many were written (`frame.num_samples` unless the frame is
   /// malformed).
-  std::uint32_t build_stamps(const udps_frame_t* frame, int time_signal);
+  std::uint32_t build_stamps(const Frame& frame, int time_signal,
+                             bool counter_gap_refused);
+
+  /// Pushes NaN for the `missing` packets' worth of samples that were never delivered,
+  /// advances the decimation accumulators and tick_, records the hole in the model, and
+  /// bumps the hole counters. Called before the frame's own samples so the gap sits
+  /// *ahead* of the data that revealed it.
+  void reserve_hole(std::uint32_t missing, const Partition& part,
+                    const std::vector<ChannelInfo>& channels, BufferStore& store, u64 g);
+
+  /// Writes a late frame's values into the NaN-filled holes their counter addresses,
+  /// amending the value ring directly (producer path) and queuing pyramid amends for
+  /// `ChannelBuffer::acquire()` to apply on the consumer thread.
+  void backfill_from(const Frame& frame, const Partition& part,
+                     const std::vector<ChannelInfo>& channels, BufferStore& store, u64 g);
+
+  /// Keeps the wire's own cadence up to date from the arrival times, in the modes where
+  /// `build_stamps()`'s arrival branch does not (see the definition).
+  void note_frame_arrival(double recv_time) noexcept;
+
+  /// Whether the counter's claim of `missing` lost packets can be believed *and* booked: the
+  /// arrival clock has to corroborate it and the ring has to be able to hold it. See the
+  /// definition for both tests and for what believing a claim that fails them looks like.
+  bool gap_plausible(std::uint32_t missing, double elapsed, const Partition& part, u64 g) const;
 
   ScopeModel& model_;
   Config cfg_;
-  udps_client* client_ = nullptr;
+  std::unique_ptr<DataSource> source_;
   std::thread thread_;
   std::atomic<bool> running_{false};
   std::atomic<bool> paused_{false};
+  PacketCapture capture_;
+  std::atomic<bool> capture_want_{false};
+  /// The pending Force request (see `request_force()`): a flag and not a queue, because two clicks
+  /// inside one packet are one acquisition, which is what a momentary button means.
+  std::atomic<bool> force_want_{false};
+  std::uint32_t capture_slots_ = 1000;
+  /// Written once, by the GTK thread, before `capture_want_` is ever published true;
+  /// the producer reads it only after the flag, so no lock is needed.
+  std::string capture_path_;
   TriggerEngine engine_;
 
   std::uint64_t tick_ = 0;        ///< base ticks consumed since the epoch
@@ -70,25 +140,92 @@ class Acquisition {
   /// included -- so the stream source is dropped in favour of arrival time.
   double last_stream_anchor_ = 0.0;
   bool have_stream_anchor_ = false;
+  /// Consecutive packets whose stream-time stamps failed those checks. A single bad
+  /// packet is a glitch in the producer's clock and is bridged at the declared cadence;
+  /// only a run of them means the declared signal is not a time base, and only then is
+  /// the arrival clock taken. Any accepted packet resets it.
+  unsigned stamp_failures_ = 0;
   /// Arrival-clock origin: the first packet's receive time, so arrival stamps are
   /// small seconds (the time ring stores f32, which cannot hold Unix epochs).
   double arrival_epoch_ = 0.0;
   bool have_arrival_epoch_ = false;
   /// Smoothed interval between two frames' arrivals, and the previous arrival: the
-  /// spine of the arrival-anchored clock (see `build_stamps`).
+  /// spine of the arrival-anchored clock (see `build_stamps`). In relative mode no frame
+  /// reaches that branch, so `on_data` keeps the same pair up to date itself -- the
+  /// reservation's plausibility test below needs a measured cadence whatever clock the
+  /// user chose, and the two writers are mutually exclusive by mode.
   double arrival_interval_ = 0.0;
   double arrival_prev_ = 0.0;
   bool have_arrival_interval_ = false;
+  /// The previous *accepted* frame's receive time, for the one measurement the reservation
+  /// test needs: how much wall time actually passed. Kept apart from `arrival_prev_` on
+  /// purpose -- that one is the arrival clock's own bookkeeping and is re-anchored by the
+  /// clock-choice code, while this is a bare witness of the wire and must never be moved by
+  /// a mode change.
+  double prev_frame_recv_ = 0.0;
+  bool have_prev_frame_recv_ = false;
   /// The stream's time source, chosen once and sticky: 0 undecided, 1 the declared
   /// time signal, 2 arrival. Re-evaluated only on a CONFIG. A per-frame choice
   /// interleaved two timelines in one ring -- some frames stamped from a declared
   /// signal carrying volt-like values, others from the arrival clock -- which is a
   /// time base no reader can make sense of (see `build_stamps`).
   int time_source_ = 0;
-  /// Set when the source changed under the recorded history: the rings have to be
+  /// Relative-time mode's clock: seconds since the stream began, accumulated at the interval
-  /// emptied before more samples go in.
+  /// the plan declares. Advanced by `lost * batch_` samples' worth for every packet the counter
-  bool history_reset_pending_ = false;
+  /// reports missing (before the frame's own samples) and then by the frame's own `n`, so it is
+  /// exactly `(counter * batch + sample_index) * dt` for a constant batch and degrades
+  /// gracefully when a frame's length disagrees.
+  ///
+  /// It is a **time**, not a position multiplied by the current plan's interval, and the
+  /// difference is the whole of one defect: a plan is rebuilt whenever the channel list changes
+  /// (a CONFIG, an enable, a session's math channel) and `Partition::base_dt` -- which is the
+  /// 1 kHz fallback until a *streamed* channel declares a rate -- can therefore change under a
+  /// running stream. With `position * dt` a plan that shortened the interval made every later
+  /// stamp *behind* the one already written, which the frame loop's monotonic clamp then held
+  /// for the rest of the run: the timeline stood still, the trigger's `history` never reached
+  /// its pre-window, and nothing was drawn (see `on_data`). Accumulated, a plan change is what
+  /// it is -- a slope change -- and the clock cannot go backwards.
+  double rel_base_s_ = 0.0;
+  /// Samples per DATA packet, fixed by the first frame. Only ever needed to size what is
+  /// *absent*: a delivered frame carries its own length. 0 until the first frame.
+  std::uint32_t batch_ = 0;
+  /// Latches the one warning about a frame whose length disagrees with the stream's first.
+  bool warned_batch_ = false;
+  /// The newest counter seen, and the hole's address. Tracked here rather than inferred from
+  /// `frame->lost` because a *late* frame's counter is behind the sequence and must not move
+  /// the mark forward.
+  std::uint32_t last_counter_ = 0;
+  bool have_counter_ = false;
+  /// Last absolute stamp written, epoch-relative, so a reserved hole can continue the
+  /// absolute clock at the declared cadence. The packets that would have carried the real
+  /// stamps never arrived, so a cadence continuation is the only honest value available.
+  double last_abs_stamp_ = 0.0;
+  /// Warn-once latch for a loss past the reservation cap. A member, not a function-local
+  /// `static`, matching the latch Task 2 added for the same reason.
+  bool warned_outage_ = false;
+  /// Warn-once latch for a reservation the arrival clock did not corroborate, or that the ring
+  /// could not hold (see `gap_plausible()`). Once per connection, like the two above.
+  bool warned_phantom_gap_ = false;
+  /// Warn-once latch for the one bridged packet whose time signal glitched.
+  bool warned_bridge_ = false;
+  /// Warn-once latch for the declared time signal failing for good, so the arrival clock is
+  /// taken instead.
+  bool warned_time_source_ = false;
+  /// Warn-once latch for a frame whose every stamp was held back by the frame loop's monotonic
+  /// clamp. The clamp exists for a stream clock that glitches; a *whole frame* behind the clock is
+  /// the timeline standing still, and while it lasts nothing is drawn and no trigger can latch.
+  bool warned_clock_stall_ = false;
+  /// Whether this connection has adopted its clock origin (`ScopeModel::set_epoch_if_unset()`).
+  /// A state and not `epoch() == 0.0`, which re-fires in relative mode -- where the first frame's
+  /// stamp *is* zero -- and moves the origin under the timeline. Per connection, like every other
+  /// piece of session state here: a new session's clock is a new clock.
+  bool epoch_adopted_ = false;
+  /// The re-plan generation this object last reacted to. The buffer is re-planned whenever the
+  /// model rebuilds it, and the state tied to the old store (`tick_` and the accumulators) is
+  /// reset when this falls behind `ScopeModel::plan_generation()`.
+  unsigned seen_plan_generation_ = 0;
   std::vector<double> stamps_;
+  std::vector<double> abs_stamps_;
   /// The decimation filter's state: a running sum per channel (and one for the shared
   /// clock) over the group of base samples that becomes one stored sample. A boxcar
   /// average, which is what turns decimation into a *resampling* rather than a stride:
@@ -100,7 +237,17 @@ class Acquisition {
   /// once the slot's samples have all been pushed. One entry per channel, refilled every slot.
   std::vector<f32> math_sample_;
   std::vector<std::uint64_t> value_acc_n_;
+  /// Per channel, `time_stride * stride[i] - 1`: the group boundary as a **mask**, so the
+  /// innermost loop tests `(tick & mask) == mask` instead of `tick % period == period - 1`.
+  /// The divisor is a runtime value, so that modulo compiled to a real 64-bit `div` once per
+  /// channel per *wire* sample -- the filter reads every sample by design, so it was the
+  /// producer's largest avoidable cost. Both factors are powers of two (`plan_partition()`
+  /// doubles `time_stride` from 1, and every `stride[i]` is 1), which is what makes the mask
+  /// equivalent; it is sized and filled with the accumulators below, so a re-plan cannot
+  /// leave it addressing the previous partition's groups.
+  std::vector<std::uint64_t> acc_mask_;
   double time_acc_ = 0.0;
+  double abs_time_acc_ = 0.0;
   std::uint64_t time_acc_n_ = 0;
   /// The partition the accumulators were sized for, so a re-plan resets them rather than
   /// averaging across the boundary.

src/capture.cpp

@@ -0,0 +1,238 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#include "capture.hpp"
+
+#include <fcntl.h>
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include <cstdio>
+#include <cstring>
+#include <ctime>
+
+#include <chrono>
+#include <vector>
+
+namespace udpscope {
+namespace {
+
+/// The file header is one 64-byte block: fixed fields first, zeroed padding after.
+constexpr std::uint64_t kHeaderBytes = 64;
+/// `seq` lives at the *end* of a slot, at a fixed offset, because the reader must
+/// find it without trusting any other field.
+constexpr std::uint64_t kSeqBytes = 8;
+
+void put_u32(std::uint8_t* p, std::uint32_t v) { std::memcpy(p, &v, 4); }
+void put_u16(std::uint8_t* p, std::uint16_t v) { std::memcpy(p, &v, 2); }
+void put_f64(std::uint8_t* p, double v) { std::memcpy(p, &v, 8); }
+std::uint32_t get_u32(const std::uint8_t* p) {
+  std::uint32_t v;
+  std::memcpy(&v, p, 4);
+  return v;
+}
+double get_f64(const std::uint8_t* p) {
+  double v;
+  std::memcpy(&v, p, 8);
+  return v;
+}
+
+double wall_seconds() {
+  struct timespec ts;
+  clock_gettime(CLOCK_REALTIME, &ts);
+  return double(ts.tv_sec) + double(ts.tv_nsec) * 1e-9;
+}
+
+/// `seq` is published with a release store *after* the bytes are down, so a reader
+/// that sees a non-zero `seq` sees the whole slot -- the reason no `fsync` is needed
+/// for the file to be readable after a crash. Plain __atomic builtins, not
+/// `std::atomic_ref`: the target is mmap'd memory the class does not own as an object.
+void publish_seq(std::uint8_t* slot, std::uint64_t seq) {
+  __atomic_store_n(reinterpret_cast<std::uint64_t*>(slot + kSlotBytes - kSeqBytes), seq,
+                   __ATOMIC_RELEASE);
+}
+
+std::uint64_t read_seq(const std::uint8_t* slot) {
+  return __atomic_load_n(reinterpret_cast<const std::uint64_t*>(slot + kSlotBytes - kSeqBytes),
+                         __ATOMIC_ACQUIRE);
+}
+
+}  // namespace
+
+void PacketCapture::set_error(const char* what) noexcept {
+  std::snprintf(error_, sizeof(error_), "%s", what);
+  error_set_.store(true, std::memory_order_release);
+}
+
+void PacketCapture::error(char* out, std::size_t cap) const noexcept {
+  if (cap == 0) return;
+  out[0] = '\0';
+  if (!error_set_.load(std::memory_order_acquire)) return;
+  std::snprintf(out, cap, "%s", error_);
+}
+
+bool PacketCapture::open(const std::string& path, std::uint32_t slot_count) {
+  close();
+  path_ = path;
+  slot_count_ = slot_count;
+  seq_ = 0;
+  cursor_ = 0;
+  stored_.store(0, std::memory_order_relaxed);
+  truncated_.store(0, std::memory_order_relaxed);
+  error_set_.store(false, std::memory_order_relaxed);
+
+  const std::chrono::steady_clock::time_point t0 = std::chrono::steady_clock::now();
+
+  // Keep the previous capture one deep: re-enabling must not destroy the capture the
+  // user enabled *for*. A failure here is reported, and the old previous kept.
+  std::string prev = path;
+  const std::size_t slash = prev.rfind('/');
+  const std::size_t dot = prev.rfind('.');
+  if (dot != std::string::npos && (slash == std::string::npos || dot > slash)) {
+    prev.insert(dot, "-prev");
+  } else {
+    prev += "-prev";
+  }
+  ::rename(path.c_str(), prev.c_str());
+
+  fd_ = ::open(path.c_str(), O_RDWR | O_CREAT | O_EXCL | O_CLOEXEC, 0600);
+  if (fd_ < 0) {
+    set_error(strerror(errno));
+    return false;
+  }
+
+  // Reserved, not sparse: a store into a page the filesystem cannot back raises
+  // SIGBUS and kills udpscope outright, and an out-of-space condition must be an
+  // error at the moment the user clicked, not a crash ten minutes later.
+  const std::uint64_t total = kHeaderBytes + std::uint64_t(slot_count) * kSlotBytes;
+  if (::posix_fallocate(fd_, 0, off_t(total)) != 0) {
+    set_error(strerror(errno));
+    ::close(fd_);
+    fd_ = -1;
+    ::unlink(path.c_str());
+    return false;
+  }
+
+  map_ = static_cast<std::uint8_t*>(
+      ::mmap(nullptr, total, PROT_READ | PROT_WRITE, MAP_SHARED, fd_, 0));
+  if (map_ == MAP_FAILED) {
+    map_ = nullptr;
+    set_error(strerror(errno));
+    ::close(fd_);
+    fd_ = -1;
+    ::unlink(path.c_str());
+    return false;
+  }
+  map_bytes_ = total;
+
+  std::uint8_t* h = map_;
+  std::memset(h, 0, kHeaderBytes);
+  std::memcpy(h, "UDPSCAP\0", 8);
+  put_u32(h + 8, 1);                      // version
+  put_u32(h + 12, slot_count);
+  put_u32(h + 16, kSlotBytes);
+  put_u32(h + 20, 0);                     // cursor: a hint, `seq` is the order
+  put_f64(h + 24, wall_seconds());        // the epoch recv_time is relative to
+  put_u32(h + 32, peer_addr_);
+  put_u16(h + 36, peer_port_);
+  put_u16(h + 38, 0);  // local_port: the client does not expose its own socket
+  const double ms =
+      std::chrono::duration<double, std::milli>(std::chrono::steady_clock::now() - t0).count();
+  open_ms_.store(ms, std::memory_order_relaxed);
+
+  enabled_.store(true, std::memory_order_release);
+  return true;
+}
+
+void PacketCapture::close() noexcept {
+  if (map_ != nullptr) {
+    ::munmap(map_, map_bytes_);
+    map_ = nullptr;
+  }
+  if (fd_ >= 0) {
+    ::close(fd_);
+    fd_ = -1;
+  }
+  map_bytes_ = 0;
+  enabled_.store(false, std::memory_order_relaxed);
+}
+
+void PacketCapture::store(const std::uint8_t* bytes, std::size_t len, double recv_time) noexcept {
+  if (!enabled_.load(std::memory_order_relaxed) || map_ == nullptr) return;
+
+  std::uint8_t* slot = map_ + kHeaderBytes + std::uint64_t(cursor_) * kSlotBytes;
+  std::uint32_t orig = std::uint32_t(len);
+  std::size_t fit = len;
+  if (fit > kMaxDatagramBytes) {
+    fit = kMaxDatagramBytes;
+    truncated_.fetch_add(1, std::memory_order_relaxed);
+  }
+
+  put_f64(slot, recv_time);
+  put_u32(slot + 8, std::uint32_t(fit));
+  put_u32(slot + 12, orig);
+  std::memcpy(slot + kRecordHeaderBytes, bytes, fit);
+  ++seq_;
+  publish_seq(slot, seq_);  // last: a non-zero `seq` is what makes a slot complete
+
+  cursor_ = (cursor_ + 1) % slot_count_;
+  put_u32(map_ + 20, cursor_);  // a hint for a human in xxd; `seq` is the order
+  stored_.fetch_add(1, std::memory_order_relaxed);
+}
+
+bool read_capture(const std::string& path, CaptureReadStats* out) {
+  if (out == nullptr) return false;
+  *out = CaptureReadStats{};
+
+  FILE* f = std::fopen(path.c_str(), "rb");
+  if (f == nullptr) return false;
+  std::fseek(f, 0, SEEK_END);
+  const long size = std::ftell(f);
+  std::fseek(f, 0, SEEK_SET);
+  out->file_bytes = std::uint64_t(size < 0 ? 0 : size);
+
+  std::uint8_t h[kHeaderBytes];
+  if (std::fread(h, 1, sizeof(h), f) != sizeof(h)) {
+    std::fclose(f);
+    return false;
+  }
+  out->header_ok = std::memcmp(h, "UDPSCAP\0", 8) == 0 && get_u32(h + 8) == 1;
+  out->slot_count = get_u32(h + 12);
+  out->slot_bytes = get_u32(h + 16);
+  out->cursor = get_u32(h + 20);
+  out->t0_realtime = get_f64(h + 24);
+  if (!out->header_ok || out->slot_count == 0 || out->slot_bytes < kRecordHeaderBytes + 8) {
+    std::fclose(f);
+    return false;
+  }
+
+  const std::uint32_t payload = out->slot_bytes - kRecordHeaderBytes - kSeqBytes;
+  std::vector<std::uint8_t> slot(out->slot_bytes);
+  for (std::uint32_t i = 0; i < out->slot_count; ++i) {
+    if (std::fseek(f, long(kHeaderBytes + std::uint64_t(i) * out->slot_bytes), SEEK_SET) != 0) {
+      break;
+    }
+    if (std::fread(slot.data(), 1, slot.size(), f) != slot.size()) break;
+    const std::uint64_t seq = read_seq(slot.data());
+    const std::uint32_t len = get_u32(slot.data() + 8);
+    const std::uint32_t orig = get_u32(slot.data() + 12);
+    if (seq == 0 && len == 0 && orig == 0) {
+      ++out->empty;
+      continue;
+    }
+    if (seq == 0) {
+      ++out->torn;  // bytes down, ordinal never published: a capture that died mid-copy
+      continue;
+    }
+    ++out->stored;
+    out->payload += len;
+    if (orig > payload) ++out->truncated;
+    if (out->first_seq == 0 || seq < out->first_seq) out->first_seq = seq;
+    if (seq > out->last_seq) out->last_seq = seq;
+  }
+  std::fclose(f);
+  return true;
+}
+
+}  // namespace udpscope

src/capture.hpp

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#pragma once
+
+#include <atomic>
+#include <cstdint>
+#include <string>
+
+namespace udpscope {
+
+/// The largest datagram the client's socket can deliver, and therefore the payload
+/// capacity of one capture slot. Kept equal to the client's own receive buffer: an
+/// over-long datagram is impossible by construction, and `store()` counts the
+/// impossibility rather than trusting it.
+inline constexpr std::uint32_t kMaxDatagramBytes = 65535 + 17;
+
+/// One slot's stride: the fixed record header, the largest datagram, and the `seq`
+/// word that is written last. 8-byte aligned.
+inline constexpr std::uint32_t kRecordHeaderBytes = 16;  ///< t_arrival f64, len u32, orig_len u32
+inline constexpr std::uint32_t kSlotBytes =
+    kRecordHeaderBytes + kMaxDatagramBytes + 8;  ///< the trailing 8 are `seq`
+
+/// Owns the ring file a packet capture stores raw datagrams into, and stores a
+/// datagram into it. It includes no GTK, no `ScopeModel`, and no client types: its
+/// whole world is bytes, a clock reading and one file.
+///
+/// Everything here runs on the producer thread except `open()`'s caller choice and
+/// the GTK thread's reads of the counters and the error, which are publishable
+/// without a lock: see the field table in the design note
+/// (`docs/superpowers/specs/2026-10-09-udp-packet-capture-design.md`).
+class PacketCapture {
+ public:
+  PacketCapture() = default;
+  ~PacketCapture() { close(); }
+
+  PacketCapture(const PacketCapture&) = delete;
+  PacketCapture& operator=(const PacketCapture&) = delete;
+
+  /// Renames an existing capture to `<path>` minus extension plus `-prev.bin`,
+  /// creates and reserves the new file, maps it, writes the header. Returns false
+  /// and leaves the object disabled on any failure, with `error()` set.
+  bool open(const std::string& path, std::uint32_t slot_count);
+
+  /// Unmaps and closes. Idempotent; keeps the counters, which read "since open()".
+  void close() noexcept;
+
+  bool enabled() const noexcept { return enabled_.load(std::memory_order_relaxed); }
+
+  /// One datagram. Called only from the producer thread. Never allocates, never
+  /// blocks, never fails: an over-long datagram is truncated to the slot and counted.
+  void store(const std::uint8_t* bytes, std::size_t len, double recv_time) noexcept;
+
+  std::uint64_t stored() const noexcept { return stored_.load(std::memory_order_relaxed); }
+  std::uint64_t truncated() const noexcept {
+    return truncated_.load(std::memory_order_relaxed);
+  }
+  std::uint32_t slot_count() const noexcept { return slot_count_; }
+  const std::string& path() const noexcept { return path_; }
+
+  /// The source's IPv4, in network order, and its port: written into the header at
+  /// open() so the pcap converter can synthesise a UDP header. Call before open(),
+  /// from the thread that owns the decision -- the same write-once discipline as the
+  /// path. `local_port` stays zero: the client does not expose its own socket.
+  void set_peer(std::uint32_t addr_net_order, std::uint16_t port) noexcept {
+    peer_addr_ = addr_net_order;
+    peer_port_ = port;
+  }
+
+  /// Wall milliseconds `open()` took, measured rather than asserted: the one cost a
+  /// toggle has, and a reading above ~50 ms is a finding about the filesystem.
+  double open_ms() const noexcept { return open_ms_.load(std::memory_order_relaxed); }
+
+  /// Copies the last open() failure out, or writes an empty string. Deliberately not
+  /// a `const std::string&`: the producer writes the fixed buffer and *then* publishes
+  /// the flag with a release store, and the GTK thread copies only when the flag reads
+  /// true -- a `std::string` shared like that is a data race with a reallocating
+  /// buffer, the kind that reads correctly for months.
+  void error(char* out, std::size_t cap) const noexcept;
+
+ private:
+  void set_error(const char* what) noexcept;
+
+  std::string path_;
+  std::uint32_t slot_count_ = 0;
+  int fd_ = -1;
+  std::uint8_t* map_ = nullptr;      ///< whole file, header first
+  std::uint64_t map_bytes_ = 0;
+  std::uint64_t seq_ = 0;            ///< 1-based ordinal since open(); producer-only
+  std::uint32_t cursor_ = 0;         ///< next slot index to write; producer-only
+  std::uint32_t peer_addr_ = 0;      ///< the source's IPv4, network order
+  std::uint16_t peer_port_ = 0;
+  std::atomic<bool> enabled_{false};
+  std::atomic<std::uint64_t> stored_{0};
+  std::atomic<std::uint64_t> truncated_{0};
+  std::atomic<bool> error_set_{false};
+  std::atomic<double> open_ms_{0.0};
+  mutable char error_[128] = {0};
+};
+
+/// What a capture file says when read back off disk. `stored` counts slots with a
+/// non-zero `seq`; `torn` counts slots with bytes but no `seq` (a capture that died
+/// mid-copy); `empty` counts all-zero slots, which a freshly reserved file is full of.
+struct CaptureReadStats {
+  bool header_ok = false;
+  std::uint32_t slot_count = 0;
+  std::uint32_t slot_bytes = 0;
+  std::uint32_t cursor = 0;
+  double t0_realtime = 0.0;
+  std::uint64_t stored = 0;
+  std::uint64_t torn = 0;
+  std::uint64_t empty = 0;
+  std::uint64_t truncated = 0;  ///< slots whose `orig_len` exceeds the payload capacity
+  std::uint64_t payload = 0;    ///< sum of stored slots' `len`: the bytes the wire delivered
+  std::uint64_t first_seq = 0;
+  std::uint64_t last_seq = 0;
+  std::uint64_t file_bytes = 0;
+};
+
+/// Reads a capture file back and validates it. Pure POSIX plus `<cstdio>`; used by the
+/// headless probe, and `tools/capture_to_pcap.py` re-implements the walk in Python.
+bool read_capture(const std::string& path, CaptureReadStats* out);
+
+}  // namespace udpscope

src/channel.cpp

@@ -31,10 +31,9 @@ ChannelBuffer::ChannelBuffer(std::shared_ptr<const plot::data::RingBuffer<f32>>
 
 void ChannelBuffer::acquire() noexcept {
   const u64 produced = values_->produced();
-  if (produced <= published_) {
+  // Nothing new skips the append pass only: the backfill drain at the end of this function
-    // Nothing new; still allow the window to slide if another reader dropped it.
+  // runs either way, because a late packet can land in a frame interval that pushed nothing.
-    return;
+  if (produced > published_) {
-  }
     // A producer that lapped this ring -- a long trigger wait, or a store that was
     // not being published for a while -- makes the incremental append meaningless:
     // the samples between `published_` and `produced_` are no longer in the ring.
@@ -60,12 +59,35 @@ void ChannelBuffer::acquire() noexcept {
     // window is pinned by the line above, so its origin is a fixed sample, and this is the one
     // place in the object's life where that sample's slot is safe to read.
     if (pyramid_.size() > 0) window_x0_ = time_of(absolute(0));
+  }
+  // Backfills, applied after the append pass above: an amend is only ever queued for a slot
+  // the value ring already produced, so the append has reached it and the pyramid's bounds
+  // test will accept it. Unconditional, outside the `produced > published_` guard -- a late
+  // packet can land in a frame interval that pushed nothing new, and the plan's placement
+  // behind the old early return would have left the pyramid stale until the next push.
+  if (!pending_amends_.empty()) {
+    for (const Amend& a : pending_amends_) pyramid_.amend(a.absolute, a.value);
+    pending_amends_.clear();
+  }
 }
 
 void ChannelBuffer::invalidate() noexcept {
   published_ = 0;
   window_x0_ = 0.0;
   pyramid_.clear();
+  pending_amends_.clear();
+}
+
+void ChannelBuffer::republish_from(u64 absolute) noexcept {
+  published_ = absolute;
+  window_x0_ = 0.0;
+  pending_amends_.clear();
+  // `clear()` leaves the pyramid empty at absolute 0, and `drop_before()` past the end
+  // restarts an empty window at the index it is given -- which is the only way to say
+  // "nothing is published, and the next append is sample `absolute`". The no-op guard is
+  // for `absolute == 0`, where `clear()` has already said exactly that.
+  pyramid_.clear();
+  if (absolute > 0) pyramid_.drop_before(absolute);
 }
 
 f64 ChannelBuffer::time_of(u64 absolute_index) const noexcept {

src/channel.hpp

@@ -48,6 +48,27 @@ class ChannelBuffer final : public plot::data::Series {
   void acquire() noexcept;
   /// Consumer thread: forgets the published window (after a rebind or a reset).
   void invalidate() noexcept;
+  /// Consumer thread: drops the published window and re-publishes it from absolute sample
+  /// `absolute` on the next `acquire()`.
+  ///
+  /// For a ring whose contents were *rewritten in place* rather than appended to -- a math
+  /// channel recomputed over its inputs' retained window. `acquire()` is incremental, so
+  /// a rewrite that leaves `produced()` where it was publishes nothing and the pyramid goes
+  /// on describing the samples the edit replaced. `invalidate()` would do it too, but it
+  /// restarts at 0 and `acquire()` would then walk every absolute index ever produced; this
+  /// restarts at the oldest index the ring still holds, so the rebuild is one window.
+  void republish_from(u64 absolute) noexcept;
+
+  /// Producer thread, under `ScopeModel::mutex()`: records that absolute sample `absolute`
+  /// has been backfilled, for `acquire()` to fold into the pyramid.
+  ///
+  /// The pyramid is mutated *only* on the consumer thread, because a bucket is a 32-byte
+  /// non-atomic aggregate the renderer reads unlocked at paint time: amending it from the
+  /// producer would let a reader see a half-updated bucket whose `sum` did not match its
+  /// `count`, which is a wrong mean out of a structure whose readers trust `count == 0` to
+  /// mean absent. The value ring is amended by the producer, which owns its writes; the
+  /// pyramid waits for here.
+  void queue_amend(u64 absolute, f32 v) { pending_amends_.push_back({absolute, v}); }
 
   void set_nominal_dt(f64 dt) noexcept { dt_ = dt; }
   /// Re-bases the x axis: `x0()`/`x_at()` become `epoch + timestamp`. Used to make
@@ -100,6 +121,13 @@ class ChannelBuffer final : public plot::data::Series {
   /// Timestamp of channel sample `absolute_index`, in seconds since `epoch_`.
   f64 time_of(u64 absolute_index) const noexcept;
 
+  struct Amend {
+    u64 absolute;
+    f32 value;
+  };
+  /// Backfills the producer has written into the value ring and the pyramid has not seen yet.
+  std::vector<Amend> pending_amends_;
+
   std::shared_ptr<const plot::data::RingBuffer<f32>> values_;
   std::shared_ptr<const plot::data::RingBuffer<f64>> times_;
   u64 stride_ = 1;

src/condition.cpp

@@ -0,0 +1,207 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#include "condition.hpp"
+
+#include <cmath>
+
+namespace udpscope {
+
+void EventDetector::configure(const EventCondition& c, double dt) noexcept {
+  if (c == cond_ && dt == dt_) return;
+  cond_ = c;
+  dt_ = dt;
+  // a = 1 - exp(-2*pi*fc*dt), clamped just under Nyquist so a never exceeds 1.
+  // fc == 0 leaves a == 1, which is a pass-through.
+  pole_a_ = 1.0;
+  if (cond_.hf_fc > 0.0 && dt > 0.0) {
+    const double nyquist = 0.5 / dt;
+    const double fc = cond_.hf_fc < nyquist * 0.99 ? cond_.hf_fc : nyquist * 0.99;
+    pole_a_ = 1.0 - std::exp(-2.0 * 3.14159265358979323846 * fc * dt);
+  }
+  reset();
+}
+
+void EventDetector::reset() noexcept {
+  have_prev_ = false;
+  prev_ = 0.0;
+  in_pulse_ = false;
+  pulse_up_ = false;
+  pulse_start_s_ = 0.0;
+  inside_ = false;
+  last_cross_s_ = 0.0;
+  dropped_ = false;
+  pole_y_ = 0.0;
+  pole_have_ = false;
+  side_ = 0;
+}
+
+double EventDetector::filter(double v) noexcept {
+  // A NaN must stay a NaN and must not poison the state: a dropout is a real
+  // reading here, not an error.
+  if (!std::isfinite(v)) return v;
+  if (!pole_have_) {
+    pole_y_ = v;
+    pole_have_ = true;
+    return pole_y_;
+  }
+  pole_y_ += pole_a_ * (v - pole_y_);
+  return pole_y_;
+}
+
+void EventDetector::decide(double v, bool& up, bool& down) noexcept {
+  up = false;
+  down = false;
+  if (cond_.noise_band <= 0.0) {
+    up = crossed_up(v);
+    down = crossed_down(v);
+    return;
+  }
+  // A Schmitt trigger: a sample inside the band decides nothing, and a crossing
+  // is a change between two *decided* sides. Seeding from the undecided side
+  // would fire on a signal that starts inside the band and leaves it without
+  // ever reaching `level`.
+  const int was = side_;
+  if (v >= cond_.level + cond_.noise_band) side_ = 1;
+  else if (v <= cond_.level - cond_.noise_band) side_ = -1;
+  up = was == -1 && side_ == 1;
+  down = was == 1 && side_ == -1;
+}
+
+double EventDetector::feed(double value, double t) noexcept {
+  value = filter(value);
+  if (!have_prev_) {
+    prev_ = value;
+    have_prev_ = true;
+    // The window condition needs a side to change *from*, and the dropout a last-seen time
+    // to count from; neither can be derived from a crossing that has not happened. Seeding
+    // them here is what lets both handlers run without a "have we started" guard.
+    const double lo = cond_.level < cond_.level2 ? cond_.level : cond_.level2;
+    const double hi = cond_.level < cond_.level2 ? cond_.level2 : cond_.level;
+    inside_ = value >= lo && value <= hi;
+    last_cross_s_ = t;
+    dropped_ = false;
+    return kNoEvent;
+  }
+  double event = kNoEvent;
+  switch (cond_.type) {
+    case TriggerType::Edge:
+      event = feed_edge(value, t);
+      break;
+    case TriggerType::PulseWidth:
+      event = feed_pulse(value, t);
+      break;
+    case TriggerType::Window:
+      event = feed_window(value, t);
+      break;
+    case TriggerType::Dropout:
+      event = feed_dropout(value, t);
+      break;
+  }
+  // After the handler: every crossing test above reads `prev_` as the previous sample.
+  prev_ = value;
+  return event;
+}
+
+double EventDetector::feed_edge(double value, double t) noexcept {
+  bool up = false;
+  bool down = false;
+  decide(value, up, down);
+  const bool fired = (cond_.edge == TriggerEdge::Rising && up) ||
+                     (cond_.edge == TriggerEdge::Falling && down) ||
+                     (cond_.edge == TriggerEdge::Both && (up || down));
+  return fired ? t : kNoEvent;
+}
+
+bool EventDetector::qualifies(double width_s) const noexcept {
+  const double a = cond_.width_s < cond_.width2_s ? cond_.width_s : cond_.width2_s;
+  const double b = cond_.width_s < cond_.width2_s ? cond_.width2_s : cond_.width_s;
+  switch (cond_.cmp) {
+    case WidthCmp::Less:
+      return width_s < cond_.width_s;
+    case WidthCmp::Greater:
+      return width_s > cond_.width_s;
+    case WidthCmp::Within:
+      return width_s >= a && width_s <= b;
+    case WidthCmp::Outside:
+      return width_s < a || width_s > b;
+  }
+  return false;
+}
+
+double EventDetector::feed_pulse(double value, double t) noexcept {
+  const bool up = crossed_up(value);
+  const bool down = crossed_down(value);
+  if (!in_pulse_) {
+    // Which crossing opens a pulse is what `edge` selects: Rising measures the time spent
+    // above the level, Falling the time below, Both every excursion either way.
+    const bool opens = (cond_.edge == TriggerEdge::Rising && up) ||
+                       (cond_.edge == TriggerEdge::Falling && down) ||
+                       (cond_.edge == TriggerEdge::Both && (up || down));
+    if (opens) {
+      in_pulse_ = true;
+      pulse_up_ = up;
+      pulse_start_s_ = t;
+    }
+    return kNoEvent;
+  }
+  const bool closes = pulse_up_ ? down : up;
+  if (!closes) return kNoEvent;
+  const double width = t - pulse_start_s_;
+  if (cond_.edge == TriggerEdge::Both) {
+    // The closing edge of one excursion is the opening edge of the next, so a square wave
+    // measures *every* half-period. Dropping the state here instead would measure every
+    // other one, and the hits would come out half as dense as the waveform.
+    pulse_up_ = !pulse_up_;
+    pulse_start_s_ = t;
+  } else {
+    in_pulse_ = false;
+  }
+  return qualifies(width) ? t : kNoEvent;
+}
+
+double EventDetector::feed_window(double value, double t) noexcept {
+  const double lo = cond_.level < cond_.level2 ? cond_.level : cond_.level2;
+  const double hi = cond_.level < cond_.level2 ? cond_.level2 : cond_.level;
+  // The band is applied on the edge the signal must *leave*, and clamped to just
+  // under half the window so `lo + band` can never pass `hi - band`.
+  double band = cond_.noise_band > 0.0 ? cond_.noise_band : 0.0;
+  const double room = 0.49 * (hi - lo);
+  if (band > room) band = room;
+  const bool inside = inside_ ? (value >= lo - band && value <= hi + band)
+                              : (value >= lo + band && value <= hi - band);
+  if (inside == inside_) return kNoEvent;
+  inside_ = inside;
+  // The event is the *change of side*, so `Rising` reads as "into the band" and `Falling`
+  // as "out of it". A band of zero width is not a band: `inside` reduces to an exact
+  // float-equality test against the level, so the condition fires on none of an ordinary
+  // signal's samples and on every transition of one that sits exactly at the level -- a
+  // +/-1 square against a band of [1, 1] fired 19 times in a standalone check. Neither
+  // answer is a band, so the panel refuses one.
+  const bool fired = (cond_.edge == TriggerEdge::Rising && inside) ||
+                     (cond_.edge == TriggerEdge::Falling && !inside) ||
+                     cond_.edge == TriggerEdge::Both;
+  return fired ? t : kNoEvent;
+}
+
+double EventDetector::feed_dropout(double value, double t) noexcept {
+  const bool up = crossed_up(value);
+  const bool down = crossed_down(value);
+  const bool crossed = (cond_.edge == TriggerEdge::Rising && up) ||
+                       (cond_.edge == TriggerEdge::Falling && down) ||
+                       (cond_.edge == TriggerEdge::Both && (up || down));
+  if (crossed) {
+    last_cross_s_ = t;
+    dropped_ = false;
+    return kNoEvent;
+  }
+  // One event per silence, not one per sample of it: without the latch a dead signal would
+  // report an event on every sample after the timeout and fill the search's hit list with
+  // one answer repeated.
+  if (dropped_) return kNoEvent;
+  if (t - last_cross_s_ <= cond_.timeout_s) return kNoEvent;
+  dropped_ = true;
+  return t;
+}
+
+}  // namespace udpscope

src/condition.hpp

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#pragma once
+
+#include <limits>
+
+namespace udpscope {
+
+/// Which way through a level counts. Shared by every condition type: for `Window` it is
+/// the direction through the *band* (into it, out of it, or either), and for `Dropout` it
+/// selects which crossings count as the signal still being alive.
+///
+/// It lives here rather than in `trigger.hpp` because the buffer search needs the
+/// evaluator without the engine's arming state.
+enum class TriggerEdge { Rising, Falling, Both };
+
+/// What shape in the signal counts as an event.
+enum class TriggerType { Edge, PulseWidth, Window, Dropout };
+
+/// How a measured pulse width is compared with the condition's bounds. `Less` is the
+/// glitch trigger: "a pulse shorter than it should be".
+enum class WidthCmp { Less, Greater, Within, Outside };
+
+/// Everything that decides whether a sample is an event. No arming, no capture window:
+/// those belong to `TriggerConfig`.
+struct EventCondition {
+  TriggerType type = TriggerType::Edge;
+  double level = 0.0;
+  double level2 = 0.0;               ///< Window: the band's other edge. Ignored otherwise.
+  TriggerEdge edge = TriggerEdge::Rising;
+  WidthCmp cmp = WidthCmp::Greater;  ///< PulseWidth only.
+  double width_s = 1.0e-3;           ///< PulseWidth only.
+  double width2_s = 2.0e-3;          ///< PulseWidth, Within/Outside only.
+  double timeout_s = 1.0e-3;         ///< Dropout only.
+  /// Half-width of the amplitude band around `level` a sample must leave before
+  /// a crossing counts. 0 is the bare comparator. In signal units.
+  double noise_band = 0.0;
+  /// Corner of a one-pole low pass applied to the sample before any comparison.
+  /// 0 is off. In Hz.
+  double hf_fc = 0.0;
+
+  bool operator==(const EventCondition& o) const noexcept {
+    return type == o.type && level == o.level && level2 == o.level2 && edge == o.edge &&
+           cmp == o.cmp && width_s == o.width_s && width2_s == o.width2_s &&
+           timeout_s == o.timeout_s && noise_band == o.noise_band && hf_fc == o.hf_fc;
+  }
+  bool operator!=(const EventCondition& o) const noexcept { return !(*this == o); }
+};
+
+/// The event condition's state machine: one sample in, an event time or nothing out.
+///
+/// It holds no arming state and no capture state -- that is `TriggerEngine`'s job -- which
+/// is what lets the buffer search run the *same* evaluator over retained samples and get
+/// the answers the live trigger would have given.
+///
+/// Every condition but `Edge` is sequential: a pulse's width is only known at its closing
+/// edge, and a dropout is a measured absence. Callers must therefore feed it **every**
+/// sample in stream order, including samples they intend to ignore; a gap is a pulse it can
+/// never close.
+class EventDetector {
+ public:
+  /// What `feed()` returns when the sample is not an event.
+  static constexpr double kNoEvent = std::numeric_limits<double>::quiet_NaN();
+
+  /// Re-applying the same condition is a no-op, deliberately: the producer calls this on
+  /// every packet, and resetting there would restart the machine before any pulse could
+  /// close. A genuinely different condition resets, because its state means nothing.
+  ///
+  /// `dt` is the stored sample interval (`Partition::slot_dt()`), needed for the
+  /// HF reject's pole. A no-op unless the condition or the interval changed.
+  void configure(const EventCondition& c, double dt) noexcept;
+  void reset() noexcept;
+
+  /// One sample, in stream order. Returns the event's own stream time, or `kNoEvent`.
+  ///
+  /// There is no finite-value check: a NaN sample is benign here (every comparison against
+  /// it is false, so it cannot fire), and rejecting one would leave `prev_` at the last good
+  /// value and let the sample *after* the NaN fire a crossing that today cannot happen.
+  double feed(double value, double t) noexcept;
+
+  double last_value() const noexcept { return prev_; }
+  bool have_last() const noexcept { return have_prev_; }
+
+ private:
+  bool crossed_up(double v) const noexcept {
+    return prev_ < cond_.level && v >= cond_.level;
+  }
+  bool crossed_down(double v) const noexcept {
+    return prev_ > cond_.level && v <= cond_.level;
+  }
+  /// The HF reject, applied to every sample before any comparison.
+  double filter(double v) noexcept;
+  /// `up`/`down` for the edge condition, through the band if there is one.
+  void decide(double v, bool& up, bool& down) noexcept;
+  double feed_edge(double value, double t) noexcept;
+  double feed_pulse(double value, double t) noexcept;
+  double feed_window(double value, double t) noexcept;
+  double feed_dropout(double value, double t) noexcept;
+  /// Whether a measured width satisfies `cond_.cmp`. `Within`/`Outside` take their two
+  /// bounds in either order, so a panel cannot make an empty band by typing the larger
+  /// figure into the first spin.
+  bool qualifies(double width_s) const noexcept;
+
+  EventCondition cond_{};
+  bool have_prev_ = false;
+  double prev_ = 0.0;
+  bool in_pulse_ = false;      ///< PulseWidth: an opening edge has been seen.
+  bool pulse_up_ = false;      ///< PulseWidth: its polarity, so we know which edge closes it.
+  double pulse_start_s_ = 0.0;
+  bool inside_ = false;        ///< Window: which side of the band the previous sample was.
+  double last_cross_s_ = 0.0;  ///< Dropout: when the signal was last seen crossing.
+  bool dropped_ = false;       ///< Dropout: the timeout has already been reported.
+  /// One-pole prefilter. `pole_a_ == 1` passes the input through, so "off"
+  /// costs no branch. `pole_y_` is the filtered value.
+  double dt_ = 0.0;
+  double pole_a_ = 1.0;
+  double pole_y_ = 0.0;
+  bool pole_have_ = false;
+  /// Which side of the band the signal was last *decided* to be on: +1 above,
+  /// -1 below, 0 undecided. A sample inside the band decides nothing.
+  int side_ = 0;
+};
+
+}  // namespace udpscope

src/config.cpp

@@ -6,6 +6,7 @@
 // For `RowSet::kMaxRows`: `--plots` names a row count, and one constant for the ceiling
 // is what stops the message and the clamp from drifting apart.
 #include "plot_host.hpp"
+#include "source/registry.hpp"
 
 #include <cstdio>
 #include <cstdlib>
@@ -40,22 +41,57 @@ double parse_double(const char* name, const std::string& v) {
 
 }  // namespace
 
+SourceConfig Config::source_config() const {
+  SourceConfig out;
+  if (source_kind == "udps") {
+    out.set("server", server);
+    out.set("port", std::to_string(port));
+    if (!multicast.empty()) out.set("multicast", multicast);
+    if (!interface_addr.empty()) out.set("interface", interface_addr);
+    out.set("recv_buffer", std::to_string(recv_buffer_bytes));
+  }
+  for (const auto& kv : source_opts.items()) out.set(kv.first, kv.second);
+  return out;
+}
+
+std::string Config::session_host() const { return udpscope::session_host(source_kind, source_config()); }
+std::uint16_t Config::session_port() const { return udpscope::session_port(source_kind, source_config()); }
+
 void print_usage(std::FILE* out, const char* argv0) {
+  std::string names;
+  for (const SourceKind* k : kinds()) names += (names.empty() ? "" : ", ") + k->id();
   std::fprintf(out,
-               "usage: %s --server ADDR --port PORT [options]\n"
+               "usage: %s --server ADDR --port PORT [--source NAME] [options]\n"
                "\n"
                "  --server ADDR        stream source IPv4 address (default 127.0.0.1)\n"
                "  --port PORT          UDP port (unicast) or TCP port (multicast) (default 8000)\n"
                "  --multicast GROUP    join GROUP for DATA instead of unicast\n"
                "  --interface ADDR     local IPv4 of the interface to join on\n"
+               "  --source NAME        source kind (%s; default udps). --server/--port/\n"
+               "                       --multicast/--interface configure udps\n"
+               "  --source-opt K=V     a setting for the source kind; repeatable\n"
                "  --buffer-mb MB       size of each of the two sample buffers (default 200)\n"
                "  --max-window SEC     largest time window the toolbar offers (default 600)\n"
                "  --holdoff SEC        default trigger hold-off (default 0.010)\n"
                "  --recv-buffer BYTES  SO_RCVBUF for the receiver socket (default 8388608)\n"
                "  --plots N            stacked plots to start with, 1..8 (default 1); rows are\n"
                "                       added and removed from the layout editor\n"
+               "  --capture-packets N  store the last N raw datagrams on disk for forensics, in a\n"
+               "                       ring under the cache directory (1000 slots is ~62.6 MiB);\n"
+               "                       off unless given, and toggleable from the status bar\n"
+               "  --relative-time      take the plot's time from the packet counter and the\n"
+               "                       declared rate, not the stream's time signal; absolute\n"
+               "                       time is then kept for export only\n"
+               "  --open FILE          open an exported waveform (.npy) instead of a live source:\n"
+               "                       signals from its columns, no socket, no acquisition\n"
+               "  --renderer NAME      render with cairo (software), gl or vulkan. cairo also\n"
+               "                       exports LIBGL_ALWAYS_SOFTWARE=1, because the plot is a\n"
+               "                       GtkGLArea and still needs a GL context. Over SSH/X11\n"
+               "                       forwarding use cairo: Vulkan cannot make a swapchain there\n"
+               "                       and the GL area has no hardware context, so the window\n"
+               "                       never paints or allocates\n"
                "  -h, --help           this text\n",
-               argv0);
+               argv0, names.c_str());
 }
 
 Config parse_args(int argc, char** argv) {
@@ -77,8 +113,21 @@ Config parse_args(int argc, char** argv) {
       c.multicast = value_of(argc, argv, i, "--multicast");
     } else if (a == "--interface" || a.rfind("--interface=", 0) == 0) {
       c.interface_addr = value_of(argc, argv, i, "--interface");
+    } else if (a == "--source" || a.rfind("--source=", 0) == 0) {
+      const std::string v = value_of(argc, argv, i, "--source");
+      if (find_kind(v) == nullptr) {
+        std::string names;
+        for (const SourceKind* k : kinds()) names += (names.empty() ? "" : ", ") + k->id();
+        fail("unknown source '" + v + "' (available: " + names + ")");
+      }
+      c.source_kind = v;
+      c.source_specified = true;
+    } else if (a == "--source-opt" || a.rfind("--source-opt=", 0) == 0) {
+      const std::string v = value_of(argc, argv, i, "--source-opt");
+      if (!c.source_opts.parse_assignment(v)) fail("--source-opt must be key=value: " + v);
     } else if (a == "--buffer-mb" || a.rfind("--buffer-mb=", 0) == 0) {
       c.buffer_mb = parse_double("--buffer-mb", value_of(argc, argv, i, "--buffer-mb"));
+      c.buffer_mb_specified = true;
       if (c.buffer_mb < 1.0) fail("--buffer-mb must be at least 1");
     } else if (a == "--max-window" || a.rfind("--max-window=", 0) == 0) {
       c.max_window_s = parse_double("--max-window", value_of(argc, argv, i, "--max-window"));
@@ -98,6 +147,24 @@ Config parse_args(int argc, char** argv) {
         fail("--plots must be 1.." + std::to_string(RowSet::kMaxRows) + ": " + v);
       }
       c.plots = static_cast<int>(n);
+    } else if (a == "--capture-packets" || a.rfind("--capture-packets=", 0) == 0) {
+      const long n = std::strtol(value_of(argc, argv, i, "--capture-packets").c_str(), nullptr, 10);
+      if (n < 1 || n > 100000) fail("--capture-packets must be 1..100000");
+      c.capture_packets = static_cast<std::uint32_t>(n);
+    } else if (a == "--open" || a.rfind("--open=", 0) == 0) {
+      c.open_waveform = value_of(argc, argv, i, "--open");
+    } else if (a == "--renderer" || a.rfind("--renderer=", 0) == 0) {
+      const std::string v = value_of(argc, argv, i, "--renderer");
+      // Only the three a source or a forwarded display actually chooses between. Anything
+      // GTK does not know would fall back with a warning and leave the user reading a
+      // renderer failure that is really a typo, so it is refused here instead.
+      if (v != "cairo" && v != "gl" && v != "vulkan") {
+        fail("--renderer must be cairo, gl or vulkan: " + v);
+      }
+      c.renderer = v;
+    } else if (a == "--relative-time") {
+      c.relative_time = true;
+      c.relative_time_specified = true;
     } else {
       fail("unknown argument: " + a);
     }

src/config.hpp

@@ -6,6 +6,8 @@
 #include <cstdint>
 #include <string>
 
+#include "source/source_config.hpp"
+
 namespace udpscope {
 
 /// Everything the command line can say. Defaults are the ones the spec names
@@ -21,9 +23,30 @@ struct Config {
   /// `server` valid". The default stays a usable value for every other path.
   bool server_specified = false;
 
+  /// `--source NAME`: which registered kind opens. `udps` is the default, and `--server/--port/
+  /// --multicast/--interface` keep meaning UDPS.
+  std::string source_kind = "udps";
+  /// Whether `--source` was given (the other half of "did the user choose a source").
+  bool source_specified = false;
+  /// Repeatable `--source-opt k=v`: the kind's own settings. For `udps` they overlay the fields above.
+  SourceConfig source_opts;
+
+  /// A source was named on the command line (`--server` or `--source`), so the chooser is skipped.
+  bool has_source() const noexcept { return server_specified || source_specified; }
+  /// The settings the kind's `make()` receives: for UDPS the four connection fields plus the receive
+  /// buffer, then `source_opts` on top.
+  SourceConfig source_config() const;
+  /// The (host, port) that name this source's session file; see `session_host()` in the registry.
+  std::string session_host() const;
+  std::uint16_t session_port() const;
+
   /// Size of *each* of the two sample buffers, in megabytes. The application
   /// always allocates two identical buffers (spec item 1).
   double buffer_mb = 200.0;
+  /// Whether `--buffer-mb` was given. A stored configuration's buffer size fills in only when the
+  /// flag was *absent*: an explicit flag beats a saved setting, and "not asked" is not the same
+  /// question as "asked for 200".
+  bool buffer_mb_specified = false;
 
   /// Largest time window the toolbar offers, in seconds. The buffer partition is
   /// sized to hold at least this much time (spec: decimation).
@@ -35,6 +58,42 @@ struct Config {
   /// Number of stacked plots (rows) to start with, 1..`RowSet::kMaxRows`. Only the
   /// starting point: rows are added and removed from the layout editor.
   int plots = 1;
+
+  /// Take the plot's time from the packet counter and the declared sample rate rather than
+  /// from the stream's own time signal, so arrival and producer-clock jitter cannot move a
+  /// sample's x. Absolute stream time is still recorded, for export only (`todo.md` item 2).
+  bool relative_time = false;
+
+  /// Whether relative time was *stated* rather than left at its default -- by `--relative-time`, or
+  /// by the preferences, which the source chooser can reach before this run is planned. A source's
+  /// stored configuration is a statement from an *older* session, so it only fills in the gap.
+  bool relative_time_specified = false;
+
+  /// `--capture-packets N`: the ring size of the raw-datagram capture, 1..100000.
+  /// 0 means the flag was absent: the capture is off, and the popover button then
+  /// uses the 1000-slot default when the user toggles it.
+  std::uint32_t capture_packets = 0;
+
+  /// `--open FILE`: a `.npy` an earlier run exported, opened for viewing and analysis instead of a
+  /// live source. File mode and source mode are exclusive -- there is no acquisition behind a file,
+  /// and the chooser's Waveforms page sets this rather than the connection fields.
+  std::string open_waveform;
+
+  /// `--renderer NAME`: the GSK renderer to force, by exporting `GSK_RENDERER` **before any GTK
+  /// call**. Empty leaves GTK's own choice alone. `cairo` is the software preset over SSH/X11
+  /// forwarding: it also exports `LIBGL_ALWAYS_SOFTWARE=1`, because the plot's `GtkGLArea` asks
+  /// for a GL context whatever GSK draws with. `gl` is the faster alternative when indirect GL
+  /// works. The variables are read when the renderer/context is created, so setting them anywhere
+  /// after `gtk_init()`/`adw_init()` is a no-op -- which is why this is a `Config` field applied
+  /// at the top of `main()` and not a preference.
+  std::string renderer;
+
+  /// The source chooser's "Guided tour" entry. The tour is drawn on the application's own window,
+  /// which does not exist while the chooser runs, so the request rides on the one value `main()`
+  /// owns and hands to both the chooser and the front end (`open_waveform` and the preferences'
+  /// relative time cross the same way) and the window starts the tour once it is up and laid out.
+  /// It is *not* a preference: it describes this request and nothing else, so nothing persists it.
+  bool tour_pending = false;
 };
 
 /// Parses argv. On `--help` prints usage to stdout and exits(0); on a bad

src/event_series.hpp

@@ -7,6 +7,7 @@
 
 #include <algorithm>
 #include <memory>
+#include <string>
 #include <vector>
 
 namespace udpscope {
@@ -32,6 +33,10 @@ struct EventSnapshot {
   /// (see `BufferStore::time()`), which also makes the cut in `publish_event()`/
   /// `publish_pause_view()` a straight copy.
   std::vector<f64> stamps;
+  /// Absolute stream seconds on the same indices as `stamps`, or empty when the store had no
+  /// absolute ring. **Not** rebased by `x_offset` or by the trigger edge: a snapshot outlives
+  /// the epoch that produced it, so it stores the absolute value outright.
+  std::vector<f64> abs_stamps;
   std::vector<std::vector<f32>> values;  ///< one array per channel, same length
   /// The stream time of this snapshot's x = 0, so `x_offset + stamps[i]` is the clock the
   /// data arrived on: the edge for a trigger event, the newest sample at the moment of the
@@ -59,8 +64,30 @@ struct EventSnapshot {
   /// already O(n), and the same channel on two rows shares it instead of building and
   /// storing it twice.
   std::vector<plot::data::MinMaxPyramid> pyramids;
+  /// The channel *names* `values` is indexed by, so a snapshot can be re-bound after the channel
+  /// list was rebuilt -- and renumbered -- under it: a persistence layer names its signal and
+  /// resolves that name here, exactly as the trigger engine names its channel and for the same
+  /// reason (an index is a position in a list that any enable, disable or CONFIG renumbers).
+  /// Empty on a snapshot nobody re-binds later (a pause view).
+  std::vector<std::string> channel_names;
 };
 
+/// Bytes one snapshot holds: both stamp arrays, every channel's samples, the pyramids built for
+/// them and the names above. The number the persistence retention is measured in -- a retained
+/// snapshot is a whole window copied out of the ring, so what bounds it is bytes, not a count.
+inline std::size_t snapshot_bytes(const EventSnapshot& s) {
+  std::size_t bytes = s.stamps.size() * sizeof(f64) + s.abs_stamps.size() * sizeof(f64) +
+                      s.y.size() * sizeof(plot::Range) +
+                      s.channel_names.size() * sizeof(std::string);
+  for (const std::vector<f32>& v : s.values) bytes += v.size() * sizeof(f32);
+  // A pyramid entry is 32 bytes (`MinMaxPyramid::Entry`), one per level-`l` bucket of
+  // `kBucket << l` samples -- the whole index is about one byte per sample.
+  for (const plot::data::MinMaxPyramid& p : s.pyramids) {
+    for (u32 l = 0; l < p.level_count(); ++l) bytes += p.level_size(l) * 32u;
+  }
+  return bytes;
+}
+
 /// A plot::data::Series view of one channel of an EventSnapshot. The stamps are
 /// near-uniform (the arrival clock), so dx is the mean spacing and x_at returns
 /// the exact stamp; gather decimates by 2^level like the ring series does.

src/event_store.cpp

@@ -0,0 +1,360 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#include "event_store.hpp"
+
+#include <dirent.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include <algorithm>
+#include <cstdio>
+#include <cstring>
+#include <ctime>
+
+#include "layout_store.hpp"
+#include "waveform.hpp"
+
+namespace udpscope {
+namespace {
+
+/// One directory under the cache holds *every* source's events, and each source gets a folder inside
+/// it: `<cache>/udpscope/events/<source>/`. The other way round -- a folder per source with an
+/// `events` inside -- spreads one feature over as many directories as there are sources, and turns
+/// "where are my events" into a question about which host you last used.
+constexpr const char* kEventsSubdir = "/events";
+
+/// `2026-10-09T11:32:00` in local time, plus the sequence number: two events inside one second are
+/// ordinary (a 5 Hz trigger latches five times a second), and a stem that collides would overwrite
+/// the event it collided with.
+std::string event_stem(double wall_time, std::uint64_t seq) {
+  const std::time_t t = static_cast<std::time_t>(wall_time);
+  std::tm tm{};
+  localtime_r(&t, &tm);
+  char buf[64];
+  std::strftime(buf, sizeof(buf), "%Y%m%d-%H%M%S", &tm);
+  char stem[96];
+  std::snprintf(stem, sizeof(stem), "%s-%04llu", buf,
+                static_cast<unsigned long long>(seq % 10000ull));
+  return stem;
+}
+
+/// `a.npy` -> `a`; anything else -> "".
+std::string stem_of(const std::string& file, const char* ext) {
+  const std::size_t n = std::strlen(ext);
+  if (file.size() <= n || file.compare(file.size() - n, n, ext) != 0) return {};
+  return file.substr(0, file.size() - n);
+}
+
+/// The event's picture, drawn from its samples: one horizontal strip per signal, min/max per pixel
+/// column, the trigger edge as a brighter line. A 24-bit BMP -- the header is nine words and the rest
+/// is the pixels, so it needs no encoder, and a person can open it with anything.
+///
+/// The palette is fixed rather than the plots': this is navigation, and what has to be told apart at
+/// a glance is one *event* from another, not one signal from another (for which the names are on the
+/// row above).
+///
+/// The height is **per strip**, not for the whole picture: with a fixed total, a six-signal event got
+/// 26 pixels a signal and an eight-signal one got 20, which is a smear and not a waveform -- the
+/// picture has to grow with the signal count, and it is the *viewer* that scales it down to a row.
+bool write_preview(const ExportTable& table, const std::string& path, int width = 480,
+                   int strip_h = 44) {
+  if (table.empty() || table.columns.empty()) return false;
+  const std::size_t rows = table.rows();
+  const std::size_t strips = table.columns.size();
+  const int total_h = strip_h * static_cast<int>(strips);
+  static const std::uint32_t kPalette[] = {0x4FA3FFu, 0xFF7A4Fu, 0x6EE07Au, 0xE06ED0u,
+                                          0xFFD24Fu, 0x6FD8E0u, 0xB9A0FFu, 0xE0E0E0u};
+
+  // One byte per pixel per channel, bottom-up and **blue first** -- both are BMP's own order, and
+  // writing RGB here is what made every external viewer show the traces in the wrong colour.
+  const int row_bytes = ((width * 3) + 3) & ~3;
+  std::vector<unsigned char> pixels(std::size_t(row_bytes) * total_h, 0);
+  const auto put = [&](int x, int y, std::uint32_t rgb, double alpha) {
+    if (x < 0 || y < 0 || x >= width || y >= total_h) return;
+    unsigned char* p = &pixels[std::size_t(total_h - 1 - y) * row_bytes + std::size_t(x) * 3];
+    const double a = std::clamp(alpha, 0.0, 1.0);
+    p[0] = static_cast<unsigned char>(p[0] * (1.0 - a) + (rgb & 0xFF) * a);
+    p[1] = static_cast<unsigned char>(p[1] * (1.0 - a) + ((rgb >> 8) & 0xFF) * a);
+    p[2] = static_cast<unsigned char>(p[2] * (1.0 - a) + ((rgb >> 16) & 0xFF) * a);
+  };
+  // The background: a dark field, so the traces read the way they do on screen.
+  for (int y = 0; y < total_h; ++y) {
+    for (int x = 0; x < width; ++x) put(x, y, 0x101418u, 1.0);
+  }
+
+  for (std::size_t c = 0; c < strips; ++c) {
+    const std::vector<f32>& values = table.columns[c].values;
+    if (values.empty()) continue;
+    double lo = values[0];
+    double hi = values[0];
+    for (f32 v : values) {
+      if (!std::isfinite(v)) continue;
+      lo = std::min(lo, double(v));
+      hi = std::max(hi, double(v));
+    }
+    if (!(hi > lo)) {
+      hi = lo + 1.0;
+    }
+    const int base = static_cast<int>(c) * strip_h;
+    const std::uint32_t colour = kPalette[c % (sizeof(kPalette) / sizeof(kPalette[0]))];
+    for (int x = 0; x < width; ++x) {
+      const std::size_t from = rows * std::size_t(x) / std::size_t(width);
+      const std::size_t to = std::max(from + 1, rows * std::size_t(x + 1) / std::size_t(width));
+      double vmin = 1e300;
+      double vmax = -1e300;
+      for (std::size_t i = from; i < to && i < rows; ++i) {
+        const double v = values[i];
+        if (!std::isfinite(v)) continue;
+        vmin = std::min(vmin, v);
+        vmax = std::max(vmax, v);
+      }
+      if (vmin > vmax) continue;
+      const auto to_y = [&](double v) {
+        const double frac = (v - lo) / (hi - lo);
+        return base + strip_h - 1 - static_cast<int>(frac * (strip_h - 1));
+      };
+      const int y0 = std::clamp(to_y(vmax), base, base + strip_h - 1);
+      const int y1 = std::clamp(to_y(vmin), base, base + strip_h - 1);
+      for (int y = y0; y <= y1; ++y) put(x, y, colour, 1.0);
+    }
+    // The strip's own baseline, so an empty stretch reads as a flat trace and not as a gap.
+    for (int x = 0; x < width; ++x) {
+      const int y = base + strip_h - 1;
+      put(x, y, 0x303840u, 1.0);
+    }
+  }
+
+  // The trigger edge: the snapshot's x = 0, which is at the same fraction of every event's window.
+  if (!table.time.empty()) {
+    const double t0 = table.time.front();
+    const double t1 = table.time.back();
+    if (t1 > t0) {
+      const int x = static_cast<int>((0.0 - t0) / (t1 - t0) * (width - 1));
+      for (int y = 0; y < total_h; ++y) put(x, y, 0xFFE9A0u, 0.85);
+    }
+  }
+
+  std::FILE* f = std::fopen(path.c_str(), "wb");
+  if (f == nullptr) return false;
+  const std::uint32_t image_bytes = std::uint32_t(row_bytes) * std::uint32_t(total_h);
+  const std::uint32_t file_bytes = 54u + image_bytes;
+  unsigned char header[54] = {};
+  header[0] = 'B';
+  header[1] = 'M';
+  const auto put32 = [&](int at, std::uint32_t v) {
+    header[at] = static_cast<unsigned char>(v & 0xFF);
+    header[at + 1] = static_cast<unsigned char>((v >> 8) & 0xFF);
+    header[at + 2] = static_cast<unsigned char>((v >> 16) & 0xFF);
+    header[at + 3] = static_cast<unsigned char>((v >> 24) & 0xFF);
+  };
+  put32(2, file_bytes);
+  put32(10, 54u);
+  put32(14, 40u);
+  put32(18, std::uint32_t(width));
+  put32(22, std::uint32_t(total_h));
+  header[26] = 1;   // planes
+  header[28] = 24;  // bits per pixel
+  put32(34, image_bytes);
+  put32(38, 2835u);  // 72 dpi, in pixels per metre
+  put32(42, 2835u);
+  std::fwrite(header, 1, sizeof(header), f);
+  std::fwrite(pixels.data(), 1, pixels.size(), f);
+  std::fclose(f);
+  return true;
+}
+
+}  // namespace
+
+std::string event_meta_text(const EventRecord& r) {
+  char buf[512];
+  std::string out;
+  std::snprintf(buf, sizeof(buf), "wall_time = %.6f\n", r.wall_time);
+  out += buf;
+  std::snprintf(buf, sizeof(buf), "duration_s = %.6f\n", r.duration_s);
+  out += buf;
+  std::snprintf(buf, sizeof(buf), "pre_s = %.6f\n", r.pre_s);
+  out += buf;
+  std::snprintf(buf, sizeof(buf), "post_s = %.6f\n", r.post_s);
+  out += buf;
+  std::snprintf(buf, sizeof(buf), "edge = %.6f\n", r.edge);
+  out += buf;
+  std::snprintf(buf, sizeof(buf), "rate_hz = %.6g\n", r.rate_hz);
+  out += buf;
+  std::snprintf(buf, sizeof(buf), "signals = %zu\n", r.signals);
+  out += buf;
+  std::snprintf(buf, sizeof(buf), "samples = %zu\n", r.samples);
+  out += buf;
+  std::snprintf(buf, sizeof(buf), "seq = %llu\n", static_cast<unsigned long long>(r.seq));
+  out += buf;
+  return out;
+}
+
+bool event_meta_parse(const std::string& text, EventRecord* out) {
+  if (out == nullptr) return false;
+  bool any = false;
+  std::size_t i = 0;
+  while (i < text.size()) {
+    const std::size_t end = text.find('\n', i);
+    const std::string line = text.substr(i, end == std::string::npos ? std::string::npos : end - i);
+    i = end == std::string::npos ? text.size() : end + 1;
+    const std::size_t eq = line.find('=');
+    if (eq == std::string::npos) continue;
+    std::string key = line.substr(0, eq);
+    std::string value = line.substr(eq + 1);
+    while (!key.empty() && (key.back() == ' ' || key.back() == '\t')) key.pop_back();
+    while (!value.empty() && (value.front() == ' ' || value.front() == '\t')) value.erase(0, 1);
+    const double number = std::atof(value.c_str());
+    if (key == "wall_time") {
+      out->wall_time = number;
+      any = true;
+    } else if (key == "duration_s") {
+      out->duration_s = number;
+      any = true;
+    } else if (key == "pre_s") {
+      out->pre_s = number;
+      any = true;
+    } else if (key == "post_s") {
+      out->post_s = number;
+      any = true;
+    } else if (key == "edge") {
+      out->edge = number;
+      any = true;
+    } else if (key == "rate_hz") {
+      out->rate_hz = number;
+      any = true;
+    } else if (key == "signals") {
+      out->signals = static_cast<std::size_t>(std::atoll(value.c_str()));
+      any = true;
+    } else if (key == "samples") {
+      out->samples = static_cast<std::size_t>(std::atoll(value.c_str()));
+      any = true;
+    } else if (key == "seq") {
+      out->seq = static_cast<std::uint64_t>(std::strtoull(value.c_str(), nullptr, 10));
+      any = true;
+    }
+  }
+  return any;
+}
+
+std::string default_events_dir() { return std::string(cache_dir()) + kEventsSubdir; }
+
+EventStore::EventStore(std::string source, std::string base_dir) {
+  if (source.empty()) return;
+  std::string safe;
+  for (char c : source) {
+    const bool ok = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') ||
+                    c == '.' || c == '_' || c == '-';
+    safe.push_back(ok ? c : '_');
+  }
+  dir_ = (base_dir.empty() ? default_events_dir() : base_dir) + "/" + safe;
+}
+
+std::string EventStore::save(const ExportTable& table, const EventRecord& meta, std::size_t keep) {
+  if (dir_.empty() || table.empty()) return {};
+  mkdirs(dir_);
+  const std::string stem = event_stem(meta.wall_time > 0.0 ? meta.wall_time : double(std::time(nullptr)),
+                                      meta.seq);
+  const std::string samples = dir_ + "/" + stem + ".npy";
+  std::string error;
+  if (!write_npy(samples, table, error)) {
+    std::fprintf(stderr, "[udpscope] event cache: %s\n", error.c_str());
+    std::fflush(stderr);
+    return {};
+  }
+  EventRecord record = meta;
+  record.stem = stem;
+  std::string text = event_meta_text(record);
+  if (std::FILE* f = std::fopen((dir_ + "/" + stem + ".txt").c_str(), "wb"); f != nullptr) {
+    std::fwrite(text.data(), 1, text.size(), f);
+    std::fclose(f);
+  }
+  write_preview(table, dir_ + "/" + stem + ".bmp");
+  prune(keep);
+  return samples;
+}
+
+std::string EventStore::redraw_preview(const EventRecord& record) const {
+  if (dir_.empty() || record.stem.empty() || record.file.empty()) return {};
+  WaveformReader reader;
+  std::string error;
+  if (!reader.open(record.file, &error)) return {};
+  // The whole event in one table, which an event can afford where an export cannot: it is bounded by
+  // the trigger's own pre/post window, so this is seconds of samples and not a session's worth.
+  ExportTable table;
+  table.columns.resize(reader.names().size());
+  for (std::size_t c = 0; c < table.columns.size(); ++c) {
+    table.columns[c].name = reader.names()[c];
+    table.columns[c].values.reserve(reader.rows());
+  }
+  table.time.reserve(reader.rows());
+  std::vector<float> values(reader.names().size(), 0.0f);
+  double t = 0.0;
+  double abs_t = 0.0;
+  while (reader.next(&t, &abs_t, values.data())) {
+    table.time.push_back(t);
+    for (std::size_t c = 0; c < table.columns.size(); ++c) {
+      table.columns[c].values.push_back(values[c]);
+    }
+  }
+  const std::string path = dir_ + "/" + record.stem + ".bmp";
+  if (!write_preview(table, path)) return {};
+  return path;
+}
+
+std::vector<EventRecord> EventStore::list() const {
+  std::vector<EventRecord> out;
+  if (dir_.empty()) return out;
+  DIR* d = ::opendir(dir_.c_str());
+  if (d == nullptr) return out;
+  while (const dirent* e = ::readdir(d)) {
+    const std::string stem = stem_of(e->d_name, ".txt");
+    if (stem.empty()) continue;
+    std::FILE* f = std::fopen((dir_ + "/" + e->d_name).c_str(), "rb");
+    if (f == nullptr) continue;
+    std::string text;
+    char buf[512];
+    std::size_t n = 0;
+    while ((n = std::fread(buf, 1, sizeof(buf), f)) > 0) text.append(buf, n);
+    std::fclose(f);
+    EventRecord r;
+    if (!event_meta_parse(text, &r)) continue;
+    r.stem = stem;
+    r.file = dir_ + "/" + stem + ".npy";
+    if (::access(r.file.c_str(), R_OK) != 0) continue;  // a sidecar without its samples
+    struct stat sb {};
+    if (::stat((dir_ + "/" + stem + ".bmp").c_str(), &sb) == 0) {
+      r.thumbnail = dir_ + "/" + stem + ".bmp";
+    }
+    out.push_back(std::move(r));
+  }
+  ::closedir(d);
+  // Newest first by the *record's* time, not the file's: a copy or a touch changes the mtime, and the
+  // list is about when the event happened.
+  std::stable_sort(out.begin(), out.end(), [](const EventRecord& a, const EventRecord& b) {
+    if (a.wall_time != b.wall_time) return a.wall_time > b.wall_time;
+    return a.seq > b.seq;
+  });
+  return out;
+}
+
+bool EventStore::forget(const std::string& stem) {
+  if (dir_.empty() || stem.empty()) return false;
+  const std::string base = dir_ + "/" + stem;
+  const bool gone = ::unlink((base + ".npy").c_str()) == 0;
+  ::unlink((base + ".txt").c_str());
+  ::unlink((base + ".bmp").c_str());
+  return gone;
+}
+
+void EventStore::prune(std::size_t keep) const {
+  const std::vector<EventRecord> all = list();
+  for (std::size_t i = keep; i < all.size(); ++i) {
+    const std::string base = dir_ + "/" + all[i].stem;
+    ::unlink((base + ".npy").c_str());
+    ::unlink((base + ".txt").c_str());
+    ::unlink((base + ".bmp").c_str());
+  }
+}
+
+}  // namespace udpscope

src/event_store.hpp

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#pragma once
+
+#include "export.hpp"
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace udpscope {
+
+/// What a cached event is, without loading its samples: the sidecar's fields, and what the pane
+/// shows in one row.
+struct EventRecord {
+  std::string stem;         ///< the file's name without the extension
+  std::string file;         ///< `<stem>.npy`, the event's table in the export format
+  std::string thumbnail;    ///< `<stem>.bmp`, the preview drawn from the samples; else empty
+  double wall_time = 0.0;   ///< CLOCK_REALTIME at the latch, for the row's label
+  double duration_s = 0.0;  ///< pre + post
+  double pre_s = 0.0;
+  double post_s = 0.0;
+  double edge = 0.0;        ///< the stream time of the event's x = 0
+  double rate_hz = 0.0;     ///< the stored sample rate at the latch
+  std::size_t signals = 0;  ///< columns in the file
+  std::size_t samples = 0;  ///< rows
+  std::uint64_t seq = 0;    ///< the run's own event counter, so two events in one second differ
+};
+
+/// The cache of captured events: `<cache_dir>/events/<source>/`, one `.npy` per event written in
+/// the **export format** -- so `--open` and the chooser's Waveforms page read it back with the
+/// loader that already exists -- beside a `.txt` sidecar holding what the list shows without
+/// loading the samples, and whatever thumbnail the caller rendered.
+///
+/// No GTK: the caller renders the thumbnail and hands over a path, exactly as it hands over the
+/// table. The store owns naming, the sidecar, pruning and listing, which is what makes it testable
+/// without a window.
+/// The directory every source's event folder is created under when no preference says otherwise:
+/// `<cache>/udpscope/events`. Exposed because the preferences dialog shows it -- "the standard
+/// location" is not an answer a user can act on, and a second copy of the path computed in the dialog
+/// is a second thing to get wrong.
+std::string default_events_dir();
+
+class EventStore {
+ public:
+  /// `source` is the `<host>-<port>` pair, the same key the packet capture uses.
+  /// `base_dir` is the directory every source's own folder is created under; empty means
+  /// `<cache>/udpscope/events`. It comes from the preferences (item 9), because a user with a small
+  /// home partition and a second disk should not have to choose between events and free space.
+  explicit EventStore(std::string source = {}, std::string base_dir = {});
+
+  /// How many events to keep, newest first. The oldest beyond it are deleted on every save; item 9's
+  /// preferences are where this becomes the user's number.
+  static constexpr std::size_t kDefaultKeep = 32;
+
+  const std::string& dir() const noexcept { return dir_; }
+  bool empty_dir() const noexcept { return dir_.empty(); }
+
+  /// Writes `table` as one event, with `meta` in the sidecar and a preview drawn beside it. Returns
+  /// the samples' path, or an empty string on failure -- a cache that cannot be written must not stop
+  /// the scope.
+  ///
+  /// The preview is drawn from the *data* -- min/max per pixel column, one strip per signal -- and not
+  /// captured from the window: the plot is a `GtkGLArea`, and a GL area's ink is not in the widget's
+  /// paint tree, so a snapshot of it is empty (`gtk_snapshot_free_to_node()` returns NULL). Drawing it
+  /// here also keeps this class GTK-free, which is what makes it testable without a window.
+  std::string save(const ExportTable& table, const EventRecord& meta,
+                   std::size_t keep = kDefaultKeep);
+
+  /// The cached events, newest first: the sidecars, never the sample files, so a listing is cheap
+  /// however large the captures are.
+  std::vector<EventRecord> list() const;
+
+  /// Draws `record`'s preview again from its samples and returns the thumbnail's path, or an empty
+  /// string when the samples cannot be read.
+  ///
+  /// This is the repair for a preview that is missing or will not decode -- a write that failed, a
+  /// truncated file, a cache written by an older build. The `.npy` is the event, the `.bmp` is only a
+  /// picture of it, so a lost picture is recoverable and must not be shown as a blank row. It reads
+  /// the samples, so unlike `list()` it is **not** cheap: call it for the one event that needs it.
+  std::string redraw_preview(const EventRecord& record) const;
+
+  /// Deletes one event's samples, sidecar and thumbnail.
+  bool forget(const std::string& stem);
+
+  /// Deletes the oldest events beyond `keep`.
+  void prune(std::size_t keep) const;
+
+ private:
+  std::string dir_;
+};
+
+/// The sidecar's text, and back. One `key = value` per line, the project's own TOML subset, so a
+/// human can read the cache with `cat` -- which is the point of a forensic directory.
+std::string event_meta_text(const EventRecord& record);
+bool event_meta_parse(const std::string& text, EventRecord* out);
+
+}  // namespace udpscope

src/export.cpp

@@ -6,8 +6,11 @@
 #include <algorithm>
 #include <bit>
 #include <cerrno>
+#include <cstdint>
 #include <cstdio>
 #include <cstring>
+#include <ctime>
+#include <utility>
 
 namespace udpscope {
 namespace {
@@ -34,18 +37,29 @@ std::string sanitise(const std::string& name) {
   return out;
 }
 
-/// The final labels: sanitised, and de-duplicated against each other *and* against the
+/// `base` carrying a `_2`, `_3` … suffix for the `n`-th copy (`n == 1` is the name itself),
-/// two time columns, with a `_2`, `_3` suffix. Two elements of one vector signal can
+/// cut to `max_len` bytes when one is given -- MDF's name field is 32 bytes wide and the file
-/// easily sanitise to the same string.
+/// is re-read by a reader that keeps only the *first* occurrence of a name, so a cut that made
-std::vector<std::string> column_labels(const ExportTable& table) {
+/// two channels equal would silently lose one.
-  std::vector<std::string> taken{"time", "abs_seconds"};
+std::string numbered(const std::string& base, int n, std::size_t max_len) {
+  const std::string suffix = n == 1 ? std::string() : "_" + std::to_string(n);
+  std::size_t room = base.size();
+  if (max_len != 0) room = max_len > suffix.size() ? max_len - suffix.size() : 0;
+  return base.substr(0, room) + suffix;
+}
+
+/// The final labels: sanitised, and de-duplicated against each other *and* against
+/// `taken` -- the names the writer already spends -- with a `_2`, `_3` suffix. Two
+/// elements of one vector signal can easily sanitise to the same string.
+std::vector<std::string> column_labels(const ExportTable& table, std::vector<std::string> taken,
+                                      std::size_t max_len = 0) {
   std::vector<std::string> out;
   out.reserve(table.columns.size());
   for (const ExportTable::Column& col : table.columns) {
     const std::string base = sanitise(col.name);
-    std::string label = base;
+    std::string label = numbered(base, 1, max_len);
     for (int n = 2; std::find(taken.begin(), taken.end(), label) != taken.end(); ++n) {
-      label = base + "_" + std::to_string(n);
+      label = numbered(base, n, max_len);
     }
     taken.push_back(label);
     out.push_back(std::move(label));
@@ -69,6 +83,74 @@ bool opened(const File& out, const std::string& path, std::string& error) {
   return false;
 }
 
+/// The block lengths of MDF 3.30, from the **reader's** own field lists
+/// (`asammdf/blocks/v2_v3_constants.py`, 8.8.27): every block is a two-letter id, a 16-bit
+/// length and then its own fields, and the reader walks the file by those lengths alone, so a
+/// block written one field too wide is a file whose reader lands in the middle of the next one.
+/// The widths here are the ones a `bytes(block)` of the reference file measures (the known-good
+/// 3.30 file `/tmp/ref.mdf` this writer was byte-diffed against).
+constexpr std::size_t kMdfIdBlock = 64;         // "MDF     3.30" and the flags, no id/length
+constexpr std::size_t kMdfHeader = 208;         // 164 common + 44 of the 3.2-era time fields
+constexpr std::size_t kMdfTxOverhead = 5;       // "TX", the u16 length and the terminating NUL
+constexpr std::size_t kMdfDataGroup = 28;       // 4 addresses, the group count, 4 reserved
+constexpr std::size_t kMdfConversion = 46;      // a NONE conversion is the common fields alone
+constexpr std::size_t kMdfChannel = 228;        // the display-name-length CNBLOCK
+constexpr std::size_t kMdfChannelGroup = 30;    // 26 + the sample-reduction address of 3.30
+constexpr std::size_t kMdfNameBytes = 31;       // a CNBLOCK's 32-byte name field, less its NUL
+
+/// A byte sink for the MDF header blocks, which are a few hundred bytes each and have to be
+/// laid out field by field. The little-endian `raw()` writes are the same assumption the `.npy`
+/// writer states at the top of this file, and `static_assert`s there.
+struct Bytes {
+  std::vector<unsigned char> v;
+
+  void raw(const void* p, std::size_t n) {
+    const auto* b = static_cast<const unsigned char*>(p);
+    v.insert(v.end(), b, b + n);
+  }
+  void u16(std::uint16_t x) {
+    const unsigned char b[2] = {static_cast<unsigned char>(x & 0xFFu),
+                                static_cast<unsigned char>((x >> 8) & 0xFFu)};
+    raw(b, sizeof(b));
+  }
+  void i16(std::int16_t x) { u16(static_cast<std::uint16_t>(x)); }
+  void u32(std::uint32_t x) {
+    const unsigned char b[4] = {static_cast<unsigned char>(x & 0xFFu),
+                                static_cast<unsigned char>((x >> 8) & 0xFFu),
+                                static_cast<unsigned char>((x >> 16) & 0xFFu),
+                                static_cast<unsigned char>((x >> 24) & 0xFFu)};
+    raw(b, sizeof(b));
+  }
+  void u64(std::uint64_t x) {
+    u32(static_cast<std::uint32_t>(x & 0xFFFFFFFFu));
+    u32(static_cast<std::uint32_t>(x >> 32));
+  }
+  void f64(double x) { raw(&x, sizeof(x)); }
+  void f32(float x) { raw(&x, sizeof(x)); }
+  void zeros(std::size_t n) { v.insert(v.end(), n, 0); }
+
+  /// A fixed-width text field: the bytes, then NUL padding. MDF's names and units are
+  /// NUL-terminated inside a field of a width the reader is told by the block size, so this is
+  /// how every string in the format is spelled.
+  void text(const std::string& s, std::size_t width) {
+    const std::size_t n = std::min(s.size(), width);
+    raw(s.data(), n);
+    zeros(width - n);
+  }
+
+  std::size_t size() const noexcept { return v.size(); }
+};
+
+/// Checked rather than trusted: a field written at the wrong width would not fail here, it
+/// would produce a file whose reader walks into the middle of the next block. The widths are
+/// the asammdf 8.8.27 reader's own field lists (`blocks/v2_v3_constants.py`).
+bool mdf_block_size(const Bytes& block, std::size_t want, const char* what, std::string& error) {
+  if (block.size() == want) return true;
+  error = std::string("internal: the MDF ") + what + " block is " + std::to_string(block.size()) +
+          " bytes, the layout wants " + std::to_string(want);
+  return false;
+}
+
 }  // namespace
 
 ExportTable collect_export(ScopeModel& model, RowSet& rows) {
@@ -97,6 +179,12 @@ ExportTable collect_export(ScopeModel& model, RowSet& rows) {
     return static_cast<std::size_t>(c) < infos.size() ? infos[static_cast<std::size_t>(c)].name
                                                      : std::string("ch") + std::to_string(c);
   };
+  // The unit travels with the column so the MDF writer can put it on the channel; the other
+  // writers ignore it, as they always have.
+  const auto unit_of = [&](int c) {
+    return static_cast<std::size_t>(c) < infos.size() ? infos[static_cast<std::size_t>(c)].unit
+                                                     : std::string();
+  };
 
   // What the rows bind to is what gets exported, so the split is the same `DisplayMode`
   // `RowSet::bind()` switches on: the frozen event only while one is held, the live ring
@@ -127,14 +215,17 @@ ExportTable collect_export(ScopeModel& model, RowSet& rows) {
     table.abs_seconds.resize(n);
     for (std::size_t i = 0; i < n; ++i) {
       table.time[i] = st[first + i];
-      table.abs_seconds[i] = abs_base + table.time[i];
+      table.abs_seconds[i] = snap->abs_stamps.empty()
+                                 ? abs_base + table.time[i]
+                                 : snap->abs_stamps[first + i];
     }
     for (const int c : chans) {
       const std::size_t ch = static_cast<std::size_t>(c);
       if (ch >= snap->values.size()) continue;
       const std::vector<f32>& src = snap->values[ch];
       if (src.size() < first + n) continue;
-      table.columns.push_back({name_of(c), std::vector<f32>(src.begin() + static_cast<std::ptrdiff_t>(first),
+      table.columns.push_back({name_of(c), unit_of(c),
+                               std::vector<f32>(src.begin() + static_cast<std::ptrdiff_t>(first),
                                                 src.begin() + static_cast<std::ptrdiff_t>(first + n))});
     }
     return table;
@@ -159,16 +250,39 @@ ExportTable collect_export(ScopeModel& model, RowSet& rows) {
   store.time().copy_from(first, n, stamps.data());
   table.time.resize(static_cast<std::size_t>(n));
   table.abs_seconds.resize(static_cast<std::size_t>(n));
+  std::vector<f64> abs_stamps;
+  if (const plot::data::RingBuffer<f64>* abs_ring = store.abs_time(); abs_ring != nullptr) {
+    abs_stamps.resize(static_cast<std::size_t>(n));
+    abs_ring->copy_from(first, n, abs_stamps.data());
+  }
   for (std::size_t i = 0; i < stamps.size(); ++i) {
     table.time[i] = stamps[i] - s0;
-    table.abs_seconds[i] = abs_base + table.time[i];
+    table.abs_seconds[i] = abs_stamps.empty()
+                               ? abs_base + table.time[i]
+                               : model.epoch() + abs_stamps[i];
   }
   for (const int c : chans) {
     const std::size_t ch = static_cast<std::size_t>(c);
     if (ch >= model.channel_count()) continue;
     std::vector<f32> values(static_cast<std::size_t>(n));
     store.values(ch).copy_from(first, n, values.data());
-    table.columns.push_back({name_of(c), std::move(values)});
+    table.columns.push_back({name_of(c), unit_of(c), std::move(values)});
+  }
+  return table;
+}
+
+ExportTable event_table(ScopeModel& model, const EventSnapshot& snapshot) {
+  ExportTable table;
+  table.time = snapshot.stamps;
+  table.abs_seconds = snapshot.abs_stamps.empty() ? snapshot.stamps : snapshot.abs_stamps;
+  std::lock_guard<std::mutex> lock(model.mutex());
+  const std::vector<ChannelInfo>& channels = model.channels();
+  for (std::size_t c = 0; c < snapshot.values.size() && c < channels.size(); ++c) {
+    ExportTable::Column column;
+    column.name = channels[c].name;
+    column.unit = channels[c].unit;
+    column.values = snapshot.values[c];
+    table.columns.push_back(std::move(column));
   }
   return table;
 }
@@ -178,7 +292,7 @@ bool write_npy(const std::string& path, const ExportTable& table, std::string& e
     error = "nothing to export: no signal is plotted in the visible range";
     return false;
   }
-  const std::vector<std::string> labels = column_labels(table);
+  const std::vector<std::string> labels = column_labels(table, {"time", "abs_seconds"});
 
   // `descr` as a list of (name, format) pairs is a *packed* structured dtype -- NumPy
   // only inserts alignment padding when asked to (`align=True`) -- so the records below
@@ -242,7 +356,7 @@ bool write_csv(const std::string& path, const ExportTable& table, std::string& e
   File out(path);
   if (!opened(out, path, error)) return false;
 
-  const std::vector<std::string> labels = column_labels(table);
+  const std::vector<std::string> labels = column_labels(table, {"time", "abs_seconds"});
   std::string line = "time,abs_seconds";
   for (const std::string& label : labels) line += "," + label;
   line += "\n";
@@ -278,4 +392,256 @@ bool write_csv(const std::string& path, const ExportTable& table, std::string& e
   return true;
 }
 
+bool write_mdf(const std::string& path, const ExportTable& table, std::string& error) {
+  if (table.empty()) {
+    error = "nothing to export: no signal is plotted in the visible range";
+    return false;
+  }
+  const std::size_t rows = table.rows();
+  const std::size_t cols = table.columns.size();
+
+  // **The master is the absolute clock, named `time`**, and the axis the plot showed goes out as
+  // an ordinary channel, `time_relative`. The relative column is 0 at a different sample in each
+  // display mode, so a master off it would put a live export and a held event's export on two
+  // timelines -- the one thing the second column exists to avoid -- while `abs_seconds` is the
+  // number the stream itself stamped the samples with. Both carry the unit `s`.
+  const std::vector<std::string> labels =
+      column_labels(table, {"time", "time_relative"}, kMdfNameBytes);
+  const std::size_t channels = cols + 2;
+  const std::size_t record = 2 * sizeof(f64) + cols * sizeof(f32);
+  if (rows > 0xFFFFFFFFull) {
+    error = "too many samples for an MDF 3 file: the channel group counts cycles in 32 bits";
+    return false;
+  }
+  if (128 + (cols - 1) * 32 > 0xFFFFu) {
+    error = "too many signals for an MDF 3 record: a channel's start offset is 16 bits";
+    return false;
+  }
+
+  // One channel per column, described once: what the CNBLOCK says about it (where in the record
+  // its samples start, how wide they are, whether it is the master) and what the CCBLOCK says
+  // (its unit). The range is measured from the samples rather than left at zero, so
+  // `range_flag = 1` means what it says.
+  struct Channel {
+    std::string name;
+    std::string unit;
+    std::uint16_t bit_offset;
+    std::uint16_t bit_count;
+    std::uint16_t data_type;  // MDF 3: 2 = float, 3 = double, both in the ID block's byte order
+    std::uint16_t type;       // 0 = value, 1 = master
+    f64 lo, hi;
+  };
+  const auto range_of = [](const auto& values) {
+    if (values.empty()) return std::pair<f64, f64>{0.0, 0.0};
+    const auto mm = std::minmax_element(values.begin(), values.end());
+    return std::pair<f64, f64>{static_cast<f64>(*mm.first), static_cast<f64>(*mm.second)};
+  };
+  std::vector<Channel> chans;
+  chans.reserve(channels);
+  const auto abs_range = range_of(table.abs_seconds);
+  const auto rel_range = range_of(table.time);
+  chans.push_back({"time", "s", 0, 64, 3, 1, abs_range.first, abs_range.second});
+  chans.push_back({"time_relative", "s", 64, 64, 3, 0, rel_range.first, rel_range.second});
+  for (std::size_t i = 0; i < cols; ++i) {
+    const auto range = range_of(table.columns[i].values);
+    chans.push_back({labels[i], table.columns[i].unit,
+                     static_cast<std::uint16_t>(128 + i * 32), 32, 2, 0, range.first, range.second});
+  }
+
+  // Every address in the file, from the fixed block lengths above: the writer therefore knows
+  // where it is going before it writes a byte, which is what lets each block carry its links.
+  const std::string comment = "udpscope export: the visible window, " + std::to_string(rows) +
+                              " samples x " + std::to_string(cols) + " signals";
+  const std::size_t hd_end = kMdfIdBlock + kMdfHeader;
+  const std::size_t comment_addr = hd_end;
+  const std::size_t data_addr = comment_addr + kMdfTxOverhead + comment.size();
+  const std::size_t dg_addr = data_addr + rows * record;
+  const std::size_t ch_addr = dg_addr + kMdfDataGroup;
+  const std::size_t cg_addr = ch_addr + channels * (kMdfConversion + kMdfChannel);
+  const std::uint64_t total = cg_addr + kMdfChannelGroup;
+  if (total > 0xFFFFFFFFull) {
+    error = "the export is larger than an MDF 3 file can address";
+    return false;
+  }
+  const auto cc_addr = [&](std::size_t i) {
+    return ch_addr + i * (kMdfConversion + kMdfChannel);
+  };
+
+  // The wall clock the measurement file was written at. `abs_time` is the same instant in
+  // nanoseconds since the epoch, which is what the 3.2-era header field asks for.
+  const std::time_t now = std::time(nullptr);
+  std::tm tm{};
+  localtime_r(&now, &tm);
+  char date[11] = {};
+  char clock[9] = {};
+  std::strftime(date, sizeof(date), "%d:%m:%Y", &tm);
+  std::strftime(clock, sizeof(clock), "%H:%M:%S", &tm);
+
+  Bytes head;
+  // Identification block: the version string, who wrote the file, and the byte order every
+  // sample in it is in.
+  head.text("MDF     ", 8);
+  head.text("3.30", 8);
+  head.text("udpscope", 8);
+  head.u16(0);    // byte order: Intel, ahead of every value and the float format below
+  head.u16(0);    // float format: IEEE
+  head.u16(330);  // MDF version, digits without the separator
+  head.u16(0);    // code page: latin-1
+  head.zeros(2);  // reserved
+  head.zeros(26); // reserved
+  head.u16(0);    // unfinalised standard flags
+  head.u16(0);    // unfinalised custom flags
+  if (!mdf_block_size(head, kMdfIdBlock, "identification", error)) return false;
+
+  // Header block, which points at the data group and at the comment that follows it.
+  head.raw("HD", 2);
+  head.u16(static_cast<std::uint16_t>(kMdfHeader));
+  head.u32(static_cast<std::uint32_t>(dg_addr));  // first data group
+  head.u32(static_cast<std::uint32_t>(comment_addr));
+  head.u32(0);  // program block: nothing wrote this but us
+  head.u16(1);  // data groups
+  head.text(date, 10);
+  head.text(clock, 8);
+  head.text("", 32);  // author
+  head.text("", 32);  // department
+  head.text("", 32);  // project
+  head.text("", 32);  // subject
+  head.u64(static_cast<std::uint64_t>(now) * 1000000000ull);
+  head.i16(static_cast<std::int16_t>(tm.tm_gmtoff / 3600));
+  head.u16(0);  // time quality
+  head.text("Local PC Reference Time", 32);
+  if (!mdf_block_size(head, hd_end, "header", error)) return false;
+
+  // The comment, in the one text block the file carries: plain words rather than the XML a
+  // writer that also *edits* files keeps its structured properties in.
+  head.raw("TX", 2);
+  head.u16(static_cast<std::uint16_t>(comment.size() + kMdfTxOverhead));
+  head.raw(comment.data(), comment.size());
+  head.zeros(1);
+
+  Bytes tail;
+  // Data group: one channel group, whose channels are chained, and the address of the samples.
+  tail.raw("DG", 2);
+  tail.u16(static_cast<std::uint16_t>(kMdfDataGroup));
+  tail.u32(0);                                         // next data group
+  tail.u32(static_cast<std::uint32_t>(cg_addr));
+  tail.u32(0);                                         // trigger block
+  tail.u32(static_cast<std::uint32_t>(data_addr));
+  tail.u16(1);  // channel groups
+  tail.u16(0);  // record IDs: the group is sorted
+  tail.zeros(4);  // reserved
+  if (!mdf_block_size(tail, kMdfDataGroup, "data group", error)) return false;
+
+  for (std::size_t i = 0; i < channels; ++i) {
+    const Channel& c = chans[i];
+    // Conversion block: the unit lives here and nowhere else in MDF 3, which is where ScryLab
+    // reads a signal's unit from. NONE because the samples are already the physical values --
+    // the table was collected as `f32`, so a conversion would only be a second copy of it.
+    Bytes cc;
+    cc.raw("CC", 2);
+    cc.u16(static_cast<std::uint16_t>(kMdfConversion));
+    cc.u16(1);  // range_flag: the range below is measured, so it is valid
+    cc.f64(c.lo);
+    cc.f64(c.hi);
+    cc.text(c.unit, 20);
+    cc.u16(0xFFFFu);
+    cc.u16(0);  // referenced parameters
+    if (!mdf_block_size(cc, kMdfConversion, "conversion", error)) return false;
+
+    // Channel block: the name ScryLab turns into the signal name, where this channel's samples
+    // sit in a record, and the link to the next channel.
+    Bytes cn;
+    cn.raw("CN", 2);
+    cn.u16(static_cast<std::uint16_t>(kMdfChannel));
+    cn.u32(i + 1 < channels ? static_cast<std::uint32_t>(cc_addr(i + 1) + kMdfConversion) : 0);
+    cn.u32(static_cast<std::uint32_t>(cc_addr(i)));
+    cn.u32(0);  // source: the stream does not say what produced a sample
+    cn.u32(0);  // dependency block
+    cn.u32(0);  // comment
+    cn.u16(c.type);
+    cn.text(c.name, 32);
+    cn.zeros(128);  // description
+    cn.u16(c.bit_offset);
+    cn.u16(c.bit_count);
+    cn.u16(c.data_type);
+    cn.u16(1);  // range_flag
+    cn.f64(c.lo);
+    cn.f64(c.hi);
+    cn.f64(0.0);    // sampling rate: only a virtual time channel carries one
+    cn.u32(0);      // long name
+    cn.u32(0);      // display name
+    cn.u16(0);      // additional byte offset
+    if (!mdf_block_size(cn, kMdfChannel, "channel", error)) return false;
+
+    tail.v.insert(tail.v.end(), cc.v.begin(), cc.v.end());
+    tail.v.insert(tail.v.end(), cn.v.begin(), cn.v.end());
+  }
+
+  // Channel group, last: it names the first channel, the record size and the cycle count from
+  // which a reader derives the size of the sample block at `data_addr`.
+  tail.raw("CG", 2);
+  tail.u16(static_cast<std::uint16_t>(kMdfChannelGroup));
+  tail.u32(0);  // next channel group
+  tail.u32(static_cast<std::uint32_t>(ch_addr + kMdfConversion));
+  tail.u32(0);  // comment
+  tail.u16(1);  // record ID
+  tail.u16(static_cast<std::uint16_t>(channels));
+  tail.u16(static_cast<std::uint16_t>(record));
+  tail.u32(static_cast<std::uint32_t>(rows));
+  tail.zeros(4);  // sample reduction address
+  if (!mdf_block_size(tail, kMdfDataGroup + channels * (kMdfConversion + kMdfChannel) +
+                                 kMdfChannelGroup,
+                      "data group and channels", error)) {
+    return false;
+  }
+
+  File out(path);
+  if (!opened(out, path, error)) return false;
+  const auto put = [&](const Bytes& bytes) {
+    return bytes.v.empty() || std::fwrite(bytes.v.data(), 1, bytes.v.size(), out.f) == bytes.v.size();
+  };
+  if (!put(head)) {
+    error = "short write to '" + path + "': " + std::strerror(errno);
+    return false;
+  }
+  // One record at a time, in the channel order the blocks above declare, so a full ring is not
+  // held twice -- the same shape the `.npy` writer streams its records in.
+  std::vector<unsigned char> rec(record);
+  for (std::size_t i = 0; i < rows; ++i) {
+    std::size_t at = 0;
+    std::memcpy(rec.data() + at, &table.abs_seconds[i], sizeof(f64));
+    at += sizeof(f64);
+    std::memcpy(rec.data() + at, &table.time[i], sizeof(f64));
+    at += sizeof(f64);
+    for (const ExportTable::Column& col : table.columns) {
+      const f32 v = i < col.values.size() ? col.values[i] : 0.0f;
+      std::memcpy(rec.data() + at, &v, sizeof(f32));
+      at += sizeof(f32);
+    }
+    if (std::fwrite(rec.data(), 1, rec.size(), out.f) != rec.size()) {
+      error = "short write to '" + path + "': " + std::strerror(errno);
+      return false;
+    }
+  }
+  if (!put(tail)) {
+    error = "short write to '" + path + "': " + std::strerror(errno);
+    return false;
+  }
+  if (std::fflush(out.f) != 0) {
+    error = "cannot flush '" + path + "': " + std::strerror(errno);
+    return false;
+  }
+  return true;
+}
+
+bool write_export(const std::string& path, const ExportTable& table, std::string& error) {
+  const auto ends_with = [&path](const char* ext) {
+    const std::size_t n = std::strlen(ext);
+    return path.size() >= n && path.compare(path.size() - n, n, ext) == 0;
+  };
+  if (ends_with(".csv")) return write_csv(path, table, error);
+  if (ends_with(".mf3") || ends_with(".mdf")) return write_mdf(path, table, error);
+  return write_npy(path, table, error);
+}
+
 }  // namespace udpscope

src/export.hpp

@@ -21,6 +21,11 @@ namespace udpscope {
 struct ExportTable {
   struct Column {
     std::string name;         ///< the legend name, sanitised for a column label
+    /// The signal's unit exactly as the CONFIG carried it, the empty string when it
+    /// carried none. The `.npy`/`.csv` writers do not spell it out (their readers get the
+    /// names and the numbers); MDF does, because the unit *is* part of what a channel is
+    /// there, and it is the only thing ScryLab reads a signal's unit from.
+    std::string unit;
     std::vector<f32> values;  ///< `rows()` long, the ring's own `f32`
   };
 
@@ -54,6 +59,12 @@ struct ExportTable {
 /// model access. In trigger mode nothing is locked: the `EventSnapshot` is immutable.
 ExportTable collect_export(ScopeModel& model, RowSet& rows);
 
+/// The held event as a table, built from the **snapshot** rather than from the rows: a cache of the
+/// acquisition, every channel the event holds, independent of which traces a row happens to show
+/// when the latch lands. The channel names are the model's, in channel order -- the same order the
+/// columns come out in, so `--open` restores the same signals.
+ExportTable event_table(ScopeModel& model, const EventSnapshot& snapshot);
+
 /// Writes a NumPy `.npy` file holding one structured array: `time` and `abs_seconds` as
 /// `<f8`, every signal as `<f4` -- the width the ring actually stores, so the file is
 /// about half the size of an all-`f8` one and invents no precision.
@@ -65,4 +76,27 @@ bool write_npy(const std::string& path, const ExportTable& table, std::string& e
 /// enough digits to round-trip each column's own type and no more.
 bool write_csv(const std::string& path, const ExportTable& table, std::string& error);
 
+/// Writes the same table as **MDF 3.30** (`.mf3`/`.mdf`), byte for byte by hand -- there is no
+/// writer library here and MF4 (HDF5) is the one format this app will not link.
+///
+/// One channel group, all channels record-interleaved, master first, which is the shape the
+/// [ScryLab data sources](https://docs.scrylab.de/docs/data-sources/) contract asks for: *every
+/// data channel becomes a signal* (the CNBLOCK's `short_name`), *the master channel of each
+/// group is the x axis* (our master is `abs_seconds`, named `time`), and *the unit is taken from
+/// the channel metadata* (MDF 3 keeps it in the channel's conversion block, the CCBLOCK). A
+/// second occurrence of a name is dropped by that reader, so the labels are de-duplicated and cut
+/// to the 31 bytes a CNBLOCK's name field holds.
+///
+/// The master is the **absolute** clock and the axis the plot showed is an ordinary channel,
+/// `time_relative`: the relative column is `0` at a different sample in every mode, so a master
+/// off it would put two exports from different modes on two timelines, while `abs_seconds` is the
+/// number the stream itself stamped the samples with. Both carry the unit `s`.
+bool write_mdf(const std::string& path, const ExportTable& table, std::string& error);
+
+/// Writes `table` with the writer **`path`'s extension** names: `.csv` -> `write_csv`,
+/// `.mf3`/`.mdf` -> `write_mdf`, anything else -> `write_npy` (the default, as the save dialog's
+/// default filter is). The export dialog and the self-check's export probe both come through
+/// here, so the two cannot offer different formats.
+bool write_export(const std::string& path, const ExportTable& table, std::string& error);
+
 }  // namespace udpscope

src/help/01-overview.txt

@@ -1,78 +0,0 @@
-<b>What udpscope is</b>
-
-udpscope plots a live UDPStreamer source. One window holds up to 8 rows of plots, each with up
-to 4 traces, and every row shares one time axis, so the whole figure scrolls together.
-Acquisition runs on its own thread and writes a ring buffer sized from <tt>--buffer-mb</tt>;
-the drawing thread reads whatever that ring holds when a frame starts, which is why a trace
-never makes the window stutter.
-
-The stream is the clock. Every interval you read on screen is measured between timestamps the
-source sent, never your machine's, so a stalled source freezes the view instead of scrolling it
--- and a source whose clock steps still gets the window you asked for.
-
-The time axis is <i>relative to now</i>. While streaming it is a fixed <tt>[-window .. 0]</tt>
-with the newest sample at 0, so x reads as an age: <tt>-1.5s</tt> is a sample a second and a half
-old. In trigger mode 0 is the event's edge instead, and a paused view keeps the ages it was
-frozen with. The source's own clock is still there when you need it -- an export writes it as a
-second column.
-
-<b>How to reach it</b>
-
-Start the app with a source (<tt>udpscope --server 127.0.0.1 --port 8000</tt>), or start it with
-no <tt>--server</tt> and pick one from the chooser, which lists the sessions you have opened
-before. A unicast source serves one client at a time: if a second viewer connects, they take
-turns and the status bar says so. To watch one source from several instances, use
-<tt>--multicast</tt> with the group and <tt>--interface</tt> with the local address.
-
-The signals arrive <i>disabled</i>. Nothing is acquired until you turn one on in the signal
-list, and enabling is what starts acquisition -- so a freshly opened scope with an idle side
-panel is working correctly, not failing to connect.
-
-<b>The window</b>
-
-• <b>The header bar</b> -- left to right: the time window (<tt>2 s</tt>), the trigger and the
-  pause, then the pane switches -- signal list, cursors, measurements, math, side panel -- and
-  the menu, which holds Fit to data, the layout editor, Export, Keyboard shortcuts, Help and
-  About.
-
-• <b>The side panel</b> -- the trigger, cursors, measurements and math panes at the top, then
-  the signal list: one row per signal with its colour, an enable switch, its name and its unit.
-  Signals are dragged from here onto a plot row.
-
-• <b>The plot</b> -- up to 8 rows, each with its own y axis and up to 4 traces, all on one
-  shared time axis. Right-click a row for its own menu (fit, add a signal, remove a trace).
-
-• <b>The status bar</b>, directly above the plot's bottom edge -- the state word, the stored
-  sample rate and the window, and the ⓘ beside it for packets, gaps and the buffer's own
-  figures. The second screenshot above is what a held capture looks like: <tt>event held</tt>,
-  the axis pinned to the event, and the trigger marker at the edge.
-
-<b>The first five minutes</b>
-
-1. <b>Connect.</b> With no <tt>--server</tt>, pick a stored session or type a host and port.
-2. <b>Enable a signal</b> in the signal list. The plot stays empty for the first fraction of a
-   second while the first window fills -- the buffer holds only what has arrived.
-3. <b>Drag it onto a row.</b> Drop a second signal on another row, or the same signal again for
-   a second view of it. The colour is per signal, so it is the same one wherever it appears.
-4. <b>Set the window</b> with the control in the header bar: type a number, pick a unit, or step
-   a decade. The trigger's event window is a share of this span, so a window change moves it.
-5. <b>Pause</b> (<tt>space</tt>) to look at a still picture; the producer keeps filling the
-   buffer behind it, and resuming shows what arrived meanwhile rather than a hole.
-6. <b>Arm the trigger</b> (<tt>a</tt>) and wait for a latch: the view freezes on one event, and
-   you can zoom in on it. Disarming mid-capture keeps what the capture got.
-7. <b>Measure it</b> -- the measurements pane computes a statistic of the visible window, and
-   <b>show on plot</b> marks it as a ruler or a pair of markers.
-8. <b>Save the data</b> with Export visible range, which writes the plotted signals over the
-   window at the stored rate to <tt>.npy</tt> or <tt>.csv</tt>.
-
-<b>Worth knowing</b>
-
-• A signal nobody enables costs nothing -- no buffer, no socket work, no measurements.
-• The window remembers itself. Rows, traces, the time window, calibration, which signals were
-  enabled, the math channels with their graphs, and the measurements are written per host and
-  port, and reloaded the next time you open that source.
-• A very wide window on a fast stream is drawn from averaged groups of samples, so the rate in
-  the status bar falls: that is the anti-alias filter, not a fault -- striding would fold a fast
-  signal back as a slow one, which looks entirely plausible on screen.
-• Every instrument the app computed -- the trigger marker, the measurement marks -- is locked to
-  the pointer's reach. The cursors are yours to drag; those are not.

src/help/02-source.txt

@@ -1,31 +0,0 @@
-<b>Choosing a source</b>
-
-A source is a host and a port, optionally reached through a multicast group on a named
-interface. Pass it on the command line, or let udpscope ask.
-
-<b>How to reach it</b>
-
-Run with <tt>--server</tt> and the app connects straight away. Run <i>without</i>
-<tt>--server</tt> and a chooser appears first: the sessions udpscope has stored, newest
-first, plus a <b>New host…</b> form for one it has not seen. The chooser runs before any
-buffer is allocated and before any socket is opened, so declining it costs nothing.
-
-<b>Worth knowing</b>
-
-• The list is the sessions that <i>named a signal</i>. A session whose streamer was down
-  stores empty slot names and is filtered out, which is what keeps the list the sources you
-  actually configured rather than every port you have ever typed.
-• A stored row reconnects the way it was reached. The multicast group and the interface are
-  written inside the session file, because the file's name (<tt>host_port.toml</tt>) cannot
-  carry them.
-• <tt>--multicast</tt> still needs <tt>--server</tt>: the CONFIG message is fetched from the
-  server, not from the group.
-• The <tt>×</tt> beside a row deletes that session file. Nothing else is removed.
-
-<b>Example</b>
-
-<tt>udpscope</tt> with two stored sessions lists
-<tt>127.0.0.1:8000  plots=1 signals=3</tt> and
-<tt>10.0.0.5:8001  plots=2 signals=4 multicast=239.1.2.3 interface=10.0.0.9</tt>.
-Activating the first reports <tt>[sources] picked 127.0.0.1:8000</tt> and continues into
-the scope with that session's layout already loaded.

src/help/03-signals.txt

@@ -1,30 +0,0 @@
-<b>Signals and calibration</b>
-
-The source's CONFIG message describes its signals: a name, a unit and a type. udpscope turns
-each enabled signal into a <i>channel</i> — a ring of values beside the shared time ring —
-and a channel is what a trace plots. Calibration is a scale and an offset applied at ingest.
-
-<b>How to reach it</b>
-
-The side panel (<tt>s</tt>) lists every signal with a switch. The <b>Signal list</b> item in
-the overflow menu opens the editor where the unit and the calibration live.
-
-<b>Worth knowing</b>
-
-• Signals start disabled, and enabling one is what starts acquiring it. A trigger on a signal
-  nobody acquires can never fire, so arming a trigger enables its signal for you.
-• Calibration is applied <i>at ingest</i>, so changing it re-plans the buffer and drops the
-  history. So does enabling or disabling a signal, and so does a new CONFIG. An empty plot
-  for a second after one of those is the ring refilling, not a fault.
-• The stream's first signal is usually its <i>timestamp</i>, and that one is never acquired.
-  It cannot be plotted, measured or used as a math source, and udpscope refuses to put it in
-  a row rather than binding a trace that would read nothing for ever.
-• A signal's colour follows the <i>signal</i>, not the slot, so the same signal on two rows
-  is one colour and the side panel's chip identifies it unambiguously. A signal on no row
-  gets a grey chip rather than none, so the panel's rows keep their height.
-
-<b>Example</b>
-
-A source declaring <tt>time</tt>, <tt>sine</tt>, <tt>ramp</tt> and <tt>noise</tt> yields three
-plottable signals. Enable all three and the exit dump reads <tt>3 signals, 3 channels</tt>;
-<tt>time</tt> is not among them.

src/help/04-layout.txt

@@ -1,35 +0,0 @@
-<b>Rows, layout and drag &amp; drop</b>
-
-The figure is a stack of rows, 1 to 8 of them, each holding up to 4 traces. Rows share one
-time axis and one pair of side margins, so their y labels line up, their data areas start and
-end on the same two columns, and their windows cannot drift apart. The left margin holds the y
-labels; the right one is empty, and is there so the newest tick's label and the newest sample's
-ink have somewhere to land instead of sitting on the frame.
-
-<b>How to reach it</b>
-
-Drag a signal's chip out of the side panel (<tt>s</tt>) and drop it on a row to add a trace.
-Press <tt>l</tt>, or pick <b>Layout editor</b> from the overflow menu, to add and remove rows:
-a <tt>×</tt> appears at the top left of each row and a <tt>+</tt> on each boundary between
-rows, including above the first and below the last. The editor's own button in the top-right
-corner leaves it.
-
-<b>Worth knowing</b>
-
-• A drop <i>adds</i> a trace to the row's next free slot; it does not replace one. With four
-  traces already on a row the drop is refused.
-• Inserting a row moves the rows below it <i>with their contents</i>. Inserting above row 1
-  puts what row 1 plotted onto row 2 and leaves the new row empty — the rows are not
-  renumbered under you.
-• A trace is remembered by the signal's <i>name</i>, not by its channel number, because a new
-  CONFIG or an enable renumbers the channels and an index would silently re-point the trace.
-• Adding or removing a row rebuilds the figure, which is cheap, but it also re-deals every
-  trace. A frozen trigger event survives the rebuild: the pinned window is restated rather
-  than re-framed on the live edge.
-
-<b>Example</b>
-
-With three traces on row 1, pressing <tt>l</tt> shows 3 buttons (one <tt>×</tt>, two
-<tt>+</tt>). Clicking the <tt>+</tt> above row 1 gives 2 rows and 5 buttons, with the three
-traces now on row 2 — the layout probe reports exactly this as
-<tt>rows=2 buttons=5 traces=[0:-|1:sine,ramp,noise]</tt>.

src/help/05-window.txt

@@ -1,33 +0,0 @@
-<b>Time window</b>
-
-The window is how much time the plot shows. Every row shares one window: the figure has a
-single x link group, so the rows cannot drift apart. The trigger's event span follows it, and
-the pre-trigger share is a share of <i>this</i> window.
-
-<b>How to reach it</b>
-
-The header bar's window button opens a popover: type a number, pick a unit under it, or step a
-decade with the arrows. The button's own label is a reading of the current window in a natural
-unit, width-locked so a change of window cannot widen the header bar.
-
-<b>Worth knowing</b>
-
-• A window too long to store at the wire rate is <i>decimated, not refused</i>. The shared clock
-  takes a power-of-two stride, and each group of samples is <b>averaged</b> rather than strided,
-  so a tone above the stored Nyquist is attenuated instead of aliasing to a false low frequency.
-• The stamp stored for a group is the group's <i>mean</i>, which is where the averaging puts the
-  value. Stamping at the end of a group would shift every trace half a stored sample late.
-• Moving the window across a decimation boundary rebuilds the buffer and drops the history.
-  Walking it inside one decade is free.
-• <b>This control is the only thing that changes the window.</b> A zoom, a pan or a fit moves the
-  view <i>inside</i> it and leaves it alone — which is the point of the previous bullet: a wheel
-  notch that redefined the window could re-plan the buffer and throw your samples away.
-• The trigger sees the <i>stored</i> (filtered) signal, not the wire signal, because an edge
-  found on a sample that is not in the buffer could not be cut out of it.
-
-<b>Example</b>
-
-1 MS/s with 200 MB of buffer. A 2 s window stores every sample (<tt>time x1</tt>). Widen it to
-600 s and the stride becomes <tt>x16</tt>: 625 S/s stored, anti-aliased at 312.5 Hz. A 2 kHz
-sine seen through that window reads <tt>y=[-0.059, 0.079]</tt> — attenuated to about 6%, not
-folded down to a full-amplitude 125 Hz one.

src/help/06-navigate.txt

@@ -1,57 +0,0 @@
-<b>Navigating the plot</b>
-
-The plot pans and zooms with the mouse and with the keyboard. Every gesture acts on the row the
-pointer is over, and because the rows share one time axis, an x change moves all of them.
-
-<b>How to reach it</b>
-
-<b>Wheel</b> zooms both axes · <b>Shift+wheel</b> zooms x only · <b>Ctrl+wheel</b> zooms y only.
-<b>Drag</b> pans · <b>Ctrl+drag</b> is a box zoom on x · <b>Alt+drag</b> a box zoom on y.
-<b>+</b> and <b>-</b> zoom both axes; <b>Ctrl</b> with them restricts to x, <b>Alt</b> to y.
-<b>Arrow keys</b> pan, <b>f</b> fits, <b>Escape</b> cancels a gesture in progress.
-The full table is in the shortcut overview (<tt>Ctrl+/</tt>).
-
-<b>Worth knowing</b>
-
-• The keyboard zoom's modifiers are <i>not</i> the wheel's, and that is deliberate: on common
-  layouts <tt>+</tt> <i>is</i> shift+<tt>=</tt>, so a bare zoom-in already arrives with Shift
-  set and Shift could not mean anything. Ctrl/Alt mirror the box-zoom drags instead.
-• A <i>pinned</i> view is navigable within its own data but cannot leave it. While an event is
-  held, a capture is filling, or the view is paused, a zoom <i>in</i> works normally — "not
-  outside the event" is not "not readable" — but a pan or a zoom out is clamped to the data.
-• Nothing you do on the plot changes the <i>time window</i> — only the header control does. A
-  zoom or a pan moves the view inside the window; <b>f</b> (and Fit X axis) is the <i>undo</i> of a
-  zoom, so a 2 s window zoomed into reads 2 s again. The window is more than the axis: it is also
-  the trigger's event span and how the samples are stored, so a wheel notch that redefined it
-  would re-plan the buffer and drop your history.
-• The axis does not scroll — the <i>data</i> does. A live axis is a fixed <tt>[-window .. 0]</tt>
-  with the newest sample at 0, so the labels stand still and the trace rolls under them. The
-  cursors stand still with the labels (they are positions on screen, so a cursor you placed stays
-  where you put it, over newer data each frame), while a measurement's marks travel with the
-  sample they measured and leave the view when it does.
-• A live view is clamped to the window you asked for, not to what the ring happens to hold.
-  That is why a buffer that has only just started filling leaves its left-hand side empty
-  instead of squeezing the window down to the first few samples.
-• Zooming hard into a held capture is exact. The renderer finds the visible samples by binary
-  search over the real timestamps, never over a nominal sample grid, so a capture whose clock
-  wandered does not drift away from its axis as you zoom.
-• A trace holding far more samples than the plot has pixels is drawn <i>one pixel column at a
-  time</i>: each column is a single vertical line from the lowest to the highest value that falls
-  in it. Drawn as a polyline instead, such a window puts three or four near-vertical lines in
-  every column at slightly different sub-pixel positions, and how they overlap beats against the
-  pixel grid — which reads as bands of light and dark that <i>crawl</i> as you pan. One line per
-  column removes the beat, and it is also much faster: a 1 MS/s view costs a couple of thousand
-  line segments a frame instead of a couple of hundred thousand.
-• Those columns are <i>graded by brightness</i>, the way a digital-phosphor scope reads: bright
-  where the signal spent its time, faint where it only passed through. A column's highest and
-  lowest value are the same whether the samples in it are spread evenly or piled at its two ends,
-  so the grading is what tells the two apart — the flat parts of a square wave come out solid and
-  the edges between them faint. It is read from a finer division of each column rather than from
-  the line that is drawn, and it costs about a millisecond a frame.
-
-<b>Example</b>
-
-Pause a live view, then press <tt>Ctrl++</tt>: x narrows and y does not move. Press
-<tt>Alt++</tt>: y narrows and x does not. Eight doublings into a held 2 s capture, the trace
-still reaches both margins — the zoom probe reports <tt>gap_px</tt> and <tt>end_px</tt> within
-a pixel or two at every step.

src/help/07-pause.txt

@@ -1,31 +0,0 @@
-<b>Pause and play</b>
-
-Pause freezes the <i>display</i>, not the acquisition. The producer keeps filling the ring at
-full rate; the view binds an immutable snapshot of the window that was on screen, and the axis
-is pinned to it.
-
-<b>How to reach it</b>
-
-The pause button in the toolbar, or <tt>Space</tt>. Press it again to resume, which rebinds the
-live ring and puts the window back on the newest data.
-
-<b>Worth knowing</b>
-
-• Nothing is lost while paused. Because the producer never stops, resuming shows current data
-  with no hole in the history behind it.
-• The axis is pinned to the <i>snapshot's own stamps</i>, not to the window that was requested.
-  A window reaching back past the oldest retained sample yields a shorter snapshot, and the
-  pinned axis is that shorter span — so you see a narrower view rather than an empty margin.
-• A paused view is pinned exactly as a held trigger event is: zoom in freely, but a pan or a
-  zoom out is clamped to the snapshot's data.
-• Pausing is the easiest way to measure a layout or read a cursor precisely, because nothing
-  under the pointer moves between frames.
-• The status bar says how long you have been paused — wall time, since the stream itself never
-  stopped. It is there so a frozen picture cannot be mistaken for a live one that went quiet.
-
-<b>Example</b>
-
-Pause with a 2 s window over a ring holding 1.4 s: the frozen axis reads
-<tt>[-1.40 .. 0.00]</tt> rather than <tt>[-2.00 .. 0.00]</tt> with 0.6 s of blank. The pause
-probe reports <tt>ring_produced</tt> still growing across the pause and
-<tt>event_size</tt> non-zero exactly while paused.

src/help/08-trigger.txt

@@ -1,35 +0,0 @@
-<b>Trigger</b>
-
-The trigger watches one signal for an edge through a level and captures a window around it.
-The captured window is frozen on screen until you re-arm.
-
-<b>How to reach it</b>
-
-The trigger button in the toolbar (<tt>t</tt>) reveals the trigger panel: the signal, the level,
-the edge (rising, falling, either), the mode (Normal or Single) and the pre-trigger share.
-<b>Arm</b> starts watching; <tt>a</tt> arms and disarms from the keyboard.
-
-<b>Worth knowing</b>
-
-• Arming <i>enables</i> the signal if it was off, because a trigger on a signal nobody acquires
-  can never fire.
-• The pre-trigger share is a share of the <i>display window</i>, not of the ring. A 2 s window
-  at 50% captures 1 s before the edge and 1 s after.
-• There are four display states, and the status bar names each: <tt>armed</tt> (watching,
-  nothing drawn yet), <tt>capturing</tt> (the edge was accepted and the post window is filling
-  <i>in view</i>, with the marker at x = 0), <tt>event held</tt> (the frozen capture) and
-  <tt>disarmed</tt>. A held capture is never quietly replaced by live data.
-• The first edge after arming is only accepted once the history reaches back a full pre-trigger
-  window, so a capture may legitimately be shorter than you asked for. The axis is pinned to
-  what the capture actually got.
-• Disarming <i>during</i> a capture publishes what the capture got to, so the picture on screen
-  at that moment stays on screen. No event fired, so the event count does not move.
-• The trigger reads the <b>stored</b> signal — decimated and averaged — not the wire signal.
-  A spike narrower than one decimation group is filtered away rather than triggering on data
-  the buffer does not contain.
-
-<b>Example</b>
-
-A 1 Hz sine, level 0, rising, 2 s window at 50%, Single. The capture spans
-<tt>[-1.000 .. 1.000]</tt> with <tt>n=20001</tt> samples at 10 kS/s — the span times the real
-rate, plus one — and the marker sits at x = 0 throughout.

src/help/09-cursors.txt

@@ -1,50 +0,0 @@
-<b>Cursors</b>
-
-Cursors read values off the traces. There are two kinds: one <i>shared vertical pair</i> that
-every row carries at the same time, and <i>horizontal rulers</i>, one pair per row, that belong
-to that row alone.
-
-<b>How to reach it</b>
-
-The cursors button in the toolbar, or <tt>c</tt>. The pane below the plot shows the readings and
-owns a <b>Reset</b> button. Drag a marker to move it. The mode dropdown offers four modes:
-<tt>vertical</tt> (the shared time pair), <tt>horizontal</tt> (the per-row rulers),
-<tt>both</tt>, and <tt>mix</tt>.
-
-<b>Worth knowing</b>
-
-• The vertical pair is <i>one</i> time for the whole figure, so moving it on any row moves it on
-  all of them. That is what makes <tt>dt</tt> meaningful across rows.
-• A ruler belongs to its row and nothing shares it, so two rows' rulers are independent.
-• <tt>mix</tt> is the reading mode: one line per <i>bound</i> trace, with the trace's own values
-  at each marker and their difference. A slot with a name but no channel behind it is not a
-  trace and gets no line.
-• A value is the <i>nearest stored sample's</i>, never a number between two samples. Zoom in past
-  the sample spacing and the line between two samples is something the plot drew, not data —
-  so a reading off it would be the drawing. The hover crosshair reads the same way.
-• Every reading carries a <i>metric prefix</i> so the digits sit in <tt>1..999</tt>:
-  <tt>10.52 mV</tt>, not <tt>0.01 V</tt>. Two decimals is all an instrument landing on an
-  <tt>f32</tt> sample can claim, so without the prefix a small value would read <tt>0.00</tt>
-  and the reading would be gone. A stream that declares no unit gets the prefix anyway, written
-  tight against the number (<tt>585.24m</tt>) — the space separates the number from its unit,
-  and a spaced <tt>m</tt> with nothing after it would read as metres.
-• A marker past the newest sample reads <tt>--</tt>. With only one marker over data the row
-  reads <tt>partial</tt>: a difference between a number and nothing is not a number.
-• In <tt>mix</tt> each marker also places a crossing annotation per trace, which is what lets
-  you see on the plot which sample a number came from. It is <i>on that sample</i>, so when the
-  marker falls between two it sits a little off its own line: the line is where you put the
-  marker, the dot is the datum being quoted. The hover crosshair's mark snaps the same way, and
-  is drawn larger than a trace's sample dots so it does not read as one more sample.
-• The time row exists only in the modes that show the vertical pair. <tt>horizontal</tt> has no
-  time row, by design.
-• A cursor <i>stays where you put it</i> while a live view rolls under it, which is what a bench
-  scope does: its <tt>T0</tt> is an age, so a marker left at <tt>-1.5s</tt> keeps reading the
-  sample a second and a half old as the stream advances. A measurement's marks do the opposite —
-  they travel with the sample they measured — because a cursor is a question you asked and a mark
-  is an answer about one particular sample.
-
-<b>Example</b>
-
-Three traces in <tt>mix</tt> mode with both markers over data: 3 lines and 6 crossing marks,
-each line reading like <tt>sine  0.31 V  -0.84 V  -1.15 V</tt>. Move the second marker past the
-newest sample and the third column reads <tt>--</tt>.

src/help/10-measurements.txt

@@ -1,54 +0,0 @@
-<b>Measurements</b>
-
-A measurement is a statistic of the <i>visible window</i> of one signal, recomputed as that
-window moves. The pane lists them with their values; each can also draw its result on the plot.
-
-<b>How to reach it</b>
-
-The measurements button in the toolbar, or <tt>m</tt>. The pane's <tt>+</tt> adds one; clicking
-a row opens the dialog where the signal, the type, the threshold share and the on-plot marks are
-set, with <b>Save</b> and <b>Delete</b>.
-
-<b>Worth knowing</b>
-
-• The types are average, top, bottom, min, max, peak to peak, amplitude, pulse duration, period
-  and frequency. <i>top</i> and <i>bottom</i> are the means of the upper and lower halves, which
-  is why a unit sine reads 0.637 (2/π) rather than 1.
-• The on-plot marks come in two kinds and the mix is the reading: a <i>level</i> mark is a ruler
-  at a value, a <i>time</i> mark is a marker at a position. An average draws one level mark; a
-  max draws a level mark <i>and</i> a time mark at the first sample that reached it.
-• Marks cannot be dragged. A measurement mark says what the measurement measured, so it is
-  created unselectable — as is the trigger marker.
-• A pass is throttled to a cadence rather than run every frame, so a ruler over a live view is
-  <i>stepped</i>. The number and the ruler come from the same pass, so they always agree.
-• An invalid pass keeps its <i>level</i> marks and drops its <i>time</i> marks. A level is a
-  property of the signal and outlives the window; a position inside the window does not. That is
-  what stops the rulers blinking off at a mode change.
-• A crossing is counted with <i>hysteresis</i>, not on a bare level: the thresholds are a tenth of
-  the window's peak to peak either side of the share, and an edge is counted only once the signal
-  has passed the far one. Period, frequency and pulse duration all depend on it. The mid level is
-  exactly where a waveform moves fastest, so any interferer faster than the fundamental recrosses a
-  single level several times per real crossing — a 5 Hz sine with a 500 Hz tone at a tenth of the
-  amplitude reads 39 Hz without the band and 5 Hz with it. The band holds to an interferer a third
-  of the waveform's own size.
-• The band is clamped to stay inside the data, which is what keeps a threshold set near an extreme
-  usable: a fixed band there would sit above every sample and the measurement would read nothing.
-  A share near an extreme still leaves the band little room, so it rejects less — which is one
-  reason period and frequency offer no share to set.
-• A window with too few crossings reads <tt>invalid</tt> / <tt>--</tt> rather than a plausible
-  invented number. Frequency over a window holding one edge is the usual case.
-• <tt>frequency</tt> is reported in Hz and <tt>period</tt>/<tt>pulse duration</tt> in seconds;
-  every other type carries the channel's own unit. A value is written with a <i>metric prefix</i>
-  so its digits sit in <tt>1..999</tt> — <tt>636.62 mV</tt>, not <tt>0.64 V</tt> — including when
-  the stream declares no unit at all, which is always the case for a math channel: there the
-  prefix goes tight against the number (<tt>636.62m</tt>), since two decimals of an unprefixed
-  small value is <tt>0.00</tt>.
-• Cost is bounded by reading the summary pyramid the producer already maintains, not the raw
-  window. The values are still exact: a bucket's sum is a sum.
-
-<b>Example</b>
-
-On a 1 Hz ±1 sine: <tt>average=0</tt>, <tt>top=0.636620</tt>, <tt>bottom=-0.636620</tt>,
-<tt>max=1</tt>, <tt>min=-1</tt>, <tt>peak to peak=2</tt>, <tt>amplitude=1</tt>,
-<tt>pulse duration=0.5 s</tt> (duty 0.5), <tt>period=1 s</tt>, <tt>frequency=1 Hz</tt>. Over a
-2 M-sample window those two passes read about 0.1% of the samples.

src/help/11-math.txt

@@ -1,51 +0,0 @@
-<b>Math channels</b>
-
-A math channel is a signal computed from other signals. You build it as a small graph — source
-nodes, operations, one output — and udpscope then treats the result as an ordinary channel.
-
-<b>How to reach it</b>
-
-The math button in the toolbar, or <tt>g</tt>. The pane's <tt>+</tt> adds a channel; opening one
-shows the graph editor: nodes as boxes, click a box to select it and edit its parameters beside
-the canvas, click an output port then an input port to wire them, drag a box to move it. The
-orange dot marks the output node.
-
-<b>Worth knowing</b>
-
-• The graph is evaluated as an ordered list, so a node may only read ones <i>above</i> it. A
-  cycle is impossible by construction rather than rejected by a check.
-• A derived channel <i>is</i> a channel. It appears in the signal panel, can be plotted,
-  measured, exported, and used as a source for another math channel.
-• The math runs on the <b>stored</b> samples — decimated and averaged — so a cutoff you type in
-  Hz means the rate the filter will actually run at. Change the window across a decimation
-  boundary and the coefficients are rebuilt for the new rate.
-• A source may only name an <i>acquired</i> channel. The stream's timestamp signal is not one:
-  a graph sourced from it validates and then reads NaN for ever, so the dropdown does not
-  offer it.
-• The output defaults to the <i>last</i> node, and a node added to a linear graph becomes the
-  output. Choosing an earlier node explicitly is respected.
-• Every numeric field starts at its own identity value — gain 1, offset 0 — not at the bottom
-  of its range.
-
-<b>Example</b>
-
-<tt>[sine] → [gain x2]</tt> gives a channel reading <tt>y=[-2, 2]</tt>. A 100 Hz low pass on the
-same source passes 50 Hz at 0.97 and 2 kHz at 0.002; a 1 kHz band pass with Q=2 passes 200 Hz at
-0.05, 1 kHz at 0.95 and 4 kHz at 0.05. Each derived channel must hold exactly as many samples as
-the shared clock has time slots.
-
-<b>Why an operation sometimes does nothing</b>. A graph's <i>output</i> is the node whose value
-becomes the channel, and it is drawn as the orange dot. A new graph is built source, then operation,
-and the last node added becomes the output -- but a graph whose output is left on the source is
-valid and simply passes its input through, which is the usual reason a gain or a filter appears to
-have no effect. <i>Set as output</i> moves the dot.
-
-<b>Save refuses an incomplete graph</b>, and says why: an input that is not connected, no output
-chosen, or a <i>channel</i> node naming a signal the scope is not acquiring. Only the channels being
-acquired are offered, because a source that is not acquired reads as no data for ever -- and a graph
-that reads NaN is harder to diagnose than one that would not save.
-
-<b>The filters are real filters.</b> A math channel's samples are produced as the stream arrives,
-once per stored slot, so a low pass carries the history a filter needs. A cutoff typed in hertz is
-against the <i>stored</i> rate, which is the wire rate until a wide window makes the buffer decimate
--- the status line's rate is that number, and the filters are rebuilt whenever it changes.

src/help/12-export.txt

@@ -1,33 +0,0 @@
-<b>Saving and export</b>
-
-Export writes the <i>visible range</i> of every plotted trace to a file: NumPy <tt>.npy</tt> or
-<tt>.csv</tt>, chosen by the extension you type.
-
-<b>How to reach it</b>
-
-<b>Export visible range…</b> in the overflow menu, or <tt>Ctrl+E</tt>. A file chooser asks where;
-the format follows the path's extension.
-
-<b>Worth knowing</b>
-
-• The table is collected at the moment you click, not when the chooser returns. A live view keeps
-  scrolling while a dialog is up, so a late collection would write a window you never saw.
-• The rows are the <b>stored samples</b>, never the LOD buckets the plot draws from. A row count
-  far below the span times the stored rate means something cut the table from the pyramid.
-• The stored rate is not always the wire rate. A window long enough to need decimation is stored
-  averaged at a lower rate, and the export carries <i>that</i> — read the status bar's ⓘ popover
-  for the figure before trusting a sample count.
-• Two time columns. <tt>time</tt> is the display timeline — negative ages ending at 0 while
-  streaming, offsets from the trigger edge while an event is held — so it is the x you read a
-  value at on screen. <tt>abs_seconds</tt> is the source's own clock for the same sample, which
-  is what lets two exports taken in different modes line up. Both are strictly increasing and
-  evenly spaced; duplicate or backwards stamps would mean the file held two clocks.
-• An export taken <i>mid-capture</i> writes the partly filled window that is on screen, which is
-  shorter than the event span. Export outside a capture if you want the whole event.
-
-<b>Example</b>
-
-A 2 s window at 10 kS/s over 3 traces writes 20001 rows and 5 columns
-(<tt>time</tt>, <tt>abs_seconds</tt>, three signals). The <tt>.npy</tt> is
-<tt>64·⌈(10+len(header)+1)/64⌉ + rows·(16 + 4·cols)</tt> bytes. Read it back with
-<tt>pd.DataFrame(np.load(path))</tt>.

src/help/13-sessions.txt

@@ -1,34 +0,0 @@
-<b>Sessions and settings</b>
-
-udpscope stores one session file per source, so reopening a source gives you the scope you
-closed. There is no global preferences file: the session <i>is</i> the settings.
-
-<b>How to reach it</b>
-
-Nothing to open — the file is written as you work. Its path is in the About dialog, and the
-directory is <tt>$XDG_CONFIG_HOME/udpscope</tt>, or <tt>~/.config/udpscope</tt> when that is
-unset. Each file is named <tt>&lt;host&gt;_&lt;port&gt;.toml</tt>.
-
-<b>Worth knowing</b>
-
-• What a session persists: the time window, the rows and each row's slot signals, the
-  calibration, which signals are enabled, the math channels with their graphs, and the
-  measurements pane.
-• Signal identity is the <i>name</i> throughout, because a new CONFIG renumbers the channels.
-• A file written by a run against a source whose streamer was down would name no signals at all,
-  so such a run does <b>not</b> write: a configured session is never overwritten by a run that
-  configured nothing.
-• The multicast group and the interface live <i>inside</i> the file, because its name cannot
-  carry them. A file from an older build has neither key and loads as unicast on the default
-  route.
-• The startup chooser lists only files that name at least one signal, which is what keeps it the
-  sources you configured rather than every port you have ever tested against.
-• Deleting a file is a supported way to start a source over; the chooser's <tt>×</tt> does
-  exactly that.
-
-<b>Example</b>
-
-Connect to <tt>127.0.0.1:8000</tt>, drop three signals on row 1 and set a 2 s window.
-<tt>~/.config/udpscope/127.0.0.1_8000.toml</tt> now holds <tt>rows=1 window_s=2</tt> with
-<tt>signals = ["sine", "ramp", "noise", ""]</tt>, and the next run reports
-<tt>layout loaded from …/127.0.0.1_8000.toml</tt> with those signals already acquired.

src/help/14-status.txt

@@ -1,46 +0,0 @@
-<b>Status bar and diagnostics</b>
-
-The status bar is two tiers. The bar itself is one glance line — the state, the rate and the
-window — and everything else is behind the ⓘ button at its right-hand end.
-
-<b>How to reach it</b>
-
-The bar is always visible under the plot. Click <b>ⓘ</b> for the detail popover.
-
-<b>Worth knowing</b>
-
-• The badge is one glyph in four colours: green <i>alternating</i> lit and dim means data is
-  arriving, and a steady colour means it is not. A badge that never blinks is not a working badge.
-  Of the two steady colours, <i>grey</i> is no stream at all or a pipeline you stopped (the
-  tooltip says which), and <i>yellow</i> is a source that answered but has sent no configuration.
-• The state field is one word from a fixed set: <tt>connecting</tt>, <tt>live</tt>,
-  <tt>paused</tt>, <tt>armed</tt>, <tt>capturing</tt>, <tt>event held</tt>, <tt>disarmed</tt>. Two
-  states add one field each: in trigger mode, how long ago the last event was; while paused, how
-  long you have been paused.
-• <tt>connecting</tt> means there is no <i>signal list</i> yet — either no session or a session
-  with no configuration behind it. Every other word claims a signal list, so until one arrives
-  there is nothing for them to describe: nothing can be enabled and no data is owed.
-• The paused figure is <i>wall</i> time, not stream time — the producer never stops while paused,
-  so it answers "how long have I been looking at this picture".
-• Nothing on the bar may change width with the stream, because the bar sits directly above the
-  plot and a wider label would relayout it. That is why the rate collapses to one figure or a
-  range rather than listing per channel, and why an elapsed time steps to a coarser unit instead
-  of growing digits.
-• <tt>gaps</tt> counts packets the receiver knows it missed. It is the number that matters: a
-  non-zero count means samples are absent from the buffer, not merely late.
-• <tt>reconnects</tt> counts sessions re-established with the source. Over unicast a climbing
-  count usually means a second client is taking the source's single session.
-• The starvation notice — <i>connected, but no data is arriving</i> — is that same situation seen
-  from the other side: the signal list is here, so something took the stream away. A source that
-  has sent <i>no</i> configuration gets a different notice, <i>trying to connect</i>, because
-  nothing was taken away — pointing the app at a port where nothing answers is that case, and the
-  usual cause is a streamer that is not running or is serving another port.
-• <tt>stored</tt> versus <tt>wire</tt> in the popover is the decimation. They differ exactly
-  when the window is too long to store at full rate.
-
-<b>Example</b>
-
-The bar reads <tt>● live · 10 kS/s · 2 s window</tt>. Behind ⓘ:
-<tt>Stream  connected, configured / packets 717 · frames 716 · gaps 0 / 3 signals · 3 channels</tt>,
-<tt>Buffer  200.0 MB · 1677 s span · time x1 / stored 10 kS/s (wire 10 kS/s)</tt>,
-<tt>Plot 1  3 traces · 195000 samples</tt>, <tt>Reconnects  0</tt>.

src/help/udpscope-help.gresource.xml

@@ -1,34 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-  SPDX-License-Identifier: MIT
-
-  The help pages, compiled into the binary for the same reason the icons are: udpscope is
-  run straight out of the build tree and has no install step, so a search path would have
-  to be located at runtime and the failure mode of not locating it is a help window full
-  of missing pages.
--->
-<gresources>
-  <gresource prefix="/org/udpscope/help">
-    <file>01-overview.txt</file>
-    <file>02-source.txt</file>
-    <file>03-signals.txt</file>
-    <file>04-layout.txt</file>
-    <file>05-window.txt</file>
-    <file>06-navigate.txt</file>
-    <file>07-pause.txt</file>
-    <file>08-trigger.txt</file>
-    <file>09-cursors.txt</file>
-    <file>10-measurements.txt</file>
-    <file>11-math.txt</file>
-    <file>12-export.txt</file>
-    <file>13-sessions.txt</file>
-    <file>14-status.txt</file>
-  
-    <!-- The screenshots live with the user documentation (docs/); the resource aliases
-         them under `img/` so a help page can name one by resource path. The path is relative
-         to this manifest's directory. -->
-    <file alias="img/main-window.png">../../docs/img/main-window.png</file>
-    <file alias="img/trigger-capture.png">../../docs/img/trigger-capture.png</file>
-    <file alias="img/math-editor.png">../../docs/img/math-editor.png</file>
-  </gresource>
-</gresources>

src/help_window.cpp

@@ -3,25 +3,35 @@
 
 #include <adwaita.h>
 
-#include <cstdio>
+#include <functional>
 #include <string>
+#include <vector>
 
 #include "build_info.hpp"
 #include "layout_store.hpp"
-#include "shortcuts.hpp"
+
+// Both come from CMakeLists: the document identifier is derived from the desktop file's
+// basename (its desktop-file id), and the directory is where the Mallard set lives in the
+// source tree, which is what the self-check scans. Yelp resolves `help:<identifier>` to
+// `<datadir>/help/<lang>/<identifier>/` on its own (freedesktop Help System Specification),
+// so the identifier and the installed directory have to name the same set -- which is why
+// neither is written out again here.
+static_assert(sizeof(UDPSCOPE_HELP_NAME) > 1, "UDPSCOPE_HELP_NAME must come from the build");
+static_assert(sizeof(UDPSCOPE_HELP_DIR) > 1, "UDPSCOPE_HELP_DIR must come from the build");
 
 namespace udpscope {
 namespace {
 
-/// Nulled by each window's own close handler, so a second open cannot present a dead widget.
+/// Nulled by each dialog's own close handler, so a second open cannot present a dead widget.
-/// One pointer per window, file-scope because there is one application.
+/// One pointer per dialog, file-scope because there is one application. The help manual is no
-///
+/// longer one of these: it opens in a separate viewer process through the `help:` URI, and a
-/// The help window is a `GtkWindow`. The other two are `AdwDialog`s, which are **not**
+/// process with no window of ours has nothing to null.
-/// `GtkWindow`s: they have no `::close-request`, so they clear on `::closed` and close with
-/// `adw_dialog_close()`.
-GtkWidget* g_help = nullptr;
 AdwDialog* g_about = nullptr;
-AdwDialog* g_shortcuts = nullptr;
+/// The overview is built from a `.ui` file, so its builder is held too: the window belongs to
+/// the builder, and a *destroyed* `GtkWindow` cannot be presented again -- which is why the
+/// builder is replaced on the next opening rather than reused.
+GtkWidget* g_shortcuts = nullptr;
+GtkBuilder* g_shortcuts_ui = nullptr;
 
 gboolean on_window_close(GtkWindow* window, gpointer slot) {
   (void)window;
@@ -36,102 +46,58 @@ void on_dialog_closed(AdwDialog* dialog, gpointer slot) {
   *static_cast<AdwDialog**>(slot) = nullptr;
 }
 
-struct HelpPage {
+/// What an asynchronous launch needs to survive the call: the window it is attributed to (held,
-  const char* section;   ///< the group heading in the sidebar
+/// because the call outlives the stack frame that made it) and the caller's reporter, if it asked
-  const char* title;     ///< the row's label and the page's heading
+/// for one. One small struct rather than two `gpointer`s, because a callback that takes both through
-  const char* resource;  ///< a path under /org/udpscope/help
+/// one `user_data` still has to get them there.
-  /// The screenshots shown above the text, as resource paths and a null terminator. A page
+struct HelpLaunch {
-  /// with none is the common case and the reason this is a list rather than one field: the
+  GtkWindow* parent = nullptr;
-  /// overview carries two, the window and a held capture.
+  std::function<void(bool, const std::string&)> done;
-  const char* const* images = nullptr;
 };
 
-/// Adding a page is one .txt file, one <file> line in the manifest and one row here.
+/// The launch failed. Report it rather than leaving a click that silently did nothing -- and say
-/// The order here is the order the sidebar shows; `section` groups consecutive rows.
+/// *which* thing is missing: `gtk_uri_launcher_launch_finish()` reports that the URI could not be
-/// How tall a page's screenshots are drawn. They are scaled to fit this *height* and centre
+/// handed over, which is the handler's absence, while a document that is not installed is a
-/// themselves in it, so a 1500x950 capture is readable without a horizontal scrollbar.
+/// different failure the launcher cannot tell it from. `help_installed_path()` settles that from the
-constexpr int kHelpShotHeight = 260;
+/// file system, so a missing *document* is not reported as a missing *handler*: with the manual
-
+/// installed the message names the viewer, and without it the message names the document, its
-/// The screenshots each page carries, in the order it shows them.
+/// expected path and the install command -- and a viewer as well, because that second possibility
-constexpr const char* kOverviewShots[] = {"/org/udpscope/help/img/main-window.png",
+/// cannot be ruled out from here.
-                                          "/org/udpscope/help/img/trigger-capture.png",
+void on_help_launched(GObject* source, GAsyncResult* result, gpointer user) {
-                                          nullptr};
+  auto* launch = static_cast<HelpLaunch*>(user);
-constexpr const char* kTriggerShots[] = {"/org/udpscope/help/img/trigger-capture.png",
-                                         nullptr};
-constexpr const char* kMathShots[] = {"/org/udpscope/help/img/math-editor.png", nullptr};
-
-constexpr HelpPage kPages[] = {
-    {"Getting started", "Overview", "/org/udpscope/help/01-overview.txt", kOverviewShots},
-    {"Getting started", "Choosing a source", "/org/udpscope/help/02-source.txt"},
-    {"Getting started", "Signals and calibration", "/org/udpscope/help/03-signals.txt"},
-    {"Getting started", "Rows, layout and drag & drop", "/org/udpscope/help/04-layout.txt"},
-    {"Viewing", "Time window", "/org/udpscope/help/05-window.txt"},
-    {"Viewing", "Navigating the plot", "/org/udpscope/help/06-navigate.txt"},
-    {"Viewing", "Pause and play", "/org/udpscope/help/07-pause.txt"},
-    {"Viewing", "Trigger", "/org/udpscope/help/08-trigger.txt", kTriggerShots},
-    {"Analysis", "Cursors", "/org/udpscope/help/09-cursors.txt"},
-    {"Analysis", "Measurements", "/org/udpscope/help/10-measurements.txt"},
-    {"Analysis", "Math channels", "/org/udpscope/help/11-math.txt", kMathShots},
-    {"Output and state", "Saving and export", "/org/udpscope/help/12-export.txt"},
-    {"Output and state", "Sessions and settings", "/org/udpscope/help/13-sessions.txt"},
-    {"Output and state", "Status bar and diagnostics", "/org/udpscope/help/14-status.txt"},
-};
-constexpr int kPageCount = static_cast<int>(sizeof(kPages) / sizeof(kPages[0]));
-
-/// The page's markup, or a one-line stand-in. `ok` reports whether the real body loaded
-/// *and* parsed: a missing resource and markup Pango rejects both render the stand-in,
-/// because a help window that fails to open is worse than one page that says so.
-std::string load_page(const HelpPage& page, bool* ok) {
-  *ok = false;
   GError* error = nullptr;
-  GBytes* bytes = g_resources_lookup_data(page.resource, G_RESOURCE_LOOKUP_FLAGS_NONE,
+  const bool ok = gtk_uri_launcher_launch_finish(GTK_URI_LAUNCHER(source), result, &error);
-                                          &error);
+  if (!ok) {
-  if (bytes == nullptr) {
+    const std::string installed = help_installed_path();
+    GtkAlertDialog* alert = gtk_alert_dialog_new("Could not open the help manual");
+    std::string detail = error != nullptr ? error->message : std::string("the launch failed");
+    detail += "\n\n";
+    if (!installed.empty()) {
+      detail += "The manual is installed at " + installed +
+                ", so what is missing is a viewer for the `help:` URI it is opened with: install "
+                "one (for example `yelp`) or make it the desktop's default for that scheme.";
+    } else {
+      // The system-wide install is named *first* on purpose: a set under the user's data
+      // directory is one a sandboxed viewer (Yelp) cannot read its figures from -- the pages
+      // open without their images -- so the no-root route carries that caveat rather than
+      // leading. The message is kept no longer than the one it replaces; do the same on edit.
+      detail += "The manual does not look installed: nothing named \"help:" UDPSCOPE_HELP_NAME
+                "\" was found where `help:` resolves. Install it system-wide:\n\n"
+                "    cmake -DCMAKE_INSTALL_PREFIX=/usr .. && sudo cmake --build build --target install-help\n\n"
+                "That writes where the viewer looks. The no-root `install-help-user` writes under "
+                "your data directory instead: a sandboxed viewer shows those pages without their "
+                "figures. A `help:` viewer (for example `yelp`) is needed as well.";
+    }
+    gtk_alert_dialog_set_detail(alert, detail.c_str());
+    gtk_alert_dialog_show(alert, launch->parent);
+    g_object_unref(alert);
+  }
+  if (launch->done) {
+    launch->done(ok, ok || error == nullptr ? std::string() : std::string(error->message));
+  }
+  if (launch->parent != nullptr) g_object_unref(launch->parent);
+  delete launch;
   if (error != nullptr) g_error_free(error);
-    return "<i>This page is missing from the build.</i>";
-  }
-  gsize size = 0;
-  const char* data = static_cast<const char*>(g_bytes_get_data(bytes, &size));
-  std::string body(data, size);
-  g_bytes_unref(bytes);
-
-  if (!pango_parse_markup(body.c_str(), -1, 0, nullptr, nullptr, nullptr, &error)) {
-    if (error != nullptr) g_error_free(error);
-    return "<i>This page could not be displayed: its markup is malformed.</i>";
-  }
-  *ok = true;
-  return body;
-}
-
-void on_help_row_selected(GtkListBox*, GtkListBoxRow* row, gpointer body_label) {
-  if (row == nullptr) return;
-  const int idx = GPOINTER_TO_INT(g_object_get_data(G_OBJECT(row), "help-page"));
-  if (idx < 0 || idx >= kPageCount) return;
-  bool ok = false;
-  const std::string body = load_page(kPages[idx], &ok);
-  gtk_label_set_markup(GTK_LABEL(body_label), body.c_str());
-  // The screenshots above it, if this page has any. The column is the label's previous sibling
-  // inside the page's box, which is what lets this handler stay a matter of the label alone --
-  // and refilling it is a page *switch*, not a frame, so rebuilding it here is cheap and is
-  // also the only way to be sure the pictures are this page's and not the last one's.
-  GtkWidget* label = GTK_WIDGET(body_label);
-  GtkWidget* parent = gtk_widget_get_parent(label);
-  GtkWidget* shots = parent != nullptr ? gtk_widget_get_first_child(parent) : nullptr;
-  if (shots != nullptr && GTK_IS_BOX(shots)) {
-    while (GtkWidget* old = gtk_widget_get_first_child(shots)) {
-      gtk_box_remove(GTK_BOX(shots), old);
-    }
-    for (const char* const* img = kPages[idx].images; img != nullptr && *img != nullptr; ++img) {
-      GtkWidget* shot = gtk_picture_new_for_resource(*img);
-      gtk_picture_set_can_shrink(GTK_PICTURE(shot), TRUE);
-      // A height, and `CONTAIN` (the default) to fit the image inside it: a picture that may
-      // shrink asks for no height at all in a box, so without this it is allocated nothing and
-      // the page shows its text with a gap where the screenshots should be.
-      gtk_widget_set_size_request(shot, -1, kHelpShotHeight);
-      gtk_box_append(GTK_BOX(shots), shot);
-    }
-    gtk_widget_set_visible(shots, gtk_widget_get_first_child(shots) != nullptr);
-  }
 }
 
 }  // namespace
@@ -175,177 +141,114 @@ const char* about_icon_name() {
   return adw_about_dialog_get_application_icon(ADW_ABOUT_DIALOG(g_about));
 }
 
+std::string help_installed_path() {
+  // The freedesktop Help System Specification's own search order: `$XDG_DATA_HOME` first, then every
+  // `$XDG_DATA_DIRS` entry in order. Yelp resolves `help:<id>` the same way, so this is a reading of
+  // where the document *would* be found rather than a second, private convention.
+  std::vector<std::string> roots;
+  roots.emplace_back(g_get_user_data_dir() != nullptr ? g_get_user_data_dir() : "");
+  const char* const* dirs = g_get_system_data_dirs();
+  for (int i = 0; dirs != nullptr && dirs[i] != nullptr; ++i) roots.emplace_back(dirs[i]);
+  for (const std::string& root : roots) {
+    if (root.empty()) continue;
+    const std::string base = root + "/help";
+    GError* error = nullptr;
+    GDir* dir = g_dir_open(base.c_str(), 0, &error);
+    if (dir == nullptr) {
+      if (error != nullptr) g_error_free(error);
+      continue;
+    }
+    // `<lang>` is a directory of its own (`C`, `en`, `it`, ...), so the document is looked for one
+    // level below the `help` root rather than straight under it.
+    while (const char* lang = g_dir_read_name(dir)) {
+      const std::string candidate = base + "/" + lang + "/" UDPSCOPE_HELP_NAME;
+      if (g_file_test((candidate + "/index.page").c_str(), G_FILE_TEST_IS_REGULAR)) {
+        g_dir_close(dir);
+        return candidate;
+      }
+    }
+    g_dir_close(dir);
+  }
+  return std::string();
+}
+
 HelpReport help_self_check() {
   HelpReport report;
-  report.pages = kPageCount;
+
-  for (const HelpPage& page : kPages) {
+  // The manual is a set of files on disk now, so the reading is a file-system one: a missing
-    bool ok = false;
+  // directory leaves `topics=0 index=false`, which is a manual that is not where the build
-    const std::string body = load_page(page, &ok);
+  // says it is -- and Yelp would show nothing for `help:<identifier>`.
-    if (ok && !body.empty()) ++report.parsed;
+  GError* error = nullptr;
-    if (report.shortest_title.empty() || body.size() < report.shortest_bytes) {
+  GDir* dir = g_dir_open(UDPSCOPE_HELP_DIR, 0, &error);
-      report.shortest_title = page.title;
+  if (dir == nullptr) {
-      report.shortest_bytes = body.size();
+    if (error != nullptr) g_error_free(error);
+    return report;
   }
+  while (const char* name = g_dir_read_name(dir)) {
+    if (!g_str_has_suffix(name, ".page")) continue;
+    if (g_strcmp0(name, "index.page") == 0) report.index = true;
+    else ++report.topics;
+  }
+  g_dir_close(dir);
+
+  // The figures the pages reference, counted for the same reason: an image that went missing
+  // is a broken figure in the viewer rather than a failed build.
+  const std::string figures = std::string(UDPSCOPE_HELP_DIR) + "/figures";
+  if (GDir* figdir = g_dir_open(figures.c_str(), 0, &error)) {
+    while (const char* name = g_dir_read_name(figdir)) {
+      if (g_str_has_suffix(name, ".png") || g_str_has_suffix(name, ".jpg")) ++report.figures;
+    }
+    g_dir_close(figdir);
+  } else if (error != nullptr) {
+    g_error_free(error);
   }
   return report;
 }
 
-void show_help(GtkWindow* parent) {
+void show_help(GtkWindow* parent, std::function<void(bool, const std::string&)> done) {
-  if (g_help != nullptr) {
+  // The freedesktop `help:` URI, handed to whatever the desktop registered for it -- Yelp on
-    gtk_window_present(GTK_WINDOW(g_help));
+  // GNOME. The launch is asynchronous, so both the parent and the reporter are carried across it in
-    return;
+  // a heap `HelpLaunch` and released in the callback; `parent` may legitimately be nullptr (the
-  }
+  // chooser runs before any window exists).
-
+  auto* launch = new HelpLaunch;
-  GtkWidget* window = gtk_window_new();
+  launch->parent = parent != nullptr ? GTK_WINDOW(g_object_ref(parent)) : nullptr;
-  g_help = window;
+  launch->done = std::move(done);
-  gtk_window_set_title(GTK_WINDOW(window), "udpscope help");
+  GtkUriLauncher* launcher = gtk_uri_launcher_new("help:" UDPSCOPE_HELP_NAME);
-  gtk_window_set_default_size(GTK_WINDOW(window), 860, 640);
+  gtk_uri_launcher_launch(launcher, parent, nullptr, on_help_launched, launch);
-  gtk_window_set_transient_for(GTK_WINDOW(window), parent);
+  g_object_unref(launcher);
-
-  // One label, width-locked by the scrolled window, holding one page's markup. The
-  // sidebar swaps the markup rather than rebuilding anything.
-  GtkWidget* body = gtk_label_new(nullptr);
-  gtk_label_set_use_markup(GTK_LABEL(body), TRUE);
-  gtk_label_set_wrap(GTK_LABEL(body), TRUE);
-  gtk_label_set_xalign(GTK_LABEL(body), 0.0f);
-  gtk_label_set_yalign(GTK_LABEL(body), 0.0f);
-  gtk_label_set_selectable(GTK_LABEL(body), TRUE);
-  gtk_widget_set_margin_start(body, 18);
-  gtk_widget_set_margin_end(body, 18);
-  gtk_widget_set_margin_top(body, 14);
-  gtk_widget_set_margin_bottom(body, 14);
-
-  GtkWidget* body_scroll = gtk_scrolled_window_new();
-  gtk_scrolled_window_set_policy(GTK_SCROLLED_WINDOW(body_scroll), GTK_POLICY_NEVER,
-                                 GTK_POLICY_AUTOMATIC);
-  // The page's own column: its screenshots above its text. Built once and *refilled* by the page
-  // switch, which is why no picture is made here -- one `GtkPicture` per image of the page.
-  GtkWidget* shot_box = gtk_box_new(GTK_ORIENTATION_VERTICAL, 8);
-  gtk_widget_set_margin_start(shot_box, 18);
-  gtk_widget_set_margin_end(shot_box, 18);
-  gtk_widget_set_margin_top(shot_box, 14);
-  gtk_widget_set_visible(shot_box, false);
-  GtkWidget* page_box = gtk_box_new(GTK_ORIENTATION_VERTICAL, 0);
-  gtk_box_append(GTK_BOX(page_box), shot_box);
-  gtk_box_append(GTK_BOX(page_box), body);
-  gtk_scrolled_window_set_child(GTK_SCROLLED_WINDOW(body_scroll), page_box);
-  gtk_widget_set_hexpand(body_scroll, TRUE);
-
-  GtkWidget* list = gtk_list_box_new();
-  gtk_list_box_set_selection_mode(GTK_LIST_BOX(list), GTK_SELECTION_SINGLE);
-  const char* current_section = nullptr;
-  for (int i = 0; i < kPageCount; ++i) {
-    if (current_section == nullptr ||
-        std::string(current_section) != kPages[i].section) {
-      current_section = kPages[i].section;
-      GtkWidget* heading = gtk_label_new(nullptr);
-      char markup[128];
-      std::snprintf(markup, sizeof(markup), "<b><small>%s</small></b>", current_section);
-      gtk_label_set_markup(GTK_LABEL(heading), markup);
-      gtk_label_set_xalign(GTK_LABEL(heading), 0.0f);
-      gtk_widget_set_margin_start(heading, 10);
-      gtk_widget_set_margin_top(heading, 10);
-      gtk_widget_set_margin_bottom(heading, 2);
-      GtkWidget* heading_row = gtk_list_box_row_new();
-      gtk_list_box_row_set_selectable(GTK_LIST_BOX_ROW(heading_row), FALSE);
-      gtk_list_box_row_set_activatable(GTK_LIST_BOX_ROW(heading_row), FALSE);
-      gtk_list_box_row_set_child(GTK_LIST_BOX_ROW(heading_row), heading);
-      gtk_list_box_append(GTK_LIST_BOX(list), heading_row);
-    }
-    GtkWidget* label = gtk_label_new(kPages[i].title);
-    gtk_label_set_xalign(GTK_LABEL(label), 0.0f);
-    gtk_widget_set_margin_start(label, 18);
-    gtk_widget_set_margin_end(label, 10);
-    gtk_widget_set_margin_top(label, 4);
-    gtk_widget_set_margin_bottom(label, 4);
-    GtkWidget* row = gtk_list_box_row_new();
-    gtk_list_box_row_set_child(GTK_LIST_BOX_ROW(row), label);
-    g_object_set_data(G_OBJECT(row), "help-page", GINT_TO_POINTER(i));
-    gtk_list_box_append(GTK_LIST_BOX(list), row);
-  }
-  g_signal_connect(list, "row-selected", G_CALLBACK(on_help_row_selected), body);
-
-  GtkWidget* list_scroll = gtk_scrolled_window_new();
-  gtk_scrolled_window_set_policy(GTK_SCROLLED_WINDOW(list_scroll), GTK_POLICY_NEVER,
-                                 GTK_POLICY_AUTOMATIC);
-  gtk_scrolled_window_set_child(GTK_SCROLLED_WINDOW(list_scroll), list);
-  gtk_widget_set_size_request(list_scroll, 220, -1);
-
-  GtkWidget* split = gtk_box_new(GTK_ORIENTATION_HORIZONTAL, 0);
-  gtk_box_append(GTK_BOX(split), list_scroll);
-  gtk_box_append(GTK_BOX(split), gtk_separator_new(GTK_ORIENTATION_VERTICAL));
-  gtk_box_append(GTK_BOX(split), body_scroll);
-  gtk_window_set_child(GTK_WINDOW(window), split);
-
-  // Select the first page so the window never opens blank.
-  GtkListBoxRow* first = gtk_list_box_get_row_at_index(GTK_LIST_BOX(list), 1);
-  if (first != nullptr) gtk_list_box_select_row(GTK_LIST_BOX(list), first);
-
-  g_signal_connect(window, "close-request", G_CALLBACK(on_window_close), &g_help);
-  gtk_window_present(GTK_WINDOW(window));
 }
 
-namespace {
-
-/// Appends one table row to `dialog`, opening a new section whenever the row's `section`
-/// string differs from the last one. `*current` is the section being filled, `*title` the
-/// name it carries; both are owned by the caller so the two tables share one run.
-///
-/// `accel` is handed to `AdwShortcutsItem` as an accelerator when it is non-empty and
-/// `subtitle` is used when it is not, which is how a wheel or a drag gets a row: neither
-/// GTK's nor libadwaita's accelerator syntax can name one, and asking them to parse
-/// "Wheel" costs a parse warning and draws nothing.
-void append_shortcut(AdwShortcutsDialog* dialog, AdwShortcutsSection** current,
-                     const char** title, const char* section, const char* accel,
-                     const char* subtitle, const char* description) {
-  if (*current == nullptr || std::string(*title) != section) {
-    *current = adw_shortcuts_section_new(section);
-    *title = section;
-    adw_shortcuts_dialog_add(dialog, *current);
-  }
-  AdwShortcutsItem* item = adw_shortcuts_item_new(description, accel);
-  if (subtitle != nullptr && *subtitle != '\0') {
-    adw_shortcuts_item_set_subtitle(item, subtitle);
-  }
-  adw_shortcuts_section_add(*current, item);
-}
-
-}  // namespace
-
 void show_shortcuts(GtkWindow* parent) {
   if (g_shortcuts != nullptr) {
-    adw_dialog_present(g_shortcuts, GTK_WIDGET(parent));
+    gtk_window_present(GTK_WINDOW(g_shortcuts));
     return;
   }
 
-  AdwDialog* dialog = adw_shortcuts_dialog_new();
+  // A `GtkShortcutsWindow` from `src/ui/shortcuts.ui` -- gedit's arrangement, and GTK's own: one
-  g_shortcuts = dialog;
+  // section per page, with the sidebar and the search box drawn by the window itself. A UI file
-  adw_dialog_set_title(dialog, "Keyboard and mouse shortcuts");
+  // rather than widget construction because of the mouse rows: an accelerator cannot spell "Ctrl
-
+  // and drag", and libadwaita's `AdwShortcutsItem` -- the modern replacement -- has no icon
-  AdwShortcutsSection* section = nullptr;
+  // property, so its cell reads "No Shortcut". `GtkShortcutsShortcut`'s one generic gesture type
-  const char* section_title = nullptr;
+  // draws the `icon` the row names. (The widget is deprecated since 4.20, but this uses none of
-  int accel_count = 0;
+  // its functions: the file is loaded as data and presented as a `GtkWindow`.)
-  const Accel* accels = app_accels(&accel_count);
+  //
-  for (int i = 0; i < accel_count; ++i) {
+  // A builder per opening, not one reused: the window belongs to the builder and `close-request`
-    append_shortcut(ADW_SHORTCUTS_DIALOG(dialog), &section, &section_title,
+  // destroys the window, so the resource is parsed again rather than an already-dead window
-                    accels[i].section, accels[i].accel, "", accels[i].description);
+  // fetched.
-  }
+  g_clear_object(&g_shortcuts_ui);
-  int gesture_count = 0;
+  g_shortcuts_ui = gtk_builder_new_from_resource("/org/udpscope/ui/shortcuts.ui");
-  const Gesture* gestures = plot_gestures(&gesture_count);
+  if (g_shortcuts_ui == nullptr) return;
-  for (int i = 0; i < gesture_count; ++i) {
+  GObject* overlay = gtk_builder_get_object(g_shortcuts_ui, "help_overlay");
-    append_shortcut(ADW_SHORTCUTS_DIALOG(dialog), &section, &section_title,
+  if (overlay == nullptr) return;
-                    gestures[i].section, gestures[i].accel, gestures[i].subtitle,
+  g_shortcuts = GTK_WIDGET(overlay);
-                    gestures[i].description);
+  gtk_window_set_transient_for(GTK_WINDOW(g_shortcuts), parent);
-  }
+  g_signal_connect(g_shortcuts, "close-request", G_CALLBACK(on_window_close), &g_shortcuts);
-
+  gtk_window_present(GTK_WINDOW(g_shortcuts));
-  g_signal_connect(dialog, "closed", G_CALLBACK(on_dialog_closed), &g_shortcuts);
-  adw_dialog_present(dialog, GTK_WIDGET(parent));
 }
 
 void close_help_windows() {
-  if (g_help != nullptr) gtk_window_close(GTK_WINDOW(g_help));
   if (g_about != nullptr) adw_dialog_close(g_about);
-  if (g_shortcuts != nullptr) adw_dialog_close(g_shortcuts);
+  if (g_shortcuts != nullptr) gtk_window_close(GTK_WINDOW(g_shortcuts));
 }
 
 }  // namespace udpscope

src/help_window.hpp

@@ -4,6 +4,7 @@
 #include <gtk/gtk.h>
 
 #include <cstddef>
+#include <functional>
 #include <string>
 
 namespace udpscope {
@@ -18,20 +19,39 @@ void show_about(GtkWindow* parent, const std::string& session_path);
 /// so the dialog is asserted to *show* the app icon rather than merely to open.
 const char* about_icon_name();
 
-/// The paged help window. Modal on nothing — it is a reference, so it stays usable while
+/// Opens the installed Mallard manual in the desktop help viewer — Yelp, through the
-/// the scope runs. Already open: presented.
+/// `help:` URI the freedesktop Help System Specification defines — rather than drawing a
-void show_help(GtkWindow* parent);
+/// window of our own. `parent` is the window the launch is attributed to (and the one an
+/// error is reported on); the viewer is a separate process, so nothing here can be closed
+/// with `close_help_windows()`.
+///
+/// `done`, when the caller gives one, is called with the *launch*'s outcome: whether the
+/// `help:` URI was handed to a viewer, and the error text when it was not. It says nothing
+/// about the viewer itself — that process may fail for its own reasons and this side cannot
+/// see them — so it is the self-check's reading of the path and not a promise that a window
+/// appeared. The failure alert is shown either way; the callback is an extra, not instead.
+void show_help(GtkWindow* parent, std::function<void(bool ok, const std::string& error)> done = {});
 
-/// What UDPSCOPE_PROBE_HELP_MS reports. `parsed` counts pages whose markup
+/// Where `help:<id>` resolves to on this system: the first of `$XDG_DATA_HOME/help/<lang>/<id>/`
-/// pango_parse_markup() accepted and whose body is non-empty; it must equal `pages`.
+/// and `$XDG_DATA_DIRS/help/<lang>/<id>/` that holds an `index.page`, or an empty string when no
+/// such directory does. This is the specification's own resolution, and the distinction a launch
+/// failure turns on: a missing *document* (install it) and a missing *handler* (install a viewer)
+/// are different problems with different fixes, and only the file system can tell them apart.
+std::string help_installed_path();
+
+/// What UDPSCOPE_PROBE_HELP_MS reports about the manual *in the tree*. `topics` is the
+/// number of `<id>.page` files other than `index.page`, and `index` says whether
+/// `index.page` is present: the manual is now a set of files on disk (installed by the
+/// `install()` rule, and read by Yelp), not a GResource in the binary, so the self-check
+/// asserts the set is *there* and must be read as a file-system finding — `topics=0
+/// index=0` means the manual is missing from `UDPSCOPE_HELP_DIR`.
 struct HelpReport {
-  int pages = 0;
+  int topics = 0;
-  int parsed = 0;
+  bool index = false;
-  std::string shortest_title;
+  int figures = 0;
-  std::size_t shortest_bytes = 0;
 };
 
-/// Loads and validates every page without building a window. Safe to call headless.
+/// Scans the manual's directory without opening a viewer. Safe to call headless.
 HelpReport help_self_check();
 
 /// The shortcut overview: the application accelerators and the plot's own interactions,
@@ -39,11 +59,11 @@ HelpReport help_self_check();
 /// deprecated as of GTK 4.18 and this project builds warning-free.
 void show_shortcuts(GtkWindow* parent);
 
-/// Closes whichever of the three windows are open. One of them is a GtkWindow -- the help
+/// Closes whichever of the two dialogs are open. Both are `AdwDialog`s, which are not
-/// window, closed with gtk_window_close(), which emits close-request so its handler runs. The
+/// `GtkWindow`s: they close with `adw_dialog_close()`, which emits `::closed`, and the
-/// other two are AdwDialogs, which are not GtkWindows: they close with adw_dialog_close(),
+/// file-scope pointer is nulled by the handler that prevents a second open presenting a dead
-/// which emits ::closed. Either way the file-scope pointer is nulled by the handler, which is
+/// widget. There is no help window left to close -- the manual opens in a separate viewer
-/// what prevents a second open presenting a dead widget. Used by the probe.
+/// process. Used by the probe.
 void close_help_windows();
 
 }  // namespace udpscope

src/icons/scalable/actions/udpscope-events-symbolic.svg

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- SPDX-License-Identifier: MIT -->
+<!-- SPDX-FileCopyrightText: 2026 Martino Ferrari -->
+<!-- The event history: a list of what was latched. A frame with three rows in it, the
+     last one short, so it reads as a list that ends rather than one that continues. Every
+     coordinate is a whole pixel of the 16px cell, and every subpath is a clockwise filled
+     `path`: a stroke, a line or a polyline keeps the colour written here and stays dark on
+     a dark theme, and the frame's hole needs `evenodd` because the rows sit inside it.
+     (No double hyphen anywhere in a comment here: xmllint, which preprocess= runs it
+     through, rejects one and fails the whole build.) -->
+<svg height="16px" width="16px" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
+  <path fill="#2e3436" fill-rule="evenodd" d="M0 1 H16 V15 H0 Z
+                                             M2 3 H14 V13 H2 Z"/>
+  <path fill="#2e3436" d="M4 4 H12 V6 H4 Z
+                          M4 7 H12 V9 H4 Z
+                          M4 10 H9 V12 H4 Z"/>
+</svg>

src/icons/scalable/actions/udpscope-math-symbolic.svg

@@ -1,13 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- SPDX-License-Identifier: MIT -->
-<!-- SPDX-FileCopyrightText: 2026 Martino Ferrari -->
-<!-- A sigma: the one pane that computes rather than reads. Four filled subpaths, all
-     wound clockwise so the default nonzero rule unions them where they overlap; the
-     diagonals run from the bars' left ends to a vertex right of centre, which is the
-     way the glyph actually points. -->
-<svg height="16px" width="16px" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
-  <path fill="#2e3436" d="M3 2 H13 V4 H3 Z
-                          M3 12 H13 V14 H3 Z
-                          M4.64 2.23 L10.64 7.23 L9.36 8.77 L3.36 3.77 Z
-                          M10.64 8.77 L4.64 13.77 L3.36 12.23 L9.36 7.23 Z"/>
-</svg>

src/icons/scalable/actions/udpscope-resize-rows-symbolic.svg

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- SPDX-License-Identifier: MIT -->
+<!-- SPDX-FileCopyrightText: 2026 Martino Ferrari -->
+<!-- A boundary that can be dragged: a vertical double-headed arrow. It says *which* edge the handle
+     moves, which a plain grip does not. Every coordinate is a whole pixel of the 16px cell, every
+     subpath is a filled `path` wound the same way (a stroke would keep this colour on a dark theme),
+     and the two heads meet the shaft exactly, at x 5..11 and x 7..9. -->
+<svg height="16px" width="16px" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
+  <path fill="#2e3436" d="M7 4 H9 V12 H7 Z
+                          M8 1 L11 5 H5 Z
+                          M8 15 L5 11 H11 Z"/>
+</svg>

src/icons/scalable/actions/udpscope-trigger-symbolic.svg

@@ -1,16 +1,26 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- SPDX-License-Identifier: MIT -->
 <!-- SPDX-FileCopyrightText: 2026 Martino Ferrari -->
-<!-- A rising edge crossing a dashed trigger level: what the trigger *is*. The dash
+<!-- The trigger: a sine and the dashed level it is looked for at, which is what a trigger *is* on a
-     rhythm is 2 on, 1 off (tight enough to read as one line rather than as a row of
+     waveform that is not a step. It used to be a rising edge, and one edge names only one of the four
-     dots), with the one wide gap at x 5..9 that the edge rises through. Every
+     shape triggers the panel offers — a wave crossing a level names the trigger's job instead. One
-     coordinate is a whole pixel of the 16px cell so nothing blurs at 1x. -->
+     period, one-pixel stairs, the way the plot rasterises its own traces, with the level through the
+     centre so the crest and the trough stand clear and the crossings fall on the steep parts. Inset
+     two pixels, like the tabs' glyphs, so no art is flush with an edge a button might clip. -->
 <svg height="16px" width="16px" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
-  <path fill="#2e3436" d="M0 11 H8 V13 H0 Z
+  <path fill="#2e3436" d="M2 7 H3 V10 H2 Z
-                          M6 3 H8 V13 H6 Z
+                          M3 5 H4 V8 H3 Z
-                          M6 3 H16 V5 H6 Z
+                          M4 3 H5 V6 H4 Z
-                          M0 7 H2 V9 H0 Z
+                          M5 3 H6 V6 H5 Z
-                          M3 7 H5 V9 H3 Z
+                          M6 4 H7 V7 H6 Z
-                          M9 7 H11 V9 H9 Z
+                          M7 6 H8 V9 H7 Z
-                          M12 7 H14 V9 H12 Z"/>
+                          M8 8 H9 V11 H8 Z
+                          M9 10 H10 V13 H9 Z
+                          M10 11 H11 V14 H10 Z
+                          M11 11 H12 V14 H11 Z
+                          M12 9 H13 V12 H12 Z
+                          M13 7 H14 V10 H13 Z
+                          M2 7 H5 V9 H2 Z
+                          M7 7 H10 V9 H7 Z
+                          M11 7 H14 V9 H11 Z"/>
 </svg>