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

# 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.
- **The dock's readouts and the pages' panels are one string, never two.** The dock (`src/ui_dock.cpp`)
  shows a read-only copy of the cursors table and of the measurement values, and it must not format
  anything: `update_cursors_pane()` and `update_measures()` format each value **once**, into a local, and
  hand that same variable to the page's label **and** to `dock_cursor_cell()` / `dock_measure_value()` --
  on every branch, including the `"--"` blanking one (cursors off, no sample). A second formatter in the
  dock would be two spellings of one reading that drift the first time `format_measure()` changes, and
  the dock exists so that the two can be read side by side. The `who` cell is copied from the page's label
  verbatim (markup chip and name), and the dock's lines are rebuilt from the page's whenever the page
  rebuilds (`dock_rebuild_cursors()`, `dock_rebuild_measures()`), so the line counts agree by
  construction. A cell is **ellipsized at a fixed character count** (who 5, values 9, measurement type 12) with
  the full text in its tooltip: the dock is 280 px wide and its layout must not depend on what a value
  reads, so a long value is cut and quoted whole in the tooltip rather than widening the column (the
  `who` cell was 8 characters, which made the readouts 304 px wide and pushed the sidebar past its
  pin). `[cursors-probe] ... dock cursors:` and `[measures-probe] ... dock measures:` assert it: `same_text=1`
  compares `gtk_label_get_text()` (the untruncated text) of every dock label with the page's, and
  `fits=1` that the Readouts box is no wider than the dock.
- **The readouts strip is a third reader of the same string, never a second formatter.** When the dock is
  not beside the plot (hidden, or the window collapsed so the dock is an overlay) the readouts are shown in the strip under the plot (`readouts_strip`, `src/ui_dock.cpp`): the
  cursor chips' `who` and *delta* labels and the measurement chips' value labels. They are written **in the
  same call** as the dock's -- `dock_cursor_cell()` and `dock_measure_value()` set the strip's label from the
  argument they were handed, and `dock_rebuild_cursors()` / `dock_rebuild_measures()` rebuild its chips
  beside the dock's lines -- so a value is still formatted once, into one local, and a feature that writes a
  dock cell without going through those two setters leaves the strip stale. The strip keeps the dock's
  rules: the same fixed-width ellipsized cells (who 6, type 10, value 9 characters, full text in the
  tooltip), the delta cell reads `--` on the same branches, and the cursor chips are *insensitive* with the
  cursors off -- through `dock_set_cursors_sensitive()`, which writes the dock's grid and the
  strip's chip box together; a second `gtk_widget_set_sensitive()` on either is two spellings of one state.
  The one place the strip hides what the dock only disables: with the cursors off the strip's Cursors group is
  not shown, with no measurement its Measures group is not, and with neither the strip is not (the dock keeps
  both blocks, `no measurements` included; the strip has no placeholder). That is
  `sync_readouts_strip()`, not a sensitivity.
  `[cursors-probe]` / `[measures-probe]` `strip: ... same_text=1` asserts it.
- **`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* (the page's body, and the dock's cursor grid beside it) 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.

- **The crosshair's axis badges are painted *over* the tick labels, and that costs a flush.**
  A badge is a fill in the crosshair's colour framing the value where the line meets the axis
  it names — and it sits *in the label strip*, on top of the tick label at that row. The tick
  labels are staged into `glyphs_over_`, the over-text batch the frame flushes **after every
  line batch**, so a panel fill drawn at the ordinary moment lands *under* them: the label
  prints through the badge and the backplate reads as transparent (the defect this rule was
  learned from). `draw_crosshair_axis_badges()` therefore flushes the accumulated over-text
  *first* — those labels are already placed, so it is one batch — then draws both fills, then
  stages the badge texts, which leave with the rest of the over batch over everything. An
  assertion on badge pixels inside a label's rows is the regression test: with the fill under
  the text, the label's glyph pixels are still lit inside the badge's rect.

- **The instruments have one owner: the main window's row set.** The two cursors, the gate band,
  the trigger marker and the measurement marks are *shared*, not copied per window. The main tick's
  `sync_scope_instruments()` writes the owner's state into every scope window each frame (the
  setters early-out, so a steady frame is a handful of comparisons), and a gesture inside a scope
  window is read back from **that** window's controllers first -- `sync_cursors()`/`sync_gate()`
  only adopt while their own plot holds the grab, which is exactly "the drag happened here" -- and
  adopted by the owner before anything is written out. The measurement marks travel by **signal
  name** (`RowSet::MeasureMark::signal`), so a window finds the row that plots it; a window that
  does not plot the signal draws none. The search marks are times on the window and are placed on
  every window by the same per-frame path.