plotter/docs/superpowers/specs/2026-09-29-plot-hardening-and-features-design.md

// SPDX-License-Identifier: MIT
// SPDX-FileCopyrightText: 2026 Martino Ferrari

# Hardening and features v0.2 — shared contracts

Design record for the bug-fix + robustness + feature wave. **This file is the
interface bible for the five parallel streams.** File ownership is exclusive:
a stream edits only the files listed under it. Everything not listed is the
integrator's.

## Bug list (B1–B7) and robustness list (R1–R9) being fixed

- **B1** f32 staging of large-magnitude x destroys geometry (epoch axes).
- **B2** tick major/minor classification ULP-fragile (`ticks.cpp:176`).
- **B3** LOD gather emits buckets straddling `[begin,end)` (`series.cpp:168`).
- **B4** `XFollow::Live` on log x holds linear span (`plot.cpp:494`, `figure.cpp`).
- **B5** zero-notch wheel disarms auto_scale; `factor==inf` unguarded
  (`controller.cpp:158`, `glfw` forwards dy=0).
- **B6** single text flush paints legend text over the crosshair readout panel.
- **B7** NaN policy incoherent (min/max drop unless seeding; sum propagates).
- **R1** `std::clamp` UB on negative viewport (`plot.cpp:886`).
- **R2** `set_x_range`/`set_y_range` store non-finite verbatim (`plot.cpp:377-384`).
- **R3** `kBucket << level` UB for level >= 58 via public `gather`.
- **R4** ring capacity rounds up but docs/reserve assume raw capacity.
- **R5** GLFW figure capture cleared by any button release.
- **R6** renderer residue: blend func, UNPACK_ALIGNMENT, no GL shutdown,
  epoch() wrap, annotation caption overflow.
- **R7** GLFW host re-lays out the figure on every event.
- **R8** measure accepts horizontal rulers, silently measures [0,0].
- **R9** minor-tick cap truncates the far end of the axis, majors included.

## Cross-cutting decisions

- **NaN policy (library-wide, documented):** a non-finite sample is *excluded*
  from every aggregate (min, max, sum, sumsq) and from cached bounds. A window
  with no finite samples aggregates to a zero-span Range / zero sums. Applies
  in `MinMaxPyramid::append`, `Series::reduce/sum/sumsq` edge folds,
  `ArraySeries::commit`, `StreamSeries::acquire` bounds. `docs/data-and-performance.md`
  gets a "Non-finite samples" paragraph.
- **Gather x contract (breaking, B1):** `Series::gather` now emits x
  **relative to `x0()`** (exactly `i*dx` for uniform series, `x_at(i)-x0()` for
  XY), never absolute x. y is unchanged. The renderer reconstructs absolute
  data x in f64 (`x0() + rel`) before transforming, so no precision is lost at
  the f32 narrowing: the staged f32 is `to_space(x_abs) - to_space(origin)`,
  which is O(visible pixels), not O(epoch).
- **Live follow on log axes (B4):** `Axis::offset` and the live-window span
  live in **axis space** (`log10` when `log`), matching how the controller's
  gestures already work (`to_space`/`from_space`). `place_live_x_window` and
  the figure link-group copies hold the log-space span constant.
- **Key-repeat policy (library-wide):** a held key repeats in every adapter
  (GLFW/Qt/GTK already do; ImGui switches to `repeat=true`).
- **Modifiers for box zoom:** Shift+Left = both axes (unchanged, default);
  Ctrl+Left = x-only; Alt+Left = y-only. Other modifier combos = both.

## Shared-header changes (made by the integrator before the fan-out)

- `include/plot/input/events.hpp`
  - `PointerEvent` gains `f64 time_s = 0.0;` (host-supplied monotonic seconds;
    powers double-click). Hosts that leave 0 simply never double-click.
  - New `GestureEvent { f32 x, y; f32 scale = 1.0f; f32 dx = 0.0f, dy = 0.0f; }`
    — pinch: zoom about (x, y) by `scale`, pan by (dx, dy). `Controller`
    gains `void on_gesture(const GestureEvent&)`.
  - New key constants: `kKeyEscape = 27`, `kKeyLeft = 256`, `kKeyRight = 257`,
    `kKeyUp = 258`, `kKeyDown = 259` (host-translated, like the ASCII ones).
- `include/plot/data/series.hpp`
  - `enum class GatherMode { Envelope, Nearest, Mean };` — downsample policy.
    `Envelope` = today's min/max pairs. `Nearest` = one raw sample per bucket
    (via `snap`), x at the sample. `Mean` = one point per bucket, y = mean
    (bucket `sum` / count), x at bucket centre.
  - `virtual void gather(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy,
    GatherMode mode = GatherMode::Envelope) const` — signature change; every
    override updates; renderer passes the mode explicitly.
  - New virtuals (uniform default, XY override):
    `virtual f64 x_at(u64 i) const` (`x0() + i*dx()`),
    `virtual bool neighbours(f64 x, u64& i0, u64& i1) const` (false when x is
    outside `[x_at(0), x_at(n-1)]`; else the bracketing indices),
    `virtual u64 snap_index(f64 x) const` (nearest index, clamped).
  - `MinMaxPyramid` gains `f64 bucket_sum(u32 l, u64 i) const` and
    `f64 bucket_sumsq(u32 l, u64 i) const` (Mean/RMS need them).
- `include/plot/plot/trace.hpp` — `Trace`/`TraceDesc` gain (trailing, defaults
  keep aggregate init source-compatible):
  `GatherMode mode = GatherMode::Envelope;`
  `f32 dash_on = 0.0f, dash_off = 0.0f;` (logical px, 0 = solid),
  `enum class Marker { None, Cross, Circle, Square }`, `Marker marker = Marker::None;`
  `f32 marker_size_px = 3.0f; u32 marker_every = 0;` (0 = auto: stride
  `ceil(samples_per_pixel)`, so markers only appear where samples are sparse).
  `width == 0` draws markers only (scatter) — documented.
- `include/plot/render/style.hpp` — gains `f32 line_aa_px = 1.0f;` (logical,
  the AA fringe half-width, clamped >= 0.25f at use). No text-colour fields:
  text colour becomes a per-call parameter (see C).
- `include/plot/plot/plot.hpp` — `set_viewport` normalises negative w/h to 0 (R1).
- ~~`include/plot/plot/crosshair.hpp` — `CrosshairRow` gains `Color color`~~
  DROPPED: `CrosshairRow` already names its trace; the renderer resolves the
  colour as `plot.trace(row.trace).color` at draw time. No field added.

## Stream A — data layer (exclusive)

Files: `include/plot/data/*`, `src/data/*`, `tests/test_series.cpp`,
`tests/test_ring_buffer.cpp`, `tests/test_minmax_pyramid.cpp`,
`tests/test_xy_series.cpp` (new), plus the `Series::gather` override
forwarders and `docs/data-and-performance.md` NaN/policy paragraphs.

1. **B3**: bucket-edge selection uses `first = max(ceil_div(origin+b, span), lbase)`,
   `last = min((origin+e)/span, lend)`; lead/trail raw spans cover the rest.
   Regression: gather at unaligned `begin`/`end` mid-window asserts no emitted
   x outside `[begin, end)` and envelope values equal exact reduce over the range.
2. **B7**: NaN policy per above; regression: NaN at first/middle/last position
   — bounds and reduce stay finite, sum skips NaN.
3. **R3**: `level_span` caps at level 57 (span 2^63); `gather(level > 57)`
   clamps; no UB/div-zero for any u32 level.
4. **R4**: docs say "at most `capacity()` rounded up to a power of two";
   `StreamSeries` reserves the *rounded* `ring_.capacity()`.
5. **GatherMode** implementation in `gather_impl` (Mean/Nearest via the new
   pyramid accessors); `XY`/`Array`/`Stream` forwarders updated; relative-x
   contract implemented everywhere (x emitted as `x_at(i) - x0()`).
6. **XY series** (full feature): `include/plot/data/xy_series.hpp`,
   `src/data/xy_series.cpp`, target `plot_core`. Sorted-ascending x
   (documented precondition, `assert` in debug); binary-search
   `neighbours`/`snap_index`; pyramid over sample index; `commit()` rebuilds.
7. **Snapshot**: `ArraySeries StreamSeries::freeze() const` — consumer-thread
   only; copies the retained window (`copy_raw`) into a fresh ArraySeries with
   this window's `x0()`/`dx()`. Freezes against the *last acquire* (documented).
8. **Incremental append**: `void ArraySeries::push(f32)` — appends, folds into
   the pyramid (`append`), extends bounds incrementally (NaN-aware), extends
   `x_bounds_`. `commit()` stays the wholesale path.
Acceptance: new tests for every item above; `plot_tests` builds and passes.

## Stream B — plot + input (exclusive)

Files: `src/plot/ticks.cpp`, `src/plot/plot.cpp`, `src/plot/figure.cpp`,
`src/input/controller.cpp`, `include/plot/input/controller.hpp`,
`include/plot/plot/axis.hpp` (offset doc), `tests/test_ticks.cpp`,
`tests/test_controller.cpp`, `tests/test_plot.cpp`, `tests/test_figure.cpp`,
`tests/test_measure.cpp`, and the plot-layer consumers of the new `Series`
virtuals (`crosshair_value`, `crosshair_span`, `covered_samples`,
`measurement` — route through `x_at`/`neighbours`/`snap_index` so an XY series
crosshairs and measures correctly).

1. **B2**: major = integer-index test (`k % ratio == 0` on the minor index,
   `k` derived from `(v - first_major)/minor_step` rounded); no float tolerance.
   Regression: epoch range 1.75e9 ± 300 s at 800 px produces labelled majors.
2. **R9**: majors are never truncated; only minors count against `kMaxTicks`.
3. **B4**: live window placement in axis space (log-aware span/offset) in
   `Plot::place_live_x_window`, `Plot::set_x_range` live branch, and the two
   figure link-group copies. Regression: streaming log axis holds visible
   decades constant across samples; scrolled-back window keeps span.
4. **B5**: `on_wheel` — `dy == 0 && dx == 0` returns; `dy == 0, dx != 0` pans x
   only (`dx` notches, 5% of the x span per notch, log-aware via `to_space`);
   zoom path rejects `factor == 1` and non-finite. Same guard in the
   middle-drag `axis_zoom`.
5. **R1**: `layout()` clamp guards `hi >= lo` before clamping (no UB even for a
   hostile viewport; `set_viewport` normalises, already done by integrator).
6. **R2**: range setters refuse non-finite endpoints (Off branch + y), keep the
   previous range and `auto_scale`.
7. **R8**: `add_measure`/`measurement` refuse horizontal-ruler (and
   vertical-ruler dead-field) cursors — `valid` stays false, `add_measure`
   returns an id that reports invalid.
8. **Interaction features**:
   - Keyboard pan: Left/Right/Up/Down pan 10% of the span per press/repeat
     (x-only for Left/Right, y-only for Up/Down; log-aware).
   - Escape (`kKeyEscape`): cancels the active drag — restores the ranges the
     axes had at `begin_drag` (captured then), drops box-zoom without applying,
     clears grab state.
   - Box-zoom masks per the modifier table above; applied per-axis at release.
   - Double-click reset: two presses of the same button within 0.35 s and 4 px
     (uses `PointerEvent::time_s`) re-fits every axis (`auto_scale = true` +
     fit). Second press does not begin a drag.
Acceptance: controller tests for each gesture incl. cancel-restore; tick
regressions; XY crosshair/measure unit tests via an `XY` fixture.

## Stream C — render (exclusive)

Files: `src/render/*`, `include/plot/render/*` (renderer/primitives/text/buffer
interfaces), `src/gl/handle.cpp`, `include/plot/gl/handle.hpp`,
`tests/test_render_smoke.cpp`, `tests/test_primitives.cpp`.

1. **B1**: implement the relative-x staging contract (see Cross-cutting):
   trace staging reconstructs `x_abs = series.x0() + rel` in f64, stages
   `f32(to_space(x_abs) - to_space(origin))`; every data-space line draw
   (grid, cursors, regions, measures, crosshair, annotations) picks a natural
   origin (its own reference data x/y) and `mapping()` folds
   `origin` into the offset uniform in f64 before the single narrowing.
   Regression: EGL smoke renders an epoch-window series and a zero-origin
   twin and asserts both rasterise to the same pixel column set (tolerance).
2. **B6**: two text batches — `text_under_` (legend names, cursor labels,
   measure labels, annotation captions) flushed *immediately before*
   `draw_crosshair_readout`; `text_over_` (readout text, tick labels, titles)
   flushed at `end_frame`. The readout panel occludes under-batch text.
   Regression: legend + overlapping readout frame — legend name pixels are not
   lit inside the readout panel rect.
3. **R6**: `begin_frame` saves `GL_BLEND_SRC/_DST` via `glGetIntegerv` and
   `end_frame` restores function + enable bit; `Texture::upload_rgba`
   saves/restores `GL_UNPACK_ALIGNMENT`; `Renderer::release_gl()` (public)
   destroys all GL handles explicitly, called first by the destructor (safe
   when the context is current) and documented for host teardown order;
   `epoch()` widened to u64 end-to-end (buffer generation + slot epoch +
   VAO cached epoch); annotation captions clamp their box inside `axes`
   (skip the caption when it cannot fit).
4. **Dash**: trace dash reaches `u_dash` per trace flush (device px, logical
   converted); legend swatch samples the dash. `dash_off == 0` = solid.
5. **Markers**: staged as line segments through the existing batch
   (Cross 2 segs, Circle 8-gon, Square 4 segs), colour = trace colour, size =
   `device(marker_size_px)`, stride `marker_every` or auto `ceil(spp)`;
   `width == 0` draws markers only. Render-smoke regression: a marker'd trace
   lights vertices a plain line does not, and a `marker_every = 3` trace
   stages 1/3 the marker count.
6. **AA knob**: `u_aa` uniform = `max(0.25, device(style.line_aa_px))`; shaders
   drop the hardcoded fringe. Default output unchanged (1.0 logical).
7. **Text colour**: per-vertex `a_colour` (vec4); `stage_text(..., Color)`;
   `flush_text` stops setting `u_color`; crosshair readout value rows draw in
   their row's trace colour (`CrosshairRow::color`), labels in `axis_text`.
   Smoke regression: a coloured readout row differs from the axis-text pass.
8. **GatherMode**: renderer passes `trace.mode` to `gather`.
Acceptance: smoke tests above; full suite green; no uniform/attribute drift
(cross-check against GLSL in the same PR).

## Stream D — adapters (exclusive)

Files: `adapters/**` only, `tests/test_glfw_host.cpp`, `tests/test_qt_pointer.cpp`,
`tests/test_gtk_input.cpp`, `tests/test_imgui_widget.cpp`,
`docs/embedding.md` (shared conventions: key repeat, touch parity, DPR note).

1. **R5**: GLFW figure capture records the button; only the owning button's
   release ends it; a second button does not steal or clear the capture
   (documented single-gesture policy). Test: press left row0, press right row1,
   release right — left drag still routes to row0.
2. **R7**: `Host` caches row rects; invalidated on resize + `set_figure`,
   refreshed once per frame; event handlers read the cache (one-frame-stale
   rows during resize — documented).
3. Key repeat: ImGui `IsKeyPressed(..., repeat=true)`; policy comment.
4. **Timestamps**: all four adapters fill `PointerEvent::time_s`
   (glfwGetTime / QEvent timestamps /1000 / gdk time /1000 / ImGui::GetTime).
5. **New keys**: GLFW maps arrows + Escape to the new constants (with
   `GLFW_KEY_LEFT` etc.); Qt maps `Key_Left...`; GTK maps `GDK_KEY_Left...`;
   ImGui `ImGuiKey_LeftArrow...`, `ImGuiKey_Escape`.
6. **Qt**: `wheelEvent` uses `pixelDelta()/40` notches when `angleDelta` is 0
   (pixelDelta path); `DevicePixelRatioChange` refreshes the controller
   viewport + scales; pinch via `grabGesture(Qt::PinchGesture)` ->
   `GestureEvent`.
7. **GTK4**: `GtkGestureZoom` attached in the plot area factory ->
   `GestureEvent` (scale + focal delta); scroll `ScrollUnit::Surface` path
   already exists — keep.
8. **GLFW**: `on_scroll` forwards unchanged (controller owns the dy=0 case).
Acceptance: adapter-gated tests updated; toolkit-free seams (qt_pointer,
gtk_input) carry the new logic so headless tests cover it.

## Stream E — build, packaging, docs, CI (exclusive)

Files: root `CMakeLists.txt`, `cmake/*`, `CMakePresets.json`,
`.github/workflows/ci.yml` (new), `plot.pc.in` (new),
`docs/building-and-testing.md`, `docs/getting-started.md`, `README.md`
(feature list + versioning), `tests/test_series.cpp` (delete the wall-clock
steady-state case only), `readme_main.cpp` (new, referenced by README).

1. `GNUInstallDirs` for every install path; `VERSION`/`SOVERSION` on
   `plot_core` when shared; `SameMinorVersion` compatibility (0.x reality);
   generated `include/plot/version.hpp` (`configure_file`, installed, added to
   the umbrella + exemption handling as needed); `plot.pc` pkg-config file;
   install `LICENSE` + `licences/OFL-1.1.txt` under
   `${CMAKE_INSTALL_DATADIR}/licenses/plot/`; `install(DIRECTORY)` gets
   `FILES_MATCHING PATTERN "*.hpp"`.
2. `PLOT_BUILD_TTF_FONT` moves to `cmake/plot_options.cmake` (docs match);
   coverage-flag detection switches to a `PLOT_COVERAGE` option check on the
   config profile, not a `CMAKE_CXX_FLAGS` string match.
3. CI: `.github/workflows/ci.yml` — ubuntu-latest, apt deps (libglfw3-dev,
   qt6-base-dev, libgtk-4-dev, libegl1, libglvnd-dev, xvfb, lcov,
   python3-fonttools), jobs: debug (configure/build/xvfb ctest), coverage
   (tools/coverage.sh, uploads the table), asan (linux-asan preset). `continue-on-error`
   on the ImGui fetch is not needed (network is available on GH runners).
4. Docs: correct the case-count math (recount from the tree at integration
   time), remove the stale hard-coded coverage figures from README and
   building-and-testing (coverage.md stays the single source, regenerated),
   document the new keys/gestures/touch parity in `interaction.md` +
   `embedding.md` (note: B/C own feature *code*; E only documents what the
   contract above specifies).
Acceptance: `cmake --install` smoke into a temp prefix finds `plot` via
`find_package` in a throwaway consumer; umbrella tests stay green; suite
counts match docs.

## Integration (integrator only)

Merge all streams; reconcile `include/plot/plot.hpp` umbrella; full
configure+build+ctest; regenerate coverage via `tools/coverage.sh`; update the
per-file coverage table and README numbers from the fresh run; run the GLFW
demo headless under Xvfb as the final smoke; update this design record's
status.

## Status: COMPLETE (2026-09-30)

All five streams landed and were integrated on `main` (uncommitted working
tree). `Controller::on_gesture` was implemented by the integrator (Stream B was
cut off before it). Incident: the root filesystem hit 100% mid-wave and
truncated `src/render/renderer.cpp` to 0 bytes; Stream C restored it from its
transcript and re-verified. Final state:

- `linux-debug` suite: **350 cases, 0 failed** (was 283); 4/4 ctest entries pass.
- Coverage: **93.9% aggregate (3730/3971) over 24 files**, every file >= 80%
  (floor 80/90) — regenerated in `docs/coverage.md` by `tools/coverage.sh`.
- Headless smoke: `plot_glfw_demo` + `plot_multiplot_demo` under `xvfb-run`,
  exit 0, screenshots contain rendered ink (65.4% / 20.0% non-background at
  1280x720); the multiplot run reports **20,901 staged GPU segments for
  ~4.5M visible samples, GL error 0** (README paragraph updated).
- Known follow-ups: real touch hardware has never exercised the Qt/GTK pinch
  paths; macOS/Windows remain untested; CI YAML is written but has run only
  locally in structure (no GitHub remote execution during this wave).