feat: grade a sparse window's polyline by slope, so phosphor does not switch off on zoom

Intensity grading was gated on the column reduction, which is gated on a density whose only job is killing the moire beat. Dwell has nothing to do with that, so narrowing a window past the threshold turned the whole phosphor model off and a discontinuity went from a third of a flat top's ink to all of it in one pixel of zoom. stage_trace_slopes() grades each segment by its own slope instead, with a measure that agrees with the dense path at the boundary, and reports itself as FrameStats::slope_traces -- disjoint from column_traces, so a host asserting graded_traces == column_traces reads the same as before. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
feat(render): a reduced column can be graded by dwell, not drawn as one flat band
2026-10-08 16:56:10 +02:00 · 2026-10-06 03:02:36 +02:00 · 2026-10-06 02:00:25 +02:00
8 changed files with 1353 additions and 10 deletions
@@ -37,6 +37,21 @@ run touched a GPU, so read it as an upper bound and a record of the software pat
  window's worth, the scroll offset is bounded by `retained - span`, so a pan or a zoom-in near an
  edge cannot leave the window's own span over data the scope never had (a window *wider* than the
  data keeps the older placement -- right edge on the newest sample);
 - a trace whose gathered window is denser than the axis is reduced **onto the pixel grid** --
  one snapped vertical segment per integer column, lit from that column's own extremes --
  because an LOD envelope staged as a polyline puts three or four near-vertical hairlines per
  column at as many sub-pixel phases, and the beat between the bucket pitch and the pixel pitch
  is a crawling moiré; one segment per column leaves one phase, so there is nothing to beat
  (`FrameStats::column_traces`, and `docs/data-and-performance.md` for the four rules it keeps);
 - and such a column can be drawn **graded by dwell** instead of as one flat band
  (`Style::intensity_grading`, off by default, `FrameStats::graded_traces`): bright where the
  signal sits, faint where it only passes through, the way a digital-phosphor scope reads. It is
  what puts back the information the reduction throws away — a column's min and max are the same
  whether its samples fill the span or pile at its two ends — so the gather is asked at a level
  finer than the pixel grid and the distribution read from those sub-buckets. Below the density at
  which columns are reduced the same switch grades the **polyline** by each segment's slope
  (`FrameStats::slope_traces`), so the look does not change as a window narrows past the
  threshold;
 - sample **markers** when a window is sparse enough that its samples are the shape
  (`Style::marker_below_samples`, 50 by default, `marker_px` across, in the trace's own colour);
 - grid with independent major/minor line classes (`Style::grid_major_visible`,
@@ -172,12 +187,12 @@ documentation.
 ```sh
 cmake --preset linux-debug
 cmake --build build/debug
-ctest --test-dir build/debug --output-on-failure   # 350 cases, 0 failed
+ctest --test-dir build/debug --output-on-failure   # 377 cases, 0 failed
 tools/coverage.sh                                  # configure+build+run+capture+floor check
 ```
-The `linux-debug` suite runs **350 cases**; the `linux-coverage` preset builds **333** of
+The `linux-debug` suite runs **377 cases**; the `linux-coverage` preset builds **360** of
 them, because its adapters are off and 17 cases need an adapter target (11 in
 `test_imgui_widget.cpp`, 6 in `test_glfw_host.cpp`). Coverage is enforced by
 `tools/coverage.sh` against `tools/coverage_floor.py`: **80%** per file under `src/` and
@@ -41,11 +41,18 @@ ctest --test-dir build/debug --output-on-failure
 ctest registers four tests: `plot_tests` (the test binary), the two header/umbrella build
 checks (`plot_headers_self_contained`, `plot_umbrella_covers_public_headers`) and
-`plot_umbrella_check`. The `plot_tests` binary itself runs **350 cases** in the `linux-debug`
+`plot_umbrella_check`. The `plot_tests` binary itself runs **377 cases** in the `linux-debug`
-preset; its harness prints one line per case and a final `350 cases, 0 failed` summary line.
+preset; its harness prints one line per case and a final `377 cases, 0 failed` summary line.
 The case counts per file are the `PLOT_TEST(...)` declarations under `tests/` — recount them
 (`grep -c '^PLOT_TEST(' tests/test_*.cpp`) after adding or removing cases.
 `PLOT_TEST_FILTER=<substring>` runs only the cases whose name contains that substring, and
 is for working *on* a case rather than for checking the library: most of the render cases
 create their own EGL context and read pixels back, so the whole binary is far slower than
 the one case being edited and its one line of measured output scrolls past 376 others. The
 summary line still counts the whole suite, so a filtered run says `377 cases, 0 failed`
 having run one — it is never evidence that the suite passes. Unset, every case runs.
 ## Install layout
 `cmake --install` follows `GNUInstallDirs`, so every path honours the standard cache
@@ -119,7 +126,7 @@ per-file table and the floor verdict live in [docs/coverage.md](coverage.md), wh
 `tools/coverage.sh` rewrites from the very run that measured them. Re-run the command for the
 live numbers.
-**One thing to know about the coverage preset:** it builds **333 of the 350 cases**. The 17
+**One thing to know about the coverage preset:** it builds **360 of the 377 cases**. The 17
 that are missing are the adapter cases that need an adapter target to exist — 11 in
 `test_imgui_widget.cpp` and 6 in `test_glfw_host.cpp` — and the coverage preset turns the
 adapters off. The toolkit-free adapter seams still run there: `test_qt_pointer.cpp` (5 cases)
@@ -166,6 +166,167 @@ series therefore stages O(visible pixels) vertices, not O(samples), and `FrameSt
 which path each trace took. Below the threshold the raw samples are drawn instead; both
 sides go through the same instanced anti-aliased quad pipeline.
 ## Dense traces are reduced onto the pixel grid
 A gathered window denser than the axis is **not** staged as a polyline. For each integer
 column of `layout.axes`, `Renderer::draw_traces` emits one exactly vertical segment from the
 lowest to the highest screen y any gathered point put in that column, flushed in framebuffer
 pixels with `u_snap` on. `FrameStats::column_traces` counts the traces that took this path.
 It exists because a polyline over such a window **moirés**, and three things compound to make
 it. `MinMaxPyramid::level_for()` picks the level whose buckets hold about
 `samples_per_pixel` samples, so a bucket spans **one to two pixel columns**;
 `GatherMode::Envelope` emits two points per bucket, so each bucket contributes a near-vertical
 min→max hairline *and* a near-vertical connector to the next — about 3.6 near-vertical
 hairlines per column; and each of those lands at a **fractional** x, so with ordinary
 src-alpha compositing a column's brightness is a non-linear function of the sub-pixel phases
 overlapping it. The phase pattern repeats at the beat between the bucket pitch and the pixel
 pitch, which is a visible banding, and panning sweeps the beat so it crawls. Reducing to one
 segment per column leaves the trace **one** sub-pixel phase, so there is nothing left to beat,
 and the snap then puts that one phase on the grid.
 Four properties of the reduction are load-bearing:
 - **It is gated on the gathered *density*, not on the level.** It runs when the window is
  `GatherMode::Envelope` and carries at least two gathered points per column of the axes —
  the raw path at 1.5–64 samples per pixel has the same beat and the same cure. The density
  term is also what keeps it away from a *sparse* window, whose trace is drawn by the two
  segments that enter and leave the frame (`a_sparse_window_between_samples_still_inks_both_margins`);
  `Nearest` and `Mean` are excluded because they are one-point-per-bucket modes a band defeats.
 - **A hole stays a hole.** A column no gathered point landed in emits nothing. Bridging it
  would draw a vertical line over x the series says nothing about.
 - **Disjoint columns are joined.** Two neighbouring columns' extremes need not overlap — a
  fast edge rises through a whole column — and two disjoint vertical segments read as a broken
  trace, which is what the polyline's connector prevented. The later column is extended to
  meet the earlier one's nearest bound, so the join is made inside the column that moved.
 - **A span shorter than the stroke is drawn *as* the stroke.** The line fragment shader ramps
  on the distance to the segment's axis and does not cap its ends, so a vertical segment
  shorter than its own width rasterises a sliver of itself, and a flat trace's column, where
  the two bounds are equal, nothing at all.
 This is the **one carve-out** in `u_snap`'s rule that chrome may be snapped and data may not
 (see `LineProgram::set_snap()`): a column *is* a pixel column and its x is already a screen
 coordinate, so there is no data position to move it off, and the y bounds the segment reports
 are untouched by the snap.
 `a_dense_trace_is_drawn_as_whole_pixel_columns` is the guard, and what it measures is the
 **number of distinct coverage levels** in the ink: 4 with the reduction against 126 with the
 polyline, over one sine period across 60 000 samples. A count of *partially covered pixels* is
 **not** the reading and was tried first — a 1.5 px stroke with a 1 px anti-aliasing fringe
 always spills into its neighbour column, so the two renderings measure 577 and 652, which
 separates nothing. The frame's whole geometry collapses with it: 627 segments against 60 054.
 ## A reduced column can be graded by dwell
 `Style::intensity_grading` draws each of those columns **graded** rather than as one flat band:
 bright where the signal sits, faint where it only passes through, the way a digital-phosphor
 scope reads. It is off by default — a change of look, not a correction of one — and
 `FrameStats::graded_traces` counts the traces that took it, a subset of `column_traces`, since
 grading is a way of drawing the reduction and not a third path.
 What it puts back is the information the reduction throws away: a column's min and max are the
 **same** whether its samples fill the span evenly or pile at its two ends, so a ramp and a pulse
 are one band. The distribution cannot be recovered from the band, which is why the gather is
 asked at a level **finer than the pixel grid** (`intensity_sub_columns` sub-buckets per column)
 and the dwell read from those sub-buckets.
 Five things carry it, and each was arrived at by being wrong first:
 - **The measure is dwell per row, each segment depositing one unit spread over the rows it
  spans** (`1 / height`). Counting +1 per row instead grades a sine's fast middle as brightly as
  its rails, which is the pattern inverted — the middle is where the signal spends the *least*
  time.
 - **The accumulator is one column wide.** Gathered x is monotonic, so points arrive column by
  column: accumulate, read, clear. A full `axes.w × axes.h` density image is 33 MB at 4K; one
  column of `axes.h` floats is L1-resident. A span is written as a `+1/height` delta at its first
  row and the negation one past its last, so it costs two writes whatever its height, and the
  running sum over the column is the per-row dwell.
 - **Normalisation is per column, against the column's own peak.** A frame-wide scale needs the
  whole image to exist before anything can be drawn, *and* reads worse: a column the signal flew
  through uniformly comes out faint at every row, so the trace fades out exactly where it moves
  fastest. The cost of the local scale is one extra non-clearing walk of the accumulator to find
  the peak.
 - **Alpha is quantised into `intensity_steps` tiers, one `LineBatch` and one draw call each.**
  The line pipeline's colour is a **uniform**, not per-instance (`LineInstance` is four floats of
  geometry; only `TextInstance` carries `a_colour`), so a per-segment alpha is inexpressible and
  the tiers are what make the gradient drawable at all. `intensity_floor` keeps the faintest tier
  visible — a fast riser is one sub-bucket deep everywhere and must not be dimmed out of
  existence — and `intensity_gamma` lifts the faint end. The floor only holds if the riser's rows
  **reach** a tier: the "lit at all" cutoff that discards a column's empty rows is
  `min(0.01 × peak, 0.5 × w_min)` over the smallest deposit any of that column's own segments
  made, and not the first term alone. A column holding a flat level *and* a riser has its peak set
  by the level — one unit in one row — while the riser spreads a unit over 300, which is three
  orders of magnitude under `0.01 × peak`, so the riser was discarded before the floor could apply
  to it. Measured on a 2098-sample square wave at 105 samples a column: **2 916 of the ungraded
  path's 35 884 riser rows**, 106 of 116 riser columns gutted entirely, with a 311-row dark run in
  a 312-row axis; the ten survivors were the phase that put a riser in a column of its own, which
  is why it read as a riser *flickering* under a pan rather than as a missing edge. With the second
  term it is 35 572 rows and 115 of 116 columns, for 48 extra segments
  (`a_graded_column_keeps_a_riser_it_shares_with_a_flat_level`). A connector between two disjoint columns
  is emitted at the **faintest** tier: it is inferred geometry, not a place the signal was
  measured to dwell.
 - **Grading may not undo the reduction.** `level_for()` answers 0 — raw samples — as soon as the
  asked-for fraction of a column falls under one bucket (`kBucket` is 64), so the finer ask is
  **floored at level 1** whenever the flat path would have used the pyramid. Without the floor
  every moderately dense frame became an O(visible) gather: measured in udpscope at 1.3 MS/s over
  a 2 s window, 172 samples a pixel, the flat path sat on the pyramid and grading dropped the
  whole figure to raw (`raw=1154 lod=0` against `raw=710 lod=453`) and cost 2.3 → 6.4 ms of draw
  mean. The floor degrades the *look* instead — fewer sub-columns than asked for, down to what the
  coarsest buckets give, which at 64 samples a bucket is still two or three per column. That is
  also why raising `intensity_sub_columns` past about 8 buys nothing: the bucket size is the
  limit, not the number.
 `a_dense_trace_can_be_graded_by_dwell` is the guard, and it draws the same frame both ways. It
 profiles the mean peak coverage over the band's two outer fifths against its middle fifth: the
 flat band is flat (**191 and 191**, one ink) and the graded one is **191 against 131**, a middle
 at 0.69 of the edge. That ratio is a *tier* ratio and not the dwell ratio — the default gamma
 0.45 and floor 0.3 compress it on purpose. The geometry stays bounded by the axis and not by its
 area: **8303 segments over a 572 px axis**, 14.5 runs a column, against the flat path's 627 at
 one end and `572 × 156` rows at the other. A fourth frame over a window wide enough that the
 flat path is on the pyramid is what exercises the floor (`raw=0 lod=1 … seg=634
 visible=200001`); the test's first window sits at 105 samples a pixel, where both paths are raw
 and the floor is never reached.
 ## A sparse polyline is graded by slope
 The column reduction stops at `dense_threshold_spp` (1.5 samples a device pixel), below which the
 trace is a polyline. Grading used to stop there with it, because it was staged *inside* the
 reduction — and that coupling was a defect, not a design. The reduction's gate is a density, and
 its only purpose is removing the moiré beat between the bucket pitch and the pixel pitch. Dwell
 has nothing to do with that beat, so zooming past the threshold turned the phosphor model off in
 one step: the same square-wave edge measured **71 of 191** at 3.4 samples a pixel and **191 of
 191** at 1.0, a 2.7× jump across one pixel of zoom, which reads as a discontinuity *lighting up*
 the moment you look at it closely. The thing a reader most needs told apart from a real signal
 excursion is a transition, and it was being drawn at full ink exactly when it filled the screen.
 `Renderer::stage_trace_slopes()` grades the polyline on the same principle, differing only where
 it must:
 - **The measure is the segment's own slope**, `1 / (1 + |Δy_screen|)`, which is dwell per row for
  a single segment. The `1 +` is not a guard against a division: a flat segment — span 0, the
  commonest case in a sparse window — must be the *brightest* tier, and this makes the measure
  dimensionless and **absolute**. There is no per-column peak to normalise against down here, and
  that is an improvement: a sparse frame's tiers mean the same thing from frame to frame, so
  panning does not reshade the trace.
 - **No gather mode is excluded.** The reduction is `Envelope`-only, because turning a bucket's
  min/max into a band answers a different question from the one a `Nearest` or `Mean` host asked.
  A segment's slope is a property of the polyline itself, so `grade` is not reused as the gate —
  only `intensity_grading` and `intensity_steps > 1` are.
 - **The geometry is bit-for-bit the ungraded polyline's**, staged exactly as `stage_xy()` stages
  it, with the same `snap = false`; only the batch a segment lands in differs. A segment with one
  non-finite end is dropped rather than clamped, which is the conclusion `add_polyline_xy()`
  reaches too.
 - **`FrameStats::slope_traces` counts it, and it is disjoint from `column_traces`.** A window is
  either dense enough to reduce onto the pixel grid or it is drawn as a polyline, never both — so
  a host asserting `graded_traces == column_traces` keeps that reading unchanged.
 `a_sparse_trace_is_graded_by_slope_like_a_dense_one` is the guard: one window either side of the
 threshold over the same transition at the same place. The level reads **191 either way** (a flat
 segment dwells in its row, so it is the top tier and full ink) and the riser reads **71 either
 way**, against the 191 the sparse frame gave before. Across the whole sweep from 101 down to 0.1
 samples a pixel the riser holds 71 and the level holds 191, so there is no step at the threshold
 left to see.
 ## One sample or a statistic of many
 Every number the library reports is one the samples actually hold. What differs between
@@ -29,6 +29,21 @@ namespace plot {
 struct FrameStats {
  u32 raw_traces = 0;        ///< traces drawn from raw samples (level 0)
  u32 lod_traces = 0;        ///< traces drawn from a min/max pyramid level
  /// Traces whose geometry was reduced onto the pixel grid: one vertical segment
  /// per column, lit from that column's own extremes. Counts a trace from either
  /// path above -- the reduction is about the *density* of the gathered points,
  /// not about which level produced them.
  u32 column_traces = 0;
  /// Traces whose columns were graded by dwell rather than drawn as one flat band
  /// (`Style::intensity_grading`). A subset of `column_traces`: grading is a way of
  /// drawing the reduction, not a third path.
  u32 graded_traces = 0;
  /// Traces drawn as a polyline whose *segments* were graded by slope -- the sparse
  /// half of the same phosphor model (`Renderer::stage_trace_slopes`). **Disjoint from
  /// `column_traces`**, and therefore from `graded_traces`: a window is either dense
  /// enough to reduce onto the pixel grid or it is drawn as a polyline, never both. A
  /// host asserting `graded_traces == column_traces` keeps that reading unchanged.
  u32 slope_traces = 0;
  u64 visible_samples = 0;   ///< samples the gathered windows covered, summed
  u32 staged_segments = 0;   ///< line segments staged, all colour groups
  u32 staged_markers = 0;    ///< marker shapes staged over the traces
@@ -404,6 +419,13 @@ class Renderer {
  /// axis-aligned line by up to half a pixel. Set on every flush, like `dash`.
  void flush_lines(const Mapping& map, Color color, f32 width, Vec2 dash = Vec2{},
                   bool snap = false) noexcept;
  /// The same, for a batch other than the renderer's own `lines_`. The graded trace
  /// pass stages one batch per alpha step, and a step has to be a draw call of its
  /// own because the line pipeline takes its colour from a uniform -- so it needs to
  /// flush a batch it chose rather than the member one. Every other caller flushes
  /// `lines_` and uses the overload above.
  void flush_lines(render::LineBatch& batch, const Mapping& map, Color color, f32 width,
                   Vec2 dash = Vec2{}, bool snap = false) noexcept;
  /// Draws every staged glyph in `batch` -- each instance carries its own tint
  /// (`a_colour`) -- and empties the batch. Text is texture-bound, so this runs
  /// once per text batch, after the line geometry it belongs over.
@@ -500,6 +522,53 @@ class Renderer {
  /// The data helpers take it too; they read the axes rect and the transforms it
  /// pins.
  void draw_traces(const Plot& plot, const PlotLayout& layout);
  /// One gathered window reduced onto the pixel grid and staged in framebuffer
  /// pixels: for each integer column of `layout.axes`, one exactly vertical
  /// segment from the lowest to the highest screen y any gathered point put in
  /// it. Returns how many columns were staged (0 stages nothing); the caller
  /// flushes with `pixel_mapping()` and `snap = true`.
  ///
  /// `gather_` is the input, read with the same origin `draw_traces` asked the
  /// series for. See `draw_traces` for when this path is taken and why.
  u32 stage_trace_columns(const Plot& plot, const PlotLayout& layout, const Trace& trace,
                          f64 x_origin, u32 points);
  /// The same reduction, graded by **dwell**: a column is drawn as a stack of runs,
  /// each at the alpha step its own share of the column's samples earns, so a flat
  /// top is bright and the edge leading to it is faint (`Style::intensity_grading`).
  ///
  /// Stages into `steps_`, one `LineBatch` per alpha step, which the caller flushes
  /// in turn -- the line pipeline's colour is a uniform, so a step is a draw call.
  /// Returns the segments staged across all steps (0 stages nothing).
  ///
  /// `gather_` is the input and must have been asked for at the *finer* level
  /// `Style::intensity_sub_columns` implies; a column's dwell is not recoverable
  /// from its own min and max (see `Style::intensity_grading`).
  u32 stage_trace_density(const Plot& plot, const PlotLayout& layout, const Trace& trace,
                          f64 x_origin, u32 points);
  /// The **sparse** window's polyline, graded by the same measure: each segment is
  /// staged into the step its own *slope* earns, so a near-vertical segment between two
  /// adjacent samples -- a discontinuity, which the signal crossed without dwelling
  /// anywhere in it -- is faint and a near-flat one is bright.
  ///
  /// It exists because grading used to be gated on the column reduction, and that
  /// reduction is gated on a *density* (two gathered points per pixel column) whose only
  /// purpose is removing the moire beat. Dwell has nothing to do with that density, so
  /// zooming in past it switched the whole phosphor model off and drew an edge as
  /// brightly as a flat top -- the edge got brighter the further in you zoomed.
  ///
  /// The measure agrees with `stage_trace_density()`'s at the boundary but is **absolute
  /// rather than per column**: below two points a column there is no column peak to
  /// normalise against, so a segment's dwell is `1 / (1 + rows it spans)` outright. A
  /// flat segment earns the top step and one crossing the whole axis earns
  /// `Style::intensity_floor`, which is what a riser's column already gets on the dense
  /// side.
  ///
  /// Geometry is staged exactly as `stage_xy()` stages it -- in the pre-affine space,
  /// relative to `x_origin` -- so only *which batch* a segment lands in differs from the
  /// ungraded polyline, and the caller flushes with the trace's own `Mapping` and
  /// `snap = false`. Returns the segments staged across all steps (0 stages nothing).
  u32 stage_trace_slopes(const Plot& plot, const Trace& trace, const f32* xy, u32 points,
                         f64 x_origin, bool log_x, bool log_y);
  /// The cursors, both orientations: one stroke per cursor, placed at the coordinate its own
  /// orientation owns (`Plot::cursor_screen_coordinate()`) and spanning the other axis' whole
  /// range, in its own colour -- or in the accent at handle width while it is hovered or
@@ -611,7 +680,25 @@ class Renderer {
  render::TextBatch glyphs_under_;
  render::TextBatch glyphs_over_;
  std::vector<f32> gather_;   ///< scratch for one gathered window, re-used
-  std::vector<f32> staged_;   ///< scratch for one staged window, re-used
+  /// One (lowest y, highest y) pair per pixel column of the axes, re-used:
  /// `stage_trace_columns()`'s working set. Two floats per column, so an 8K-wide
  /// axis is 64 kB -- bounded by the *screen*, where `gather_` is bounded by the
  /// window.
  std::vector<f32> columns_;
  /// `stage_trace_density()`'s working set, and deliberately **one column wide**: the
  /// gathered points arrive in x order, so a column can be accumulated, read and
  /// cleared before the next one starts. A full-axes density image would be
  /// `axes.w * axes.h` (33 MB at 4K); this is `axes.h` (a few kB) and stays in L1.
  ///
  /// Each sub-bucket's span is written as a +1 at its first row and a -1 one past
  /// its last, so accumulating a span costs two writes whatever its height; the
  /// running sum over the column is then how many sub-buckets cover each row, which
  /// is the dwell.
  std::vector<f32> column_rows_;
  /// One batch per alpha step of the grading (`Style::intensity_steps`), re-used
  /// across frames: the line pipeline takes its colour from a uniform, so segments
  /// at different alphas cannot share a draw call and must be staged apart.
  std::vector<render::LineBatch> steps_;
  mutable std::vector<u8> readback_;  ///< dump_frame_ppm's row buffer
  /// The host's `GL_COLOR_CLEAR_VALUE`, queried on the first `begin_frame()` (GL
@@ -177,6 +177,90 @@ struct Style {
                                   ///< sides draw through the one instanced
                                   ///< anti-aliased quad path.
  // --- intensity grading: counts and ratios, never sizes -------------------
  /// Draw a dense trace's pixel columns **graded by how long the signal dwells at
  /// each height**, the way a digital-phosphor scope does, instead of as one flat
  /// band per column: bright where samples pile up (a flat top, a peak), faint
  /// where they only pass through (an edge, a noise excursion).
  ///
  /// Off by default, because it is a change of *look* and not a correction: the
  /// flat band is the honest answer to "what did this column reach", and a host
  /// that wants that -- or that draws few enough samples never to take the column
  /// path at all -- should not have its traces restyled by an upgrade. A scope-like
  /// host turns it on.
  ///
  /// It is not derivable from the flat band. A column's min and max are the same
  /// whether its samples fill the span or sit piled at its two ends, which is
  /// exactly the difference between a ramp and a pulse -- so grading needs the
  /// gather asked at a *finer* level than the pixel grid (`intensity_sub_columns`)
  /// and reads the distribution from those sub-buckets.
  ///
  /// The measure is *dwell per row*, and the weighting is the whole of it: each
  /// sub-column segment deposits **one unit spread over the rows it spans**, so a
  /// tall crossing leaves a thin smear and a short one at a turning point leaves a
  /// bright mark. Counting a row at +1 per segment that touches it instead -- the
  /// obvious thing -- grades a sine's fast middle as brightly as its rails, which
  /// is the pattern inverted.
  ///
  /// Below `dense_threshold_spp`, where there are no columns to reduce, this grades
  /// the **polyline** by each segment's own slope instead (`FrameStats::slope_traces`
  /// against `graded_traces`) -- the same measure for a sparse window, where a
  /// segment *is* the sub-column. One switch covers both because the alternative was
  /// a defect: gated on the reduction, the model switched off as a window narrowed
  /// past the threshold, and an edge drawn at a third of a flat top's ink jumped to
  /// all of it in one pixel of zoom.
  bool intensity_grading = false;
  /// Sub-buckets per pixel column the gather is asked for when grading: the level
  /// is chosen for `samples_per_pixel / intensity_sub_columns`, so a column's
  /// density is read from this many envelopes instead of from one.
  ///
  /// It buys resolution in *dwell*, linearly, for the same factor in gathered
  /// points -- and the points stay bounded by the screen, which is the property
  /// that matters (8 of them over a 1000 px axis is 16 000 points whatever the
  /// window holds). Below about 4 a pulse's flat levels and its edge are too few
  /// samples apart to separate.
  ///
  /// It is a *want*, not a promise: the renderer floors the level it asks for at the
  /// pyramid's coarsest bucket level, so a window too sparse to hold this many buckets
  /// a column is graded from however many it does hold. Without that floor `level_for`
  /// answers 0 -- raw samples -- the moment a sub-column falls under one bucket, which
  /// turns a frame the flat path draws off the pyramid into an O(visible) gather. So
  /// raising this past about 8 costs resolution nothing and buys it nothing either: the
  /// bucket size is the limit, not this number.
  u32 intensity_sub_columns = 8;
  /// Quantisation of the grading, in alpha steps. Each step is one draw call (the
  /// line pipeline's colour is a uniform, so a per-segment alpha would mean a
  /// per-instance one), and the segments are bounded by the columns, so the cost
  /// of a step is a draw call over a few hundred instances.
  ///
  /// Four is enough to read a waveform's structure and few enough that a step is a
  /// visible tier rather than a gradient -- the point is to separate "dwelt here"
  /// from "passed through", not to measure.
  u32 intensity_steps = 4;
  /// Alpha the faintest graded step is drawn at, as a fraction of the trace's own.
  ///
  /// Not 0: a column the signal merely passed through is still a column the signal
  /// *reached*, and a riser dimmed out of existence is a square wave drawn as two
  /// disconnected lines. This is the floor that keeps the trace continuous.
  f32 intensity_floor = 0.3f;
  /// Exponent the normalised dwell is raised to before it is quantised. Below 1 it
  /// lifts the faint end, which is what makes a fast edge visible beside a flat top
  /// whose dwell is three orders of magnitude greater.
  ///
  /// The dwell is normalised **against the column's own peak**, not against a scale
  /// for the whole frame, so the steps spend their range on the structure *inside*
  /// each column. One scale for the frame needs the whole `w * h` density image
  /// (33 MB at 4K, which is why the accumulator is one column wide) and reads
  /// worse: a column the signal flew straight through holds little dwell at any
  /// height, so it would grade uniformly faint -- a trace that fades out exactly
  /// where it moves fastest.
  f32 intensity_gamma = 0.45f;
  /// `logical` in device pixels: the single conversion point for every logical
  /// metric above, so the arithmetic appears once per consumer instead of a `*
  /// ui_scale` scattered over the renderer and the layout.
@@ -616,9 +616,14 @@ void Renderer::upload_text_vertices(std::span<const f32> interleaved) noexcept {
 void Renderer::flush_lines(const Mapping& map, Color color, f32 width, Vec2 dash,
                           bool snap) noexcept {
-  const u32 segments = lines_.segment_count();
+  flush_lines(lines_, map, color, width, dash, snap);
 }
 void Renderer::flush_lines(render::LineBatch& batch, const Mapping& map, Color color, f32 width,
                           Vec2 dash, bool snap) noexcept {
  const u32 segments = batch.segment_count();
  if (segments != 0 && ready_) {
-    upload_vertices(lines_.data());
+    upload_vertices(batch.data());
    line_program_.bind();
    line_program_.set_scale(map.scale);
    line_program_.set_offset(map.offset);
@@ -643,7 +648,7 @@ void Renderer::flush_lines(const Mapping& map, Color color, f32 width, Vec2 dash
    stats_.staged_segments += segments;
    ++stats_.draw_calls;
  }
-  lines_.clear();  // keeps the capacity, so the next group re-uses the store
+  batch.clear();  // keeps the capacity, so the next group re-uses the store
 }
 void Renderer::flush_text(render::TextBatch& batch) noexcept {
@@ -972,6 +977,379 @@ void Renderer::draw_titles(const Plot& plot, const PlotLayout& layout) {
 // ------------------------------------------------------------------- data
 u32 Renderer::stage_trace_columns(const Plot& plot, const PlotLayout& layout, const Trace& trace,
                                  f64 x_origin, u32 points) {
  const Transform xt = plot.x_transform(trace.axis_x);
  const Transform yt = plot.y_transform(trace.axis_y);
  const f32 left = layout.axes.x;
  // One column per whole pixel of the axes, plus the partial one at the right-hand
  // edge: `axes.w` is fractional, and the samples that land in that last fraction
  // are inside the frame.
  const u32 count = static_cast<u32>(layout.axes.w) + 1u;
  constexpr f32 kInf = std::numeric_limits<f32>::infinity();
  columns_.resize(2u * static_cast<usize>(count));
  for (u32 c = 0; c < count; ++c) {
    columns_[2u * c] = kInf;         // the lowest screen y seen in this column
    columns_[2u * c + 1u] = -kInf;   // and the highest; `lo <= hi` is "present"
  }
  for (u32 k = 0; k < points; ++k) {
    const f64 x_abs = x_origin + static_cast<f64>(gather_[2u * k]);
    const f64 sx = xt.to_screen_x(x_abs);
    const f64 sy = yt.to_screen_y(static_cast<f64>(gather_[2u * k + 1u]));
    // A NaN sample, and a non-positive one on a log axis, have no position: both
    // arrive here as a non-finite screen coordinate.
    if (!std::isfinite(sx) || !std::isfinite(sy)) continue;
    const f64 column = std::floor(sx - static_cast<f64>(left));
    // Clamped, not dropped. The gathered window carries one sample of slack on each
    // side, and that sample's ink belongs to the edge column -- it is what the
    // polyline drew there, under the same clip. Nothing further out can arrive: the
    // window is the visible range's.
    const u32 c = !(column > 0.0)                           ? 0u
                  : column >= static_cast<f64>(count - 1u)   ? count - 1u
                                                            : static_cast<u32>(column);
    const f32 y = static_cast<f32>(sy);
    if (y < columns_[2u * c]) columns_[2u * c] = y;
    if (y > columns_[2u * c + 1u]) columns_[2u * c + 1u] = y;
  }
  const f32 width = style_.device(trace.width);
  u32 staged = 0;
  f32 prev_lo = 0.0f;
  f32 prev_hi = 0.0f;
  bool joined = false;   // the column before this one is present, so there is a join to make
  for (u32 c = 0; c < count; ++c) {
    f32 lo = columns_[2u * c];
    f32 hi = columns_[2u * c + 1u];
    if (!(lo <= hi)) {
      // No sample landed here. A hole in the data stays a hole: bridging it would
      // draw a vertical line over x the series says nothing about, where the
      // polyline drew a diagonal across the gap at most one pixel wide.
      joined = false;
      continue;
    }
    // Connectivity. Two columns' extremes need not overlap -- a fast edge rises
    // through a whole column -- and two disjoint vertical segments read as a broken
    // trace, which is exactly what the polyline's connecting segment prevented. The
    // later column is extended to meet the earlier one's nearest bound, so the join
    // is made inside the column that moved and no ink appears left of it.
    if (joined) {
      if (hi < prev_lo) {
        hi = prev_lo;
      } else if (lo > prev_hi) {
        lo = prev_hi;
      }
    }
    prev_lo = lo;
    prev_hi = hi;
    joined = true;
    // A span shorter than the stroke is drawn *as* the stroke: the fragment shader
    // ramps on the distance to the segment's axis and does not cap its ends, so a
    // vertical segment shorter than its own width rasterises a sliver of itself --
    // and a column of a flat trace, where `lo == hi`, nothing at all.
    if (hi - lo < width) {
      const f32 mid = 0.5f * (lo + hi);
      lo = mid - 0.5f * width;
      hi = mid + 0.5f * width;
    }
    // The column's centre, in framebuffer pixels. Every segment therefore shares one
    // sub-pixel phase, which is the whole point (see `draw_traces`), and the flush's
    // snap puts that one phase on the grid.
    const f32 x = left + static_cast<f32>(c) + 0.5f;
    lines_.add_segment({x, lo}, {x, hi});
    ++staged;
  }
  return staged;
 }
 u32 Renderer::stage_trace_density(const Plot& plot, const PlotLayout& layout, const Trace& trace,
                                  f64 x_origin, u32 points) {
  if (points < 2u) return 0u;
  // At least two steps, or there is nothing to grade and the faintest step is also
  // the brightest -- a one-step grading is the flat band drawn dimmer, which is not
  // what any host asking for this wants.
  const u32 steps = std::max(2u, style_.intensity_steps);
  // Exactly `steps`, never merely at least: the flush loop reads `steps_.size()` as the
  // step count and divides by it, so a batch left over from a larger setting would be
  // flushed at the wrong alpha -- or, being uncleared, at all.
  steps_.resize(steps);
  for (u32 t = 0; t < steps; ++t) steps_[t].clear();
  const Transform xt = plot.x_transform(trace.axis_x);
  const Transform yt = plot.y_transform(trace.axis_y);
  const f32 left = layout.axes.x;
  const f32 top = layout.axes.y;
  const u32 columns = static_cast<u32>(layout.axes.w) + 1u;
  // One accumulator row per whole pixel of the axes, plus the partial one at the
  // bottom edge, plus one past the end for a span's closing delta.
  const u32 rows = static_cast<u32>(layout.axes.h) + 1u;
  column_rows_.assign(static_cast<usize>(rows) + 1u, 0.0f);
  const f32 width = style_.device(trace.width);
  const f32 gamma = style_.intensity_gamma > 0.0f ? style_.intensity_gamma : 1.0f;
  const f32 bottom = top + layout.axes.h;
  u32 staged = 0;
  u32 column = 0;        // the column being accumulated
  bool open = false;     // it has at least one segment
  u32 prev_column = 0;   // the last column that emitted anything, for the join below
  f32 prev_lo = 0.0f;
  f32 prev_hi = 0.0f;
  bool joined = false;
  // The smallest deposit any segment made into the column being accumulated, which is
  // what bounds the "lit at all" test below. Reset per column by `emit_column()`.
  f32 w_min = std::numeric_limits<f32>::infinity();
  // Reads one column's accumulator out as graded runs and clears it, so the next column
  // starts empty. Two walks of it, which is nothing -- it is one column wide and in L1 --
  // and the first is what makes the second's grading *relative to this column*:
  //
  // the brightest row of a column is always the top tier. That is deliberate and it is
  // the difference between grading and dimming. The alternative, one scale for the whole
  // frame, needs a pass over every column before any of them can be drawn (an
  // `axes.w * axes.h` image, 33 MB at 4K) and makes a column the signal flew through
  // *uniformly* faint -- a trace that fades out where it moves fastest, which is where a
  // reader is most often looking. Per column, the dwell structure *inside* each one is
  // what the tiers spend their range on: the rails of a sine are bright and its fast
  // middle is faint, in every column.
  //
  // The runs are maximal stretches of equal tier, so this is O(rows) segments per column
  // at worst and a handful in practice: a column of a clean waveform is a bright ridge
  // and a faint tail.
  const auto emit_column = [&]() {
    const f32 x = left + static_cast<f32>(column) + 0.5f;
    f32 peak = 0.0f;
    {
      f32 cover = 0.0f;
      for (u32 r = 0; r < rows; ++r) {
        cover += column_rows_[r];
        if (cover > peak) peak = cover;
      }
    }
    const f32 inv = peak > 0.0f ? 1.0f / peak : 0.0f;
    // What counts as covered at all: **a row one segment covered is lit**. The deposits
    // are fractions, so this cannot be an integer test, and it cannot be a share of the
    // column's peak alone either -- that was this function's one real defect. A square
    // wave's riser is a single segment spread over the whole axis, so it deposits
    // `1/rows` per row, while a flat level in the same column is one deposit of 1.0 per
    // sub-bucket piled on one row: at 105 samples a column the peak is ~50 and the share
    // floor is ~0.5, eighty times the riser's own 0.006. Every row of the edge was
    // unlit, and the connector could not bridge it either -- the two levels are both lit,
    // so the column's band already spans the gap and neither gap test fires. Measured on
    // a true square at 104.8 spp over a 312-row axis: 106 of 116 riser columns drawn as
    // two disconnected marks with up to 311 dark rows between them, the other 10 kept by
    // the phase that put the riser in a column of its own -- which is why it read as an
    // edge *flickering* rather than as one missing. `intensity_floor` guards a lit row's
    // alpha and was documented as preventing exactly this; it never got the chance.
    //
    // So the share term is kept only for what it is good for -- suppressing residue from
    // the running-sum reconstruction -- and is capped by half the smallest deposit the
    // column actually received, which no real segment's contribution can fall under.
    const f32 lit_floor = std::min(0.01f * peak, 0.5f * w_min);
    f32 cover = 0.0f;
    bool in_run = false;
    u32 run_tier = 0;
    u32 run_start = 0;
    f32 band_lo = 0.0f;
    f32 band_hi = 0.0f;
    bool any = false;
    // One past the last row too: it closes a run that reaches the bottom edge.
    for (u32 r = 0; r <= rows; ++r) {
      cover += column_rows_[r];
      column_rows_[r] = 0.0f;
      const bool lit = r < rows && cover > lit_floor;
      u32 tier = 0;
      if (lit) {
        const f32 share = std::min(1.0f, cover * inv);
        const u32 t = static_cast<u32>(std::pow(share, gamma) * static_cast<f32>(steps));
        tier = std::min(steps - 1u, t);
      }
      if (in_run && (!lit || tier != run_tier)) {
        f32 lo = top + static_cast<f32>(run_start);
        f32 hi = top + static_cast<f32>(r);
        // A run shorter than the stroke is drawn *as* the stroke, for the reason
        // `stage_trace_columns()` gives: the fragment shader ramps on the distance to
        // the segment's axis and does not cap its ends.
        if (hi - lo < width) {
          const f32 mid = 0.5f * (lo + hi);
          lo = mid - 0.5f * width;
          hi = mid + 0.5f * width;
        }
        steps_[run_tier].add_segment({x, lo}, {x, hi});
        ++staged;
        in_run = false;
      }
      if (lit && !in_run) {
        run_start = r;
        run_tier = tier;
        in_run = true;
      }
      if (lit) {
        if (!any) {
          band_lo = top + static_cast<f32>(r);
          any = true;
        }
        band_hi = top + static_cast<f32>(r) + 1.0f;
      }
    }
    open = false;
    w_min = std::numeric_limits<f32>::infinity();
    if (!any) {
      joined = false;   // nothing visible here: a hole, like an uncovered column
      return;
    }
    // Connectivity, the same rule as the flat path: two columns' bands need not
    // overlap -- a fast edge rises through a whole column -- and two disjoint
    // verticals read as a broken trace. The gap is bridged by a segment of its own at
    // the **faintest** tier rather than by extending a run, because a connector is
    // inferred geometry and not a place the signal was measured to dwell: grading it
    // bright would claim the opposite of what it is.
    if (joined && column == prev_column + 1u) {
      if (band_hi < prev_lo) {
        steps_[0].add_segment({x, band_hi}, {x, prev_lo});
        ++staged;
      } else if (band_lo > prev_hi) {
        steps_[0].add_segment({x, prev_hi}, {x, band_lo});
        ++staged;
      }
    }
    prev_lo = band_lo;
    prev_hi = band_hi;
    prev_column = column;
    joined = true;
  };
  f64 px = 0.0;
  f64 py = 0.0;
  bool have_prev = false;
  for (u32 k = 0; k < points; ++k) {
    const f64 x_abs = x_origin + static_cast<f64>(gather_[2u * k]);
    const f64 sx = xt.to_screen_x(x_abs);
    const f64 sy = yt.to_screen_y(static_cast<f64>(gather_[2u * k + 1u]));
    // A NaN sample, and a non-positive one on a log axis, have no position -- and it
    // breaks the chain as well as skipping the point: a segment from the sample
    // before it to the one after would cross x the series says nothing about.
    if (!std::isfinite(sx) || !std::isfinite(sy)) {
      have_prev = false;
      continue;
    }
    if (have_prev) {
      // The *segment*, not the point, is what carries dwell: it is a stretch of the
      // waveform, and where it went slowly it covers few rows and where it went fast it
      // covers many. This is where a height-based heuristic cannot reach -- a column's
      // min and max cannot tell a ramp from a pulse, and a column's segments can (see
      // `Style::intensity_grading`).
      //
      // It is charged to the column its earlier end falls in. The gather is asked at
      // `intensity_sub_columns` buckets per column, so a segment is a fraction of a
      // column wide and splitting one across a boundary would buy a fraction of one
      // sub-bucket's dwell.
      const f64 c = std::floor(px - static_cast<f64>(left));
      // Clamped, not dropped, for the reason `stage_trace_columns()` gives: the
      // gathered window carries one sample of slack on each side and that sample's
      // ink belongs to the edge column.
      const u32 ci = !(c > 0.0)                                 ? 0u
                     : c >= static_cast<f64>(columns - 1u)      ? columns - 1u
                                                               : static_cast<u32>(c);
      if (open && ci != column) emit_column();   // x is increasing, so ci > column
      if (!open) {
        column = ci;
        open = true;
      }
      const f64 lo = std::min(py, sy);
      const f64 hi = std::max(py, sy);
      // Wholly outside the axes is wholly clipped, and a clamp would move its ink to
      // the edge and invent a ridge there. A segment that *crosses* the edge is
      // clamped instead, which is the coverage the clip leaves -- so a column's shares
      // are shares of what is visible in it, which is what is being graded.
      if (hi >= static_cast<f64>(top) && lo <= static_cast<f64>(bottom)) {
        const f64 ra = std::floor(lo - static_cast<f64>(top));
        const f64 rb = std::floor(hi - static_cast<f64>(top));
        const u32 r0 = !(ra > 0.0) ? 0u
                       : ra >= static_cast<f64>(rows - 1u) ? rows - 1u
                                                          : static_cast<u32>(ra);
        const u32 r1 = !(rb > 0.0) ? 0u
                       : rb >= static_cast<f64>(rows - 1u) ? rows - 1u
                                                          : static_cast<u32>(rb);
        // A segment deposits one unit of dwell, **spread over the rows it covers** --
        // which is the whole measurement, and counting the rows instead was wrong in a
        // way worth recording: a sub-bucket holds about as many samples as any other, so
        // a segment crossing a hundred rows is those samples *passing through* each of
        // them, while one covering two rows is the same samples *sitting* in them. Giving
        // each crossed row a full unit makes a sine's fast middle as bright as its rails,
        // which is the pattern grading exists to show.
        //
        // Two writes whatever the height: the running sum over the column is then the
        // dwell at each row.
        const f32 w = 1.0f / static_cast<f32>(r1 - r0 + 1u);
        if (w < w_min) w_min = w;
        column_rows_[r0] += w;
        column_rows_[r1 + 1u] -= w;
      }
    }
    px = sx;
    py = sy;
    have_prev = true;
  }
  if (open) emit_column();
  return staged;
 }
 u32 Renderer::stage_trace_slopes(const Plot& plot, const Trace& trace, const f32* xy, u32 points,
                                 f64 x_origin, bool log_x, bool log_y) {
  if (points < 2u) return 0u;
  // At least two, for the reason `stage_trace_density()` gives: a one-step grading is
  // the whole trace drawn dimmer, which is not what a host asking for this wants.
  const u32 steps = std::max(2u, style_.intensity_steps);
  steps_.resize(steps);
  for (u32 t = 0; t < steps; ++t) steps_[t].clear();
  const Transform yt = plot.y_transform(trace.axis_y);
  const f32 gamma = style_.intensity_gamma > 0.0f ? style_.intensity_gamma : 1.0f;
  const f32 fsteps = static_cast<f32>(steps);
  u32 staged = 0;
  for (u32 i = 0; i + 1u < points; ++i) {
    const f64 y0 = static_cast<f64>(xy[2u * i + 1u]);
    const f64 y1 = static_cast<f64>(xy[2u * i + 3u]);
    const f64 s0 = yt.to_screen_y(y0);
    const f64 s1 = yt.to_screen_y(y1);
    // A NaN sample, and a non-positive one on a log axis, have no position, and the
    // *segment* is what is being staged -- so one unplaceable end drops it entirely
    // rather than being clamped to somewhere the series says nothing about. The
    // ungraded polyline reaches the same conclusion through `add_polyline_xy()`, which
    // a non-finite vertex excludes from both of its segments.
    if (!std::isfinite(s0) || !std::isfinite(s1)) continue;
    // Dwell, the same quantity `stage_trace_density()` deposits and for the same
    // reason: a segment is a stretch of the waveform, and the rows it spans are the
    // rows the signal crossed *on its way* rather than sat in. `1 + span` so a flat
    // segment -- span 0, the commonest case in a sparse window -- is 1 and not a
    // division by zero, which also makes the measure dimensionless and absolute: no
    // per-column peak exists to normalise against down here.
    const f32 span = static_cast<f32>(std::fabs(s1 - s0));
    const f32 dwell = 1.0f / (1.0f + span);
    const u32 t = std::min(steps - 1u, static_cast<u32>(std::pow(dwell, gamma) * fsteps));
    // Staged exactly as `stage_xy()` does, so the geometry is bit-for-bit the ungraded
    // polyline's and only the batch differs. The linear case needs no mapping at all --
    // the gather already emitted x relative to this origin.
    if (!log_x && !log_y) {
      steps_[t].add_segment(Vec2{xy[2u * i], xy[2u * i + 1u]},
                            Vec2{xy[2u * i + 2u], xy[2u * i + 3u]});
    } else {
      const f64 ox = space(x_origin, log_x);
      steps_[t].add_segment(
          Vec2{static_cast<f32>(space(static_cast<f64>(xy[2u * i]) + x_origin, log_x) - ox),
               static_cast<f32>(space(y0, log_y))},
          Vec2{static_cast<f32>(space(static_cast<f64>(xy[2u * i + 2u]) + x_origin, log_x) - ox),
               static_cast<f32>(space(y1, log_y))});
    }
    ++staged;
  }
  return staged;
 }
 void Renderer::draw_traces(const Plot& plot, const PlotLayout& layout) {
  // Both dimensions: a zero-width rect selects no level, and a zero-height one
  // would flatten every trace onto a single row -- a frame that looks like a
@@ -1013,9 +1391,30 @@ void Renderer::draw_traces(const Plot& plot, const PlotLayout& layout) {
    // This is the whole performance contract: the window, never the series.
    const u64 visible = last - first;
    const f64 samples_per_pixel = static_cast<f64>(visible) / static_cast<f64>(layout.axes.w);
-    const u32 level = samples_per_pixel >= static_cast<f64>(style_.dense_threshold_spp)
+    // Grading reads a column's *distribution*, which one envelope per column cannot
    // carry (`Style::intensity_grading`), so the gather is asked for the level a
    // fraction of a column implies. The *gate* is still the pixel grid's density: a
    // window sparse enough to be drawn as a polyline is drawn as one, graded or not.
    const bool grade = style_.intensity_grading && trace.mode == data::GatherMode::Envelope &&
                       style_.intensity_sub_columns > 1u && style_.intensity_steps > 1u;
    const u32 flat_level = samples_per_pixel >= static_cast<f64>(style_.dense_threshold_spp)
                               ? series.pyramid().level_for(n, samples_per_pixel)
                               : 0u;
    // The finer level, floored at the pyramid's coarsest bucket level. Grading asks for a
    // fraction of a column and `level_for` answers 0 -- raw samples -- as soon as that
    // fraction falls under one bucket, so an unfloored ask turns every moderately dense
    // frame into an O(visible) gather: measured at 1.3 MS/s over a 2 s window, 172 samples
    // a pixel, where the flat path sits on the pyramid and grading dropped the whole figure
    // to raw (`raw=1154 lod=0` against `raw=710 lod=453`) and cost 2.3 -> 6.4 ms a frame.
    // The floor degrades the *look* instead: fewer sub-columns than asked for, down to
    // whatever the coarsest buckets give, which at 64 samples a bucket is still two or three
    // per column. Grading is a way of drawing a reduction and may not undo it.
    const u32 level =
        grade && flat_level > 0u
            ? std::max(1u, series.pyramid().level_for(
                               n, samples_per_pixel /
                                      static_cast<f64>(style_.intensity_sub_columns)))
            : flat_level;
    gather_.clear();
    // The visible range's minimum is the gather origin: the emitted f32 is then O(the span on
@@ -1111,9 +1510,98 @@ void Renderer::draw_traces(const Plot& plot, const PlotLayout& layout) {
    // trace/axis hierarchy on a high-DPI panel. `width == 0` is scatter: the
    // markers below are the whole trace.
    if (trace.width > 0.0f) {
      // A window denser than two gathered points per pixel column is drawn as *columns*
      // rather than as a polyline: one exactly vertical, pixel-snapped segment per column,
      // spanning what that column's own points reach.
      //
      // The polyline's geometry at this density is a stack of near-vertical hairlines at
      // *fractional* x -- an envelope bucket spans (spp/2, spp] samples, so there are one to
      // two buckets per column, each emitting its own min->max hairline plus a connector to
      // the next, about three and a half per column. Each is composited with its own
      // sub-pixel coverage, so a column's brightness is a non-linear function of those
      // phases; the phases repeat at the beat between the bucket pitch and the pixel pitch,
      // which is a **moire** across the trace, and panning sweeps the beat so the pattern
      // crawls. It is strongest exactly where a scope is used hardest: a high sample rate, a
      // high signal frequency, or a noisy signal, all of which make the ribbon thin enough
      // for its per-column coverage to be visible as texture.
      //
      // Reducing to one segment per column removes the cause rather than the symptom: there
      // is one phase on the whole trace (and the snap puts it on the grid), so there is
      // nothing left to beat. It is also O(axes.w) geometry instead of O(buckets), and it
      // loses nothing a reader could have seen -- a column cannot show more than the extremes
      // of what it covers, which is what the band is.
      //
      // Two conditions, and each refuses a case this would damage.
      // - `Envelope` only. `Nearest` and `Mean` are one-point-per-bucket modes chosen so the
      //   trace reads as *samples* or as a smoothed line; a min/max band would answer a
      //   different question from the one the host asked.
      // - Two points per column. Below that the gather is sparser than the grid, and the
      //   polyline's segments are the shape: `Series::gather()` also falls back to raw samples
      //   when no complete bucket fits the range, and that window's trace is drawn by the two
      //   segments that enter and leave the frame (see
      //   `a_sparse_window_between_samples_still_inks_both_margins`). The real envelope path
      //   emits two to four points per column by construction, so the test holds exactly when
      //   it ran.
      const bool columns = trace.mode == data::GatherMode::Envelope &&
                           static_cast<f64>(points) >= 2.0 * static_cast<f64>(layout.axes.w);
      // `snap = true` on geometry that is not chrome, which is the one carve-out in that
      // uniform's rule ("a line that reports a data position may not be moved off it"): a
      // column *is* a pixel column, and its x is already a screen coordinate derived from
      // one -- there is no data position to move it off. The y bounds, which are what the
      // segment reports, are untouched by the snap. It holds for both staging paths.
      const u32 staged =
          !columns ? 0u
          : grade  ? stage_trace_density(plot, layout, trace, x_range.min, points)
                   : stage_trace_columns(plot, layout, trace, x_range.min, points);
      if (staged != 0u && grade) {
        // One draw call per alpha step, faintest first: the line pipeline's colour is a
        // uniform, so a per-segment alpha is not expressible and a step is a batch. They
        // are flushed in order so the bright ridge composites over the faint tail rather
        // than under it -- the runs within a column do not overlap, but their AA fringes
        // do, and that is the order a phosphor display puts them in.
        for (u32 t = 0; t < steps_.size(); ++t) {
          if (steps_[t].segment_count() == 0u) continue;
          Color color = trace.color;
          color.a *= style_.intensity_floor +
                     (1.0f - style_.intensity_floor) * static_cast<f32>(t) /
                         static_cast<f32>(steps_.size() - 1u);
          flush_lines(steps_[t], pixel_mapping(), color, style_.device(trace.width), dash, true);
        }
        ++stats_.column_traces;
        ++stats_.graded_traces;
      } else if (staged != 0u) {
        flush_lines(pixel_mapping(), trace.color, style_.device(trace.width), dash, true);
        ++stats_.column_traces;
      } else {
        // The sparse half of the phosphor model. `grade` is not reused as the gate: it
        // requires `Envelope`, because the *column reduction* turns a bucket's min/max
        // into a band and that answers a different question from the one a `Nearest` or
        // `Mean` host asked. A segment's slope is a property of the polyline itself, so
        // no gather mode is excluded here.
        const u32 sparse =
            style_.intensity_grading && style_.intensity_steps > 1u
                ? stage_trace_slopes(plot, trace, gather_.data(), points, x_range.min, log_x,
                                     log_y)
                : 0u;
        if (sparse != 0u) {
          // Faintest first, and `snap = false` -- the same order as the graded columns
          // for the same compositing reason, but these segments sit at *data* positions
          // and the snap uniform's rule applies to them in full.
          for (u32 t = 0; t < steps_.size(); ++t) {
            if (steps_[t].segment_count() == 0u) continue;
            Color color = trace.color;
            color.a *= style_.intensity_floor +
                       (1.0f - style_.intensity_floor) * static_cast<f32>(t) /
                           static_cast<f32>(steps_.size() - 1u);
            flush_lines(steps_[t], map, color, style_.device(trace.width), dash, false);
          }
          ++stats_.slope_traces;
        } else {
          stage_xy(gather_.data(), points, x_range.min, log_x, log_y);
          flush_lines(map, trace.color, style_.device(trace.width), dash);
        }
      }
    }
    // Markers, staged as line segments through this same batch in *pixel* space
    // (so their size is device pixels whatever the data scale is). The stride is
@@ -3,6 +3,7 @@
 #pragma once
 #include <cstdio>
 #include <cstdlib>
 #include <cmath>
 #include <chrono>
 #include <algorithm>
@@ -57,7 +58,9 @@ inline void check_near(double a, double b, const char* file, int line, const cha
 inline int run_all() {
  int failed = 0;
  const char* only = std::getenv("PLOT_TEST_FILTER");
  for (auto& c : cases()) {
    if (only != nullptr && std::string(c.name).find(only) == std::string::npos) continue;
    try {
      c.fn();
      std::printf("[ ok ] %s\n", c.name);
@@ -38,6 +38,23 @@ constexpr plot::u32 kH = 360;
 /// 1M-wide window holds ~16 of them (the dense envelope spans the full height in
 /// every column) while a 640-wide one is a nearly flat line (the sparse path's
 /// polyline crosses every column exactly once).
 /// A sine of **one period per pixel column** for the window
 /// `a_dense_trace_can_be_graded_by_dwell` draws (60 000 x-units over a 572 px axis, so
 /// 104.9 samples a column). That is the one density at which a column *has* a dwell
 /// structure to grade: its envelope spans the full amplitude, so the band is tall, and
 /// the sub-buckets inside it are a fraction of a period each, so the ones at the sine's
 /// turning points are short and the ones crossing its middle are long. A period of many
 /// columns leaves every band a thin ribbon with nothing to distinguish, and a period of a
 /// fraction of a column fills every sub-bucket to the full amplitude -- also nothing.
 std::vector<plot::f32> fast_sine_samples() {
  std::vector<plot::f32> y(1'000'000);
  const double w = 2.0 * 3.14159265358979323846 / 104.9;
  for (plot::u64 i = 0; i < y.size(); ++i) {
    y[i] = static_cast<plot::f32>(std::sin(static_cast<double>(i) * w));
  }
  return y;
 }
 std::vector<plot::f32> sine_samples() {
  std::vector<plot::f32> y(1'000'000);
  for (plot::u64 i = 0; i < y.size(); ++i) {
@@ -868,6 +885,260 @@ PLOT_TEST(dense_and_sparse_paths_agree_on_extent) {
  ctx.destroy();
 }
 /// A window denser than the pixel grid inks **whole columns**, which is what kills the moire.
 ///
 /// Reported as "strong moire patterns due to a large number of vertical lines" on a high rate,
 /// a high frequency or a noisy signal. The polyline at this density is a stack of near-vertical
 /// hairlines at *fractional* x -- one to two envelope buckets per column, each a min->max
 /// hairline plus a connector -- so a column's brightness is a non-linear function of those
 /// sub-pixel phases, and the phases repeat at the beat between the bucket pitch and the pixel
 /// pitch. That beat is the pattern, and panning sweeps it, so it crawls.
 ///
 /// The observable is the beat's own cause, measured: how many **distinct coverage levels** the
 /// trace's ink takes. One segment per column puts every column's ink at one sub-pixel phase, so
 /// the AA ramp is evaluated at the same few distances everywhere and the ink lands on **4**
 /// levels; the polyline's hairlines sit at arbitrary phases and its ink spreads over **126** of
 /// them. That spread *is* the texture, and it is what beats against the pixel pitch.
 ///
 /// A count of partially covered pixels is *not* the reading, which is worth knowing before
 /// adding one: both renderings put about the same amount of ink in the fringe (577 against 652
 /// here, of 1400-odd inked pixels), because a 1.5 px stroke with a 1 px fringe always spills
 /// into its neighbour. The fix is not that the fringe is gone, it is that it is the *same*
 /// fringe in every column.
 ///
 /// The window is one period of the sine over 107 samples per pixel: dense enough for the
 /// reduction and slow enough that the band is a *thin ribbon*, which is where the beat shows.
 /// A window whose buckets each span several periods paints a solid block and hides it.
 PLOT_TEST(a_dense_trace_is_drawn_as_whole_pixel_columns) {
  plottest::HeadlessContext ctx(kW, kH);
  plot::Status st;
  PLOT_CHECK(ctx.create(&st));
  PLOT_CHECK(plot::gl::load(nullptr));
  plot::Renderer r;
  PLOT_CHECK(r.init(&st));
  plot::data::ArraySeries s(sine_samples(), 0.0, 1.0);
  plot::Plot p;
  p.set_viewport({0, 0, static_cast<plot::f32>(kW), static_cast<plot::f32>(kH)});
  const plot::u32 ax = p.add_x_axis({"t", {0.0, 60'000.0}, false, plot::AxisPlace::Bottom, false});
  const plot::u32 ay = p.add_y_axis({"v", {-1.0, 1.0}, false, plot::AxisPlace::Left, false});
  p.add_trace({&s, plot::Color::hex(0x40C0FF), 1.5f, ax, ay});
  r.begin_frame(kW, kH, {0, 0, static_cast<plot::f32>(kW), static_cast<plot::f32>(kH)});
  r.draw(p);
  r.end_frame();
  dump_if_requested(r, "columns.ppm");
  const plot::Rect a = p.layout().axes;
  // Blue over the background minus red is the trace's coverage, linearly: 8 at no coverage
  // and 199 at full (0x40C0FF over 0x101418). Nothing else in this frame is blue-dominant --
  // the grid and the axis line are grey -- so the two bands below are the trace's own ink,
  // split at three quarters covered.
  plot::u32 inked = 0;
  plot::u32 histogram[256] = {};
  for (plot::u32 row = 0; row < static_cast<plot::u32>(a.h); ++row) {
    for (plot::u32 col = 0; col < static_cast<plot::u32>(a.w); ++col) {
      plot::u8 px[4] = {};
      const plot::u32 x = static_cast<plot::u32>(a.x) + col;
      PLOT_CHECK(ctx.read_pixel(x, ctx.height - 1u - (static_cast<plot::u32>(a.y) + row), px));
      const int cover = static_cast<int>(px[2]) - static_cast<int>(px[0]);
      if (cover > 40) {   // the trace's ink, at a quarter covered or better
        ++inked;
        ++histogram[cover];
      }
    }
  }
  // How many *distinct* coverages the ink takes is the beat, measured. A column's ink is
  // placed at one sub-pixel phase, so the AA ramp is evaluated at the same few distances in
  // every column and the ink lands on a handful of levels; a polyline's hairlines sit at
  // arbitrary phases, so its ink spreads over the whole range of them. The floor of 4 pixels
  // per level ignores the stragglers at the ribbon's turning points.
  plot::u32 levels = 0;
  for (plot::u32 c = 0; c < 256u; ++c) {
    if (histogram[c] >= 4u) ++levels;
  }
  std::printf("[columns] axes=[%.1f %.1f %.1f %.1f] raw=%u lod=%u columns=%u segments=%u "
              "visible=%llu inked=%u levels=%u\n",
              a.x, a.y, a.w, a.h, r.stats().raw_traces, r.stats().lod_traces,
              r.stats().column_traces, r.stats().staged_segments,
              static_cast<unsigned long long>(r.stats().visible_samples), inked, levels);
  // The reduction ran, and on the *raw* path: the gate is the gathered density, not the level.
  PLOT_CHECK(r.stats().column_traces == 1);
  PLOT_CHECK(r.stats().visible_samples > 50'000u);
  // One segment per column, so the frame's whole geometry -- grid and axis lines included --
  // is bounded by the axis' width: 627 against the polyline's 60 054.
  PLOT_CHECK(r.stats().staged_segments < static_cast<plot::u32>(a.w) + 64u);
  // The ribbon is there, and its ink sits on a handful of coverage levels (4) rather than on a
  // continuum of them (126).
  PLOT_CHECK(inked > static_cast<plot::u32>(a.w));
  PLOT_CHECK(levels <= 8u);
  PLOT_CHECK(!r.last_frame_had_gl_error());
  ctx.destroy();
 }
 /// `Style::intensity_grading`: a reduced column is drawn **graded by dwell** -- bright
 /// where the signal sits, faint where it only passes through -- which is the second half
 /// of the moire answer. The columns alone removed the beat; this is what puts back the
 /// information a flat band throws away, the way a phosphor display does.
 ///
 /// The observable is the thing the feature claims and nothing weaker: within one column,
 /// the rows at the **edges** of the band are brighter than the rows in its **middle**.
 /// For a sine of one period per column that is exactly right -- it dwells at its turning
 /// points and crosses its middle at full speed -- and it is a property of the *rendering*
 /// rather than of the waveform, because the same frame drawn ungraded puts the band's
 /// edge and its middle at the same coverage. Both frames are measured here, so what is
 /// asserted is the difference between them.
 ///
 /// It also pins what grading may *not* cost. The reduction still runs (`column_traces`),
 /// so the beat is still gone; the geometry is still bounded by the axis' width times a
 /// small factor, because a run is a stretch of equal tier and not a row; and the draw
 /// calls are bounded by the steps, since the line pipeline's colour is a uniform.
 PLOT_TEST(a_dense_trace_can_be_graded_by_dwell) {
  plottest::HeadlessContext ctx(kW, kH);
  plot::Status st;
  PLOT_CHECK(ctx.create(&st));
  PLOT_CHECK(plot::gl::load(nullptr));
  plot::Renderer r;
  PLOT_CHECK(r.init(&st));
  plot::data::ArraySeries s(fast_sine_samples(), 0.0, 1.0);
  plot::Plot p;
  p.set_viewport({0, 0, static_cast<plot::f32>(kW), static_cast<plot::f32>(kH)});
  const plot::u32 ax = p.add_x_axis({"t", {0.0, 60'000.0}, false, plot::AxisPlace::Bottom, false});
  const plot::u32 ay = p.add_y_axis({"v", {-1.0, 1.0}, false, plot::AxisPlace::Left, false});
  p.add_trace({&s, plot::Color::hex(0x40C0FF), 1.5f, ax, ay});
  // The band's edges against its middle, averaged over columns across the axis. The
  // shares are of the band's own height, so the reading does not depend on where the
  // band happens to sit or on how tall it is: the outer fifth at each end against the
  // middle fifth.
  struct Profile {
    plot::u32 edge = 0;     ///< mean peak coverage over the band's two outer fifths
    plot::u32 middle = 0;   ///< mean peak coverage over its middle fifth
    plot::u32 columns = 0;  ///< columns that held a band at all
  };
  auto profile = [&](const plot::Rect& a) -> Profile {
    const plot::u32 rows = static_cast<plot::u32>(a.h);
    std::vector<int> cover(rows, 0);
    plot::u64 edge_sum = 0;
    plot::u64 middle_sum = 0;
    Profile out;
    for (plot::u32 col = 8; col + 8 < static_cast<plot::u32>(a.w); col += 16) {
      plot::u32 lo = rows;
      plot::u32 hi = 0;
      for (plot::u32 row = 0; row < rows; ++row) {
        plot::u8 px[4] = {};
        const plot::u32 x = static_cast<plot::u32>(a.x) + col;
        PLOT_CHECK(ctx.read_pixel(x, ctx.height - 1u - (static_cast<plot::u32>(a.y) + row), px));
        cover[row] = static_cast<int>(px[2]) - static_cast<int>(px[0]);
        if (cover[row] > 20) {   // the faintest step is 0.3 of 191, so this is under it
          if (row < lo) lo = row;
          hi = row;
        }
      }
      // A band of fewer than 15 rows has no middle fifth to speak of; at this density
      // there is none, but the reading would be meaningless if there were.
      if (lo >= hi || hi - lo < 15u) continue;
      const plot::u32 h = hi - lo + 1u;
      const plot::u32 fifth = h / 5u;
      int edge = 0;
      int middle = 0;
      for (plot::u32 row = lo; row <= hi; ++row) {
        const plot::u32 d = row - lo;
        if (d < fifth || d >= h - fifth) {
          if (cover[row] > edge) edge = cover[row];
        } else if (d >= 2u * fifth && d < 3u * fifth) {
          if (cover[row] > middle) middle = cover[row];
        }
      }
      edge_sum += static_cast<plot::u64>(edge);
      middle_sum += static_cast<plot::u64>(middle);
      ++out.columns;
    }
    if (out.columns != 0) {
      out.edge = static_cast<plot::u32>(edge_sum / out.columns);
      out.middle = static_cast<plot::u32>(middle_sum / out.columns);
    }
    return out;
  };
  // Ungraded first: the reference the grading is read against.
  r.begin_frame(kW, kH, {0, 0, static_cast<plot::f32>(kW), static_cast<plot::f32>(kH)});
  r.draw(p);
  r.end_frame();
  dump_if_requested(r, "ungraded.ppm");
  const plot::Rect a = p.layout().axes;
  const Profile flat = profile(a);
  const plot::u32 flat_segments = r.stats().staged_segments;
  const plot::u32 flat_draws = r.stats().draw_calls;
  PLOT_CHECK(r.stats().column_traces == 1 && r.stats().graded_traces == 0);
  PLOT_CHECK(!r.last_frame_had_gl_error());
  r.style().intensity_grading = true;
  r.begin_frame(kW, kH, {0, 0, static_cast<plot::f32>(kW), static_cast<plot::f32>(kH)});
  r.draw(p);
  r.end_frame();
  dump_if_requested(r, "graded.ppm");
  const Profile lit = profile(a);
  std::printf("[graded] axes=[%.1f %.1f %.1f %.1f] flat edge=%u middle=%u cols=%u seg=%u "
              "draws=%u | graded edge=%u middle=%u cols=%u seg=%u draws=%u columns=%u "
              "graded_traces=%u\n",
              a.x, a.y, a.w, a.h, flat.edge, flat.middle, flat.columns, flat_segments,
              flat_draws, lit.edge, lit.middle, lit.columns, r.stats().staged_segments,
              r.stats().draw_calls, r.stats().column_traces, r.stats().graded_traces);
  // Both frames measured a band in most of the columns they sampled, or the two
  // profiles are not comparable and everything below is vacuous.
  PLOT_CHECK(flat.columns > 20u && lit.columns == flat.columns);
  // The flat band is flat: its edge and its middle are one ink (191 and 191).
  PLOT_CHECK(flat.middle > 0u && flat.edge * 100u < flat.middle * 115u);
  // The graded one is not, and in the direction a sine dwells in: 191 against 131, a
  // middle at 0.69 of the edge. The figure is a *tier* ratio and not the dwell ratio --
  // the per-row dwell at the rails is several times the crossing's, and
  // `intensity_gamma` (0.45) and `intensity_floor` (0.3) are there to compress exactly
  // that into a range an eye reads as shading rather than as a gap. So the threshold is
  // what the quantised ink does, with room for a step either way.
  PLOT_CHECK(lit.middle > 0u && lit.middle * 100u < lit.edge * 80u);
  // The reduction still ran, so the beat the columns removed is still gone.
  PLOT_CHECK(r.stats().column_traces == 1 && r.stats().graded_traces == 1);
  // A run is a stretch of equal tier, not a row: the geometry stays bounded by the
  // axis' width times a small factor, nothing like `w * h`. Measured 8303 over a 572 px
  // axis, 14.5 runs a column -- the dwell profile's own structure (four tiers from the
  // dim middle out to each rail) plus the quantiser's dither at each boundary. The flat
  // path's 627 is the other end of the scale, and 572 * 156 rows is what this is not.
  PLOT_CHECK(r.stats().staged_segments < 24u * static_cast<plot::u32>(a.w));
  // And the draw calls by the steps: one per tier that staged anything, over the flat
  // frame's single trace draw.
  PLOT_CHECK(r.stats().draw_calls <= flat_draws + r.style().intensity_steps);
  // And the level floor, which the window above cannot see: at 105 samples a pixel the
  // flat path is already on raw samples, so grading asks for nothing finer. A wider
  // window puts the flat path on the pyramid, and there a sub-column is `spp / 8` -- which
  // falls under one bucket long before the column does, so an unfloored ask answers level
  // 0 and gathers the whole visible window. That is a real cost and it was measured: at
  // 1.3 MS/s over a 2 s window udpscope's own frame report went from `raw=710 lod=453` to
  // `raw=1154 lod=0` and 2.3 -> 6.4 ms a frame. The floor is one bucket level, so the
  // reading is simply that a graded frame stays on the pyramid.
  p.set_x_range(ax, {0.0, 200'000.0});
  r.begin_frame(kW, kH, {0, 0, static_cast<plot::f32>(kW), static_cast<plot::f32>(kH)});
  r.draw(p);
  r.end_frame();
  std::printf("[graded] wide: raw=%u lod=%u columns=%u graded=%u seg=%u visible=%llu\n",
              r.stats().raw_traces, r.stats().lod_traces, r.stats().column_traces,
              r.stats().graded_traces, r.stats().staged_segments,
              static_cast<unsigned long long>(r.stats().visible_samples));
  PLOT_CHECK(r.stats().visible_samples > 100'000u);
  PLOT_CHECK(r.stats().lod_traces == 1 && r.stats().raw_traces == 0);
  PLOT_CHECK(r.stats().column_traces == 1 && r.stats().graded_traces == 1);
  PLOT_CHECK(r.stats().staged_segments < 24u * static_cast<plot::u32>(a.w));
  PLOT_CHECK(!r.last_frame_had_gl_error());
  ctx.destroy();
 }
 // Resolution #1 of the brief: the renderer draws into whatever framebuffer is
 // bound and clears only its viewport, so a host that embeds the plot in a
 // sub-rect (Qt/GTK/ImGui) keeps the rest of its surface. Coordinates are given
@@ -6714,3 +6985,230 @@ PLOT_TEST(figure_rows_draw_their_own_horizontal_rulers) {
  }
  (void)layout;
 }
 namespace {
 /// A true square wave: `period` samples a cycle, half at +1 and half at -1, so every
 /// transition is a single-sample discontinuity. That is the waveform the phosphor model
 /// is hardest on -- a riser has no intermediate samples to deposit ink in, so whatever
 /// the grading does to it is the whole of what a reader sees.
 std::vector<plot::f32> square_samples(plot::u64 period) {
  std::vector<plot::f32> y(1'000'000);
  for (plot::u64 i = 0; i < y.size(); ++i) {
    y[i] = (i % period) < period / 2u ? 1.0f : -1.0f;
  }
  return y;
 }
 }  // namespace
 /// A column the signal only *passed* through must still be a column it reached:
 /// `intensity_floor` exists so that "a riser dimmed out of existence is a square wave
 /// drawn as two disconnected lines", and the per-column grading used to break that
 /// promise on exactly the waveform it names.
 ///
 /// The cause was the "lit at all" cutoff inside the column reduction. Grading normalises
 /// a column against its own peak and then discards sub-buckets under `0.01 * peak`. A
 /// column holding both a flat level and a riser has a peak set by the level -- the level
 /// deposits its whole unit into one row -- while the riser spreads a unit over 300 rows,
 /// so every riser row lands three orders of magnitude under the cutoff and is dropped
 /// before the floor can be applied to it. The floor never sees the riser; there is no
 /// tier 0 to fall back to.
 ///
 /// Measured over this frame's 116 riser columns: the graded path inked 2 916 of the
 /// ungraded path's 35 884 rows (8%), gutting 106 of the 116 and leaving a 311-row dark
 /// run in a 312-row axis. The ten survivors are the phase that puts a riser in a column
 /// of its own, which is what made the defect read as a *flicker* under panning rather
 /// than as a missing edge. The cutoff is now `min(0.01 * peak, 0.5 * w_min)`, so it can
 /// never exclude a deposit some segment actually made, and the reading is 35 572 rows
 /// (99.1%) with 115 of 116 columns intact.
 PLOT_TEST(a_graded_column_keeps_a_riser_it_shares_with_a_flat_level) {
  plottest::HeadlessContext ctx(kW, kH);
  plot::Status st;
  PLOT_CHECK(ctx.create(&st));
  PLOT_CHECK(plot::gl::load(nullptr));
  plot::Renderer r;
  PLOT_CHECK(r.init(&st));
  // 2098 samples a cycle over 104.8 samples a column is about 20 columns a cycle, so a
  // riser's column also holds a long stretch of the level it leaves -- the sharing this
  // test is about -- rather than being a column of pure transition.
  plot::data::ArraySeries s(square_samples(2098), 0.0, 1.0);
  plot::Plot p;
  p.set_viewport({0, 0, static_cast<plot::f32>(kW), static_cast<plot::f32>(kH)});
  const plot::u32 ax = p.add_x_axis({"t", {0.0, 60'000.0}, false, plot::AxisPlace::Bottom, false});
  const plot::u32 ay = p.add_y_axis({"v", {-1.0, 1.0}, false, plot::AxisPlace::Left, false});
  p.add_trace({&s, plot::Color::hex(0x40C0FF), 1.5f, ax, ay});
  // Columns whose band spans more than half the axis: on a square wave those are the
  // transitions and nothing else, since a level's own band is a ribbon a few rows deep.
  // "Tall" is the property at stake -- a riser drawn as a stub is as wrong as one not
  // drawn at all -- so it is both how the columns are chosen and what is asserted of
  // them, read from the ungraded frame and then re-read from the graded one.
  const auto tall_columns = [&](const plot::Rect& a) {
    const plot::u32 rows = static_cast<plot::u32>(a.h);
    std::vector<plot::u32> out;
    for (plot::u32 col = 0; col < static_cast<plot::u32>(a.w); ++col) {
      plot::u32 lo = rows;
      plot::u32 hi = 0;
      for (plot::u32 row = 0; row < rows; ++row) {
        plot::u8 px[4] = {};
        PLOT_CHECK(ctx.read_pixel(static_cast<plot::u32>(a.x) + col,
                                  ctx.height - 1u - (static_cast<plot::u32>(a.y) + row), px));
        // 20 of the 191 a full stroke inks, which is under the faintest tier
        // (`intensity_floor` 0.3) -- so a row this rejects is a row no tier drew.
        if (static_cast<int>(px[2]) - static_cast<int>(px[0]) > 20) {
          if (row < lo) lo = row;
          hi = row;
        }
      }
      if (lo < hi && hi - lo > rows / 2u) out.push_back(col);
    }
    return out;
  };
  // The axes rect is read *after* a draw: `Plot::layout()` sizes its label strips from
  // the tick text at the style's font, so before the first frame it answers with the
  // unmeasured estimate and the window would be off by 11 columns in x.
  r.begin_frame(kW, kH, {0, 0, static_cast<plot::f32>(kW), static_cast<plot::f32>(kH)});
  r.draw(p);
  r.end_frame();
  dump_if_requested(r, "riser-ungraded.ppm");
  const plot::Rect a = p.layout().axes;
  const std::vector<plot::u32> flat = tall_columns(a);
  PLOT_CHECK(r.stats().column_traces == 1 && r.stats().graded_traces == 0);
  r.style().intensity_grading = true;
  r.begin_frame(kW, kH, {0, 0, static_cast<plot::f32>(kW), static_cast<plot::f32>(kH)});
  r.draw(p);
  r.end_frame();
  dump_if_requested(r, "riser-graded.ppm");
  const std::vector<plot::u32> lit = tall_columns(a);
  PLOT_CHECK(r.stats().column_traces == 1 && r.stats().graded_traces == 1);
  PLOT_CHECK(!r.last_frame_had_gl_error());
  // How many of the ungraded frame's own riser columns survived the grading, which is
  // the reading the ratio below is taken from. Both lists are ascending, so this is one
  // pass.
  plot::u32 kept = 0;
  for (plot::usize i = 0, j = 0; i < flat.size() && j < lit.size();) {
    if (flat[i] == lit[j]) {
      ++kept;
      ++i;
      ++j;
    } else if (flat[i] < lit[j]) {
      ++i;
    } else {
      ++j;
    }
  }
  std::printf("[riser] axes=[%.1f %.1f %.1f %.1f] flat=%zu graded=%zu kept=%u\n", a.x, a.y, a.w,
              a.h, flat.size(), lit.size(), kept);
  // Enough columns to make the ratio mean something; 116 were measured.
  PLOT_CHECK(flat.size() > 50u);
  // And the grading kept all but one of them. The one is real and is not the defect: the
  // ungraded path inks *two* full-height columns per transition -- a column's own min/max,
  // the connectivity extension to its neighbour, and the gathered window's slack sample
  // all land in x -- where the reduction inks one, which is also why 116 columns appear
  // for 58 transitions. Before the fix this read 10 of 116.
  PLOT_CHECK(kept * 100u >= static_cast<plot::u32>(flat.size()) * 95u);
 }
 /// Dwell dimming must not switch off when the window gets narrow. It used to, because
 /// the grading was gated on the *column reduction*, and that reduction is gated on two
 /// gathered points per pixel column -- a density whose only purpose is removing the
 /// moire beat. Zooming past `dense_threshold_spp` therefore turned the whole phosphor
 /// model off in one step, and a discontinuity that had been drawn at a third of the
 /// level's ink was suddenly drawn at all of it: measured 71 of 191 at 3.4 samples a
 /// pixel and 191 of 191 at 1.0, which is what a user reported as an edge that "lights
 /// up" on zoom.
 ///
 /// `Renderer::stage_trace_slopes()` grades the polyline by each segment's own slope, so
 /// the model now spans both rasterisation paths. The riser reads 71 either side of the
 /// threshold, and this test is that pair of readings.
 PLOT_TEST(a_sparse_trace_is_graded_by_slope_like_a_dense_one) {
  plottest::HeadlessContext ctx(kW, kH);
  plot::Status st;
  PLOT_CHECK(ctx.create(&st));
  PLOT_CHECK(plot::gl::load(nullptr));
  plot::Renderer r;
  PLOT_CHECK(r.init(&st));
  plot::data::ArraySeries s(square_samples(2098), 0.0, 1.0);
  plot::Plot p;
  p.set_viewport({0, 0, static_cast<plot::f32>(kW), static_cast<plot::f32>(kH)});
  const plot::u32 ax = p.add_x_axis({"t", {0.0, 60'000.0}, false, plot::AxisPlace::Bottom, false});
  // -2..2 so the two levels sit a quarter in from each edge rather than on it: a level
  // on the boundary row is half clipped away, and its ink would then read low for a
  // reason that has nothing to do with grading.
  const plot::u32 ay = p.add_y_axis({"v", {-2.0, 2.0}, false, plot::AxisPlace::Left, false});
  p.add_trace({&s, plot::Color::hex(0x40C0FF), 1.5f, ax, ay});
  r.style().intensity_grading = true;
  struct Reading {
    int riser = 0;  ///< peak ink in the riser's own columns, at mid height
    int flat = 0;   ///< peak ink in a level's columns, well clear of the riser
  };
  // Both windows are centred on the transition at sample 1049, so the riser's column is
  // known by construction rather than searched for -- a search would have to decide what
  // a riser looks like, which is the very thing in question.
  const auto measure = [&](double window) {
    p.set_x_range(ax, {1049.0 - window / 2.0, 1049.0 + window / 2.0});
    r.begin_frame(kW, kH, {0, 0, static_cast<plot::f32>(kW), static_cast<plot::f32>(kH)});
    r.draw(p);
    r.end_frame();
    const plot::Rect a = p.layout().axes;
    const plot::u32 rows = static_cast<plot::u32>(a.h);
    const plot::u32 cols = static_cast<plot::u32>(a.w);
    const plot::u32 mid = cols / 2u;
    Reading out;
    for (plot::u32 col = 0; col < cols; ++col) {
      for (plot::u32 row = 0; row < rows; ++row) {
        plot::u8 px[4] = {};
        PLOT_CHECK(ctx.read_pixel(static_cast<plot::u32>(a.x) + col,
                                  ctx.height - 1u - (static_cast<plot::u32>(a.y) + row), px));
        const int cover = static_cast<int>(px[2]) - static_cast<int>(px[0]);
        if (col + 6u < mid || col > mid + 6u) {
          // A level's own ink. The six-column guard is for the near-vertical stroke's
          // own width plus the connector either side of it.
          if (cover > out.flat) out.flat = cover;
        } else if (row >= 3u * rows / 8u && row <= 5u * rows / 8u) {
          // The riser's own ink: the middle quarter of the axis, which neither level
          // reaches. Reading the full height instead answers 191 at every zoom, because
          // the riser's column contains a level too.
          if (cover > out.riser) out.riser = cover;
        }
      }
    }
    return out;
  };
  // 3.4 samples a pixel and 1.0, so one window either side of `dense_threshold_spp`
  // (1.5) over the same waveform at the same place.
  const Reading dense = measure(2000.0);
  const plot::FrameStats dense_stats = r.stats();
  const Reading sparse = measure(600.0);
  const plot::FrameStats sparse_stats = r.stats();
  std::printf("[slope] dense riser=%d flat=%d graded=%u slopes=%u | sparse riser=%d flat=%d "
              "graded=%u slopes=%u\n",
              dense.riser, dense.flat, dense_stats.graded_traces, dense_stats.slope_traces,
              sparse.riser, sparse.flat, sparse_stats.graded_traces, sparse_stats.slope_traces);
  // The two frames took the two paths, or the comparison is between a frame and itself.
  PLOT_CHECK(dense_stats.graded_traces == 1 && dense_stats.slope_traces == 0);
  PLOT_CHECK(sparse_stats.slope_traces == 1 && sparse_stats.graded_traces == 0);
  // Neither path dims the level: a flat segment dwells in its row, so it is the top tier
  // and full ink. Both read 191.
  PLOT_CHECK(dense.flat > 180 && sparse.flat > 180);
  // And both dim the discontinuity, to about a third -- `intensity_floor` is 0.3 and a
  // riser spanning the axis is the longest span there is, so it sits on the floor. Both
  // read 71. Before the slope grading the sparse frame read 191 here.
  PLOT_CHECK(dense.riser * 100 < dense.flat * 55);
  PLOT_CHECK(sparse.riser * 100 < sparse.flat * 55);
  // The point of the exercise: the same edge at the two zooms is the same ink, so there
  // is no step at the threshold for a reader to see. A tier either way is 23 of 191, and
  // the measured pair is exact.
  PLOT_CHECK(std::abs(dense.riser - sparse.riser) < 24);
  PLOT_CHECK(!r.last_frame_had_gl_error());
 }