fix: a density grid is bounded in cells, not by the window's pixels

A grid was the axes rect in device pixels, so dragging a window wide made the
image wider with it -- and the per-frame pass over it is O(cells): the fade
multiplies every cell, a host's ink()/peak() read every cell, and a frame the
fade moved converts and uploads every cell as one byte. At 2x device scale a
1520x850 window's axes rect is 2877 device pixels wide, so four rows of one
trace are 4.5 M cells and 4.9 MB uploaded a frame; measured headless on
llvmpipe with a 2 s window, 12.9 ms of tick and 12.8 ms of draw a frame, every
frame under a time fade -- a cost that follows the window and has no ceiling.

The grid is now the axes rect up to kDensityCellCap (2^18 cells, a mebibyte of
counts), scaled down uniformly past it so cells stay square and the picture
keeps the axes' aspect, and magnified back over the rect with a linear filter:
a cell is a count, so a fragment between two of them is between their two ink
levels, which a point sample cannot give once a cell is several pixels wide.
The same four rows at the cap are 1.05 M cells, 3.9 ms of tick and 5.6 ms of
draw and 1.0 MB uploaded, while a grid under the cap is untouched -- a 640x360
viewport's 573x313 axes is still 179 349 cells, one a device pixel.

The image's footprint is the axes rect rounded up to whole device pixels on
both sides of the pipe, so a grid under the cap keeps the exact
one-texel-a-pixel mapping it has always had (sx/sy come out exactly 1) and only
a capped grid reads its cell index through a scale. Moving the decay itself to
the GPU was considered and left out: the CPU grid is what ink()/peak() read,
what the deposit adds to and what the per-sweep dedupe keys on, so a GPU image
would have to be reconciled with it per frame -- a larger change than this
bound, and not one to half-do.

Tests: a_density_grid_is_capped_whatever_the_window reads the bound off a
3840x2160 viewport (261 504 cells of a 3784x2138 axes, aspect kept),
a_capped_density_is_magnified_over_the_axes_rect reads the screen side of it
(569x460 cells covering all 832 of the rect's columns), and the density cases
now assert their capped figures. 399 cases, 0 failed.

.gitignore

@@ -3,3 +3,15 @@ build/
 # Not this project's and not generated by it: a Solarus game-engine message that
 # happens to sit in the repo root.
 error.txt
+
+# An *in-tree* configure writes these beside the sources. `build/` above only covers the
+# directory the presets use, and `cmake -S . -B .` leaves the whole of CMake's output in the
+# repository root -- which then reads as an untracked submodule to whoever has it checked out.
+CMakeFiles/
+CMakeCache.txt
+cmake_install.cmake
+Makefile
+CTestTestfile.cmake
+CPackConfig.cmake
+# Configured from `include/plot/version.hpp.in`, so it is output and not a source file.
+include/plot/version.hpp

README.md

@@ -14,6 +14,12 @@ built on top of it.
 | Qt6 | `plot::qt6` | `adapters/qt6/` |
 | GTK4 | `plot::gtk4` | `adapters/gtk4/` |
 
+The GTK4 adapter exists for, and is exercised by, a real consumer: **udpscope**, an oscilloscope-style viewer
+for a UDPStreamer source, at <https://git.ferrarinas.it/martino/udpscope>. It embeds the core through
+`plot::gtk4`, and the library's interaction layer — cursors, measurement marks, the shading of a span a host
+has declared invalid — has been shaped by what that host needed. The notes in `src/`, `docs/` and `tests/`
+that say "in udpscope's case" are those places.
+
 The visible x range is mapped onto sample indices through the series' own x
 (`Series::neighbours()`, a binary search over the real stamps), never through the
 `(x - x0()) / dx()` grid: `dx()` is a *nominal* spacing, and a series whose x is a streamed
@@ -48,7 +54,24 @@ run touched a GPU, so read it as an upper bound and a record of the software pat
   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;
+  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;
+- a **phosphor density** a host can turn on for a plot (`Plot::set_density()`, an image rather
+  than a set of retained traces): **one grid per trace**, in that trace's own colour, the axes
+  rect in device pixels, drawn *in place of* the traces -- a host may not also draw them over it --
+  into which each acquisition is deposited, 1.0 per cell a trace crosses, so brightness is how
+  often it passed. It fades either by a **time constant** in stream seconds or by a
+  **per-acquisition factor**, and the newest acquisition is deposited like every other, so it
+  fades too. The resolution is bounded (`kDensityCellCap`, 262 144 cells -- a mebibyte of counts --
+  a grid, past which the rect is scaled down uniformly and the image magnified back over it with a
+  linear filter), because the per-frame pass is `O(cells)` and the window is not bounded at all:
+  memory is the cap times the traces on screen times 4 bytes, whatever the window (a 640x360
+  viewport's axes is 179 349 cells per trace, 717 kB, under it, while four rows of one trace in a
+  3040x1700 one used to be 4.5 M cells and 18 MB between them). The deposit walks the axes'
+  columns rather than the samples, and a frame whose grids did not move costs one draw call per
+  trace (`FrameStats::density_cells`/`density_upload_bytes`); see `docs/data-and-performance.md`;
 - 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`,
@@ -78,7 +101,10 @@ run touched a GPU, so read it as an upper bound and a record of the software pat
 - input parity across hosts: pinch-zoom and pan gestures on Qt6 and GTK4 drive the same
   controller paths as mouse and wheel (touch parity), with keyboard panning
   (arrow keys), Escape cancelling a drag or box-zoom, double-click re-fitting the axes,
-  and modifier-masked box zoom (Shift = both axes, Ctrl = x only, Alt = y only);
+  and modifier-masked box zoom (Shift = both axes, Ctrl = x only, Alt = y only), the area being
+  chosen framed as the drag runs -- a low-alpha fill under a light border, widened along the axis
+  the release will *not* zoom, so Ctrl's frame is the band it is about to apply rather than the
+  sliver a straight horizontal drag sweeps;
 - DPI-consistent sizing: metrics are logical units converted once through
   `Style::ui_scale`;
 - an anti-aliased embedded monospaced font, plus an optional runtime TrueType backend
@@ -184,12 +210,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   # 396 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 **396 cases**; the `linux-coverage` preset builds **379** 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

adapters/gtk4/gtk_plot_area.cpp

@@ -344,6 +344,21 @@ u32 PlotArea::pointer_row() const noexcept {
   return row_in(row_rects_, pointer_.y);
 }
 
+void PlotArea::sync_selection_frames() noexcept {
+  const auto frame_for = [](input::Controller& c) -> Rect {
+    return c.drag_mode() == input::DragMode::BoxZoom ? c.selection_preview() : Rect{};
+  };
+  if (figure_ != nullptr) {
+    for (u32 i = 0; i < row_controllers_.size(); ++i) {
+      // An empty rect on the rows that are not choosing: `Rect` has no equality to compare
+      // with, and a store of the same value is what keeps this path free of anything else.
+      figure_->plot(i).set_selection_rect(frame_for(*row_controllers_[i]));
+    }
+    return;
+  }
+  plot_->set_selection_rect(frame_for(controller_));
+}
+
 void PlotArea::sync_figure_crosshair() noexcept {
   if (row_rects_.empty() || row_controllers_.empty()) return;
   const u32 row_count = static_cast<u32>(row_rects_.size());
@@ -534,6 +549,9 @@ void PlotArea::render() noexcept {
   // `::resize` ratio, not `gtk_widget_get_scale_factor()` -- the latter is the
   // ceiling under fractional scaling and would over-scale the chrome by up to 60%.
   renderer_->style().ui_scale = mapping_.factor;
+  // After the scale and before the draw: the preview reads the row's layout, and a layout measured
+  // with the previous frame's scale is not the one being drawn.
+  sync_selection_frames();
   renderer_->begin_frame(static_cast<u32>(viewport.w), static_cast<u32>(viewport.h), viewport);
   if (figure_ != nullptr) {
     renderer_->draw(*figure_);

adapters/gtk4/gtk_plot_area.hpp

@@ -397,6 +397,17 @@ class PlotArea {
   /// Spreads one row's crosshair over the whole figure (see "Figure mode"). Run once
   /// per frame, from the render callback, after this frame's row rects are cached.
   void sync_figure_crosshair() noexcept;
+  /// Hands each row's plot the box-zoom frame its controller is showing, or takes it off
+  /// the ones whose gesture is over. Run once per frame from the render callback, like
+  /// the crosshair's spread and for a related reason: a frame has to go away when a drag
+  /// ends by *any* route -- the release, Escape, a row rebuilt mid-gesture -- and a
+  /// per-event hook would have to be repeated at every one of them, which is how a frame
+  /// ends up stuck on screen after a cancelled zoom.
+  ///
+  /// Reads `selection_preview()`, which needs the row's layout, only for a controller
+  /// actually in `BoxZoom`: the cost is paid while a range is being chosen and never
+  /// otherwise.
+  void sync_selection_frames() noexcept;
   /// `figure_->set_viewport(px)`, one `layout()` into the rect cache, and each row's
   /// own rect to its controller. The figure-mode half of `refresh_viewport()` and of
   /// `render()`, which must not drift apart.

docs/building-and-testing.md

@@ -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`
-preset; its harness prints one line per case and a final `350 cases, 0 failed` summary line.
+`plot_umbrella_check`. The `plot_tests` binary itself runs **396 cases** in the `linux-debug`
+preset; its harness prints one line per case and a final `396 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 `396 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 **379 of the 396 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)

docs/data-and-performance.md

@@ -251,7 +251,18 @@ Five things carry it, and each was arrived at by being wrong first:
   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. A connector between two disjoint columns
+  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
@@ -276,6 +287,156 @@ flat path is on the pyramid is what exercises the floor (`raw=0 lod=1 … seg=63
 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.
+
+## A phosphor density is the trace, one grid per trace
+
+`Plot::set_density()` gives a plot a **phosphor density**: an image of how often its traces have
+passed, drawn *in place of them* -- one grid per trace, in that trace's own colour -- fading by a
+time constant or by an acquisition count. It is the library's because the library is the side that
+knows a trace's device geometry; a host that built one itself would be re-rasterising traces the
+renderer has already staged.
+
+The split from the grading above is what it costs: grading measures *one* frame's dwell and
+throws it away, while the density **keeps** what it measured — that is the whole point of it, and
+also why it cannot be a per-frame accumulator.
+
+- **The grid is the screen's, not the data's — bounded — and there is one per trace.** The axes
+  rect in device pixels (`DensityGrid`, `plot/plot/density.hpp`), one `f32` cell each, **up to
+  `kDensityCellCap` = 262 144 cells** (2^18, a mebibyte of counts): under the cap the grid *is* the
+  rect — the axes of a 640x360 viewport is a **573x313** grid of **179 349 cells** and **717 396
+  bytes**, and a thousand acquisitions through it cost the same — and past it the rect is scaled
+  down *uniformly*, so a cell stays square and the picture keeps the axes' aspect. A plot holds one
+  of these for **each trace it draws**, so the display's memory is that figure times the traces on
+  screen; the bound is per *grid*, so four traces hold at most 1 MiB each whatever the window is.
+  The colour is the reason for the per-trace split: a density that had one hue for the plot could
+  not say *which* trace put the ink there, and two signals agreeing in a cell would read as one
+  blended pixel. `Plot::density_grid(trace)` returns a trace's image; a trace with no series (an
+  unbound slot) holds no grid at all.
+
+  The cap is what keeps the resolution from following the window, and the window is not a fixed
+  thing: a 1520x850-logical window at 2x device scale has a 2877-pixel-wide axes rect, and four
+  rows of one trace are **4.5 M cells** — 18 MB of counts, every one of them walked per frame. The
+  pass is `O(cells)` in all three places it happens, so an unbounded image makes the *frame* cost a
+  function of the window: measured on llvmpipe (four traces, one a row, a 2 s window, a 3040x1700
+  framebuffer) the grid pass alone was **12.9 ms of tick and 12.8 ms of draw a frame** and 4.9 MB
+  uploaded, against **3.9 ms / 5.6 ms** and 1.0 MB at the cap. The renderer magnifies the capped
+  image back over the rect with a **linear** filter, because a cell is a *count* — a continuous
+  quantity — and a fragment between two of them is between their two ink levels, which is what a
+  linear tap returns and a point sample cannot (it would show the cell grid as blocks once a cell
+  is several pixels wide). A one-cell-tall feature is thereby spread over its neighbours, which is
+  what any magnification of an image does.
+- **A cell's value is a number of sweeps**, and a trace covering it during one
+  `Plot::accumulate_density()` leaves 1.0, **once however many of its own samples crossed it**.
+  Counting the hits instead puts a single dense sweep at the ceiling of the brightness scale and
+  hides the sweeps behind it, and a cell would then mean "how much the beam moved here" rather
+  than "how many acquisitions were here". The dedupe is a stamp per grid *row* (one `u64`, a few
+  kB, shared by every trace's deposit), keyed by (trace, column), so two sweeps agreeing on a cell
+  still count twice and the two segments that share a column boundary do not.
+- **The deposit is one pass per cell, not one per sample.** A trace's visible window is mapped to
+  sample indices and gathered exactly as `Renderer::draw_traces()` maps it (`neighbours()`, the
+  same 64-spp gate for the LOD level), then walked as a polyline: for each grid column the
+  segment covers, the rows it spans in that column get +1 each. A window of millions of samples
+  over hundreds of columns therefore costs *columns*, plus one row of ink per column the trace
+  crossed — the deposit is bounded by the screen, not by the data, which is what makes an
+  accumulation affordable at the trigger's own rate.
+- **The newest acquisition is deposited like every other, and no trace is drawn over the image.**
+  `Renderer::draw_traces()` returns at once while a density is on: the trace ink *is* the image, so
+  the acquisition just drawn is a sweep *inside* it and fades with the rest. Drawing the polyline
+  on top as well would put a solid, unfading stroke over its own faint ghost — the "persistent
+  image + last acquisition" a user reported, where the newest acquisition never faded.
+- **The brightness ceiling is the trace's own brightness, and the ramp is linear in sweeps.**
+  `DensityConfig::full_scale` defaults to **one sweep**, so a cell with one acquisition's ink is
+  drawn in its trace's colour at that colour's own alpha, and a signal crossing the same place
+  every acquisition settles *exactly* at the colour its trace would have drawn — the settlement is
+  a clamp, not a gain. `gamma` defaults to 1.0, because a cell's value is a count and half as many
+  sweeps must read as half the ink. A ceiling at the *fade's steady state* (`1/(1-0.5)=2`) was the
+  first default and is a legitimate alternative: it makes the newest sweep a fraction of the
+  settled brightness so the fade's ramp is visible, at the cost of a gain offset between the newest
+  sweep and the image behind it. The case that reads either one off the *screen* rather than the
+  grid is `a_phosphor_density_is_the_trace_in_its_own_colour`.
+- **The scale is applied once, on the CPU.** `DensityConfig::full_scale` and `gamma` map a cell's
+  count to a luminance byte when the grid changed, and the shaders (`kDensityVS`/`kDensityFS`)
+  only tint that byte with the trace's colour. The one derivation is deliberate: a value a host
+  reads back through `DensityGrid::ink()`/`peak()` and the picture it sees come from the same
+  numbers.
+- **Per frame, it is one texture upload and one draw call *per trace* — or one draw call each.**
+  The upload is one byte per cell (**179 kB** for the axes above, and at most 256 kB a trace at
+  `kDensityCellCap`, whatever the window); the one texture is re-filled per trace, and a frame whose
+  grids did not move skips the conversion and the uploads entirely and pays the quads alone
+  (`FrameStats::density_upload_bytes` reads 0 for it). The decay is what makes the grids move every
+  frame under `TimeConstant`, and what makes them stand still between acquisitions under
+  `PerAcquisition`.
+  A `TimeConstant` fade therefore does pay the conversion and the upload every frame, whatever the
+  bound — a *bounded* bill rather than a free one. Applying the fade on the GPU instead was
+  considered and is a **larger** change than this bound and was deliberately not bundled with it:
+  the image would have to live in a ping-pong target the decay multiplies in place, while the
+  *count* stays on the CPU, because that is what a host reads back through `ink()`/`peak()`, what
+  the deposit adds whole swaths to, and what the per-sweep dedupe keys on — so the two would have
+  to be reconciled per frame anyway. The bound is what makes that reconciliation a fixed cost.
+
+`a_density_grid_is_the_axes_in_device_pixels` reads the resolution and the memory back
+(**578x453 = 261 834 cells, 1 047 336 bytes** on its 640x480 viewport, which is past the cap, and
+the 320x240 leg it ends on is the axes rect *exactly*, one cell a device pixel —
+`ink=578 peak=1` for one flat sweep, the ink of one sweep *is* the columns it covers),
+`a_density_grid_is_capped_whatever_the_window` reads the bound itself off a 3840x2160 viewport
+(**681x384 = 261 504 cells = 1 046 016 bytes of a 3784x2138 axes**: the cells never exceed
+`kDensityCellCap`, the grid is within 1 % of the whole budget and its aspect is the axes' — the
+uniform scaling), and `a_capped_density_is_magnified_over_the_axes_rect` reads the *screen* side of
+it (**569x460 = 261 740 cells of an 832x673 axes**: the image covers all **832** of the rect's
+columns rather than the 569 cells it holds — the assertion a quad drawn at the grid's own size
+fails — the sweep stays on the row its transform maps it to, and its ink is most of the trace's own
+colour, `green=195` against a background of `65`, the rest being the magnification's blend),
+`a_density_halves_per_acquisition_and_keeps_the_newest_brightest` reads the count schedule
+(578 → 867 → 1012 on a 578-column grid, i.e. `1 + 1/2 + 1/4` of the width, `peak_steady=2.000`),
+`a_density_fades_by_its_time_constant` reads `exp(-dt/tau)` off the ink,
+`a_density_holds_one_grid_per_trace` reads two traces' grids apart (**261 834 cells each,
+ink 578/578**, in two different rows), and
+`a_phosphor_density_is_the_trace_in_its_own_colour` reads the frame: `cells=179349 uploaded=179349`
+on the frame the grid moved and `uploaded=0` on the identical one after it; a saturated cell is the
+trace's own colour exactly (`full=224`, the trace's `0xE0` green, against `bg=25`, where the old
+near-white tint read ~190 red); one time constant dims it (`faded=115`); and a steady state
+(`steady=224`) against a quarter of it (`quarter=138`) keeps the trace's hue, red near the
+background's.
+
 ## One sample or a statistic of many
 
 Every number the library reports is one the samples actually hold. What differs between

docs/interaction.md

@@ -192,6 +192,16 @@ without knowing what a pointer is. `hovered_cursor()`, `grabbed_cursor()`, `hove
 `grabbed_region()` and `region_grab(u32)` expose the same answers to a host (a resize cursor, a
 tooltip, a status line).
 
+The frame an open box zoom is drawing is published the same way and for the same reason
+(`Plot::set_selection_rect()`), and the plot still learns nothing about pointers: the host reads the
+rect off the controller -- `Controller::selection_preview()` -- on every frame of the drag and takes it
+off the plot when the gesture ends. The preview is deliberately not what the pointer swept. Shift
+frames both axes and its preview is the swept box; Ctrl frames x only, so its preview is widened to the
+full height of the axes, and Alt's to the full width. The swept sliver is the *gesture*; the widened
+rect is what the *release* will apply, which is the one worth showing while it is still only a
+gesture. Nothing is previewed until the drag has swept every axis the release will act on: an empty
+rect widened is a band the width of the plot, which would claim a range that does not exist yet.
+
 ## Live follow
 
 An x axis has a follow state, `XFollow::Off` (the default) or `XFollow::Live`

docs/styling.md

@@ -42,6 +42,8 @@ Colours (neither logical nor device — nothing to scale):
 | `axis_text` | `0xC8D0DC` | tick labels and axis titles |
 | `cursor` | `0xFFB020` | cursor markers; also the hovered/grab highlight |
 | `measure_fill` | `0xFFB020` at α 0.15 | the measurement band |
+| `invalid_fill` | `0x8A94A6` at α 0.18 | a span the host declared invalid (`Plot::set_invalid_spans()`) |
+| `invalid_repaired_fill` | `0x8A94A6` at α 0.08 | the same span once the host has marked it repaired |
 | `crosshair` | `0xE6EBF2` | crosshair lines and the readout panel's border (hue-neutral by design; trace markers keep each trace's own colour) |
 
 The scale:

include/plot/data/minmax_pyramid.hpp

@@ -76,6 +76,19 @@ class MinMaxPyramid {
   /// whose samples were all non-finite is stored as an empty aggregate
   /// (count 0, zero sums) that every reader treats as absent.
   void append(f32 v);
+  /// Folds a backfilled sample into every aggregate that covers absolute index
+  /// `absolute_sample`.
+  ///
+  /// **Precondition: the sample at that index was appended non-finite.** That is what makes
+  /// this purely additive -- min/max widen, sum/sumsq accumulate and count rises by one, at
+  /// every covering level -- so no bucket is ever recomputed and the cost is O(levels)
+  /// regardless of how wide the repaired span is. Amending a *finite* sample would need the
+  /// old value removed from sum/sumsq and could not restore min/max at all, which is why
+  /// this is a one-way NaN-to-value operation and not a general write.
+  ///
+  /// An index outside `[window_base(), window_end())` is a no-op: the window slides on the
+  /// consumer thread, so a caller cannot prove the slot is still held before asking.
+  void amend(u64 absolute_sample, f32 v);
   /// Slides the retained window's leading edge to absolute sample index
   /// `absolute_sample`, dropping every aggregate that covered a sample before it.
   /// Monotonic, and a no-op only when `absolute_sample <= window_base()`: an empty

include/plot/data/ring_buffer.hpp

@@ -64,6 +64,24 @@ class RingBuffer {
     for (u64 i = 0; i < n; ++i) push(vs[i]);
   }
 
+  /// Producer thread only: rewrites the slot at absolute index `absolute`, without pushing.
+  /// Returns false when that index is not retained -- already overwritten, or not yet
+  /// produced -- in which case nothing is written.
+  ///
+  /// This is for *backfill*: a slot pushed as a placeholder and corrected when the data that
+  /// belongs there arrives late. It is the same race class as `push()` -- one relaxed store
+  /// into a slot a consumer may be reading, and T is lock-free by the class's static_assert,
+  /// so a reader sees the old value or the new one and never a torn one. It deliberately does
+  /// not touch `produced_`: the count fixes which indices a snapshot reads, and an amend
+  /// changes a value inside that window rather than extending it.
+  bool amend(u64 absolute, T v) {
+    const u64 p = produced_.load(std::memory_order_relaxed);
+    if (absolute >= p) return false;
+    if (p > cap_ && absolute < p - cap_) return false;
+    buf_[static_cast<usize>(absolute & mask_)].store(v, std::memory_order_relaxed);
+    return true;
+  }
+
   /// Consumer: retained element count, saturating at capacity().
   u64 size() const noexcept {
     const u64 p = produced_.load(std::memory_order_acquire);
@@ -109,6 +127,18 @@ class RingBuffer {
   /// pushing).
   void clear() noexcept { produced_.store(0, std::memory_order_relaxed); }
 
+  /// Consumer thread only: discards every element and resumes the absolute count
+  /// at `absolute`, so the next push() lands there (not safe while a producer is
+  /// pushing).
+  ///
+  /// This is for a *recompute*: a ring whose contents are derived from another is
+  /// emptied and refilled from a given absolute origin, and it must come back
+  /// numbered as its source is. clear() would restart it at 0 and leave every
+  /// absolute index -- base(), produced(), copy_from() -- off by that origin.
+  void clear_to(u64 absolute) noexcept {
+    produced_.store(absolute, std::memory_order_relaxed);
+  }
+
  private:
   u64 cap_;
   u64 mask_;

include/plot/input/controller.hpp

@@ -229,6 +229,18 @@ class Controller {
   DragMode drag_mode() const noexcept { return mode_; }
   /// The current box-zoom selection in pixels; meaningful while BoxZoom.
   Rect selection_rect() const noexcept { return selection_; }
+
+  /// The rectangle a host should *draw* for the open box zoom: the swept area, widened to the full
+  /// axes along whichever axis the modifier's mask will not zoom. Ctrl frames the x range only, so its
+  /// preview is the band that spans the plot -- which is what the release will zoom -- where the area
+  /// a purely horizontal drag sweeps is a sliver a few pixels tall. Shift (and any other combo) frames
+  /// both, and gets the swept box itself.
+  ///
+  /// Meaningful while `BoxZoom`, like `selection_rect()`; the zero rect otherwise.
+  ///
+  /// Defined in the implementation: widening the preview to the axes needs the plot's layout, and
+  /// `Plot` is only forward-declared here.
+  Rect selection_preview() const noexcept;
   /// The cursor under the pointer -- a vertical marker or a horizontal ruler, whichever
   /// line the pointer is nearer -- or `kInvalid` when the pointer is outside the plot area
   /// or no cursor is within a few pixels.

include/plot/plot.hpp

@@ -54,6 +54,7 @@
 #include <plot/plot/axis.hpp>
 #include <plot/plot/crosshair.hpp>
 #include <plot/plot/cursor.hpp>
+#include <plot/plot/density.hpp>
 #include <plot/plot/figure.hpp>
 #include <plot/plot/grid.hpp>
 #include <plot/plot/legend.hpp>

include/plot/plot/density.hpp

@@ -0,0 +1,195 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#pragma once
+#include <span>
+#include <vector>
+
+#include <plot/core/types.hpp>
+
+namespace plot {
+
+/// The most cells one density grid may hold: **262 144**, a mebibyte of `f32` counts.
+///
+/// A grid is the axes rect in device pixels -- the screen's resolution and not the data's, which is
+/// the whole point of accumulating into a grid -- but the screen is not a fixed thing. A window can
+/// be dragged to any width, and at 2x device scale the axes rects of a 1520x850-logical window are
+/// 2877 device pixels wide each: four rows of one trace are **4.5 M cells**, 18 MB of counts
+/// between them, and every one of them is walked per frame. That walk is `O(cells)`: the fade
+/// multiplies every cell, a host's `ink()`/`peak()` read every cell, and a frame the fade moved
+/// converts and uploads every cell as one byte. So a resolution tied to the window is a per-frame
+/// cost tied to the window, with no ceiling -- measured headless on llvmpipe with four rows of one
+/// trace, a 2 s window and a 3040x1700 framebuffer: **4.5 M cells, 12.9 ms of tick and 12.8 ms of
+/// draw a frame, 4.9 MB uploaded**.
+///
+/// This is the ceiling, in **cells** rather than in pixels: the axes rect is scaled down, uniformly,
+/// until it fits, so a cell stays square and the picture keeps the axes' aspect (see `DensityGrid`).
+/// The number is a frame's budget read off that same measurement -- the same four rows at the cap
+/// are 1.05 M cells and **3.9 ms of tick and 5.6 ms of draw**, a third and a half of the unbounded
+/// grid's pass -- while the image is still 681 columns across on a 3784-pixel axes rect. It is a
+/// **cap** and not a resolution: a grid whose axes rect is under it is still exactly that rect in
+/// device pixels, and only an axes rect of more than a quarter of a megapixel -- a 4K window's, or
+/// one row of a tall one -- is scaled.
+inline constexpr usize kDensityCellCap = usize{1} << 18;
+
+/// Which way a plot's **phosphor density** fades between the acquisitions drawn into it.
+///
+/// The two are answers to two different questions, which is why the choice belongs to the
+/// caller rather than to a default: a bench scope's persistence is set by *time* -- "the trace
+/// is still visible a second after it was drawn" -- while a sweep-to-sweep accumulation is set
+/// by *count* -- "the tenth acquisition back is gone". The two agree only while the trigger
+/// rate is constant, and a rate that varies between runs is exactly when a caller has to pick.
+enum class DensityDecay {
+  /// `intensity *= exp(-dt / time_constant_s)` every time the grid is advanced
+  /// (`Plot::decay_density()`), so the image fades while you watch it whatever the trigger
+  /// rate -- a slow stream draws faint sweeps, a fast one bright ones, and both are still
+  /// legible a time constant later. A `time_constant_s <= 0` freezes the grid instead of
+  /// fading it.
+  TimeConstant,
+  /// `intensity *= per_acquisition` once per accumulated acquisition, applied by
+  /// `Plot::accumulate_density()` *before* the new acquisition is deposited, so the sweep just
+  /// drawn is the brightest and each older one is the factor down: the N-th back is gone
+  /// whatever the rate. It scales with the trigger rate by construction -- the record of the
+  /// last few sweeps is what the display holds -- which is what a caller wants when the
+  /// interesting comparison is between successive acquisitions and not between seconds.
+  PerAcquisition,
+};
+
+/// A plot's phosphor density: whether the grid is on, how it fades, and how a cell's count is
+/// turned into brightness. Plain data, replaced wholesale by `Plot::set_density()`.
+///
+/// The image is **one grid per trace**, drawn in that trace's own colour (`Trace::color`), because
+/// a density that had one hue for the whole plot could not say *which* trace put the ink there --
+/// two signals agreeing in a cell would be one blended pixel, and a display of several traces
+/// could not be read back to the trace it came from. A cell's brightness is a count of sweeps in
+/// *that trace's* colour: `full_scale` (default one sweep, the trace's own brightness) is where it
+/// saturates, and a signal crossing the same place every acquisition settles exactly at the colour
+/// its trace would have drawn.
+///
+/// Its reason to exist as a *plot* feature rather than a host's overlay is the same one
+/// `Plot::set_invalid_spans()` has: the plot is what knows a trace's device geometry -- the
+/// visible window about to be drawn, on the axes rect the layout settled -- so the host would
+/// otherwise have to rasterise traces the library has already staged, at a second derivation of
+/// the same mapping that could disagree with the first.
+struct DensityConfig {
+  /// Whether the grid is drawn *and* accumulated. Off is the default and costs nothing: no
+  /// grid is allocated, no frame uploads one, and the traces are drawn exactly as they were.
+  /// Turning it off drops what was accumulated --- a caller that has stopped paying is not
+  /// holding a stale image -- see `Plot::set_density()`.
+  bool enabled = false;
+  /// How the grid fades (see `DensityDecay`).
+  DensityDecay decay = DensityDecay::PerAcquisition;
+  /// `TimeConstant`'s constant, in **stream seconds** -- the same clock the x axis reads, so a
+  /// caller advancing the density by its frame's own `dt` gets a fade that does not depend on
+  /// the frame rate. `<= 0` freezes the grid.
+  f32 time_constant_s = 1.0f;
+  /// `PerAcquisition`'s factor, clamped to `[0, 1]` at use. 0.5 -- half per acquisition -- is
+  /// what a phosphor's afterglow looks like sweep to sweep: 1, 0.5, 0.25, 0.125 and by the
+  /// seventh the layer is under 1 %.
+  f32 per_acquisition = 0.5f;
+  /// The cell value that reads as **full brightness**, in accumulated sweeps -- and the one field
+  /// a caller reads *off its own trace* rather than off the fade. A cell at this value is drawn in
+  /// its trace's own colour at that colour's own alpha; the default of **one sweep** is therefore
+  /// the ink the newest acquisition leaves, so the acquisition just drawn reads exactly as the
+  /// trace it is a picture of (a signal crossing the same place every acquisition settles at the
+  /// trace's brightness, where a ceiling above one sweep would settle *brighter* than the trace and
+  /// leave a gain offset between the newest sweep and the image behind it). Everything above the
+  /// ceiling clamps to the same pixel: where several acquisitions agree, the cell is the trace's
+  /// colour at full strength and no brighter.
+  ///
+  /// A caller that wants the fade's own ramp on screen instead -- the newest sweep a *fraction* of
+  /// the steady state, so the eye can rank the sweeps -- sets this to the sum the fade settles at
+  /// (for `PerAcquisition`'s factor `f` that is `1/(1-f)`) and accepts the gain offset; that was
+  /// this field's first default, and it is a legitimate choice, not the one a phosphor makes.
+  f32 full_scale = 1.0f;
+  /// The gamma applied to the normalised cell value before it becomes a luminance. **1.0 by
+  /// default: linear in sweeps**, because that is what a count means -- a cell covered by half the
+  /// acquisitions is half the ink. Under 1 lifts the faint end, and that is what
+  /// `Style::intensity_gamma` is for where the value is a *dwell fraction* rather than a count;
+  /// here it flattens the top instead (0.45 maps a quarter of the scale to 0.54 and the ceiling to
+  /// 1.0, which is most of the ramp spent on the last sweep). Over 1 darkens the faint end for a
+  /// caller that wants only the strong agreement visible.
+  f32 gamma = 1.0f;
+};
+
+/// The density's own image: **the axes rect in device pixels, up to `kDensityCellCap` cells**, so
+/// its resolution is the screen's and not the data's -- the whole point of accumulating into a grid
+/// rather than keeping the acquisitions that were drawn into it -- while still being bounded by
+/// something other than the window a user has dragged. Under the cap the grid *is* the axes rect and
+/// a cell is a device pixel; past it the rect is scaled down uniformly (see `kDensityCellCap` for
+/// the number and the frame budget it comes from), and the renderer magnifies the image back over
+/// the rect with a linear filter, because a cell is a count of sweeps and not a pixel of a picture.
+///
+/// The bound is what makes the memory and the per-frame cost *numbers* rather than functions of the
+/// window: `columns() * rows() * 4` bytes whatever the trigger has done **and** whatever the
+/// window is, at most **262 144 cells, 1 048 576 bytes** a grid -- against the 4.5 MB a trace a
+/// 3040x1700 framebuffer's axes used to ask for, and the 26 ms of tick and draw a frame the pass
+/// over four of them then cost. A plot holds **one grid per trace** (see `DensityConfig`), so a
+/// display's memory is that figure times the traces actually drawn -- a plot's unbound slots hold no
+/// grid -- and four traces hold at most 4 MiB between them. The renderer adds one byte per cell as
+/// the luminance it uploads (`DensityGrid::cells()` is `f32` because a **count** is what decays and
+/// what `ink()`/`peak()` report; the byte is derived per changed frame, not stored here).
+///
+/// A cell's value is a **number of sweeps**: every visible trace of the plot that covers that cell
+/// during one `Plot::accumulate_density()` leaves 1.0 in it -- once, however many of that trace's
+/// own samples crossed it -- so brightness means how many acquisitions were here, and two traces
+/// agreeing in one cell is twice the ink. (What the *beam* did inside one column is a different
+/// question, and the library answers it elsewhere: `Style::intensity_grading`.) Decay multiplies
+/// the whole image, so a cell's value is a decaying count of sweeps and not a bounded score.
+///
+/// The grid is indexed row-major from the axes rect's **top-left** corner: cell `(c, r)` is at
+/// `r * columns() + c` and covers the device span `[axes.x + c*w/columns(), axes.x + (c+1)*w/columns())`
+/// by `[axes.y + r*h/rows(), axes.y + (r+1)*h/rows())` -- the device pixel `(axes.x + c, axes.y + r)`
+/// while the rect is under the cap, and a block of them when the plot scaled the image down.
+/// `revision()` moves on every change, which is what lets the renderer skip the upload -- and the
+/// whole conversion -- on a frame the grid did not move.
+class DensityGrid {
+ public:
+  /// Grid width in cells: the axes rect's width in device pixels, rounded up, scaled down when the
+  /// rect is past `kDensityCellCap` (see the class comment). 0 until the first accumulation on a
+  /// laid-out plot.
+  u32 columns() const noexcept { return columns_; }
+  /// Grid height in cells: the axes rect's height in device pixels, rounded up, scaled down with
+  /// `columns()`: `columns() * rows()` cells.
+  u32 rows() const noexcept { return rows_; }
+  usize cell_count() const noexcept {
+    return static_cast<usize>(columns_) * static_cast<usize>(rows_);
+  }
+  /// The cells, row-major from the top-left, one per cell of the axes rect -- see the class comment
+  /// for the resolution and what one cell's value means.
+  std::span<const f32> cells() const noexcept { return cells_; }
+  /// One cell, or 0.0 outside the grid.
+  f32 at(u32 column, u32 row) const noexcept {
+    if (column >= columns_ || row >= rows_) return 0.0f;
+    return cells_[static_cast<usize>(row) * columns_ + column];
+  }
+  /// The **total ink**: every cell's value summed. The reading that says how much has been
+  /// drawn into the grid at all -- it grows with each accumulation and falls with each decay,
+  /// and is 0 for a grid that is off or was just cleared.
+  f64 ink() const noexcept {
+    f64 total = 0.0;
+    for (const f32 v : cells_) total += static_cast<f64>(v);
+    return total;
+  }
+  /// The **peak**: the brightest cell's value, 0 for an empty grid. It is the reading that
+  /// says whether the accumulation is saturating (at or past `DensityConfig::full_scale`, which
+  /// reads as full brightness) and whether the decay has reached the sweep behind the newest.
+  f32 peak() const noexcept {
+    f32 top = 0.0f;
+    for (const f32 v : cells_) top = v > top ? v : top;
+    return top;
+  }
+  /// How many times the image changed: bumped by every accumulation, decay, clear and resize.
+  /// The renderer compares it with the revision it last uploaded, so a frame that changed
+  /// nothing uploads nothing.
+  u64 revision() const noexcept { return revision_; }
+
+ private:
+  friend class Plot;
+  std::vector<f32> cells_;
+  u32 columns_ = 0;
+  u32 rows_ = 0;
+  u64 revision_ = 0;
+};
+
+}  // namespace plot

include/plot/plot/plot.hpp

@@ -2,6 +2,7 @@
 // SPDX-FileCopyrightText: 2026 Martino Ferrari
 
 #pragma once
+#include <span>
 #include <vector>
 
 #include <plot/core/rect.hpp>
@@ -11,6 +12,7 @@
 #include <plot/plot/axis.hpp>
 #include <plot/plot/crosshair.hpp>
 #include <plot/plot/cursor.hpp>
+#include <plot/plot/density.hpp>
 #include <plot/plot/grid.hpp>
 #include <plot/plot/legend.hpp>
 #include <plot/plot/measure.hpp>
@@ -49,6 +51,28 @@ constexpr bool x_strip_has_title(XStrip mode) noexcept {
   return mode == XStrip::Both || mode == XStrip::TitleOnly;
 }
 
+/// One span of the primary x axis the host has declared invalid, in **data** coordinates --
+/// `Region`'s convention. In udpscope's case a reserved hole: samples the stream's counter says
+/// exist and that have not been delivered.
+///
+/// `repaired` says the host has since filled the span's samples in. Such a span is **still
+/// reported**, because the shading is a record of what the window was missing, but it is drawn in
+/// the fainter of the two tints -- so a reader can distinguish a gap that is still empty from one
+/// that has since been repaired, and from a span that has left the list entirely.
+struct InvalidSpan {
+  f64 x0 = 0.0;
+  f64 x1 = 0.0;
+  bool repaired = false;
+};
+
+/// One invalid span's measured shading: the rect, clipped to the axes' columns, and the state that
+/// chooses its tint. A struct and not a bare `Rect` for `RegionLayout`'s reason -- the renderer
+/// draws exactly what the layout measured and derives nothing of its own.
+struct InvalidSpanLayout {
+  Rect fill;
+  bool repaired = false;
+};
+
 /// Pixel geometry of a plot's chrome, all of it in the same pixel space as
 /// `Rect` (origin top-left) and therefore in **device** pixels: everything here is
 /// what the renderer draws with, already converted from the logical metrics in
@@ -105,6 +129,15 @@ struct PlotLayout {
   /// controller's hit test reads the very same rects, so where a region is drawn and
   /// where a pointer can grab it cannot drift apart.
   std::vector<RegionLayout> regions;
+  /// Every invalid span's shading, in `Plot::invalid_spans()` order and clipped to the axes'
+  /// columns. Measured here for the regions' first reason -- the frame draws exactly these
+  /// numbers -- and reserving nothing, so a hole cannot move the strips the labels were
+  /// measured into. A span entirely outside the window contributes no rect at all, so this is
+  /// not index-aligned with `invalid_spans()` and nothing needs it to be: there is no hit test
+  /// on a band and no label beside it. Each entry carries the span's `repaired` state alongside
+  /// its rect, so the tint is chosen where the geometry is measured rather than looked up again
+  /// at draw time.
+  std::vector<InvalidSpanLayout> invalid_spans;
   /// The crosshair's geometry, when one is active: the two lines' stroke boxes, the
   /// readout panel and one row per visible trace with the value of the sample nearest the
   /// pointer. Placed here rather than derived by the renderer, exactly as the legend and
@@ -112,6 +145,13 @@ struct PlotLayout {
   /// clamped against the rect it was measured for, so nothing of the readout can be drawn
   /// over a label strip or into a figure's neighbouring row.
   CrosshairLayout crosshair;
+  /// The box-zoom frame, when a modified drag has one open: the area the gesture is framing, in
+  /// viewport pixels, already widened along whichever axis the modifier will *not* zoom (see
+  /// `input::Controller::selection_preview()`, which is where that is decided). Here rather than
+  /// derived by the renderer, for the regions' reason -- the frame draws exactly these numbers -- and
+  /// left as the zero rect whenever no gesture is open, which is what both the fill and the four
+  /// border segments read as "draw nothing".
+  Rect selection;
 };
 
 /// What a pointer is on, as of the last pointer event: the cursor marker under it, the
@@ -525,6 +565,104 @@ class Plot {
   void set_x_note(std::string text);
   const std::string& x_note() const noexcept { return x_note_; }
 
+  /// Spans of the primary x axis the host has declared invalid -- in udpscope's case a reserved
+  /// hole: samples the stream's counter says exist and that have not been delivered. Each span's
+  /// `x0`/`x1` are in **data** coordinates, `Region`'s convention, and is shaded behind
+  /// the traces and over the grid.
+  ///
+  /// Deliberately *not* a `Region`: a region is interactive -- draggable bounds, hot zones, a
+  /// label, a cached statistic, a controller hit test -- and a plot can carry dozens of holes at
+  /// once, which would put a hundred-odd grab targets in the way of every pointer event for
+  /// marks nobody can usefully drag. This is passive shading and nothing else.
+  ///
+  /// The span is copied, so the caller's storage need not outlive the call. Spans need not be
+  /// sorted and may overlap; an empty call clears the shading.
+  ///
+  /// A span whose `repaired` flag is set is shaded more faintly (`Style::invalid_repaired_fill`
+  /// against `Style::invalid_fill`). Clearing the shading is the host's decision and nothing
+  /// here retires a span on its own: a repaired span is drawn until the host stops sending it.
+  void set_invalid_spans(std::span<const InvalidSpan> spans);
+  std::span<const InvalidSpan> invalid_spans() const noexcept { return invalid_spans_; }
+
+  // --- phosphor density --------------------------------------------------
+
+  /// Turns this plot's **phosphor density** on or off, and states how it fades. Off -- the
+  /// default -- is the plot exactly as it was: no grid is allocated, no geometry is deposited
+  /// and no frame uploads anything.
+  ///
+  /// On, the plot keeps an intensity grid behind each of its traces, in that trace's own colour
+  /// (see `DensityGrid` for the resolution, the bound on it and the per-cell meaning, and
+  /// `DensityConfig` for the per-trace colour and the memory the grids cost), and deposits the
+  /// acquisition on screen into it with `accumulate_density()`. While a density is on the
+  /// renderer draws **no solid trace** over it: the trace ink *is* the image, so the newest
+  /// acquisition is deposited like every other and fades with the rest -- a trace left drawn on
+  /// top of its own density could never fade, which is what a report of "the last acquisition
+  /// never fades" was. It is deliberately *not* a set of retained traces -- the library has the
+  /// trace geometry in hand, so a density costs one grid per trace whatever the trigger has done,
+  /// where retaining the acquisitions would cost a window copy each.
+  ///
+  /// Like `set_invalid_spans()` it reserves **no layout space** and nothing on it can be picked:
+  /// it is drawn inside the axes it was sized to, and a pointer neither finds it nor is found by
+  /// it. A cell is a device pixel of that axes rect while the rect is under `kDensityCellCap` and
+  /// a block of them past it, which the renderer scales back up with a linear filter -- the image
+  /// reserves no space either way, so the bound changes its resolution and nothing about the
+  /// layout.
+  ///
+  /// **Disabling drops what was accumulated at once**, not at the next acquisition: a caller who
+  /// has stopped paying for the display is not left holding a stale image of it, which is the
+  /// rule the app's own `set_persist_depth()` follows for the very same reason. Re-enabling
+  /// starts from an empty grid -- the image is sized to the screen, and a screen it has not been
+  /// sized against yet is a screen it has nothing to say about.
+  void set_density(const DensityConfig& config);
+  /// The configuration, as set.
+  const DensityConfig& density() const noexcept { return density_; }
+  /// The accumulated image **of a trace**, for a host that wants to draw it or read it back. There
+  /// is one per trace, in trace order, because each is drawn in that trace's own colour (see
+  /// `DensityConfig`); an out-of-range trace reads an empty (0x0) image. Empty until the first
+  /// `accumulate_density()` on a laid-out plot, and dropped by `set_density()` off.
+  const DensityGrid& density_grid(u32 trace) const noexcept {
+    return trace < density_grids_.size() ? density_grids_[trace] : empty_density_grid();
+  }
+
+  /// Deposits **the acquisition on screen** into each trace's grid: every visible trace of this
+  /// plot, the newest acquisition included, over the x window its own axis is showing, 1.0 into
+  /// every cell it covers -- **once per cell per sweep**, however many of that trace's own samples
+  /// crossed it, so a cell's value is how many traces have covered it since the last decay and not
+  /// how much the beam moved (see `DensityGrid`; the dwell question is
+  /// `Style::intensity_grading`'s). Called once per *acquisition*, which is the cadence the grids
+  /// count in: a caller that deposited every frame would add one sweep sixty times a second, and
+  /// the per-acquisition fade would have nothing to measure itself against. The renderer draws no
+  /// polyline for a trace whose density is on (see `set_density()`), so this deposit is the whole
+  /// of what the newest acquisition looks like -- and it fades with the rest.
+  ///
+  /// The geometry is the frame's own. The visible x range is mapped onto sample indices through
+  /// the series' own x (`Series::neighbours()`), never the `dx()` grid, and never the whole
+  /// series -- exactly as `Renderer::draw_traces()` maps it -- and the gathered points are taken
+  /// to pixels through the transforms the plot's last `layout()` pinned. So this belongs *after*
+  /// a layout: a plot that has never been laid out has no axes rect to size the grid to and
+  /// deposits nothing.
+  ///
+  /// The grid is sized to that axes rect, **the rect in device pixels up to `kDensityCellCap`
+  /// cells** (`DensityGrid`), and a grid of the wrong size is reallocated -- which drops what it
+  /// held, because the image is of the axes rect and a new rect is a new image. Under
+  /// `DensityDecay::PerAcquisition` the fade happens here, before the deposit, so the acquisition
+  /// just drawn is the brightest. A NaN sample is a gap: it deposits nothing and joins nothing,
+  /// the library-wide policy.
+  void accumulate_density();
+
+  /// Fades the grid by `dt_s` of **stream seconds** -- the clock the x axis reads, so a caller
+  /// advancing the display by its frame's own `dt` gets a fade that does not depend on the frame
+  /// rate. Only `DensityDecay::TimeConstant` fades here: `PerAcquisition`'s factor is applied by
+  /// `accumulate_density()`, because there is no acquisition in a frame that merely passed.
+  /// A non-positive `dt_s` and a non-positive `time_constant_s` are both no-ops, so a caller that
+  /// has not measured a frame yet cannot wipe the grid by accident.
+  void decay_density(f64 dt_s);
+
+  /// Empties the grid (and leaves the configuration alone). What a caller does when the data
+  /// under the image is replaced: the screen-relative image of another stream's sweeps says
+  /// nothing about this one.
+  void clear_density() noexcept;
+
   /// The measurement for `id`. Re-evaluated only when a cursor moved, when the
   /// measure was added, or when the series underneath it changed: a different
   /// series, a longer one, or a sliding window whose sample count stayed the same
@@ -702,6 +840,21 @@ class Plot {
   /// calls this when the pointer leaves the axes.
   void clear_crosshair() noexcept { crosshair_.active = false; }
 
+  /// The box-zoom frame the host is showing, in **viewport pixels**, or the zero rect for none.
+  ///
+  /// Set by the host from `input::Controller::selection_preview()` while a modified left drag is
+  /// choosing a range, and taken off when it ends. It is the *host's* job and not the plot's because
+  /// the plot has no controller and learns nothing about pointer, button or modifier (see
+  /// `plot::input`): this is the receiving end of that boundary, exactly as `set_hot_handles()` is.
+  /// Drawn as a frame -- a slightly opaque fill under a light border -- over everything else inside
+  /// the axes, so the area being framed stays legible against the traces it covers.
+  void set_selection_rect(Rect rect) noexcept { selection_ = rect; }
+  /// Takes the frame off, leaving the same state as before any drag: the next one starts from nothing.
+  void clear_selection_rect() noexcept { selection_ = Rect{}; }
+  /// The frame as set -- what `layout()` measures into `PlotLayout::selection`, and what a host or a
+  /// test reads back without paying a layout.
+  Rect selection_rect() const noexcept { return selection_; }
+
   /// Switches the readout panel off -- or back on -- without moving the crosshair: the lines and
   /// the per-trace markers stay, the panel is not measured and no row is listed. A host that wants
   /// the pointer's column marked but not a panel over its data sets this once; it is deliberately
@@ -852,6 +1005,30 @@ class Plot {
   /// region's pixel geometry is derived -- the controller hit-tests what this
   /// measured instead of mapping the bounds through the transform again.
   void build_regions();
+  /// Measures every invalid span into `layout_.invalid_spans`: its interval clipped to the axes'
+  /// columns, with a one-device-pixel floor, and the state that picks its tint. Here and not in
+  /// the renderer for `build_regions()`' reason -- one x mapping, the frame's own.
+  void build_invalid_spans();
+  /// Deposits one trace's visible window into its own density grid: the same index window
+  /// `Renderer::draw_traces()` maps -- `neighbours()` for the ends, the 64-spp gate for the LOD
+  /// level -- gathered into `density_points_`, mapped to pixels through the transforms of the
+  /// plot's last layout, and left with `deposit_density_segment()`. A trace with no series, no
+  /// visible window or non-positive `dx()` deposits nothing.
+  void deposit_density_trace(const Trace& trace, DensityGrid& grid);
+  /// Deposits one already-mapped segment of a trace polyline into `grid`: for every grid column
+  /// the segment crosses, the rows it covers in that column, +1 each. The columns it also *clips*:
+  /// a column whose slice of the segment lies entirely outside the axes is skipped, so a trace off
+  /// the top of the plot deposits nothing rather than a band along the edge, and a segment with
+  /// both ends past an edge keeps the part that is inside. A degenerate segment (`x0 == x1`, or a
+  /// non-finite coordinate) fills the single column it is in.
+  void deposit_density_segment(f32 x0, f32 y0, f32 x1, f32 y1, DensityGrid& grid) noexcept;
+  /// Grows `density_grids_` -- one grid per trace -- to the last layout's axes rect in device
+  /// pixels, clearing a grid when the size moved (a *different* screen is a different image), and
+  /// returns whether any grid is usable. The one place the grids are allocated.
+  bool size_density_grids();
+  /// The image an out-of-range trace reads (see `density_grid()`): a shared empty grid, so the
+  /// accessor need not hand back a reference into nothing.
+  static const DensityGrid& empty_density_grid() noexcept;
   /// Exact statistics of `region` over `series`, or an invalid result when the
   /// interval covers no sample. The one place the region arithmetic lives.
   static RegionStats evaluate_region_stats(const Region& region, const data::Series& series);
@@ -899,6 +1076,28 @@ class Plot {
   std::vector<MeasureSlot> measures_;
   std::vector<Annotation> annotations_;
   std::vector<Region> regions_;
+  std::vector<InvalidSpan> invalid_spans_;
+  /// The phosphor density: its configuration, the grids it accumulates into, and the scratch the
+  /// one visible window being deposited is gathered into. **One grid per trace** -- the image is of
+  /// the axes rect but each trace's is tinted with that trace's own colour (see `DensityConfig`), so
+  /// the memory is `traces * columns * rows * 4` bytes and not one plot's worth -- and each is
+  /// bounded by `kDensityCellCap`. The vector tracks `traces_` and outlives the frames its images
+  /// were drawn in, which is the whole point of accumulating into an image rather than retaining
+  /// traces.
+  DensityConfig density_{};
+  std::vector<DensityGrid> density_grids_;
+  /// Scratch for `deposit_density_trace()`: interleaved (x, y) of one gathered window, re-used
+  /// across traces and frames so a steady-state accumulation allocates nothing. Bounded by the
+  /// window, not the series, as `Renderer::gather_` is.
+  std::vector<f32> density_points_;
+  /// The per-sweep dedupe's stamps, one per grid **row** and shared by every trace's deposit: the
+  /// key of the last (trace, column) to deposit at that row, so one acquisition's own samples
+  /// cannot count a cell twice (see `deposit_density_segment()`). One `u64` a row -- a few kB at
+  /// any window -- and not one per cell, which would double a grid's memory for a comparison.
+  std::vector<u64> density_stamp_;
+  /// The sweep's own number, bumped once per trace deposited: the high half of every stamp key, so
+  /// every trace of a plot, and every acquisition, deposits exactly once per cell it covers.
+  u32 density_trace_ = 0;
   /// The (region, trace) statistics cache, filled on demand by `region_stats()`
   /// and so mutable: a lookup on a const Plot may cache, exactly as `measures_`
   /// does. Entries are created for the pairs a caller actually asks about, never
@@ -913,6 +1112,11 @@ class Plot {
   /// The crosshair's state (see Crosshair): at most one per plot, placed by
   /// `set_crosshair()` and read back by `crosshair()` and `layout()`.
   Crosshair crosshair_{};
+
+  /// The host's box-zoom frame (`set_selection_rect()`): viewport pixels, the zero rect when no
+  /// modified drag is choosing a range. State rather than a `PlotLayout` field alone because a host
+  /// sets it on every drag motion and reads it back; `layout()` only carries it through.
+  Rect selection_{};
   /// The samples `crosshair_value()` reads a span through: `Series::gather()` appends
   /// `(x, y)` pairs and never clears, so the lookup clears this and refills it with the at
   /// most two samples a span covers. Sized to hold them from construction -- four floats is

include/plot/render/program.hpp

@@ -84,4 +84,37 @@ class TextProgram {
   gl::Program program_;
 };
 
+/// Linked phosphor-density program and its uniform surface: one textured quad over a plot's
+/// axes rect. It fails exactly the way the two above do, propagating `Unsupported` and
+/// `GLFailure`.
+///
+/// It is the one pipeline with **no vertex data**: the quad's four corners come from
+/// `gl_VertexID`, so a draw is one four-vertex strip whatever the grid's size and there is no
+/// buffer to stage or upload. The density itself reaches the GPU as a texture -- one texel per
+/// cell -- which is the one thing this pipeline has that the others do not.
+///
+/// `create()` also points the `u_density` sampler at texture unit 0, which is the unit
+/// `plot::gl::Texture::bind()` defaults to, and leaves this program bound. The texture stays
+/// with the caller, who owns its lifetime.
+class DensityProgram {
+ public:
+  bool create(Status* st = nullptr) noexcept;
+  bool valid() const noexcept { return program_.id() != 0; }
+  void bind() const noexcept { program_.use(); }
+
+  /// `u_viewport`: render target size in pixels.
+  void set_viewport(Vec2 px) const noexcept;
+  /// `u_origin` and `u_size`: the quad in `Rect` pixels -- the axes rect's top-left corner and its
+  /// size, which is the area the image is drawn over (its own grid may hold fewer cells than the
+  /// rect has pixels: see `kDensityCellCap`). They are two uniforms rather than a rect because a
+  /// `vec4` uniform would need a fourth setter shape for one caller; a corner and a size are what
+  /// the vertex shader builds the quad from anyway.
+  void set_rect(Vec2 origin, Vec2 size) const noexcept;
+  /// `u_color`: the tint the cells' luminances are multiplied into.
+  void set_color(Color color) const noexcept;
+
+ private:
+  gl::Program program_;
+};
+
 }  // namespace plot::render

include/plot/render/renderer.hpp

@@ -38,10 +38,28 @@ struct FrameStats {
   /// (`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
   u32 draw_calls = 0;        ///< draw calls issued, line and text
+  /// The phosphor density's own cells, when one was drawn: the **sum** of every trace's
+  /// `Plot::density_grid()` resolution, zero for a plot with the density off. It is what the
+  /// *frame* drew, so a host reading the density's cost off a frame reads it here rather than off
+  /// the grids, which say what is accumulated and not what was spent -- and it is the number that
+  /// scales with the trace count, since the image is one grid per trace (see `DensityConfig`).
+  u32 density_cells = 0;
+  /// The bytes of that image the frame **uploaded**: `columns * rows` when the grid had changed
+  /// since the last frame and 0 when it had not. It is the one field that separates the two
+  /// costs of a density -- the conversion and upload on the frame that moved, the single draw
+  /// call on the frames that did not -- which is exactly the pair a host comparing frame times
+  /// with the display on and off needs to tell apart.
+  u32 density_upload_bytes = 0;
 };
 
 /// Draws a `Plot` into whatever framebuffer is bound.
@@ -87,8 +105,8 @@ class Renderer {
   Renderer(const Renderer&) = delete;
   Renderer& operator=(const Renderer&) = delete;
 
-  /// Destroys every GL object this renderer created: both programs, both vertex
-  /// arrays and their instance buffers, and the glyph atlas texture. The
+  /// Destroys every GL object this renderer created: all three programs, the vertex arrays and
+  /// their instance buffers, the glyph atlas texture and the density's own texture. The
   /// renderer is left uninitialised (`ready() == false`) and `init()` can be
   /// called again on the same object.
   ///
@@ -507,6 +525,34 @@ class Renderer {
   void draw_plot(Plot& plot, const PlotLayout& layout);
 
   void draw_grid(const Plot& plot);
+  /// The plot's **phosphor density** (`Plot::set_density()`), when one is on: one textured quad per
+  /// trace over the axes rect, each in **that trace's own colour** -- a saturated cell is the trace
+  /// at its own brightness -- drawn over the grid and the invalid-span bands. The traces themselves
+  /// are not drawn while it is on (`draw_traces()` returns), so this is the whole of the data ink
+  /// and the newest acquisition is inside it.
+  ///
+  /// Each trace's image reaches the GPU as an `GL_R8` texture, one texel per cell, converted here
+  /// from the grid's counts -- the scale and the gamma are the plot's and this stage derives
+  /// neither, so the numbers a host reads back and the picture it sees are one derivation. The
+  /// texture is magnified over the axes rect with a linear filter, because past `kDensityCellCap` a
+  /// cell is several device pixels across. A frame whose grids did not change skips the conversion
+  /// *and* the uploads and costs the draw calls, which `FrameStats::density_upload_bytes` says per
+  /// frame.
+  void draw_density(const Plot& plot, const PlotLayout& layout);
+  /// One grid's quad: fills the shared `GL_R8` texture from `grid` (skipping when its revision and
+  /// address are the ones already uploaded) and draws it over the axes rect in `tint` -- the rect,
+  /// and not the grid's own cell count, so a capped grid is scaled back over the area it is an
+  /// image of. The one place the density conversion lives, shared by every trace of
+  /// `draw_density()`.
+  void draw_density_grid(const DensityConfig& config, const DensityGrid& grid, Color tint,
+                         const PlotLayout& layout);
+  /// `Plot::invalid_spans()`, as `PlotLayout::invalid_spans` measured them: one fill per span,
+  /// in `style_.invalid_fill` or — for a span the host has marked repaired —
+  /// `style_.invalid_repaired_fill`. Over the grid and under everything else inside the axes, so
+  /// a hole reads as a property of the plot's background -- the grid shows through it and a trace
+  /// that does have data in those columns is drawn on top, which is what distinguishes a reserved
+  /// hole from a trace that has gone quiet.
+  void draw_invalid_spans(const PlotLayout& layout);
   void draw_axis_lines(const Plot& plot);
   /// The chrome helpers take the frame's layout: `Plot::layout()` recomputes the
   /// ticks, the strips and the grid, so it is computed once, in `draw()`, and handed
@@ -539,6 +585,30 @@ class Renderer {
   /// 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
@@ -617,6 +687,11 @@ class Renderer {
   /// pointer is on: a readout the legend covered would be the feature failing at its one job.
   void draw_crosshair_readout(const Plot& plot, const PlotLayout& layout);
 
+  /// The host's box-zoom frame (`PlotLayout::selection`): a fill at `selection_fill` under a border at
+  /// `selection_edge`, or nothing at all when nothing was swept. Drawn last of the interior passes, so
+  /// the area being framed is legible over the traces, the regions and the readout alike.
+  void draw_selection_frame(const PlotLayout& layout);
+
   /// One marker shape (`Marker`) at a viewport-pixel centre: `Cross` two
   /// segments, `Circle` an 8-gon, `Square` four. Staged into the line batch in
   /// pixel space, at `size_px` half-extent, so a marker's size is device pixels
@@ -637,6 +712,27 @@ class Renderer {
   render::TextAtlas atlas_;
   render::LineProgram line_program_;
   render::TextProgram text_program_;
+  /// The phosphor density's pipeline, its one attribute-less vertex array and the texture a grid is
+  /// uploaded into. The texture is `GL_R8`, one texel per cell of the plot's grid, and is re-filled
+  /// for each trace in turn -- a trace's grid is drawn before the next trace's replaces it -- so a
+  /// row of several traces still costs the one texture. It is re-created when the grid's size moves
+  /// (a resized plot is a differently sized image, and the plot has already dropped what the old one
+  /// held).
+  render::DensityProgram density_program_;
+  gl::VertexArray density_vao_;
+  gl::Texture density_texture_;
+  /// The luminance image as uploaded, re-used across frames so a steady-state frame reallocates
+  /// nothing: one byte per cell.
+  std::vector<u8> density_pixels_;
+  u32 density_w_ = 0;
+  u32 density_h_ = 0;
+  /// The grid the texture currently holds, by address, and its revision. Compared per frame and per
+  /// trace, so a frame whose grids did not move skips the conversion *and* the upload -- the pause
+  /// in a persistence display. The address is part of the key because the texture is shared: two
+  /// traces of one plot have two grids with two revisions, and without the address a skip would
+  /// draw one trace's image under another's colour.
+  const DensityGrid* density_uploaded_grid_ = nullptr;
+  u64 density_uploaded_revision_ = 0;
   render::LineVertexArray line_vao_;
   render::TextVertexArray text_vao_;
 

include/plot/render/shaders.hpp

@@ -68,4 +68,26 @@ extern const char* const kLineFS;
 extern const char* const kTextVS;
 extern const char* const kTextFS;
 
+/// GLSL source of the phosphor-density pipeline: one textured quad over the axes rect.
+///
+/// The vertex shader builds the quad from `gl_VertexID` -- a four-vertex `GL_TRIANGLE_STRIP`
+/// like the other two pipelines, and the only one with **no vertex attributes at all**: the
+/// image is one rectangle whose corners are uniform state, so there is no geometry to stage and
+/// nothing to upload (the density's own bytes go to a texture, not to a buffer).
+///
+/// Uniforms: `u_viewport` (vec2, pixels), `u_origin` (vec2, the quad's top-left corner in `Rect`
+/// pixels), `u_size` (vec2, its size in pixels -- the axes rect the image is drawn over, which the
+/// texture's cells are spread across: one texel a cell while the rect is under `kDensityCellCap`,
+/// and a filtered magnification past it), `u_color` (vec4), `u_density` (sampler2D, unit 0).
+///
+/// The fragment shader multiplies the sampled single-channel image into `u_color`'s alpha, which
+/// is the whole of the brightness mapping: a cell's count was turned into a luminance byte on the
+/// CPU (`Plot`), where the count, the decay and the gamma live, so this stage has no scale of its
+/// own to get out of step with the numbers a host reads back.
+///
+/// `Rect` is top-left origin while GL is bottom-left, so the y axis is flipped exactly once,
+/// here, as in the line pipeline.
+extern const char* const kDensityVS;
+extern const char* const kDensityFS;
+
 }  // namespace plot::render

include/plot/render/style.hpp

@@ -55,6 +55,28 @@ struct Style {
   Color axis_text = Color::hex(0xC8D0DC);
   Color cursor = Color::hex(0xFFB020);
   Color measure_fill = Color::hex(0xFFB020, 0.15f);
+  /// The box-zoom selection's frame, drawn while a modified left drag is choosing a range: a light
+  /// neutral near full alpha for the border and the same neutral at a low one for the fill. Neutral
+  /// and not a trace colour, on `invalid_fill`'s argument -- the frame says "this is the area", and a
+  /// tint a trace could have would read as data. The fill's alpha is chosen against the same floor:
+  /// low enough that what is under the frame stays readable, because the point is to show what is
+  /// being selected, not to hide it.
+  Color selection_fill = Color::hex(0xC8D0DC, 0.12f);
+  Color selection_edge = Color::hex(0xC8D0DC, 0.85f);
+  /// The shading over a span the host has declared invalid (`Plot::set_invalid_spans()`): the
+  /// axis furniture's own neutral grey at a low alpha, on the same model as `measure_fill`
+  /// above. Neutral and not a trace colour on purpose -- a band is the *absence* of data, and
+  /// one in a hue a trace could have would read as a signal rather than as a gap. The alpha is
+  /// low enough that the grid under it stays legible, which is what makes the band read as a
+  /// region of the plot rather than as a panel laid over it.
+  Color invalid_fill = Color::hex(0x8A94A6, 0.18f);
+  /// The same shading for a span whose samples have since arrived and been written in, at well
+  /// under half the alpha. The gap is still reported -- the window was drawn without that data --
+  /// but a reader can tell a hole that is still empty from one that has been filled. Fainter by
+  /// alpha alone and not by hue, so the two read as two depths of one mark rather than as two
+  /// different kinds of thing; and still above the threshold where the difference from *no* band
+  /// is visible, which is the floor this alpha is chosen against.
+  Color invalid_repaired_fill = Color::hex(0x8A94A6, 0.08f);
   /// The crosshair's colour: its two lines and the readout panel's border (spec §15). Markers are
   /// deliberately *not* this colour -- they carry each trace's own, because a marker says *which*
   /// trace and the line says *where*.
@@ -202,6 +224,14 @@ struct Style {
   /// 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

src/data/minmax_pyramid.cpp

@@ -179,6 +179,43 @@ void MinMaxPyramid::append(f32 v) {
   }
 }
 
+void MinMaxPyramid::amend(u64 absolute_sample, f32 v) {
+  if (!std::isfinite(v)) return;
+  if (absolute_sample < base_ || absolute_sample >= count_) return;
+
+  const f64 vd = f64(v);
+  const auto fold = [&](Entry& e) {
+    // An empty bucket's `mm` is meaningless (see the Entry note), so the first finite
+    // sample *sets* the extremes instead of widening from a zero that was never a sample.
+    if (e.count == 0) {
+      e.mm.min = v;
+      e.mm.max = v;
+    } else {
+      e.mm.min = std::min(e.mm.min, v);
+      e.mm.max = std::max(e.mm.max, v);
+    }
+    e.sum += vd;
+    e.sumsq += vd * vd;
+    ++e.count;
+  };
+
+  // The in-progress level-0 bucket, when the index lies inside it. It is not an entry yet,
+  // so the loop below cannot reach it; leaving it out would lose the amendment for a hole
+  // whose tail is still filling, which is exactly the hole a prompt backfill arrives into.
+  if (count_ % kBucket != 0 && absolute_sample >= (count_ / kBucket) * kBucket) {
+    fold(pending_);
+  }
+
+  // Every level independently: min/max/sum/sumsq/count are each associative, so folding the
+  // value into a parent gives the same aggregate as re-merging its children would.
+  for (u32 l = 0; l < static_cast<u32>(levels_.size()); ++l) {
+    const u64 i = absolute_sample / level_span(l);
+    if (i < levels_[l].base) continue;
+    if (i - levels_[l].base >= static_cast<u64>(levels_[l].entries.size())) continue;
+    fold(levels_[l].entries[static_cast<usize>(i - levels_[l].base)]);
+  }
+}
+
 void MinMaxPyramid::drop_before(u64 absolute_sample) {
   if (absolute_sample <= base_) return;
   if (absolute_sample > count_) {

src/input/controller.cpp

@@ -751,6 +751,31 @@ void Controller::pan(const PointerEvent& e) {
   }
 }
 
+Rect Controller::selection_preview() const noexcept {
+  // Nothing to preview off a box zoom: the mask bits outlive the gesture -- `end_drag()` clears the
+  // selection, not them -- so widening without this guard would hand out a full-band rect for a drag
+  // that finished minutes ago.
+  if (mode_ != DragMode::BoxZoom) return Rect{};
+  // And nothing has been framed until the drag has swept every axis the release will apply: at the
+  // press instant the selection is an empty rect at the pointer, and the *widened* form of that is a
+  // band the width of the plot, which is a claim about a range that does not exist yet. Ctrl's other
+  // axis is deliberately not required: a drag with no vertical movement at all is a band across the
+  // plot, which is exactly what Ctrl is for.
+  if ((box_zoom_x_ && !(selection_.w > 0.0f)) || (box_zoom_y_ && !(selection_.h > 0.0f))) return Rect{};
+  Rect preview = selection_;
+  if (box_zoom_x_ && box_zoom_y_) return preview;
+  const Rect& axes = plot_->layout().axes;
+  if (!box_zoom_x_) {
+    preview.x = axes.x;
+    preview.w = axes.w;
+  }
+  if (!box_zoom_y_) {
+    preview.y = axes.y;
+    preview.h = axes.h;
+  }
+  return preview;
+}
+
 void Controller::box_zoom_update(const PointerEvent& e) {
   const f32 x = std::min(origin_x_, e.x);
   const f32 y = std::min(origin_y_, e.y);

src/plot/plot.cpp

@@ -344,6 +344,311 @@ void Plot::set_y_axis_origin_from_range(u32 axis, bool on) {
 
 void Plot::set_x_note(std::string text) { x_note_ = std::move(text); }
 
+void Plot::set_invalid_spans(std::span<const InvalidSpan> spans) {
+  invalid_spans_.assign(spans.begin(), spans.end());
+}
+
+// --- phosphor density ---------------------------------------------------------
+
+void Plot::set_density(const DensityConfig& config) {
+  // Disabling is a caller asking to stop paying for the display, and a trigger that has stopped
+  // firing never reaches another accumulation -- so the image goes now rather than at an event
+  // that may not come. The same rule, for the same reason, as the app's `set_persist_depth()`.
+  if (density_.enabled && !config.enabled) {
+    for (DensityGrid& grid : density_grids_) {
+      grid.cells_.clear();
+      grid.cells_.shrink_to_fit();
+      grid.columns_ = 0u;
+      grid.rows_ = 0u;
+      ++grid.revision_;
+    }
+    density_grids_.clear();
+    density_grids_.shrink_to_fit();
+  }
+  // The two fields the renderer turns a cell's count into a luminance with: a change to either is
+  // a change to every cell's *byte*, and a grid's own revision does not see it. A host that states
+  // its configuration every frame (udpscope does) must not force a re-upload per frame, so this
+  // bumps only when one of the two actually moved -- and then a re-upload is owed.
+  const bool rescale = density_.enabled && config.enabled &&
+                       (density_.full_scale != config.full_scale || density_.gamma != config.gamma);
+  density_ = config;
+  if (rescale) {
+    for (DensityGrid& grid : density_grids_) ++grid.revision_;
+  }
+}
+
+void Plot::decay_density(f64 dt_s) {
+  if (!density_.enabled || density_.decay != DensityDecay::TimeConstant) return;
+  // A non-positive frame and a non-positive time constant are both "do not fade": the first is a
+  // caller that has not measured a frame yet, and the second is a caller asking for a grid that
+  // is drawn and never fades.
+  if (!(dt_s > 0.0) || !(density_.time_constant_s > 0.0f)) return;
+  const f32 factor =
+      static_cast<f32>(std::exp(-dt_s / static_cast<f64>(density_.time_constant_s)));
+  if (!(factor < 1.0f)) return;
+  for (DensityGrid& grid : density_grids_) {
+    if (grid.cells_.empty()) continue;
+    for (f32& cell : grid.cells_) cell *= factor;
+    ++grid.revision_;
+  }
+}
+
+void Plot::clear_density() noexcept {
+  for (DensityGrid& grid : density_grids_) {
+    if (grid.cells_.empty()) continue;
+    std::fill(grid.cells_.begin(), grid.cells_.end(), 0.0f);
+    ++grid.revision_;
+  }
+}
+
+bool Plot::size_density_grids() {
+  const Rect& axes = layout_.axes;
+  if (!(axes.w >= 1.0f) || !(axes.h >= 1.0f)) return false;
+  u32 columns = static_cast<u32>(std::ceil(axes.w));
+  u32 rows = static_cast<u32>(std::ceil(axes.h));
+  if (columns == 0u || rows == 0u) return false;
+  // **The grid is the axes rect in device pixels, up to `kDensityCellCap`.** Beyond it the rect is
+  // scaled down *uniformly*, so the cells stay square in device pixels and the picture keeps the
+  // axes' aspect: a cap on one axis alone would stretch a cell, and a density smeared in one
+  // direction only reads as a bug in the data rather than as a coarse image. The cells are then no
+  // longer one device pixel across, which is why the renderer magnifies the image with a linear
+  // filter instead of a point sample -- see `Renderer::draw_density_grid()`.
+  //
+  // The floor of the product is what makes the cap hold: `floor(w*s) * floor(h*s) <= w*s * h*s
+  // <= cap` for the `s` chosen, and the two `max(1, ...)` keep a very thin axes rect from
+  // rounding to nothing.
+  const u64 pixels = static_cast<u64>(columns) * static_cast<u64>(rows);
+  if (pixels > static_cast<u64>(kDensityCellCap)) {
+    const f64 scale = std::sqrt(static_cast<f64>(kDensityCellCap) / static_cast<f64>(pixels));
+    columns = std::max(1u, static_cast<u32>(static_cast<f64>(columns) * scale));
+    rows = std::max(1u, static_cast<u32>(static_cast<f64>(rows) * scale));
+  }
+  // **One grid per trace**, because a density is drawn in the colour of the trace that laid it
+  // down (see `DensityConfig`). The vector tracks the trace list, so a trace added after the first
+  // accumulation gets its own empty grid here while the grids already sized keep what they held.
+  if (density_grids_.size() != traces_.size()) density_grids_.resize(traces_.size());
+  // The per-sweep dedupe's stamps are one per grid **row** and shared by every trace's deposit:
+  // the key a cell is deduped against carries the trace's number (see
+  // `deposit_density_segment()`), so a stamp left by one trace's sweep never matches another's, and
+  // a zeroed stamp -- every key has a non-zero trace number in its high half -- matches nothing.
+  if (density_stamp_.size() != rows) density_stamp_.assign(rows, 0u);
+  bool usable = false;
+  for (usize i = 0u; i < traces_.size(); ++i) {
+    DensityGrid& grid = density_grids_[i];
+    if (!traces_[i].visible()) {
+      // A trace with nothing to draw gets no image: the grid is per *trace*, and a slot with no
+      // series is not one. Dropping it here is also what keeps the display's memory proportional
+      // to the traces actually on screen rather than to a plot's fixed trace slots -- a row of four
+      // signals out of eight slots holds four grids, not eight.
+      if (!grid.cells_.empty()) {
+        grid.cells_.clear();
+        grid.cells_.shrink_to_fit();
+        grid.columns_ = 0u;
+        grid.rows_ = 0u;
+        ++grid.revision_;
+      }
+      continue;
+    }
+    if (columns != grid.columns_ || rows != grid.rows_) {
+      // A grid of another size is another image, and there is nothing honest to carry over from
+      // one to the other: the cells are device pixels, so a resize moves every one of them. Drop
+      // what it held rather than resample it -- the display restarts, which is what a scope does
+      // when its screen changes.
+      grid.cells_.assign(static_cast<usize>(columns) * rows, 0.0f);
+      grid.columns_ = columns;
+      grid.rows_ = rows;
+      ++grid.revision_;
+    }
+    usable = usable || !grid.cells_.empty();
+  }
+  return usable;
+}
+
+void Plot::accumulate_density() {
+  if (!density_.enabled) return;
+  if (!size_density_grids()) return;
+  // The fade before the deposit, never after: under `PerAcquisition` the acquisition just drawn
+  // is the brightest one and each older one is the factor down, which is what "the N-th back is
+  // gone" means. TimeConstant fades in `decay_density()` instead, because its fade is the clock's
+  // and not the acquisition's.
+  if (density_.decay == DensityDecay::PerAcquisition) {
+    const f32 factor = std::clamp(density_.per_acquisition, 0.0f, 1.0f);
+    for (DensityGrid& grid : density_grids_) {
+      if (grid.cells_.empty()) continue;
+      for (f32& cell : grid.cells_) cell *= factor;
+      ++grid.revision_;
+    }
+  }
+  // **Every visible trace of the acquisition on screen, the newest included.** The current
+  // acquisition is deposited here like any other, so it is inside the image and fades with it --
+  // there is no second, solid trace drawn over the density (see `Renderer::draw_traces()`), which
+  // is what a report of "the last acquisition never fades" turned out to be. One grid each, so two
+  // traces that agree read as two colours at full strength where they overlap and not as one
+  // blended one.
+  const usize n = std::min(density_grids_.size(), traces_.size());
+  for (usize i = 0u; i < n; ++i) deposit_density_trace(traces_[i], density_grids_[i]);
+}
+
+void Plot::deposit_density_trace(const Trace& trace, DensityGrid& grid) {
+  if (!trace.visible()) return;
+  const data::Series& series = *trace.series;
+  const u64 n = series.size();
+  if (!(series.dx() > 0.0) || n == 0u) return;
+
+  // The same index window `Renderer::draw_traces()` maps, by the same calls: `neighbours()` on
+  // the series' own stamps -- never the `(x - x0()) / dx()` grid, which is a nominal spacing and
+  // would lose the segments entering and leaving the frame -- with one sample of slack on each
+  // side and clamped to the series.
+  const Range window = x_range(trace.axis_x);
+  u64 first = 0u;
+  u64 last = n;
+  u64 i0 = 0u;
+  u64 i1 = 0u;
+  if (series.neighbours(window.min, i0, i1)) first = i0 > 0u ? i0 - 1u : 0u;
+  if (series.neighbours(window.max, i0, i1)) last = std::min(n, i1 + 1u);
+  if (last <= first) return;
+
+  // The same level gate the renderer uses, and for the same reason: a window denser than the
+  // pixel grid is a *reduction*, and the density is a reduction of it too -- one pass per cell
+  // the column's own envelope crosses. The levels agree because the ask is the same ask.
+  const f64 samples_per_pixel =
+      static_cast<f64>(last - first) / static_cast<f64>(layout_.axes.w);
+  const u32 level = samples_per_pixel >= static_cast<f64>(style_.dense_threshold_spp)
+                        ? series.pyramid().level_for(n, samples_per_pixel)
+                        : 0u;
+
+  density_points_.clear();
+  series.gather(level, first, last, window.min, density_points_, trace.mode);
+  if (density_points_.size() < 2u) return;
+
+  // A fresh stamp for this trace's part of this acquisition: the key a cell is deduped against is
+  // `(this, column)`, so every trace of a plot deposits once per cell it covers even where they
+  // overlap, and a cell one trace crosses twice in one sweep deposits once.
+  ++density_trace_;
+  const Transform tx = x_transform(trace.axis_x);
+  const Transform ty = y_transform(trace.axis_y);
+  f32 px = 0.0f;
+  f32 py = 0.0f;
+  u32 run = 0u;  // points in the current unbroken run
+  // A run's *first* point is not deposited on its own: the segment that leaves it already puts
+  // ink in that cell, and depositing both would count the pen's arrival twice -- a single pass
+  // would read as two in the cell every trace starts in, which is exactly the cell a peak
+  // reading is taken from. A run of one point -- a lone visible sample, or one isolated by a
+  // gap -- is deposited as a degenerate segment instead, because a place a trace *was* is ink
+  // however short its stay.
+  const auto flush_run = [&]() {
+    if (run == 1u) deposit_density_segment(px, py, px, py, grid);
+  };
+  for (usize k = 0; k + 1u < density_points_.size(); k += 2u) {
+    // x is gathered relative to the visible range's minimum (see `Series::gather()`), so the
+    // absolute x is reconstructed in f64 before it is mapped -- the same reconstruction, and the
+    // same reason, as the staging paths.
+    const f64 x_abs = window.min + static_cast<f64>(density_points_[k]);
+    const f64 y_abs = static_cast<f64>(density_points_[k + 1u]);
+    if (!std::isfinite(x_abs) || !std::isfinite(y_abs)) {
+      flush_run();  // a NaN is a gap: it joins nothing, so the trace is deposited in pieces
+      run = 0u;
+      continue;
+    }
+    const f32 sx = static_cast<f32>(tx.to_screen_x(x_abs));
+    const f32 sy = static_cast<f32>(ty.to_screen_y(y_abs));
+    if (!std::isfinite(sx) || !std::isfinite(sy)) {
+      flush_run();
+      run = 0u;
+      continue;
+    }
+    if (run > 0u) deposit_density_segment(px, py, sx, sy, grid);
+    px = sx;
+    py = sy;
+    ++run;
+  }
+  flush_run();
+  ++grid.revision_;
+}
+
+void Plot::deposit_density_segment(f32 x0, f32 y0, f32 x1, f32 y1, DensityGrid& grid) noexcept {
+  const u32 columns = grid.columns_;
+  const u32 rows = grid.rows_;
+  if (columns == 0u || rows == 0u) return;
+  if (density_stamp_.size() < rows) return;  // sized with the grid; nothing deposits before that
+  if (!std::isfinite(x0) || !std::isfinite(y0) || !std::isfinite(x1) || !std::isfinite(y1)) return;
+  const Rect& axes = layout_.axes;
+  // **The image's footprint is the axes rect rounded up to whole device pixels** -- the rect
+  // `size_density_grids()` counted the cells on -- so `sx`/`sy` are exactly **1** while that rect is
+  // under `kDensityCellCap`: a cell *is* a device pixel and this is the arithmetic the density has
+  // always used. Past the cap they are a fraction of one, and the cell index is read through the
+  // scale rather than straight off the pixel. (The rounding is why the footprint, not the
+  // fractional rect, is the reference: a cell is defined on whole pixels, and a grid of `ceil(w)` of
+  // them covers the rect the axes was laid out with.)
+  const f32 sx = axes.w > 0.0f ? static_cast<f32>(columns) / std::ceil(axes.w) : 1.0f;
+  const f32 sy = axes.h > 0.0f ? static_cast<f32>(rows) / std::ceil(axes.h) : 1.0f;
+  const f32 lo_x = std::min(x0, x1);
+  const f32 hi_x = std::max(x0, x1);
+  i32 c0 = static_cast<i32>(std::floor((lo_x - axes.x) * sx));
+  i32 c1 = static_cast<i32>(std::floor((hi_x - axes.x) * sx));
+  // Clipped to the axes' columns *and* to the grid: a segment reaching past the right edge keeps
+  // the part that is inside, and one entirely outside deposits nothing at all. The clamp is what
+  // keeps ink off the edge column when a trace leaves the frame sideways.
+  c0 = std::max(c0, 0);
+  c1 = std::min(c1, static_cast<i32>(columns) - 1);
+  if (c1 < c0) return;
+
+  const f32 span = hi_x - lo_x;
+  const f32 denom = x1 - x0;
+  const i32 last_row = static_cast<i32>(rows) - 1;
+  // The segment's y span inside one column's own slice of x: the two ends of the slice taken
+  // along the segment. Every column's span meets its neighbour's end exactly (the y is linear in
+  // x), so the deposit is a continuous trace and not a dotted one.
+  const auto column_y_span = [&](i32 column, f32& out_lo, f32& out_hi) {
+    const f32 ca = axes.x + static_cast<f32>(column) / sx;
+    f32 ya = y0;
+    f32 yb = y1;
+    if (span > 0.0f && denom != 0.0f) {
+      const f32 a = std::max(ca, lo_x);
+      const f32 b = std::min(ca + 1.0f / sx, hi_x);
+      ya = y0 + (a - x0) / denom * (y1 - y0);
+      yb = y0 + (b - x0) / denom * (y1 - y0);
+    }
+    out_lo = std::min(ya, yb);
+    out_hi = std::max(ya, yb);
+  };
+  for (i32 c = c0; c <= c1; ++c) {
+    f32 y_lo = 0.0f;
+    f32 y_hi = 0.0f;
+    column_y_span(c, y_lo, y_hi);
+    // A column whose slice of the segment lies wholly outside the axes deposits nothing: without
+    // this, a trace above the top of the plot would paint a band along the top row, which is the
+    // one thing a density must not do -- it would say the trace was there.
+    if (!(y_hi >= axes.y) || !(y_lo <= axes.bottom())) continue;
+    const f32 top = std::max(y_lo, axes.y);
+    // One ULP inside the bottom edge, so a segment ending exactly on it lands in the last row
+    // rather than one past the end.
+    const f32 bottom = std::min(y_hi, std::nextafter(axes.bottom(), axes.y));
+    i32 r0 = std::clamp(static_cast<i32>(std::floor((top - axes.y) * sy)), 0, last_row);
+    i32 r1 = std::clamp(static_cast<i32>(std::floor((bottom - axes.y) * sy)), 0, last_row);
+    // **One pass per cell per sweep, not per hit.** A column of a dense window is crossed hundreds
+    // of times by one acquisition's own samples, and counting each crossing would put a single
+    // sweep at the ceiling of the brightness scale: the newer sweeps behind it would be invisible,
+    // and a cell's value would mean "how much the beam moved here" instead of "how many
+    // acquisitions were here" -- which is what a persistence display is. The stamp is per
+    // *(trace, column)*, so two sweeps that agree on a cell still count twice, and the two segments
+    // that share a column's boundary do not.
+    const u64 key = (static_cast<u64>(density_trace_) << 32) | static_cast<u64>(static_cast<u32>(c));
+    f32* column_cells = grid.cells_.data() + static_cast<usize>(c);
+    for (i32 r = r0; r <= r1; ++r) {
+      const usize row = static_cast<usize>(r);
+      if (density_stamp_[row] == key) continue;  // this sweep has already put its ink here
+      density_stamp_[row] = key;
+      column_cells[row * static_cast<usize>(columns)] += 1.0f;
+    }
+  }
+}
+
+const DensityGrid& Plot::empty_density_grid() noexcept {
+  static const DensityGrid empty{};
+  return empty;
+}
+
 f64 Plot::x_axis_origin(u32 axis) const {
   return axis < x_axes_.size() ? x_axes_[axis].origin : 0.0;
 }
@@ -1091,11 +1396,16 @@ const PlotLayout& Plot::layout() {
   // measured from the *placed* live windows, which is what makes a region's data
   // interval map to the pixel columns the frame will actually use.
   build_regions();
+  build_invalid_spans();
   build_legend();
   // The crosshair last: its panel is fitted into `axes` and its lines are held inside it, and
   // its rows are the sample values nearest a data x -- so it wants the transforms the
   // settled layout pins, exactly as the legend and the regions do.
   build_crosshair();
+  // The box-zoom frame is not measured, only carried: the host already has it in viewport pixels from
+  // the controller that produced it, and re-deriving it here would be a second rounding of the same
+  // rectangle -- and a second place for it to disagree with what the gesture is doing.
+  layout_.selection = selection_;
   return layout_;
 }
 
@@ -1358,6 +1668,41 @@ void Plot::build_regions() {
   }
 }
 
+void Plot::build_invalid_spans() {
+  layout_.invalid_spans.clear();
+  if (invalid_spans_.empty()) return;
+
+  const Rect& axes = layout_.axes;
+  // The primary x axis' transform, taken here for `build_regions()`' reason: after the live
+  // windows have been placed and the strips have settled, so these are the columns the frame
+  // draws with and a band is anchored to the data by construction rather than by a second
+  // mapping that would have to be kept in step with this one.
+  const Transform tx = x_transform(0u);
+  // A hole can be narrower than a column -- one missing sample in a window of hundreds of
+  // thousands -- and a fill rounded to zero width would draw nothing, losing exactly the case
+  // the band is most needed for. One device pixel is the floor.
+  const f32 min_w = std::max(1.0f, style_.device(1.0f));
+
+  for (const InvalidSpan& span : invalid_spans_) {
+    const f64 a = std::min(span.x0, span.x1);
+    const f64 b = std::max(span.x0, span.x1);
+    if (!std::isfinite(a) || !std::isfinite(b)) continue;
+    const f32 lo = static_cast<f32>(tx.to_screen_x(a));
+    const f32 hi = static_cast<f32>(tx.to_screen_x(b));
+    // Scrolled out of the window: nothing to shade. Tested before the floor is applied, so a
+    // span off the left edge is dropped rather than pinned to it as a one-pixel band that
+    // accuses the samples at the window's start.
+    if (hi < axes.x || lo > axes.right()) continue;
+    const f32 first = std::clamp(lo, axes.x, axes.right());
+    const f32 last = std::clamp(hi, axes.x, axes.right());
+    const f32 w = std::min(std::max(last - first, min_w), axes.w);
+    // Widening a band at the right edge would run it over the axis line, so the floor is taken
+    // out of the left instead: the span's own edge is kept wherever there is room for it.
+    const f32 x = std::clamp(first, axes.x, axes.right() - w);
+    layout_.invalid_spans.push_back(InvalidSpanLayout{Rect{x, axes.y, w, axes.h}, span.repaired});
+  }
+}
+
 // --- crosshair (spec §15) --------------------------------------------------
 
 CrosshairSpan crosshair_span(const data::Series& series, f64 x) noexcept {

src/render/program.cpp

@@ -60,4 +60,27 @@ void TextProgram::set_texture_size(Vec2 texels) const noexcept {
   program_.set_uniform("u_tex_size", texels);
 }
 
+bool DensityProgram::create(Status* st) noexcept {
+  program_ = gl::Program::from_source(kDensityVS, kDensityFS, st);
+  if (program_.id() == 0) {
+    return false;
+  }
+  // The grid texture is bound to texture unit 0 by plot::gl::Texture::bind(), so the sampler
+  // has to point there. Set once, here, not per frame -- the same shape as the text program's.
+  program_.use();
+  program_.set_uniform_int("u_density", 0);
+  return true;
+}
+
+void DensityProgram::set_viewport(Vec2 px) const noexcept { program_.set_uniform("u_viewport", px); }
+
+void DensityProgram::set_rect(Vec2 origin, Vec2 size) const noexcept {
+  program_.set_uniform("u_origin", origin);
+  program_.set_uniform("u_size", size);
+}
+
+void DensityProgram::set_color(Color color) const noexcept {
+  program_.set_uniform("u_color", color);
+}
+
 }  // namespace plot::render

src/render/renderer.cpp

@@ -193,14 +193,23 @@ Renderer::~Renderer() {
 void Renderer::release_gl() noexcept {
   ready_ = false;
   // Assigning fresh objects releases every GL name through the handles'
-  // destructors: both programs, both vertex arrays and their instance buffers,
-  // and the atlas texture. Safe to call more than once; every assignment is a
-  // no-op while the renderer is uninitialised.
+  // destructors: all three programs, the vertex arrays and their instance
+  // buffers, the glyph atlas texture and the density's own texture. Safe to call
+  // more than once; every assignment is a no-op while the renderer is
+  // uninitialised.
   atlas_ = render::TextAtlas{};
   line_program_ = render::LineProgram{};
   text_program_ = render::TextProgram{};
+  density_program_ = render::DensityProgram{};
   line_vao_ = render::LineVertexArray{};
   text_vao_ = render::TextVertexArray{};
+  density_vao_ = gl::VertexArray{};
+  density_texture_ = gl::Texture{};
+  density_pixels_.clear();
+  density_w_ = 0;
+  density_h_ = 0;
+  density_uploaded_grid_ = nullptr;
+  density_uploaded_revision_ = 0;
   lines_.clear();
   glyphs_under_.clear();
   glyphs_over_.clear();
@@ -252,10 +261,10 @@ bool Renderer::init(Status* st) noexcept {
     return false;
   }
 
-  if (!line_program_.create(st) || !text_program_.create(st)) {
+  if (!line_program_.create(st) || !text_program_.create(st) || !density_program_.create(st)) {
     return false;
   }
-  if (!line_vao_.create(st, mode) || !text_vao_.create(st, mode)) {
+  if (!line_vao_.create(st, mode) || !text_vao_.create(st, mode) || !density_vao_.create(st)) {
     return false;
   }
   ready_ = true;
@@ -516,6 +525,13 @@ void Renderer::draw_plot(Plot& plot, const PlotLayout& layout) {
   // against the line passes would not change a pixel.)
   set_clip(layout.axes);
   draw_grid(plot);
+  // The holes over the grid and under the data: a band is chrome of the *background*, not an
+  // overlay, so everything a frame draws inside the axes is drawn on top of it.
+  draw_invalid_spans(layout);
+  // ... the density included: it is trace ink and not chrome, so it goes over the bands exactly
+  // where the traces did -- and, while it is on, *instead* of them (`draw_traces()` returns) -- and
+  // under them for the same reason they are under the data.
+  draw_density(plot, layout);
   clear_clip();
   draw_axis_lines(plot);
   set_clip(layout.axes);
@@ -542,6 +558,9 @@ void Renderer::draw_plot(Plot& plot, const PlotLayout& layout) {
   // panel is drawn over the legend and every other overlay rather than under them, and its
   // text joins the frame's over flush with the tick labels and titles.
   draw_crosshair_readout(plot, layout);
+  // The selection frame last of all: it is the gesture still in progress, and nothing inside the axes
+  // should be able to sit on top of the area being chosen.
+  draw_selection_frame(layout);
   clear_clip();
   draw_tick_labels(plot, layout);
   draw_titles(plot, layout);
@@ -1096,6 +1115,9 @@ u32 Renderer::stage_trace_density(const Plot& plot, const PlotLayout& layout, co
   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 --
@@ -1124,10 +1146,25 @@ u32 Renderer::stage_trace_density(const Plot& plot, const PlotLayout& layout, co
       }
     }
     const f32 inv = peak > 0.0f ? 1.0f / peak : 0.0f;
-    // What counts as covered at all. The deposits are fractions, so this cannot be an
-    // integer test: it is a share of the column's own peak, small enough to keep a row a
-    // single thin segment grazed and large enough not to light a row on rounding alone.
-    const f32 lit_floor = 0.01f * peak;
+    // 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;
@@ -1175,6 +1212,7 @@ u32 Renderer::stage_trace_density(const Plot& plot, const PlotLayout& layout, co
       }
     }
     open = false;
+    w_min = std::numeric_limits<f32>::infinity();
     if (!any) {
       joined = false;   // nothing visible here: a hole, like an uncovered column
       return;
@@ -1263,6 +1301,7 @@ u32 Renderer::stage_trace_density(const Plot& plot, const PlotLayout& layout, co
         // 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;
       }
@@ -1275,7 +1314,70 @@ u32 Renderer::stage_trace_density(const Plot& plot, const PlotLayout& layout, co
   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) {
+  // **No solid trace while the density is on.** The trace ink *is* the density image (see
+  // `Plot::set_density()` and `draw_density()`): every visible trace was deposited, the newest
+  // acquisition included, so drawing the polyline as well would put a solid, unfading stroke over
+  // its own faint image -- the "persistent image + last acquisition" a report described, where the
+  // newest acquisition never faded because it was never only the image. The traces still exist --
+  // the legend, the crosshair readout and the measurements read them -- they are simply not drawn
+  // as lines.
+  if (plot.density().enabled) return;
   // 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
   // rendering choice rather than the collapsed plot it is.
@@ -1498,8 +1600,33 @@ void Renderer::draw_traces(const Plot& plot, const PlotLayout& layout) {
         flush_lines(pixel_mapping(), trace.color, style_.device(trace.width), dash, true);
         ++stats_.column_traces;
       } else {
-        stage_xy(gather_.data(), points, x_range.min, log_x, log_y);
-        flush_lines(map, trace.color, style_.device(trace.width), dash);
+        // 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);
+        }
       }
     }
 
@@ -1628,6 +1755,123 @@ void Renderer::draw_cursor_label(const Plot& plot, const PlotLayout& layout, con
   }
 }
 
+void Renderer::draw_invalid_spans(const PlotLayout& layout) {
+  for (const InvalidSpanLayout& band : layout.invalid_spans) {
+    fill_pixels(band.fill, band.repaired ? style_.invalid_repaired_fill : style_.invalid_fill);
+  }
+}
+
+void Renderer::draw_density(const Plot& plot, const PlotLayout& layout) {
+  const DensityConfig& config = plot.density();
+  if (!config.enabled) {
+    // A plot that has stopped drawing a density is not holding a stale one: forget what the shared
+    // texture holds, so a re-enable -- which drops the grids and rebuilds them, possibly at the same
+    // addresses and with fresh revisions -- re-uploads rather than trusting a cache entry that
+    // happens to match.
+    density_uploaded_grid_ = nullptr;
+    return;
+  }
+  if (!(layout.axes.w > 0.0f) || !(layout.axes.h > 0.0f)) return;
+  if (!density_program_.valid()) return;  // a pipeline that never linked draws nothing
+  // One quad per trace, in that trace's own colour: the plot holds one grid per trace (see
+  // `DensityConfig`), so where two traces agree the viewer sees both colours, and a saturated cell
+  // is the colour of the trace whose ink filled it and not a blend. A trace with no visible series
+  // was deposited into nothing (its grid is empty), so it is skipped.
+  for (u32 i = 0u; i < plot.trace_count(); ++i) {
+    const Trace& trace = plot.trace(i);
+    if (!trace.visible()) continue;
+    draw_density_grid(config, plot.density_grid(i), trace.color, layout);
+  }
+}
+
+void Renderer::draw_density_grid(const DensityConfig& config, const DensityGrid& grid, Color tint,
+                                 const PlotLayout& layout) {
+  const u32 columns = grid.columns();
+  const u32 rows = grid.rows();
+  if (columns == 0u || rows == 0u) return;
+
+  // The image as the shader reads it: one byte per cell, `full_scale` and `gamma` already
+  // applied. The conversion lives here rather than in the fragment shader so that a cell's
+  // *count* has exactly one reading -- the plot's, which is also what a host reads back through
+  // `DensityGrid::ink()`/`peak()`, and which decays once per frame on the CPU anyway.
+  //
+  // **One texture, re-filled per trace.** The cache is keyed by the grid's own address as well as
+  // its revision, so a plot drawn twice with nothing changed (the steady state of a display that
+  // has stopped being swept) skips the conversion *and* the upload -- while a row of several traces
+  // re-fills the one texture once per trace, which is what a figure of several rows already cost
+  // before the density was per trace.
+  const bool resized = columns != density_w_ || rows != density_h_;
+  if (resized) {
+    if (!density_texture_.create_r8(columns, rows, nullptr)) {
+      gl_error_ = true;
+      return;
+    }
+    // **Linear, and it used to be a point sample.** The filter is the thing that makes a cell
+    // bigger than a pixel acceptable: a cell is a *count*, a continuous quantity, so a fragment
+    // between two of them is between their two ink levels -- which is exactly what a linear tap
+    // returns, and what a `GL_NEAREST` fetch cannot (it would show the grid's own steps as blocks
+    // once the image is scaled up, `kDensityCellCap` cells spread across a wider axes rect). The
+    // nearest tap was right only while a cell *was* a device pixel and every fragment landed in
+    // its own; minification interpolates for the same reason, so a plot whose rect is under the
+    // cap (cell and pixel one and the same, up to the rounding of `ceil`) reads as it always did.
+    density_texture_.set_filter(gl::GL_LINEAR, gl::GL_LINEAR);
+    density_w_ = columns;
+    density_h_ = rows;
+    density_uploaded_grid_ = nullptr;  // a fresh texture holds nothing
+  }
+  if (resized || density_uploaded_grid_ != &grid || grid.revision() != density_uploaded_revision_) {
+    const f32 full = config.full_scale > 0.0f ? config.full_scale : 1.0f;
+    const f32 gamma = config.gamma > 0.0f ? config.gamma : 1.0f;
+    // The gamma through a 256-entry table rather than a `pow` per cell: the output *is* eight
+    // bits, so quantising the count first and lifting the quantised value costs nothing a
+    // per-cell `pow` would have bought, and it keeps the per-frame pass a loop of multiplies.
+    u8 lut[256];
+    for (u32 i = 0u; i < 256u; ++i) {
+      const f32 v = static_cast<f32>(i) / 255.0f;
+      lut[i] = static_cast<u8>(std::clamp(std::pow(v, gamma), 0.0f, 1.0f) * 255.0f + 0.5f);
+    }
+    density_pixels_.resize(grid.cell_count());
+    const f32* cells = grid.cells().data();
+    for (usize i = 0; i < density_pixels_.size(); ++i) {
+      const f32 v = cells[i] / full;
+      const u32 quantised =
+          static_cast<u32>(std::clamp(v, 0.0f, 1.0f) * 255.0f + 0.5f);
+      density_pixels_[i] = lut[std::min(quantised, 255u)];
+    }
+    // `upload_r8` sets GL_UNPACK_ALIGNMENT to 1 and leaves it there (see gl::Texture), so the
+    // host's own value is saved and put back -- the same care `TextAtlas::sync()` takes around
+    // its own upload, since the two share a context and a frame.
+    gl::GLint alignment = 4;
+    gl::glGetIntegerv(gl::GL_UNPACK_ALIGNMENT, &alignment);
+    density_texture_.upload_r8(columns, rows, density_pixels_.data());
+    gl::glPixelStorei(gl::GL_UNPACK_ALIGNMENT, alignment);
+    density_uploaded_grid_ = &grid;
+    density_uploaded_revision_ = grid.revision();
+    // += and not =: a figure draws a density per trace per row, and what this field reports is the
+    // frame's upload, not the last one's.
+    stats_.density_upload_bytes += columns * rows;
+  }
+
+  // The quad covers the image's own **footprint**: the axes rect rounded up to whole device pixels,
+  // the rect `Plot::size_density_grids()` counted the cells on. While that rect is under
+  // `kDensityCellCap` it is exactly `columns` by `rows` pixels -- one texel a pixel, the mapping
+  // this has always had -- and past the cap the grid is smaller and the image is magnified back
+  // over it. The uv still runs 0..1 over the quad, so a fragment between two cells is a linear
+  // blend of them: the filter the texture was created with.
+  density_program_.bind();
+  density_program_.set_viewport({viewport_.w, viewport_.h});
+  density_program_.set_rect({layout.axes.x, layout.axes.y},
+                            {std::ceil(layout.axes.w), std::ceil(layout.axes.h)});
+  // The tint is the trace's own colour: its alpha is the trace's, so a saturated cell reads as the
+  // trace at its own brightness, and the shader multiplies it by the cell's luminance.
+  density_program_.set_color(tint);
+  density_texture_.bind();
+  density_vao_.bind();
+  gl::glDrawArrays(gl::GL_TRIANGLE_STRIP, 0, 4);
+  stats_.density_cells += columns * rows;
+  ++stats_.draw_calls;
+}
+
 void Renderer::draw_regions(const Plot& plot, const PlotLayout& layout) {
   const HotHandles hot = plot.hot_handles();
   const f32 edge_w = style_.device(style_.line_width_px);
@@ -1851,6 +2095,27 @@ void Renderer::stage_marker(plot::Marker marker, Vec2 centre_px, f32 size_px) {
   }
 }
 
+void Renderer::draw_selection_frame(const PlotLayout& layout) {
+  const Rect& frame = layout.selection;
+  // Two guards, not one: a drag swept flat in one direction has a real extent on one axis and none on
+  // the other, and a border on that is still the gesture's own answer -- the fill is what a zero
+  // extent has nothing of.
+  if (!(frame.w > 0.0f) && !(frame.h > 0.0f)) return;
+  if (frame.w > 0.0f && frame.h > 0.0f) fill_pixels(frame, style_.selection_fill);
+  // The border frames the pixels the fill covers and not the measured rect's own fractional edges:
+  // the readout panel's rounding and the readout panel's reason, since a hairline straddling a
+  // fractional edge is a frame bright on two sides and dim on the others.
+  const f32 left = std::ceil(frame.x - 0.5f) + 0.5f;
+  const f32 right = std::ceil(frame.right() - 0.5f) - 0.5f;
+  const f32 top = std::ceil(frame.y - 0.5f) + 0.5f;
+  const f32 bottom = std::ceil(frame.bottom() - 0.5f) - 0.5f;
+  lines_.add_segment({left, top}, {right, top});
+  lines_.add_segment({left, bottom}, {right, bottom});
+  lines_.add_segment({left, top}, {left, bottom});
+  lines_.add_segment({right, top}, {right, bottom});
+  flush_lines(pixel_mapping(), style_.selection_edge, style_.device(1.0f));
+}
+
 void Renderer::draw_readout_panel(const Rect& panel, Color border) {
   if (!(panel.w > 0.0f) || !(panel.h > 0.0f)) return;
   // The frame's own background at a partial alpha, which dims whatever it covers instead of erasing

src/render/shaders.cpp

@@ -235,4 +235,48 @@ void main() {
 }
 )";
 
+const char* const kDensityVS = R"(#version 330 core
+// No vertex attributes at all: the image is one axis-aligned rectangle whose corners are
+// uniform state, so the quad comes from gl_VertexID alone and there is no vertex buffer to
+// fill. The density's own bytes go to a texture (see kDensityFS), never to a buffer.
+uniform vec2 u_viewport;  // render target size, pixels
+uniform vec2 u_origin;    // the quad's top-left corner in Rect pixels
+uniform vec2 u_size;      // the quad's size in pixels -- the axes rect, which the image fills
+
+out vec2 v_uv;
+
+void main() {
+  // A four-vertex triangle strip, like the line and text pipelines: the corner index is the
+  // vertex id's two bits, so 0,1,2,3 are (0,0), (1,0), (0,1), (1,1).
+  vec2 corner = vec2(float(gl_VertexID & 1), float((gl_VertexID >> 1) & 1));
+  vec2 px = u_origin + corner * u_size;
+  // Rect is top-left origin, GL is bottom-left: the one and only y flip.
+  vec2 ndc = vec2(px.x / u_viewport.x * 2.0 - 1.0, 1.0 - px.y / u_viewport.y * 2.0);
+  gl_Position = vec4(ndc, 0.0, 1.0);
+  // uv runs 0..1 across the whole image, so a fragment lands wherever the axes rect puts it
+  // between the grid's cells: one texel a cell while the rect is under the cap (a cell a device
+  // pixel, the sampling all but a point sample) and a linear magnification of the image past it.
+  v_uv = corner;
+}
+)";
+
+const char* const kDensityFS = R"(#version 330 core
+in vec2 v_uv;  // cell coordinate in [0,1] across the quad
+
+uniform sampler2D u_density;  // GL_R8 luminance, one texel per cell, GL_LINEAR
+uniform vec4 u_color;
+
+out vec4 o_color;
+
+void main() {
+  // The cell's count was already turned into a luminance on the CPU, where the count, the
+  // decay and the gamma live -- so this stage has no scale of its own that a host reading the
+  // grid's numbers back could disagree with. All that is left is the tint: the density is drawn
+  // once per trace, in that trace's own colour (the caller's `u_color`), so a saturated cell is
+  // the trace at its own brightness and a faint one is the same hue at a lower alpha.
+  float ink = texture(u_density, v_uv).r;
+  o_color = vec4(u_color.rgb, u_color.a * ink);
+}
+)";
+
 }  // namespace plot::render

tests/harness.hpp

@@ -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);

tests/test_controller.cpp

@@ -2403,3 +2403,54 @@ PLOT_TEST(an_unselectable_cursor_is_neither_hovered_nor_grabbed) {
   PLOT_CHECK_NEAR(p.cursor(readout).x, before, 1e-12);
   PLOT_CHECK(c.grabbed_cursor() == normal);
 }
+
+PLOT_TEST(a_ctrl_box_zoom_previews_the_band_it_will_zoom) {
+  // What a host draws for an open box zoom is not always the area the pointer swept. Ctrl frames the
+  // x range only, so what its release will change is a *band* across the plot -- and a pointer dragged
+  // straight across sweeps a sliver a couple of pixels tall, which would be the frame showing the
+  // gesture instead of its effect. Shift frames both axes and gets the swept box itself; Alt is the
+  // other single-axis mask, and gets the other frame.
+  plot::Plot p;
+  p.set_viewport({0, 0, 800, 400});
+  p.add_x_axis({"t", {0.0, 800.0}, true, plot::AxisPlace::Bottom, false});
+  const plot::Rect axes = p.layout().axes;
+  constexpr plot::u32 kAlt = static_cast<plot::u32>(plot::input::Mod::Alt);
+  plot::input::Controller c(p);
+  c.set_viewport({0, 0, 800, 400});
+
+  c.on_pointer({100, 200, 0, 0, plot::input::Button::Left, kCtrl, true, true, false});
+  // Nothing framed until something was swept: the press alone is an empty rect at the pointer, and a
+  // full-width band derived from it would claim a range that does not exist yet.
+  PLOT_CHECK_NEAR(c.selection_preview().w, 0.0, 1e-6);
+  c.on_pointer({300, 202, 200, 2, plot::input::Button::Left, kCtrl, true, false, false});
+  const plot::Rect ctrl = c.selection_preview();
+  PLOT_CHECK_NEAR(ctrl.x, 100.0, 1e-6);
+  PLOT_CHECK_NEAR(ctrl.w, 200.0, 1e-6);
+  PLOT_CHECK_NEAR(ctrl.y, axes.y, 1e-6);
+  PLOT_CHECK_NEAR(ctrl.h, axes.h, 1e-6);
+  // The gesture's own geometry is untouched: the widening happens in the preview, so the range the
+  // release computes is still the one the pointer described.
+  PLOT_CHECK_NEAR(c.selection_rect().h, 2.0, 1e-6);
+  c.on_pointer({300, 202, 0, 0, plot::input::Button::Left, kCtrl, false, false, true});
+
+  c.on_pointer({100, 50, 0, 0, plot::input::Button::Left, kShift, true, true, false});
+  c.on_pointer({400, 150, 300, 100, plot::input::Button::Left, kShift, true, false, false});
+  const plot::Rect both = c.selection_preview();
+  PLOT_CHECK_NEAR(both.x, 100.0, 1e-6);
+  PLOT_CHECK_NEAR(both.y, 50.0, 1e-6);
+  PLOT_CHECK_NEAR(both.w, 300.0, 1e-6);
+  PLOT_CHECK_NEAR(both.h, 100.0, 1e-6);
+  c.on_pointer({400, 150, 0, 0, plot::input::Button::Left, kShift, false, false, true});
+
+  c.on_pointer({100, 50, 0, 0, plot::input::Button::Left, kAlt, true, true, false});
+  c.on_pointer({110, 150, 10, 100, plot::input::Button::Left, kAlt, true, false, false});
+  const plot::Rect alt = c.selection_preview();
+  PLOT_CHECK_NEAR(alt.x, axes.x, 1e-6);
+  PLOT_CHECK_NEAR(alt.w, axes.w, 1e-6);
+  PLOT_CHECK_NEAR(alt.y, 50.0, 1e-6);
+  PLOT_CHECK_NEAR(alt.h, 100.0, 1e-6);
+  c.on_pointer({110, 150, 0, 0, plot::input::Button::Left, kAlt, false, false, true});
+  // Closed: a frame on a finished gesture would claim the old selection is still open.
+  PLOT_CHECK(c.drag_mode() == plot::input::DragMode::None);
+  PLOT_CHECK_NEAR(c.selection_preview().w, 0.0, 1e-6);
+}

tests/test_minmax_pyramid.cpp

@@ -6,6 +6,7 @@
 #include <plot/data/detail/merge_count.hpp>
 #include <plot/data/minmax_pyramid.hpp>
 #include <algorithm>
+#include <limits>
 #include <random>
 
 using plot::data::kBucket;
@@ -342,3 +343,69 @@ PLOT_TEST(pyramid_level_cap_keeps_the_span_shift_defined) {
   p.append(1.0f);
   PLOT_CHECK(p.level_count() >= 1);
 }
+
+PLOT_TEST(amend_folds_a_backfilled_sample_into_every_covering_level) {
+  // A hole is appended as NaN -- which the pyramid already stores as an empty aggregate --
+  // and amended later when the packet that owned it finally arrives. The amendment has to
+  // reach every level that covers the index, because the renderer reads whichever level the
+  // zoom picked: repairing level 0 alone would make a trace whole when zoomed in and still
+  // broken when zoomed out.
+  MinMaxPyramid p;
+  p.reserve(8 * kBucket);
+  for (u64 i = 0; i < 8 * kBucket; ++i) {
+    // One NaN, at an index comfortably inside the first bucket of every level.
+    p.append(i == 5 ? std::numeric_limits<f32>::quiet_NaN() : 1.0f);
+  }
+  // Before: every covering bucket aggregates kBucket-1 ones and knows nothing of index 5.
+  PLOT_CHECK(p.bucket_count(0, 0) == kBucket - 1);
+  PLOT_CHECK_NEAR(p.bucket(0, 0).max, 1.0);
+
+  p.amend(5, 7.0f);
+
+  // Level 0 gained the sample.
+  PLOT_CHECK(p.bucket_count(0, 0) == kBucket);
+  PLOT_CHECK_NEAR(p.bucket(0, 0).max, 7.0);
+  PLOT_CHECK_NEAR(p.bucket_sum(0, 0), f64(kBucket - 1) + 7.0);
+  PLOT_CHECK_NEAR(p.bucket_sumsq(0, 0), f64(kBucket - 1) + 49.0);
+  // And so did every coarser level that covers it.
+  for (u32 l = 1; l < p.level_count(); ++l) {
+    if (p.level_size(l) == 0) continue;
+    const u64 span = u64{kBucket} << l;
+    const u64 b = 5 / span;
+    if (b < p.level_base(l) || b - p.level_base(l) >= p.level_size(l)) continue;
+    PLOT_CHECK_NEAR(p.bucket(l, b).max, 7.0);
+    PLOT_CHECK(p.bucket_count(l, b) == span);
+  }
+}
+
+PLOT_TEST(amend_makes_an_all_nan_bucket_present_again) {
+  // A bucket whose every sample was non-finite is stored with count 0, which every reader
+  // treats as absent. One amendment has to make it present -- min and max become the value
+  // rather than widening from a meaningless zero, which is the case a plain fold gets wrong.
+  MinMaxPyramid p;
+  p.reserve(4 * kBucket);
+  const f32 nan = std::numeric_limits<f32>::quiet_NaN();
+  for (u64 i = 0; i < 2 * kBucket; ++i) p.append(i < kBucket ? nan : 1.0f);
+  PLOT_CHECK(p.bucket_count(0, 0) == 0);
+
+  p.amend(3, -2.0f);
+
+  PLOT_CHECK(p.bucket_count(0, 0) == 1);
+  PLOT_CHECK_NEAR(p.bucket(0, 0).min, -2.0);
+  PLOT_CHECK_NEAR(p.bucket(0, 0).max, -2.0);
+}
+
+PLOT_TEST(amend_outside_the_window_is_a_no_op) {
+  // An index the window has already dropped, or one not yet appended, has nowhere to go.
+  // Silently ignoring it is what lets the caller amend without first proving the ring still
+  // holds the slot -- a race it cannot win, because the window slides on the other thread.
+  MinMaxPyramid p;
+  p.reserve(4 * kBucket);
+  for (u64 i = 0; i < 4 * kBucket; ++i) p.append(1.0f);
+  p.drop_before(2 * kBucket);
+  const u64 before = p.bucket_count(0, 2);
+  p.amend(5, 99.0f);                 // dropped
+  p.amend(100 * kBucket, 99.0f);     // never appended
+  PLOT_CHECK(p.bucket_count(0, 2) == before);
+  PLOT_CHECK_NEAR(p.bucket(0, 2).max, 1.0);
+}

tests/test_plot.cpp

@@ -2789,3 +2789,425 @@ PLOT_TEST(an_annotation_can_be_moved_by_id) {
   p.set_annotation(42u, other);
   PLOT_CHECK_NEAR(p.annotation(id).x, 3.5, 1e-12);
 }
+
+PLOT_TEST(the_selection_frame_is_carried_and_taken_off) {
+  // The box-zoom frame is the host's to set -- the plot has no controller and learns nothing about
+  // pointers -- so what it owes is to carry it: out through `layout()` unchanged, because it is
+  // already in viewport pixels and a second derivation would be a second rounding of the same
+  // rectangle, and gone when the host takes it off, because a frame left behind claims the selection
+  // is still open.
+  plot::Plot p;
+  p.set_viewport({0, 0, 800, 400});
+  PLOT_CHECK(p.layout().selection.w == 0.0f && p.layout().selection.h == 0.0f);  // nothing swept
+  p.set_selection_rect({10.0f, 20.0f, 30.0f, 40.0f});
+  PLOT_CHECK_NEAR(p.selection_rect().x, 10.0, 1e-6);
+  PLOT_CHECK_NEAR(p.layout().selection.y, 20.0, 1e-6);
+  PLOT_CHECK_NEAR(p.layout().selection.w, 30.0, 1e-6);
+  PLOT_CHECK_NEAR(p.layout().selection.h, 40.0, 1e-6);
+  p.clear_selection_rect();
+  PLOT_CHECK_NEAR(p.selection_rect().w, 0.0, 1e-6);
+  PLOT_CHECK_NEAR(p.layout().selection.h, 0.0, 1e-6);
+}
+
+// --- phosphor density -------------------------------------------------------
+
+namespace {
+
+/// A two-sample flat series: one segment across the whole window at y = 0, which is the
+/// simplest geometry a density can be read against -- one cell per column and nothing else.
+std::vector<f32> flat_pair() { return std::vector<f32>{0.0f, 0.0f}; }
+
+/// A plot with one flat trace over a 640x480 viewport, laid out. The axes rect it returns is
+/// the one `accumulate_density()` sizes the grid to, so a test reads both together.
+struct DensityFixture {
+  plot::data::ArraySeries series;
+  plot::Plot plot;
+  plot::u32 ax = 0;
+  plot::u32 ay = 0;
+
+  explicit DensityFixture(std::vector<f32> y = flat_pair(), plot::f64 dx = 1.0)
+      : series(std::move(y), 0.0, dx) {
+    plot.set_viewport({0.0f, 0.0f, 640.0f, 480.0f});
+    ax = plot.add_x_axis({"t", {0.0, 1.0}, false, plot::AxisPlace::Bottom, false});
+    ay = plot.add_y_axis({"v", {-1.0, 1.0}, false, plot::AxisPlace::Left, false});
+    PLOT_CHECK(plot.add_trace({&series, plot::Color::hex(0x00E070), 1.5f, ax, ay, "flat"}) == 0u);
+    plot.set_x_range(ax, {0.0, 1.0});
+    plot.set_y_range(ay, {-1.0, 1.0});
+    plot.layout();
+  }
+};
+
+}  // namespace
+
+/// The grid is the screen's, not the data's: one cell per device pixel of the axes rect **up to
+/// `kDensityCellCap`**, and nothing at all until the density is switched on. The figures here are
+/// the ones the API's memory claim rests on -- `cell_count * 4` bytes, whatever the trigger has
+/// done and whatever the window is.
+PLOT_TEST(a_density_grid_is_the_axes_in_device_pixels) {
+  DensityFixture f;
+  const plot::Rect axes = f.plot.layout().axes;
+  // The 640x480 viewport this fixture asks for is past the cap, so its grid is the axes rect
+  // *scaled down* -- the rule the library states, written out here so the assertion is arithmetic
+  // rather than a recorded number. A grid under the cap is the rect itself, which the 320x240 leg
+  // at the end reads.
+  const auto capped = [](plot::u32 w, plot::u32 h) {
+    std::pair<plot::u32, plot::u32> out{w, h};
+    const plot::u64 pixels = static_cast<plot::u64>(w) * static_cast<plot::u64>(h);
+    if (pixels > static_cast<plot::u64>(plot::kDensityCellCap)) {
+      const plot::f64 s = std::sqrt(static_cast<plot::f64>(plot::kDensityCellCap) /
+                                    static_cast<plot::f64>(pixels));
+      out.first = std::max(1u, static_cast<plot::u32>(static_cast<plot::f64>(w) * s));
+      out.second = std::max(1u, static_cast<plot::u32>(static_cast<plot::f64>(h) * s));
+    }
+    return out;
+  };
+  const auto [columns, rows] =
+      capped(static_cast<plot::u32>(std::ceil(axes.w)), static_cast<plot::u32>(std::ceil(axes.h)));
+  // The row a device y lands in is read through the grid's cells-per-*whole*-pixel, which is what
+  // the deposit uses (see `deposit_density_segment()`): 1 while the grid is the rect.
+  const plot::f32 sy = static_cast<plot::f32>(rows) / std::ceil(axes.h);
+  PLOT_CHECK(static_cast<plot::u64>(columns) * rows <= plot::kDensityCellCap);
+
+  // Off is the default, and off is *nothing*: no grid, no ink, and an accumulation that
+  // deposits nothing at all.
+  PLOT_CHECK(!f.plot.density().enabled);
+  f.plot.accumulate_density();
+  PLOT_CHECK(f.plot.density_grid(0u).cell_count() == 0u);
+  PLOT_CHECK(f.plot.density_grid(0u).ink() == 0.0);
+  PLOT_CHECK(f.plot.density_grid(0u).peak() == 0.0f);
+
+  plot::DensityConfig cfg;
+  cfg.enabled = true;
+  f.plot.set_density(cfg);
+  PLOT_CHECK(f.plot.density().enabled);
+  f.plot.accumulate_density();
+
+  const plot::DensityGrid& grid = f.plot.density_grid(0u);
+  PLOT_CHECK(grid.columns() == columns);
+  PLOT_CHECK(grid.rows() == rows);
+  PLOT_CHECK(grid.cell_count() == static_cast<plot::usize>(columns) * rows);
+  // `4 bytes * cells`, and never more than the cap: the whole point of the bound.
+  const plot::usize bytes = grid.cell_count() * sizeof(plot::f32);
+  PLOT_CHECK(bytes <= static_cast<plot::usize>(plot::kDensityCellCap) * sizeof(plot::f32));
+  std::printf("[density] grid=%ux%u cells=%zu grid_bytes=%zu ink=%.0f peak=%.0f\n",
+              grid.columns(), grid.rows(), grid.cell_count(), bytes, grid.ink(),
+              static_cast<double>(grid.peak()));
+
+  // One flat trace over the whole window lights every column exactly once: one segment, no
+  // column reached twice, so the ink *is* the width and the peak is one pass.
+  PLOT_CHECK_NEAR(grid.ink(), static_cast<double>(columns), 1.0);
+  PLOT_CHECK_NEAR(grid.peak(), 1.0, 1e-4);
+
+  // ... and all of it in one row, the one y = 0 maps to.
+  const plot::Transform ty = f.plot.y_transform(f.ay);
+  const int row = static_cast<int>(std::floor((ty.to_screen_y(0.0) - axes.y) * sy));
+  plot::u32 lit = 0;
+  for (plot::u32 r = 0; r < grid.rows(); ++r) {
+    for (plot::u32 c = 0; c < grid.columns(); ++c) {
+      if (grid.at(c, r) <= 0.0f) continue;
+      ++lit;
+      PLOT_CHECK(static_cast<int>(r) == row);
+    }
+  }
+  PLOT_CHECK(lit == columns);
+
+  // The accumulation is a *screen* image: a plot that has moved to another axes rect gets a
+  // grid of that size and nothing carried over from the old one -- and that rect is under the
+  // cap, so the grid is it *exactly*: one cell a device pixel, no scaling at all.
+  f.plot.set_viewport({0.0f, 0.0f, 320.0f, 240.0f});
+  f.plot.layout();
+  f.plot.accumulate_density();
+  const plot::DensityGrid& small = f.plot.density_grid(0u);
+  const plot::Rect small_axes = f.plot.layout().axes;
+  PLOT_CHECK(small.columns() == static_cast<plot::u32>(std::ceil(small_axes.w)));
+  PLOT_CHECK(small.rows() == static_cast<plot::u32>(std::ceil(small_axes.h)));
+  PLOT_CHECK(small.cell_count() <= plot::kDensityCellCap);
+  PLOT_CHECK(small.columns() < columns);
+  PLOT_CHECK_NEAR(small.ink(), static_cast<double>(small.columns()), 1.0);
+}
+
+/// The cap is what keeps the resolution from following the window: a grid is never more than
+/// `kDensityCellCap` cells, whatever the axes rect is, so the memory a display holds and the frame
+/// pass over it are numbers and not functions of how wide the window was dragged. The scaling is
+/// **uniform**, so a cell stays square and the picture keeps the axes' aspect -- the reading that
+/// separates this from a cap on one axis, which would stretch every cell by the other one's ratio.
+PLOT_TEST(a_density_grid_is_capped_whatever_the_window) {
+  DensityFixture f;
+  f.plot.set_viewport({0.0f, 0.0f, 3840.0f, 2160.0f});
+  f.plot.layout();
+  plot::DensityConfig cfg;
+  cfg.enabled = true;
+  f.plot.set_density(cfg);
+  f.plot.accumulate_density();
+
+  const plot::DensityGrid& grid = f.plot.density_grid(0u);
+  const plot::Rect axes = f.plot.layout().axes;
+  PLOT_CHECK(static_cast<plot::u64>(grid.columns()) * grid.rows() <= plot::kDensityCellCap);
+  PLOT_CHECK(grid.cell_count() * sizeof(plot::f32) <= 1'048'576u);
+  // ... and it is as large as the cap allows: flooring a uniform scale costs at most the two
+  // columns and rows the truncation drops, so the grid is within a hair of the whole budget.
+  PLOT_CHECK(static_cast<plot::f64>(grid.cell_count()) >
+             0.99 * static_cast<plot::f64>(plot::kDensityCellCap));
+  // Uniform: the grid's aspect is the axes rect's, to the rounding of the two floors.
+  PLOT_CHECK_NEAR(static_cast<plot::f64>(grid.columns()) / grid.rows(),
+                  static_cast<plot::f64>(axes.w) / axes.h, 0.01);
+
+  // A cap on the *cells* also returns a full sweep's worth of ink: one flat pass over the window
+  // is one per column however fine or coarse the grid is.
+  PLOT_CHECK_NEAR(grid.ink(), static_cast<double>(grid.columns()), 1.0);
+  PLOT_CHECK_NEAR(grid.peak(), 1.0, 1e-4);
+  std::printf("[density] capped grid=%ux%u cells=%zu bytes=%zu of a %ux%u axes\n", grid.columns(),
+              grid.rows(), grid.cell_count(), grid.cell_count() * sizeof(plot::f32),
+              static_cast<plot::u32>(std::ceil(axes.w)), static_cast<plot::u32>(std::ceil(axes.h)));
+}
+
+/// Per acquisition the image is multiplied by the factor *before* the new acquisition is
+/// deposited, so the sweep on screen is the brightest and the one behind it is the factor
+/// down: the schedule a phosphor's afterglow has, and the reading that says which way round
+/// the halving goes.
+PLOT_TEST(a_density_halves_per_acquisition_and_keeps_the_newest_brightest) {
+  DensityFixture f;
+  plot::DensityConfig cfg;
+  cfg.enabled = true;
+  cfg.decay = plot::DensityDecay::PerAcquisition;
+  cfg.per_acquisition = 0.5f;
+  f.plot.set_density(cfg);
+
+  f.plot.accumulate_density();
+  // The grid is sized by the first accumulation, so the width is read after it -- and the ink
+  // of one pass *is* the width: one segment across the window, one cell per column.
+  const double width = static_cast<double>(f.plot.density_grid(0u).columns());
+  const double one = f.plot.density_grid(0u).ink();
+  PLOT_CHECK_NEAR(one, width, 1.0);
+
+  f.plot.accumulate_density();
+  const double two = f.plot.density_grid(0u).ink();
+  PLOT_CHECK_NEAR(two, width * 1.5, 2.0);
+  PLOT_CHECK_NEAR(f.plot.density_grid(0u).peak(), 1.5f, 1e-3);
+
+  f.plot.accumulate_density();
+  const double three = f.plot.density_grid(0u).ink();
+  PLOT_CHECK_NEAR(three, width * 1.75, 2.0);
+  PLOT_CHECK_NEAR(f.plot.density_grid(0u).peak(), 1.75f, 1e-3);
+
+  // The steady state of a stream that keeps sweeping: 1 + 1/2 + 1/4 + ... = 2 passes.
+  for (int i = 0; i < 40; ++i) f.plot.accumulate_density();
+  PLOT_CHECK_NEAR(f.plot.density_grid(0u).peak(), 2.0f, 1e-3);
+
+  // A factor of 0 is "only the newest acquisition is on screen": the grid is the last pass.
+  cfg.per_acquisition = 0.0f;
+  f.plot.set_density(cfg);
+  f.plot.accumulate_density();
+  PLOT_CHECK_NEAR(f.plot.density_grid(0u).ink(), width, 1.0);
+  PLOT_CHECK_NEAR(f.plot.density_grid(0u).peak(), 1.0f, 1e-3);
+
+  std::printf("[density] per-acquisition ink: 1=%.0f 2=%.0f 3=%.0f peak_steady=%.3f\n", one, two,
+              three, 2.0);
+}
+
+/// The time constant is the other question: the image fades while you watch, by the frame's own
+/// `dt` against a constant stated in seconds, and it is the *caller* who advances it -- there is
+/// no clock in the library, which is what makes the reading reproducible.
+PLOT_TEST(a_density_fades_by_its_time_constant) {
+  DensityFixture f;
+  plot::DensityConfig cfg;
+  cfg.enabled = true;
+  cfg.decay = plot::DensityDecay::TimeConstant;
+  cfg.time_constant_s = 2.0f;
+  f.plot.set_density(cfg);
+  f.plot.accumulate_density();
+  const double full = f.plot.density_grid(0u).ink();
+
+  // A frame that has not been measured yet (dt <= 0) does not wipe the grid, and neither does
+  // a frame under `PerAcquisition`, which fades in `accumulate_density()` instead.
+  f.plot.decay_density(0.0);
+  PLOT_CHECK_NEAR(f.plot.density_grid(0u).ink(), full, 1e-6);
+  f.plot.decay_density(-1.0);
+  PLOT_CHECK_NEAR(f.plot.density_grid(0u).ink(), full, 1e-6);
+
+  // Quarter of a time constant: exp(-0.25).
+  f.plot.decay_density(0.5);
+  const double quarter = full * std::exp(-0.25);
+  PLOT_CHECK_NEAR(f.plot.density_grid(0u).ink(), quarter, quarter * 1e-4);
+
+  // Ten more constants and the display is gone to within a rounding: 4.5e-5 of the ink.
+  for (int i = 0; i < 10; ++i) f.plot.decay_density(2.0);
+  PLOT_CHECK(f.plot.density_grid(0u).ink() < quarter * 1e-3);
+  PLOT_CHECK(f.plot.density_grid(0u).peak() < 1e-3f);
+
+  // A non-positive constant freezes the grid rather than fading it.
+  cfg.time_constant_s = 0.0f;
+  f.plot.set_density(cfg);
+  f.plot.accumulate_density();
+  const double frozen = f.plot.density_grid(0u).ink();
+  f.plot.decay_density(100.0);
+  PLOT_CHECK_NEAR(f.plot.density_grid(0u).ink(), frozen, 1e-6);
+
+  // And `PerAcquisition` fades in `accumulate_density()` alone: a frame that only passed
+  // changes nothing.
+  cfg.decay = plot::DensityDecay::PerAcquisition;
+  f.plot.set_density(cfg);
+  const double before = f.plot.density_grid(0u).ink();
+  f.plot.decay_density(1.0);
+  PLOT_CHECK_NEAR(f.plot.density_grid(0u).ink(), before, 1e-6);
+
+  std::printf("[density] time-constant ink: full=%.0f quarter=%.1f frozen=%.0f\n", full, quarter,
+              frozen);
+}
+
+/// Switching off drops the image at once -- not at the next acquisition, which a trigger that
+/// has stopped firing never sends -- and turning it back on starts from an empty grid.
+PLOT_TEST(switching_a_density_off_drops_the_image_at_once) {
+  DensityFixture f;
+  plot::DensityConfig cfg;
+  cfg.enabled = true;
+  f.plot.set_density(cfg);
+  f.plot.accumulate_density();
+  PLOT_CHECK(f.plot.density_grid(0u).ink() > 0.0);
+
+  f.plot.clear_density();
+  PLOT_CHECK(f.plot.density_grid(0u).ink() == 0.0);
+  PLOT_CHECK(f.plot.density_grid(0u).peak() == 0.0f);
+  // The clear keeps the allocation -- the grid is still the screen's -- so the next
+  // accumulation does not have to reallocate it.
+  PLOT_CHECK(f.plot.density_grid(0u).cell_count() > 0u);
+
+  f.plot.accumulate_density();
+  PLOT_CHECK(f.plot.density_grid(0u).ink() > 0.0);
+
+  cfg.enabled = false;
+  f.plot.set_density(cfg);
+  PLOT_CHECK(f.plot.density_grid(0u).cell_count() == 0u);
+  PLOT_CHECK(f.plot.density_grid(0u).ink() == 0.0);
+
+  // ... and an accumulation while it is off deposits nothing (it is not a hidden build-up).
+  f.plot.accumulate_density();
+  PLOT_CHECK(f.plot.density_grid(0u).cell_count() == 0u);
+}
+
+/// What is deposited is where the *trace* is, and nowhere else: a trace off the visible y range
+/// leaves no ink rather than a band along the edge it left by, and a NaN sample is a gap that
+/// joins nothing.
+PLOT_TEST(a_density_deposits_only_where_the_trace_is) {
+  // y = 5 against a [-1, 1] axis: the segment's whole column span is above the axes.
+  DensityFixture off(std::vector<f32>{5.0f, 5.0f});
+  plot::DensityConfig cfg;
+  cfg.enabled = true;
+  off.plot.set_density(cfg);
+  off.plot.accumulate_density();
+  PLOT_CHECK_NEAR(off.plot.density_grid(0u).ink(), 0.0, 1e-9);
+
+  // ... and the same series inside the axis deposits one cell per column, in two rows: the
+  // first half at y = -1 and the second at y = +1, joined by a diagonal.
+  DensityFixture split(std::vector<f32>{-1.0f, 1.0f});
+  split.plot.set_density(cfg);
+  split.plot.accumulate_density();
+  const plot::DensityGrid& grid = split.plot.density_grid(0u);
+  PLOT_CHECK(grid.ink() >= static_cast<double>(grid.columns()));
+  const plot::Transform ty = split.plot.y_transform(split.ay);
+  const plot::Rect axes = split.plot.layout().axes;
+  // The row a device y lands in is the grid's own mapping: the axis rect scaled by the grid's
+  // cells-per-pixel (1 while the rect is under `kDensityCellCap`, less past it).
+  const plot::f32 sy =
+      axes.h > 0.0f ? static_cast<plot::f32>(grid.rows()) / std::ceil(axes.h) : 1.0f;
+  // The deposit keeps one ULP of the bottom edge off its row, so `y = -1` -- which maps *onto*
+  // the bottom edge -- lands in the last row rather than one past the end.
+  const auto row_of = [&](plot::f64 y) {
+    return static_cast<plot::u32>(std::clamp(
+        static_cast<int>(std::floor((ty.to_screen_y(y) - axes.y) * sy)), 0,
+        static_cast<int>(grid.rows()) - 1));
+  };
+  PLOT_CHECK(grid.at(0u, row_of(-1.0)) > 0.0f);
+  PLOT_CHECK(grid.at(grid.columns() - 1u, row_of(1.0)) > 0.0f);
+  // Inverted on screen: y = +1 is the *lower* row index, which is the one y flip of the mapping.
+  PLOT_CHECK(row_of(1.0) < row_of(-1.0));
+
+  // A NaN in the middle is a gap: it joins nothing, so the trace is deposited as two runs and
+  // the columns where the gap is stay empty -- where the same series with the sample filled in
+  // lights every one of them. Five samples at x = 0, 0.25, 0.5, 0.75, 1.0.
+  const auto column_ink = [](const plot::DensityGrid& g, plot::u32 column) {
+    double sum = 0.0;
+    for (plot::u32 r = 0; r < g.rows(); ++r) sum += static_cast<double>(g.at(column, r));
+    return sum;
+  };
+  DensityFixture whole(std::vector<f32>{0.0f, 0.0f, 0.0f, 0.0f, 0.0f}, 0.25);
+  whole.plot.set_density(cfg);
+  whole.plot.accumulate_density();
+  DensityFixture gap(
+      std::vector<f32>{0.0f, 0.0f, std::numeric_limits<f32>::quiet_NaN(), 0.0f, 0.0f}, 0.25);
+  gap.plot.set_density(cfg);
+  gap.plot.accumulate_density();
+
+  const plot::DensityGrid& whole_grid = whole.plot.density_grid(0u);
+  const plot::DensityGrid& gap_grid = gap.plot.density_grid(0u);
+  const plot::Transform tx = gap.plot.x_transform(gap.ax);
+  const plot::Rect gap_axes = gap.plot.layout().axes;
+  const plot::f32 gsx = gap_axes.w > 0.0f
+                            ? static_cast<plot::f32>(gap_grid.columns()) / std::ceil(gap_axes.w)
+                            : 1.0f;
+  const plot::u32 column = static_cast<plot::u32>(std::clamp(
+      static_cast<int>(std::floor((tx.to_screen_x(0.5) - gap_axes.x) * gsx)), 0,
+      static_cast<int>(gap_grid.columns()) - 1));
+  PLOT_CHECK(column_ink(whole_grid, column) > 0.0);  // the sample is there: the column is lit
+  PLOT_CHECK(column_ink(gap_grid, column) == 0.0);   // the NaN is a gap: nothing joins across it
+  PLOT_CHECK(gap_grid.ink() < whole_grid.ink());
+
+  std::printf("[density] off-range ink=%.0f split ink=%.0f gap ink=%.0f whole ink=%.0f\n",
+              off.plot.density_grid(0u).ink(), grid.ink(), gap_grid.ink(), whole_grid.ink());
+}
+
+/// **One grid per trace.** A plot of two signals holds two images, each deposited from its own
+/// trace and drawn in its own colour (the colour is the renderer's, and here the *count* is what is
+/// read): the two traces at two levels leave ink in two different rows, so one grid holding one
+/// trace's ink and not the other's is the reading that says the images are not shared.
+PLOT_TEST(a_density_holds_one_grid_per_trace) {
+  plot::data::ArraySeries lo(std::vector<plot::f32>{-0.5f, -0.5f}, 0.0, 1.0);
+  plot::data::ArraySeries hi(std::vector<plot::f32>{0.5f, 0.5f}, 0.0, 1.0);
+  plot::Plot p;
+  p.set_viewport({0.0f, 0.0f, 640.0f, 480.0f});
+  const plot::u32 ax = p.add_x_axis({"t", {0.0, 1.0}, false, plot::AxisPlace::Bottom, false});
+  const plot::u32 ay = p.add_y_axis({"v", {-1.0, 1.0}, false, plot::AxisPlace::Left, false});
+  PLOT_CHECK(p.add_trace({&lo, plot::Color::hex(0x4FA3FF), 1.5f, ax, ay, "lo"}) == 0u);
+  PLOT_CHECK(p.add_trace({&hi, plot::Color::hex(0xFF8A4F), 1.5f, ax, ay, "hi"}) == 1u);
+  p.set_x_range(ax, {0.0, 1.0});
+  p.set_y_range(ay, {-1.0, 1.0});
+  p.layout();
+
+  plot::DensityConfig cfg;
+  cfg.enabled = true;
+  p.set_density(cfg);
+  p.accumulate_density();
+
+  PLOT_CHECK(p.trace_count() == 2u);
+  const plot::DensityGrid& g0 = p.density_grid(0u);
+  const plot::DensityGrid& g1 = p.density_grid(1u);
+  // Both are sized to the one axes rect, and each holds exactly its own trace's one pass: the ink
+  // is the width in each grid, so neither picked up the other trace's ink (two traces would be two
+  // widths in a shared grid).
+  PLOT_CHECK(g0.cell_count() > 0u);
+  PLOT_CHECK(g1.cell_count() == g0.cell_count());
+  PLOT_CHECK_NEAR(g0.ink(), static_cast<double>(g0.columns()), 1.0);
+  PLOT_CHECK_NEAR(g1.ink(), static_cast<double>(g1.columns()), 1.0);
+
+  const plot::Transform ty = p.y_transform(ay);
+  const plot::Rect axes = p.layout().axes;
+  const plot::f32 sy =
+      axes.h > 0.0f ? static_cast<plot::f32>(g0.rows()) / std::ceil(axes.h) : 1.0f;
+  const auto row_of = [&](plot::f64 y) {
+    return static_cast<plot::u32>(std::floor((ty.to_screen_y(y) - axes.y) * sy));
+  };
+  const plot::u32 lo_row = row_of(-0.5);
+  const plot::u32 hi_row = row_of(0.5);
+  PLOT_CHECK(lo_row != hi_row);
+  PLOT_CHECK(g0.at(0u, lo_row) > 0.0f);
+  PLOT_CHECK(g1.at(0u, hi_row) > 0.0f);
+  PLOT_CHECK(g0.at(0u, hi_row) == 0.0f);  // no trace but `lo` is in the lower grid
+  PLOT_CHECK(g1.at(0u, lo_row) == 0.0f);
+
+  // An out-of-range trace reads an empty image rather than anything borrowed.
+  PLOT_CHECK(p.density_grid(2u).cell_count() == 0u);
+  PLOT_CHECK(p.density_grid(9u).ink() == 0.0);
+
+  std::printf("[density] per-trace grids: cells=%zu each ink=%.0f/%.0f rows lo=%u hi=%u\n",
+              g0.cell_count(), g0.ink(), g1.ink(), lo_row, hi_row);
+}

tests/test_render_smoke.cpp

@@ -6985,3 +6985,867 @@ 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());
+}
+
+/// An invalid span is the opposite of the x note: the note is chrome that a pan must not move,
+/// and a band marks a *region of the data*, so it must pan and zoom with it. A band that stayed
+/// put under a pan would accuse the wrong samples of being missing, which is worse than drawing
+/// nothing. It also must reserve no layout space -- the label strips were measured before any
+/// band existed, and a hole must not be able to move them.
+///
+/// Measured as a footprint for the x note's reason: the band's rect is deliberately not readable
+/// back, so the only way to see it is the pixels a frame *with* it differs from the same frame
+/// without one, at the same view. Diffing at a fixed view is also what makes the measurement
+/// robust: whatever the trace does under a pan cancels between the two frames, so the bounding
+/// box is the band and nothing else.
+PLOT_TEST(an_invalid_span_is_shaded_and_moves_with_the_data) {
+  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", s.x_bounds(), true, plot::AxisPlace::Bottom, false});
+  const plot::u32 ay = p.add_y_axis({"v", {-1.0, 1.0}, false, plot::AxisPlace::Left, false});
+  PLOT_CHECK(p.add_trace({&s, plot::Color::hex(0x00E070, 1.0f), 1.5f, ax, ay, "signal"}) == 0u);
+
+  // The bounding box of the pixels the band, and only the band, is responsible for, plus the
+  // axes rect the frame was laid out into so the caller can check it did not move.
+  const auto footprint = [&](const plot::Range& view, plot::InvalidSpan span,
+                             plot::Rect& axes_out, const char* dump) {
+    p.set_x_range(ax, view);
+    const plot::InvalidSpan one[1] = {span};
+    p.set_invalid_spans(one);
+    r.begin_frame(kW, kH, kFrameRect);
+    r.draw(p);
+    r.end_frame();
+    PLOT_CHECK(!r.last_frame_had_gl_error());
+    dump_if_requested(r, dump);
+    const std::vector<plot::u8> with = read_frame(ctx);
+    axes_out = p.layout().axes;
+    p.set_invalid_spans({});
+    r.begin_frame(kW, kH, kFrameRect);
+    r.draw(p);
+    r.end_frame();
+    PLOT_CHECK(!r.last_frame_had_gl_error());
+    const std::vector<plot::u8> without = read_frame(ctx);
+    plot::u32 lo_x = kW, lo_y = kH, hi_x = 0, hi_y = 0, differing = 0;
+    for (plot::u32 y = 0; y < kH; ++y) {
+      for (plot::u32 x = 0; x < kW; ++x) {
+        const plot::usize at = (plot::usize(y) * kW + x) * 4u;
+        if (with[at] == without[at] && with[at + 1u] == without[at + 1u] &&
+            with[at + 2u] == without[at + 2u] && with[at + 3u] == without[at + 3u]) {
+          continue;
+        }
+        ++differing;
+        lo_x = std::min(lo_x, x);
+        lo_y = std::min(lo_y, y);
+        hi_x = std::max(hi_x, x);
+        hi_y = std::max(hi_y, y);
+      }
+    }
+    // A comparison of two frames is only evidence if the band was in one of them.
+    PLOT_CHECK(differing > 0u);
+    return plot::Rect{static_cast<plot::f32>(lo_x), static_cast<plot::f32>(lo_y),
+                      static_cast<plot::f32>(hi_x - lo_x + 1u),
+                      static_cast<plot::f32>(hi_y - lo_y + 1u)};
+  };
+
+  // A band over the middle third of a 640-wide window.
+  plot::Rect axes_a{0.0f, 0.0f, 0.0f, 0.0f};
+  const plot::Rect none_box = footprint({0.0, 640.0}, {640.0 / 3.0, 1280.0 / 3.0, false}, axes_a,
+                                        "invalid_span.ppm");
+  // Inside the axes on every side -- a hole is not allowed to paint over a label strip -- and
+  // the full height of the data area, because the whole column has no data.
+  PLOT_CHECK(none_box.x >= axes_a.x && none_box.right() <= axes_a.right() + 1.0f);
+  PLOT_CHECK(none_box.y >= axes_a.y && none_box.bottom() <= axes_a.bottom() + 1.0f);
+  PLOT_CHECK_NEAR(none_box.h, axes_a.h, 2.0);
+  // The middle third: a third of the width, starting a third of the way across. Two pixels of
+  // slack for the fill's fractional edges.
+  PLOT_CHECK_NEAR(none_box.x - axes_a.x, axes_a.w / 3.0f, 2.0);
+  PLOT_CHECK_NEAR(none_box.w, axes_a.w / 3.0f, 2.0);
+
+  // The same span under a pan of exactly 64 device pixels' worth of data. The band is anchored
+  // in the data, so it must move by 64 pixels -- the x note, measured the same way, does not
+  // move at all, which is the distinction this pair of cases draws.
+  const plot::f64 per_px = 640.0 / plot::f64(axes_a.w);
+  const plot::f64 dx = 64.0 * per_px;
+  plot::Rect axes_b{0.0f, 0.0f, 0.0f, 0.0f};
+  const plot::Rect panned = footprint({dx, 640.0 + dx}, {640.0 / 3.0, 1280.0 / 3.0, false},
+                                      axes_b, "invalid_span_panned.ppm");
+  PLOT_CHECK_NEAR(panned.x, none_box.x - 64.0f, 2.0);
+  PLOT_CHECK_NEAR(panned.w, none_box.w, 2.0);
+  // The layout is identical across both: the band reserved nothing, so the strips the labels
+  // were measured into are where they were before any band existed.
+  PLOT_CHECK_NEAR(axes_b.x, axes_a.x, 1e-4);
+  PLOT_CHECK_NEAR(axes_b.y, axes_a.y, 1e-4);
+  PLOT_CHECK_NEAR(axes_b.w, axes_a.w, 1e-4);
+  PLOT_CHECK_NEAR(axes_b.h, axes_a.h, 1e-4);
+
+  std::printf("[invalid span] band %.0f,%.0f %.0fx%.0f panned %.0f,%.0f %.0fx%.0f "
+              "(shift %.1f px) in axes %.0f,%.0f %.0fx%.0f\n",
+              none_box.x, none_box.y, none_box.w, none_box.h, panned.x, panned.y, panned.w,
+              panned.h, none_box.x - panned.x, axes_a.x, axes_a.y, axes_a.w, axes_a.h);
+  ctx.destroy();
+}
+
+/// A hole narrower than a pixel is still a report. A reserved span of one sample at a window
+/// width of hundreds of thousands maps to a fraction of a column, and a fill rounded to zero
+/// width would draw nothing -- the one case where the feature is most needed is the one where
+/// naive rounding silently drops it. The band therefore has a one-device-pixel floor.
+PLOT_TEST(a_sub_pixel_invalid_span_is_still_shaded) {
+  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", s.x_bounds(), true, plot::AxisPlace::Bottom, false});
+  const plot::u32 ay = p.add_y_axis({"v", {-1.0, 1.0}, false, plot::AxisPlace::Left, false});
+  PLOT_CHECK(p.add_trace({&s, plot::Color::hex(0x00E070, 1.0f), 1.5f, ax, ay, "signal"}) == 0u);
+
+  // One sample's worth of hole in a 200 000-wide window: well under a hundredth of a column.
+  p.set_x_range(ax, {0.0, 200000.0});
+  const plot::InvalidSpan one[1] = {{100000.0, 100000.0, false}};
+  p.set_invalid_spans(one);
+  r.begin_frame(kW, kH, kFrameRect);
+  r.draw(p);
+  r.end_frame();
+  PLOT_CHECK(!r.last_frame_had_gl_error());
+  dump_if_requested(r, "invalid_span_subpixel.ppm");
+  const std::vector<plot::u8> with = read_frame(ctx);
+  p.set_invalid_spans({});
+  r.begin_frame(kW, kH, kFrameRect);
+  r.draw(p);
+  r.end_frame();
+  PLOT_CHECK(!r.last_frame_had_gl_error());
+  const std::vector<plot::u8> without = read_frame(ctx);
+
+  plot::u32 columns = 0, differing = 0;
+  for (plot::u32 x = 0; x < kW; ++x) {
+    bool any = false;
+    for (plot::u32 y = 0; y < kH; ++y) {
+      const plot::usize at = (plot::usize(y) * kW + x) * 4u;
+      if (with[at] != without[at] || with[at + 1u] != without[at + 1u] ||
+          with[at + 2u] != without[at + 2u] || with[at + 3u] != without[at + 3u]) {
+        any = true;
+        ++differing;
+      }
+    }
+    if (any) ++columns;
+  }
+  // Drawn, and narrow: the floor is one device pixel, not a visible band widened to be seen.
+  PLOT_CHECK(differing > 0u);
+  PLOT_CHECK(columns >= 1u && columns <= 2u);
+  std::printf("[invalid span] sub-pixel hole lit %u column(s), %u pixels\n", columns, differing);
+  ctx.destroy();
+}
+
+/// The band carries three states and not two: a hole still missing its samples is shaded solidly,
+/// a hole whose late packets have all arrived is shaded faintly, and a hole whose slots have aged
+/// out of the host's buffer is not shaded at all. The faint tier is what keeps the report honest
+/// -- the window *was* drawn without that data -- while telling a reader it is no longer missing.
+///
+/// Measured as ink rather than as a sampled pixel: at a fixed view the trace, the grid and the
+/// labels are byte-identical across all three frames, so every differing byte is the band's own
+/// and a sum of absolute differences measures the tint and nothing else. The alternative -- read
+/// one pixel inside the band -- would be measuring whatever the trace happens to do there.
+PLOT_TEST(a_repaired_invalid_span_is_fainter_than_a_missing_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(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", s.x_bounds(), true, plot::AxisPlace::Bottom, false});
+  const plot::u32 ay = p.add_y_axis({"v", {-1.0, 1.0}, false, plot::AxisPlace::Left, false});
+  PLOT_CHECK(p.add_trace({&s, plot::Color::hex(0x00E070, 1.0f), 1.5f, ax, ay, "signal"}) == 0u);
+  p.set_x_range(ax, {0.0, 640.0});
+
+  // One band over the middle third, at one fixed view, in each of the three states.
+  const auto frame = [&](bool shaded, bool repaired, const char* dump) {
+    const plot::InvalidSpan one[1] = {{640.0 / 3.0, 1280.0 / 3.0, repaired}};
+    if (shaded) {
+      p.set_invalid_spans(one);
+    } else {
+      p.set_invalid_spans({});
+    }
+    r.begin_frame(kW, kH, kFrameRect);
+    r.draw(p);
+    r.end_frame();
+    PLOT_CHECK(!r.last_frame_had_gl_error());
+    if (dump != nullptr) dump_if_requested(r, dump);
+    return read_frame(ctx);
+  };
+
+  const std::vector<plot::u8> none = frame(false, false, nullptr);
+  const std::vector<plot::u8> missing = frame(true, false, "invalid_span_missing.ppm");
+  const std::vector<plot::u8> repaired = frame(true, true, "invalid_span_repaired.ppm");
+
+  // Total ink a frame laid down over the unshaded one, and the columns it covers.
+  const auto ink = [&](const std::vector<plot::u8>& with, plot::u32& lo_x, plot::u32& hi_x) {
+    unsigned long long total = 0;
+    lo_x = kW;
+    hi_x = 0;
+    for (plot::u32 y = 0; y < kH; ++y) {
+      for (plot::u32 x = 0; x < kW; ++x) {
+        const plot::usize at = (plot::usize(y) * kW + x) * 4u;
+        unsigned d = 0;
+        for (plot::usize c = 0; c < 4u; ++c) {
+          const unsigned a = with[at + c];
+          const unsigned b = none[at + c];
+          d += a > b ? a - b : b - a;
+        }
+        if (d == 0u) continue;
+        total += d;
+        lo_x = std::min(lo_x, x);
+        hi_x = std::max(hi_x, x);
+      }
+    }
+    return total;
+  };
+
+  plot::u32 m_lo = 0, m_hi = 0, r_lo = 0, r_hi = 0;
+  const unsigned long long missing_ink = ink(missing, m_lo, m_hi);
+  const unsigned long long repaired_ink = ink(repaired, r_lo, r_hi);
+
+  // A repaired hole is still drawn. A tint that vanished would be the "retire the band on repair"
+  // behaviour this feature deliberately does not have: the window was missing that data when it
+  // was drawn, and the band is the record of it.
+  PLOT_CHECK(repaired_ink > 0ull);
+  // And the solid one is unmistakably heavier. The defaults are alpha 0.18 against 0.08, better
+  // than two to one, so half again is a wide margin and not a tuned threshold.
+  PLOT_CHECK(missing_ink > repaired_ink + repaired_ink / 2ull);
+  // Same pixels either way: the state chooses the tint and nothing about the geometry.
+  PLOT_CHECK(m_lo == r_lo && m_hi == r_hi);
+  std::printf("[invalid span] missing ink %llu over columns %u..%u, repaired ink %llu over "
+              "%u..%u\n",
+              missing_ink, m_lo, m_hi, repaired_ink, r_lo, r_hi);
+  ctx.destroy();
+}
+
+PLOT_TEST(the_box_zoom_frame_lands_exactly_where_it_says) {
+  // The frame a host sets has to reach the framebuffer and cover exactly the rect it names. Both halves
+  // are read back rather than trusted, and the two renders are compared: what is under the frame is a
+  // trace, the grid and the axis chrome, so the assertions are differential -- a predicate guessing
+  // those colours would be testing the guess.
+  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", s.x_bounds(), true, plot::AxisPlace::Bottom, false});
+  const plot::u32 ay = p.add_y_axis({"v", {-1.0, 1.0}, true, plot::AxisPlace::Left, false});
+  p.add_trace({&s, plot::Color::hex(0x40C0FF), 1.5f, ax, ay});
+
+  // The *floor* of a pixel rather than its luminance: the fill is the axis furniture's light neutral at
+  // a low alpha, so over a saturated trace it can lower a channel while it raises the floor, and the
+  // floor is what says "something light was laid over this".
+  const auto floor_of = [&](plot::u32 x, plot::u32 y) {
+    plot::u8 px[4] = {};
+    PLOT_CHECK(ctx.read_pixel(x, ctx.height - 1u - y, px));
+    return static_cast<int>(std::min(px[0], std::min(px[1], px[2])));
+  };
+  // The renderer does not clear -- that is the host's -- and a second draw over the first would double
+  // every trace and change every pixel for reasons that have nothing to do with the frame.
+  const auto draw = [&](bool framed) {
+    if (framed) p.set_selection_rect({200.0f, 100.0f, 200.0f, 120.0f});
+    plot::gl::glClearColor(0.0f, 0.0f, 0.0f, 1.0f);
+    plot::gl::glClear(plot::gl::GL_COLOR_BUFFER_BIT);
+    r.begin_frame(kW, kH, {0, 0, static_cast<plot::f32>(kW), static_cast<plot::f32>(kH)});
+    r.draw(p);
+    r.end_frame();
+  };
+
+  draw(false);
+  const int border_before = floor_of(200, 160);   // the frame's left border, mid-height
+  const int inside_before = floor_of(300, 160);   // the middle of the framed area
+  const int outside_before = floor_of(500, 160);  // to the right of it
+  draw(true);
+  const int border_after = floor_of(200, 160);
+  const int inside_after = floor_of(300, 160);
+  const int outside_after = floor_of(500, 160);
+
+  // A frame, not a wash: the border is nearly opaque, the fill is not.
+  PLOT_CHECK(border_after > inside_after);
+  PLOT_CHECK(border_after > border_before + 60);
+  // A fill, not a panel: it lightens what it covers and leaves it readable.
+  PLOT_CHECK(inside_after > inside_before + 10);
+  // Exactly the rect, and not a pixel beyond it: this is the assertion that the frame matches the area
+  // the gesture is choosing rather than merely being somewhere on screen.
+  PLOT_CHECK(outside_after == outside_before);
+  p.clear_selection_rect();
+}
+
+/// The phosphor density **is the trace**, in the trace's own colour: it covers the axes rect in
+/// `Trace::color`, the newest acquisition is deposited into it like every other -- so it fades, and
+/// no solid polyline is drawn over the ink -- and it costs an upload on the frame a grid moved and
+/// nothing on the frame it did not.
+///
+/// Three things are read off the *screen*, because neither the grid's counts nor a tint alone can
+/// make them: that a saturated cell is the trace's own colour and not a monochrome wash; that a
+/// cell a quarter of the way up the scale is dimmer *and the same hue*; and that the acquisition
+/// just deposited fades -- which is only true if it is *inside* the image and not a stroke drawn
+/// on top of its own faint ghost (the "persistent image + last acquisition" report).
+PLOT_TEST(a_phosphor_density_is_the_trace_in_its_own_colour) {
+  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(std::vector<plot::f32>{0.0f, 0.0f}, 0.0, 1.0);
+  plot::Plot p;
+  p.set_viewport({0.0f, 0.0f, static_cast<plot::f32>(kW), static_cast<plot::f32>(kH)});
+  const plot::u32 ax = p.add_x_axis({"t", {0.0, 1.0}, false, plot::AxisPlace::Bottom, false});
+  const plot::u32 ay = p.add_y_axis({"v", {-1.0, 1.0}, false, plot::AxisPlace::Left, false});
+  const plot::Color trace_color = plot::Color::hex(0x00E070);
+  PLOT_CHECK(p.add_trace({&s, trace_color, 1.5f, ax, ay, "flat"}) == 0u);
+  p.set_x_range(ax, {0.0, 1.0});
+  p.set_y_range(ay, {-1.0, 1.0});
+
+  // The baseline: no density at all, and no grid to draw one from.
+  r.begin_frame(kW, kH, kFrameRect);
+  r.draw(p);
+  r.end_frame();
+  PLOT_CHECK(!r.last_frame_had_gl_error());
+  PLOT_CHECK(r.stats().density_cells == 0u);
+  PLOT_CHECK(r.stats().density_upload_bytes == 0u);
+  const std::vector<plot::u8> without = read_frame(ctx);
+
+  const auto channel = [&](const std::vector<plot::u8>& f, plot::u32 x, plot::u32 y, int c) {
+    return static_cast<int>(f[(plot::usize(y) * kW + x) * 4u + static_cast<plot::usize>(c)]);
+  };
+  const plot::Transform tx = p.x_transform(ax);
+  const plot::Transform ty = p.y_transform(ay);
+  const plot::u32 mid_x = static_cast<plot::u32>(tx.to_screen_x(0.5));
+  const plot::u32 trace_row = static_cast<plot::u32>(ty.to_screen_y(0.0));
+  // A row well away from the sweep, and away from the trace in the no-density frame: the
+  // background to read every cell against, rather than a guessed one.
+  const plot::u32 blank_row = trace_row + 40u < kH ? trace_row + 40u : trace_row - 40u;
+
+  // **The newest acquisition is in the image, and it fades.** A time fade from the first deposit:
+  // one time constant must dim the same pixel, which a stroke drawn over the density could not do.
+  plot::DensityConfig cfg;
+  cfg.enabled = true;
+  cfg.decay = plot::DensityDecay::TimeConstant;
+  cfg.time_constant_s = 1.0f;  // the ceiling stays the library's one sweep -- the trace's own
+  p.set_density(cfg);
+  p.accumulate_density();  // the acquisition on screen, deposited like any other
+
+  r.begin_frame(kW, kH, kFrameRect);
+  r.draw(p);
+  r.end_frame();
+  PLOT_CHECK(!r.last_frame_had_gl_error());
+  dump_if_requested(r, "density.ppm");
+  const plot::FrameStats first = r.stats();
+  const std::vector<plot::u8> fresh = read_frame(ctx);
+
+  // The image is drawn -- it changed pixels -- and every pixel it changed is inside the axes:
+  // a density reserves no layout space and paints nothing over a label strip.
+  const plot::Rect axes = p.layout().axes;
+  plot::u32 lo_x = kW, lo_y = kH, hi_x = 0u, hi_y = 0u, differing = 0u;
+  for (plot::u32 y = 0u; y < kH; ++y) {
+    for (plot::u32 x = 0u; x < kW; ++x) {
+      const plot::usize at = (plot::usize(y) * kW + x) * 4u;
+      if (fresh[at] == without[at] && fresh[at + 1u] == without[at + 1u] &&
+          fresh[at + 2u] == without[at + 2u]) {
+        continue;
+      }
+      ++differing;
+      lo_x = std::min(lo_x, x);
+      lo_y = std::min(lo_y, y);
+      hi_x = std::max(hi_x, x);
+      hi_y = std::max(hi_y, y);
+    }
+  }
+  PLOT_CHECK(differing > 0u);
+  PLOT_CHECK(static_cast<plot::f32>(lo_x) >= axes.x - 1.0f);
+  PLOT_CHECK(static_cast<plot::f32>(hi_x) <= axes.right() + 1.0f);
+  PLOT_CHECK(static_cast<plot::f32>(lo_y) >= axes.y - 1.0f);
+  PLOT_CHECK(static_cast<plot::f32>(hi_y) <= axes.bottom() + 1.0f);
+
+  // One trace, so one grid and one upload of one byte a cell -- and the *same* grid the plot
+  // reports, so the picture and the numbers are one derivation.
+  const plot::DensityGrid& grid = p.density_grid(0u);
+  PLOT_CHECK(first.density_cells == static_cast<plot::u32>(grid.cell_count()));
+  PLOT_CHECK(first.density_upload_bytes == static_cast<plot::u32>(grid.cell_count()));
+
+  // **The colour**: the cell the sweep is in is the trace's own colour at full strength -- one
+  // sweep is the ceiling, so a saturated cell *is* the trace -- and not the near-white monochrome
+  // the density used to draw in. The trace has no red and plenty of green and blue; a monochrome
+  // wash at full ink had all three high and near equal.
+  const int bg_g = channel(fresh, mid_x, blank_row, 1);
+  const int cell_r = channel(fresh, mid_x, trace_row, 0);
+  const int cell_g = channel(fresh, mid_x, trace_row, 1);
+  const int cell_b = channel(fresh, mid_x, trace_row, 2);
+  PLOT_CHECK(cell_r < 40);                            // the trace's colour has no red in it
+  PLOT_CHECK(cell_g > 150);                           // ... and its green is the ink
+  PLOT_CHECK(cell_g > cell_b && cell_b > cell_r);     // the hue is the trace's, not a neutral
+  PLOT_CHECK(cell_g > bg_g + 40);
+  // A saturated cell **is** the trace's colour: one sweep at the ceiling draws the trace's own
+  // rgba, so the pixel matches it exactly rather than merely resembling it.
+  const plot::u8* cell_px = fresh.data() + (plot::usize(trace_row) * kW + mid_x) * 4u;
+  PLOT_CHECK(pixel_is(cell_px, trace_color));
+
+  // One time constant of the same pixel: dimmer, and still the trace's hue. This is the assertion
+  // that the current acquisition is inside the density -- the fade `exp(-dt/tau)`.
+  const double before = grid.ink();
+  p.decay_density(1.0);  // dt = tau, so the whole image is e^-1 of what it was
+  const double after = grid.ink();
+  PLOT_CHECK_NEAR(after / before, std::exp(-1.0), 1e-4);
+  r.begin_frame(kW, kH, kFrameRect);
+  r.draw(p);
+  r.end_frame();
+  PLOT_CHECK(!r.last_frame_had_gl_error());
+  const std::vector<plot::u8> faded = read_frame(ctx);
+  const int faded_g = channel(faded, mid_x, trace_row, 1);
+  const int faded_r = channel(faded, mid_x, trace_row, 0);
+  PLOT_CHECK(faded_g < cell_g - 20);  // the newest acquisition faded
+  PLOT_CHECK(faded_r < 40);           // and it faded *as the trace's colour*, not toward a neutral
+  PLOT_CHECK(faded_g > bg_g);         // ... to more than the background: still on screen
+
+  // **No solid trace over the image.** Move the series to y = +0.5 and draw *without* depositing:
+  // the plot draws no polyline while the density is on, so the +0.5 row is background and the only
+  // ink on screen is the sweep already in the image. A trace drawn over its own ghost -- the
+  // reported "persistent image + last acquisition" -- would put its colour at +0.5 here.
+  s.reset(std::vector<plot::f32>{0.5f, 0.5f}, 0.0, 1.0);
+  r.begin_frame(kW, kH, kFrameRect);
+  r.draw(p);
+  r.end_frame();
+  PLOT_CHECK(!r.last_frame_had_gl_error());
+  const std::vector<plot::u8> moved = read_frame(ctx);
+  const plot::u32 moved_row = static_cast<plot::u32>(ty.to_screen_y(0.5));
+  PLOT_CHECK(moved_row != trace_row);
+  // At +0.5 there is only the grid: the frame with the density is *identical* to the frame without
+  // one there, so nothing was drawn at the moved trace's own row -- no stroke over the image. (The
+  // row the sweep is in still holds its ink, so the image itself did not go away.)
+  PLOT_CHECK(channel(moved, mid_x, moved_row, 1) == channel(without, mid_x, moved_row, 1));
+  PLOT_CHECK(channel(moved, mid_x, moved_row, 0) == channel(without, mid_x, moved_row, 0));
+  PLOT_CHECK(channel(moved, mid_x, trace_row, 1) > bg_g + 20);  // the image is still there
+  s.reset(std::vector<plot::f32>{0.0f, 0.0f}, 0.0, 1.0);
+
+  // **The steady state and a quarter of it, in the signal's colour.** Many acquisitions of a
+  // per-acquisition fade settle at `1/(1-f)` sweeps, which the one-sweep ceiling clamps to the
+  // trace's colour; a decay to a quarter of that ink is dimmer and keeps the hue.
+  plot::DensityConfig steady_cfg = cfg;
+  steady_cfg.decay = plot::DensityDecay::PerAcquisition;
+  steady_cfg.per_acquisition = 0.5f;
+  p.set_density(steady_cfg);
+  for (int i = 0; i < 24; ++i) p.accumulate_density();
+  r.begin_frame(kW, kH, kFrameRect);
+  r.draw(p);
+  r.end_frame();
+  PLOT_CHECK(!r.last_frame_had_gl_error());
+  const std::vector<plot::u8> steady = read_frame(ctx);
+  const int steady_g = channel(steady, mid_x, trace_row, 1);
+  const int steady_r = channel(steady, mid_x, trace_row, 0);
+  PLOT_CHECK(steady_g > bg_g + 60);
+  PLOT_CHECK(steady_r < 40);
+  // A quarter of the ink: `dt = tau*ln(4)` is one step of the time fade to a quarter.
+  plot::DensityConfig quarter_cfg = steady_cfg;
+  quarter_cfg.decay = plot::DensityDecay::TimeConstant;
+  quarter_cfg.time_constant_s = 1.0f;
+  p.set_density(quarter_cfg);
+  const double steady_ink = grid.ink();
+  p.decay_density(std::log(4.0));
+  PLOT_CHECK_NEAR(grid.ink() / steady_ink, 0.25, 1e-6);
+  r.begin_frame(kW, kH, kFrameRect);
+  r.draw(p);
+  r.end_frame();
+  PLOT_CHECK(!r.last_frame_had_gl_error());
+  const std::vector<plot::u8> quarter = read_frame(ctx);
+  const int quarter_g = channel(quarter, mid_x, trace_row, 1);
+  const int quarter_r = channel(quarter, mid_x, trace_row, 0);
+  PLOT_CHECK(steady_g > quarter_g + 20);
+  PLOT_CHECK(quarter_g > bg_g + 10);
+  PLOT_CHECK(quarter_r < 40);  // still the signal's colour, not a neutral wash
+
+  // A frame with nothing new to deposit: the grid did not move, so the conversion and the upload
+  // are skipped -- the frame costs the one draw call -- and the picture is bit-identical.
+  r.begin_frame(kW, kH, kFrameRect);
+  r.draw(p);
+  r.end_frame();
+  PLOT_CHECK(!r.last_frame_had_gl_error());
+  PLOT_CHECK(r.stats().density_cells > 0u);
+  PLOT_CHECK(r.stats().density_upload_bytes == 0u);
+  const std::vector<plot::u8> again = read_frame(ctx);
+  PLOT_CHECK(again == quarter);
+
+  std::printf("[density gl] cells=%u uploaded=%u differing=%u trace row=%u blank row=%u"
+              " axes=%.0f,%.0f %.0fx%.0f\n",
+              first.density_cells, first.density_upload_bytes, differing, trace_row, blank_row,
+              axes.x, axes.y, axes.w, axes.h);
+  std::printf("[density gl] green: bg=%d full=%d faded=%d steady=%d quarter=%d"
+              " (fresh ink %.0f -> %.0f)\n",
+              bg_g, cell_g, faded_g, steady_g, quarter_g, before, after);
+  ctx.destroy();
+}
+
+/// A grid **past `kDensityCellCap`** is the axes rect scaled down, and the frame magnifies the image
+/// back over that rect: this is the screen-side half of the bound --
+/// `a_density_grid_is_capped_whatever_the_window` reads the counts of a capped grid, and the two
+/// agree only if the deposit and the draw use the same footprint, the axes rect in *whole* device
+/// pixels.
+///
+/// What is read here is what a wrong scale moves: the image covers the rect's own columns rather
+/// than the smaller grid's (the assertion a quad drawn at the grid's size fails), it stays inside
+/// the rect, and the sweep is on the row its own transform maps y = 0 to, in the trace's colour.
+PLOT_TEST(a_capped_density_is_magnified_over_the_axes_rect) {
+  const plot::u32 w = 900, h = 720;
+  plottest::HeadlessContext ctx(w, h);
+  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(std::vector<plot::f32>{0.0f, 0.0f}, 0.0, 1.0);
+  plot::Plot p;
+  p.set_viewport({0.0f, 0.0f, static_cast<plot::f32>(w), static_cast<plot::f32>(h)});
+  const plot::u32 ax = p.add_x_axis({"t", {0.0, 1.0}, false, plot::AxisPlace::Bottom, false});
+  const plot::u32 ay = p.add_y_axis({"v", {-1.0, 1.0}, false, plot::AxisPlace::Left, false});
+  const plot::Color colour = plot::Color::hex(0x00E070);
+  PLOT_CHECK(p.add_trace({&s, colour, 1.5f, ax, ay, "flat"}) == 0u);
+  p.set_x_range(ax, {0.0, 1.0});
+  p.set_y_range(ay, {-1.0, 1.0});
+
+  const plot::Rect frame{0.0f, 0.0f, static_cast<plot::f32>(w), static_cast<plot::f32>(h)};
+  r.begin_frame(w, h, frame);
+  r.draw(p);
+  r.end_frame();
+  PLOT_CHECK(!r.last_frame_had_gl_error());
+  const std::vector<plot::u8> without = read_frame(ctx);
+
+  plot::DensityConfig cfg;
+  cfg.enabled = true;
+  p.set_density(cfg);
+  p.accumulate_density();
+  const plot::DensityGrid& grid = p.density_grid(0u);
+  const plot::Rect axes = p.layout().axes;
+  // The rect is past the cap, so the grid is smaller than it and the frame has to scale the image
+  // up -- and the one flat sweep still lights every column, once.
+  PLOT_CHECK(grid.cell_count() > 0u);
+  PLOT_CHECK(grid.cell_count() <= plot::kDensityCellCap);
+  PLOT_CHECK(static_cast<plot::u64>(grid.columns()) < static_cast<plot::u64>(std::ceil(axes.w)));
+  PLOT_CHECK(static_cast<plot::u64>(grid.rows()) < static_cast<plot::u64>(std::ceil(axes.h)));
+  PLOT_CHECK_NEAR(grid.ink(), static_cast<double>(grid.columns()), 1.0);
+
+  r.begin_frame(w, h, frame);
+  r.draw(p);
+  r.end_frame();
+  PLOT_CHECK(!r.last_frame_had_gl_error());
+  const plot::FrameStats stats = r.stats();
+  PLOT_CHECK(stats.density_cells == static_cast<plot::u32>(grid.cell_count()));
+  PLOT_CHECK(stats.density_upload_bytes == static_cast<plot::u32>(grid.cell_count()));
+  const std::vector<plot::u8> capped = read_frame(ctx);
+
+  const auto differs = [&](plot::u32 x, plot::u32 y) {
+    const plot::usize k = (plot::usize(y) * w + x) * 4u;
+    return capped[k] != without[k] || capped[k + 1u] != without[k + 1u] ||
+           capped[k + 2u] != without[k + 2u];
+  };
+  const auto at = [&](const std::vector<plot::u8>& f, plot::u32 x, plot::u32 y, int c) {
+    return static_cast<int>(f[(plot::usize(y) * w + x) * 4u + static_cast<plot::usize>(c)]);
+  };
+
+  // **The image covers the rect's columns, not the grid's.** A quad drawn at the grid's own size --
+  // the temptation once a cell is no longer a pixel -- would paint the left `columns` of the rect
+  // and leave the rest of it blank, which this counts.
+  plot::u32 changed_cols = 0;
+  plot::u32 lo_x = w, hi_x = 0, lo_y = h, hi_y = 0;
+  for (plot::u32 x = 0; x < w; ++x) {
+    bool any = false;
+    for (plot::u32 y = 0; y < h; ++y) {
+      if (!differs(x, y)) continue;
+      any = true;
+      lo_x = std::min(lo_x, x);
+      hi_x = std::max(hi_x, x);
+      lo_y = std::min(lo_y, y);
+      hi_y = std::max(hi_y, y);
+    }
+    if (any) ++changed_cols;
+  }
+  PLOT_CHECK(changed_cols > 0u);
+  PLOT_CHECK(changed_cols + 2u >= static_cast<plot::u32>(axes.w));
+  // ... and it stays inside the rect it is an image of.
+  PLOT_CHECK(static_cast<plot::f32>(lo_x) >= axes.x - 1.0f);
+  PLOT_CHECK(static_cast<plot::f32>(hi_x) <= axes.right() + 1.0f);
+  PLOT_CHECK(static_cast<plot::f32>(lo_y) >= axes.y - 1.0f);
+  PLOT_CHECK(static_cast<plot::f32>(hi_y) <= axes.bottom() + 1.0f);
+
+  // The sweep is on the row its own transform maps y = 0 to, in the trace's own colour: the cell's
+  // one sweep is spread over the block of device pixels it was magnified into, so what is asserted
+  // is that the ink is *there* -- the brightest row of the rect is that row -- and that its hue is
+  // the trace's rather than the background's.
+  const plot::u32 mid_x = static_cast<plot::u32>(p.x_transform(ax).to_screen_x(0.5));
+  const plot::u32 trace_row = static_cast<plot::u32>(p.y_transform(ay).to_screen_y(0.0));
+  // The background to read the ink against is a row of the *without* frame away from the sweep's
+  // own: the trace itself is drawn there (the density is off in that frame), so the trace's own row
+  // is the trace's colour and not a background at all.
+  const plot::u32 blank_row = trace_row + 40u < h ? trace_row + 40u : trace_row - 40u;
+  const int bg_g = at(without, mid_x, blank_row, 1);
+  int band_g = 0;
+  int band_y = 0;
+  for (plot::u32 y = static_cast<plot::u32>(axes.y); y < static_cast<plot::u32>(axes.bottom()); ++y) {
+    const int g = at(capped, mid_x, y, 1);
+    if (g > band_g) {
+      band_g = g;
+      band_y = static_cast<int>(y);
+    }
+  }
+  PLOT_CHECK(band_g > bg_g + 40);                     // the sweep is on screen at all
+  PLOT_CHECK(at(capped, mid_x, trace_row, 0) < 40);   // ... in the trace's own hue ...
+  PLOT_CHECK(at(capped, mid_x, trace_row, 1) > bg_g + 40);
+  PLOT_CHECK(std::abs(band_y - static_cast<int>(trace_row)) <= 2);
+
+  std::printf("[density gl] capped grid=%ux%u cells=%zu of a %.0fx%.0f axes: changed cols=%u"
+              " brightest row=%d (transform says %u), green=%d against bg=%d\n",
+              grid.columns(), grid.rows(), grid.cell_count(), axes.w, axes.h, changed_cols, band_y,
+              trace_row, band_g, bg_g);
+  ctx.destroy();
+}

tests/test_ring_buffer.cpp

@@ -21,6 +21,43 @@ PLOT_TEST(ring_clear_resets) {
   PLOT_CHECK_NEAR(r[0], 42.0);
 }
 
+PLOT_TEST(ring_clear_to_resumes_the_absolute_count) {
+  // A recompute: a derived ring is emptied and refilled from the absolute origin its source
+  // retains, so it has to come back numbered as the source is. `clear()` restarts at 0, which
+  // leaves a refilled ring reporting a produced() a whole window behind an identically fed one.
+  plot::data::RingBuffer<f32> src(8);
+  plot::data::RingBuffer<f32> derived(8);
+  for (int i = 0; i < 20; ++i) {
+    src.push(f32(i));
+    derived.push(f32(i) * 2.0f);
+  }
+  PLOT_CHECK(src.base() == 12);
+
+  derived.clear_to(src.base());
+  for (u64 i = 0; i < src.size(); ++i) derived.push(src[i] * 3.0f);
+
+  // Numbered as the source: same produced(), same base(), and the retained windows pair up.
+  PLOT_CHECK(derived.produced() == src.produced());
+  PLOT_CHECK(derived.base() == src.base());
+  PLOT_CHECK(derived.size() == src.size());
+  PLOT_CHECK_NEAR(derived[0], 36.0);    // 12 * 3
+  PLOT_CHECK_NEAR(derived[7], 57.0);    // 19 * 3
+  // And the absolute reader agrees with the windowed one, which is what a snapshot reads.
+  f32 at = 0.0f;
+  derived.copy_from(19, 1, &at);
+  PLOT_CHECK_NEAR(at, 57.0);
+}
+
+PLOT_TEST(ring_clear_to_zero_is_clear) {
+  plot::data::RingBuffer<f32> r(8);
+  for (int i = 0; i < 5; ++i) r.push(f32(i));
+  r.clear_to(0);
+  PLOT_CHECK(r.size() == 0);
+  PLOT_CHECK(r.produced() == 0);
+  r.push(42.0f);
+  PLOT_CHECK_NEAR(r[0], 42.0);
+}
+
 PLOT_TEST(ring_capacity_rounds_up_to_a_power_of_two) {
   // The capacity is rounded up so slot addressing stays a mask, and capacity()
   // reports the rounded value -- the one callers must size for (R4).
@@ -35,3 +72,27 @@ PLOT_TEST(ring_capacity_rounds_up_to_a_power_of_two) {
   PLOT_CHECK_NEAR(r[0], 872.0);           // oldest retained
   PLOT_CHECK_NEAR(r[127], 999.0);         // newest
 }
+
+PLOT_TEST(ring_amend_rewrites_a_retained_slot) {
+  // Backfill: a slot pushed as a placeholder is rewritten once the data that belongs there
+  // arrives. The index is absolute, because that is the only coordinate a late packet can
+  // compute -- a retained-window index would have moved by the time it got here.
+  plot::data::RingBuffer<f32> r(8);
+  for (int i = 0; i < 6; ++i) r.push(f32(i));
+  PLOT_CHECK(r.amend(3, 42.0f));
+  PLOT_CHECK_NEAR(r[3], 42.0);
+  PLOT_CHECK(r.produced() == 6);   // an amend is not a push
+}
+
+PLOT_TEST(ring_amend_refuses_an_index_the_ring_no_longer_holds) {
+  // The window slides on the producer, so a late amend may arrive after its slot was
+  // overwritten. Writing it anyway would corrupt whatever sample now owns that slot, so the
+  // bounds test is the whole safety of the operation and the caller reads the result.
+  plot::data::RingBuffer<f32> r(8);
+  for (int i = 0; i < 20; ++i) r.push(f32(i));
+  PLOT_CHECK(r.base() == 12);
+  PLOT_CHECK(!r.amend(3, 42.0f));     // aged out
+  PLOT_CHECK(!r.amend(20, 42.0f));    // never produced
+  PLOT_CHECK_NEAR(r[0], 12.0);        // and nothing moved
+  PLOT_CHECK_NEAR(r[7], 19.0);
+}