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

# 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 a plot
  whose x strip draws labels** (`plot::x_strip_has_labels(x_strip_mode())`: the bottom row, and any row above it whose
  columns differ from the row below's) carries one, every other plot 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_` (it scans **every**
  row's member, in order, since a labelled strip on a row other than the first takes x gestures too), 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`.