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 and never hidden -- 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.
  `[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.