Correct downsampling and better layout

CLAUDE.md

@@ -14,7 +14,8 @@ cmake --build build
 ```
 
 Options: `--server`, `--port`, `--multicast`, `--interface`, `--buffer-mb` (per
-buffer, default 200), `--max-window`, `--holdoff`, `--recv-buffer`, `--plots` (1..4).
+buffer, default 200), `--max-window`, `--holdoff`, `--recv-buffer`, `--plots` (the row
+count to *start* with, 1..`RowSet::kMaxRows`; the layout editor owns it afterwards).
 
 `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
@@ -25,7 +26,25 @@ there rather than worked around here: `Figure::set_min_y_gutter()` (a floor unde
 common left 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.
-Changing those means committing in the submodule and moving its pin.
+
+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`. All three carry
+upstream tests — `the_atlas_is_filtered_not_point_sampled`,
+`grid_hairlines_land_on_whole_pixels` and `the_tick_at_the_origin_reads_zero`; 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 below:
+
+```sh
+cmake --build deps/plotter/build/debug
+xvfb-run -a deps/plotter/build/debug/tests/plot_tests     # expect "0 failed"
+```
 
 ## Verification
 
@@ -49,6 +68,14 @@ xvfb-run -a env UDPSCOPE_EXIT_AFTER_MS=8000 UDPSCOPE_ENABLE_ALL_MS=1000 \
   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.
 - `UDPSCOPE_PROBE_PAUSE_MS` — pause acquisition mid-run so layout numbers are
   measured on a still picture.
 - `UDPSCOPE_EXPORT_MS` (+ optional `UDPSCOPE_EXPORT_PATH`, default
@@ -111,7 +138,7 @@ Two lines of the self-check output are assertions in disguise:
   `dx_ratio` above 1 scales every index up, `a` lands past the first visible sample, and
   the samples in between sit in the buffer, readable by the crosshair, and are never
   drawn: the live view's older part goes blank while its newest part looks fine. Also
-  read `axis=` in the companion line against the `window dropdown:` line in the dump —
+  read `axis=` in the companion line against the `window control:` line in the dump —
   a live axis narrower than the requested window is the same symptom from the other
   cause (see the `clamp_to_data()` invariant below). Both need a *saturated* ring to
   show up, so run them under `--buffer-mb 1`, which wraps in a few seconds.
@@ -150,6 +177,47 @@ Two lines of the self-check output are assertions in disguise:
   `64·⌈(10+len(header)+1)/64⌉ + rows·(16 + 4·cols)`, so a size that is not that is a
   mispacked record. Read it back with `pd.DataFrame(np.load(path))` after changing
   either writer.
+- `[window-probe] <action> label=.. entry=.. unit=U window=W event_span=E cap=C decim=M
+  stored=R aa=F buffered=B` (stderr, `UDPSCOPE_PROBE_WINDOW_MS`) — **`window` must equal
+  `event_span`** on every line (the trigger's event span is the display window; a capture
+  cut to a different length than the axis frames is the "post window is empty" defect's
+  cousin) and **neither may exceed `cap`**. The `unit ms->s` line is the one that catches
+  the feedback loop: changing the unit re-interprets the typed number, so "500" in ms
+  becomes 500 **s exactly**, and a `window=499.98` there means the control re-parsed its own
+  rounded readout (`8.333 min × 60`) instead of the request — see the `window_sync_unit`
+  invariant below. `label` is a reading to three decimals in a natural unit and is
+  *expected* to be lossy (500 s reads `8.333 min`); it is the `window=` figure that has to
+  be exact.
+  For the resampling: **`buffered` must be ≥ `window`** on every line — that is what the
+  decimation is for, and a `buffered` short of the window is the old "the control is capped
+  to what the ring holds" behaviour coming back. `decim` must be a power of two,
+  `stored × decim` must equal the wire rate, and `aa` must be exactly `stored / 2`. Run it
+  under `--buffer-mb 1`, which saturates in a few seconds and makes windows past ~6 s
+  decimate; at 200 MB nothing inside `--max-window` needs to.
+- **The anti-alias check** is the same probe run against a waveform above the stored
+  Nyquist: `--buffer-mb 1 --freq 2000` with the probe ending on a 60 s window gives
+  `decim=16`, a 625 S/s stored rate and a 312.5 Hz corner, and the channel dump's
+  `ch 0 'sine' ... y=[-0.059, 0.079]` is the assertion — a boxcar of 16 at 10 kS/s passes
+  2 kHz at about 6%. **A `y=[-1, 1]` there means the filter is gone** and the 2 kHz sine has
+  aliased to a full-amplitude 125 Hz one, which looks entirely plausible on screen. This is
+  the only check that distinguishes averaging from striding.
+- `[layout-probe] <action> rows=N buttons=B rows_y=[..] close=[..] add=[..] traces=[..]`
+  (stderr, `UDPSCOPE_PROBE_LAYOUT_MS`) — **`buttons` must be `2N+1`** while the editor is
+  up (one `×` per row, one `+` per boundary) and **0 on the `editor off` line**: the
+  buttons exist only while the editor does. **`traces=` is the real assertion**: an insert
+  or a remove moves the rows' *contents* with them, so `add above 0` must read
+  `[0:-|1:sine,…]` — row 0's signals now on row 1, not renumbered onto the new empty row —
+  and `remove 0` must pull them back to `0:`. A `traces=` where the signals stayed on row 0
+  means `carry_row()` was skipped and the rows were renumbered under the user.
+  Geometrically, each `close=` must equal its row's top from `rows_y` plus the pad, and
+  `add=` must be centred on the boundaries (so strictly increasing, the first at 0 and the
+  last clamped to the area's bottom). The `rows_y` spans must tile: a gap other than
+  `kRowGap` means the figure and the overlay disagree about where a row is, which is how a
+  `×` ends up on the wrong row. Also read `x-desync 0` in the dump — every row the editor
+  adds has to join the one x link group. Run it at `--plots 8` as well: the cap and the
+  floor are the two refusals, and because the probe emits `::clicked` straight at the
+  widget it reaches the handler even when the button is insensitive, so `add above 0` there
+  must leave `rows=` and `traces=` untouched rather than growing a ninth row.
 - `badge frames: lit=L dim=D idle=I` — the activity badge's phase per frame. Over a run
   that acquired anything **both `lit` and `dim` must be non-zero**: that is what "it
   blinks" means, and a badge stuck lit is indistinguishable from a working one in a
@@ -157,6 +225,23 @@ Two lines of the self-check output are assertions in disguise:
   connected; a large `idle` is correct only when the run paused or disarmed (a
   `UDPSCOPE_PROBE_DISARM_MS` run should show hundreds). The `mode ...` lines carry the
   rest of the status line, so `rate` and `last event ... ago` are checked there.
+- `frame cost: tick A/B ms over N, draw C/D ms (max at frame F), paint E/G ms over M` and
+  `frame path: raw=R lod=L frames, segments S/T (mean/max), visible max V samples` — the
+  drawing cost, split into the frame tick, `PlotArea`'s own draw (timed from the frame
+  clock's `before-paint` to the end of the host's `render` handler) and the whole GTK
+  paint. **`segments` max must stay in the tens of thousands and `lod` must dominate `raw`
+  on any run holding a large capture**: a max in the *millions* with `lod=0` is the
+  empty-pyramid defect (see the `MinMaxPyramid` invariant below) — the renderer drawing
+  every raw sample of a held event on every frame, which measured 6,000,073 segments and
+  100–230 ms a frame at 1 MS/s. `raw` frames are expected and cheap below 64 samples per
+  pixel, which is where `level_for()`'s own gate puts the boundary. **`draw`'s max must sit
+  at a frame near 0** — that is the warm-up (glyph atlas, first vertex-buffer growth); a
+  late `F` is a frame whose own geometry was expensive and worth tracing. `tick`'s max is
+  the publish stall: `publish_event()` builds the snapshot's pyramids under `mutex()`, so a
+  latch at over 1 MS/s costs one ~40 ms tick, which must not produce `gaps`. Both these
+  lines and the disarm probe's `axis=`/`snap=` need a fast source to say anything —
+  `tools/mock_udpstreamer.py --rate 1300000 --batch 20000` — since at the default 10 kS/s a
+  whole window fits in the raw path and the publish is too short to lose a race.
 
 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.
@@ -228,7 +313,8 @@ Layers to keep straight:
   `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 4 rows, each a
+- `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
@@ -258,12 +344,69 @@ far the largest file.
   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 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.
 - **Any structural change rebuilds the buffer and drops history**: a CONFIG, an
-  enable/disable, or a calibration change. Calibration is applied at ingest, which is
-  why it re-partitions.
+  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.
+- **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 (see below).
+  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.
+- **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 `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.
@@ -277,6 +420,21 @@ far the largest file.
   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. The probe's `data=` vs `drawn=`
   is the guard.
+- **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.
+- **`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 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
@@ -324,6 +482,19 @@ far the largest file.
   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
@@ -365,6 +536,26 @@ far the largest file.
   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.
+- **`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 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.
+- **`apply_time_window()` is the only place the display window changes.** It clamps to
+  `window_limit()` and moves `RowSet::set_time_window()` and `ScopeModel::set_event_span()`
+  together, because the trigger's pre-trigger share is a share of *this* window. Paths that
+  change the span for their own reasons (Fit, an event pin) call `sync_window_display()`
+  instead, which only restates the control and never moves the plot — calling `apply_` there
+  would clamp a legitimately short capture up to the requested window.
 - **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 Arm/Disarm button in the trigger panel still has text.