feat(plot)!: harden pipeline, XY series, dash/markers, touch, packaging

Breaking: Series::gather emits x relative to x0() and takes a GatherMode;
consumers reconstruct absolute x in f64 before mapping (series.hpp documents
the contract).

Bugs, each pinned by a fail-before regression test:
- render: f32 staging quantised epoch-time x into 128 px columns; every
  data-space draw now stages to_space(x) - to_space(origin) with the origin
  folded into the offset uniform in f64 (epoch/zero-origin twins rasterise
  identically)
- ticks: major test was ULP-fragile and blanked epoch axes; majors are an
  integer-index test and are never truncated by the minor cap
- gather: LOD envelope emitted buckets straddling [begin,end); ceil/floor
  bucket edges + raw lead/trail spans
- live follow: log x axes held a linear span and zoomed every frame; span and
  offset now live in axis space (plot + both figure link-group paths)
- input: a zero-notch wheel disarmed auto_scale on every axis; dy==0 pans x,
  factor == 1 / inf refused in wheel and drag zoom
- render: the single text flush painted legend names over the crosshair
  readout panel; two batches, under flushed before the panel
- data: NaN dropped from min/max unless it seeded the fold; non-finite
  samples are now excluded from every aggregate and from cached bounds

Robustness: viewport normalisation (no clamp UB), non-finite range refusal,
pyramid level cap at 57 (no shift/div UB through public gather), rounded ring
capacity documented + pre-sized, GL blend func and UNPACK_ALIGNMENT
save/restore, Renderer::release_gl() teardown, u64 buffer epochs, annotation
captions clamped, button-aware GLFW row capture, cached figure row rects (no
per-event layout), ruler-pair measurement refused, span-nonfinite guards in
axis_ends.

Features: XY series (sorted x, binary-search neighbours/snap, LOD over sample
index); StreamSeries::freeze(); ArraySeries::push(); per-trace dash and
markers (scatter at width 0) with auto or literal stride; GatherMode
Envelope/Nearest/Mean via bucket_sum/sumsq; Style::line_aa_px; per-glyph text
colour (readout values in trace colour); wheel-dx x pan; arrow-key pan;
Escape cancels a drag and restores captured ranges; modifier-masked box zoom
(Shift both, Ctrl x, Alt y); double-click reset via PointerEvent::time_s;
ImGui key repeat unified; pinch gestures on Qt and GTK; pixelDelta wheel path
and DevicePixelRatioChange handling; GNUInstallDirs, SOVERSION,
SameMinorVersion, generated plot/version.hpp, relocatable plot.pc, licence
install, FILES_MATCHING, GitHub Actions CI (debug/coverage/asan).

Suite 283 -> 350 cases, 0 failed; coverage 93.9% (3730/3971) over 24 files,
floor 80/90 held; ASAN preset suite green; all four demos run headless (the
GTK scripted-resize check needs a window manager and fails identically on the
parent commit); readme_main.cpp committed and compiles with the README
command; pkg-config and find_package consumption verified from a relocated
install prefix.

src/data/array_series.cpp

@@ -4,6 +4,7 @@
 #include <plot/data/array_series.hpp>
 
 #include <algorithm>
+#include <cmath>
 #include <cstddef>
 #include <utility>
 
@@ -23,23 +24,45 @@ void ArraySeries::commit() {
   pyramid_.clear();
   pyramid_.reserve(n);
 
+  // Bounds seed on the first *finite* sample and fold the rest: a non-finite
+  // sample is excluded from every aggregate, and a window with none aggregates
+  // to a zero-span Range (the library-wide NaN policy).
   f32 lo = 0.0f, hi = 0.0f;
-  bool first = true;
+  bool finite = false;
   for (const f32 v : y_) {
     pyramid_.append(v);
-    if (first) {
-      lo = v;
-      hi = v;
-      first = false;
-    } else {
+    if (!std::isfinite(v)) continue;
+    if (finite) {
       lo = std::min(lo, v);
       hi = std::max(hi, v);
+    } else {
+      lo = v;
+      hi = v;
+      finite = true;
     }
   }
-  y_bounds_ = first ? Range{0.0, 0.0} : Range{f64(lo), f64(hi)};
+  y_has_finite_ = finite;
+  y_bounds_ = finite ? Range{f64(lo), f64(hi)} : Range{0.0, 0.0};
   x_bounds_ = n == 0 ? Range{x0_, x0_} : Range{x0_, x0_ + f64(n - 1) * dx_};
 }
 
+void ArraySeries::push(f32 v) {
+  y_.push_back(v);
+  pyramid_.append(v);
+  // The incremental twin of commit()'s fold: skip non-finite, seed on the first
+  // finite sample, extend after that.
+  if (std::isfinite(v)) {
+    if (y_has_finite_) {
+      y_bounds_.min = std::min(y_bounds_.min, f64(v));
+      y_bounds_.max = std::max(y_bounds_.max, f64(v));
+    } else {
+      y_bounds_ = Range{f64(v), f64(v)};
+      y_has_finite_ = true;
+    }
+  }
+  x_bounds_ = Range{x0_, x0_ + f64(y_.size() - 1) * dx_};
+}
+
 u64 ArraySeries::size() const { return static_cast<u64>(y_.size()); }
 
 f64 ArraySeries::x0() const { return x0_; }
@@ -52,8 +75,9 @@ Range ArraySeries::y_bounds() const { return y_bounds_; }
 
 const MinMaxPyramid& ArraySeries::pyramid() const { return pyramid_; }
 
-void ArraySeries::gather(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy) const {
-  gather_impl(level, begin, end, out_xy);
+void ArraySeries::gather(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy,
+                         GatherMode mode) const {
+  gather_impl(level, begin, end, out_xy, mode);
 }
 
 void ArraySeries::copy_raw(u64 begin, u64 end, f32* out) const {

src/data/minmax_pyramid.cpp

@@ -12,8 +12,12 @@
 namespace plot::data {
 namespace {
 
-/// Samples covered by one level-l bucket.
-constexpr u64 level_span(u32 l) { return u64{kBucket} << l; }
+/// Samples covered by one level-l bucket. Clamped to kMaxPyramidLevel: the
+/// shift past level 57 would overflow u64 (UB), and a bucket wider than any
+/// u64 sample count is the same bucket as the widest one anyway.
+constexpr u64 level_span(u32 l) {
+  return u64{kBucket} << (l > kMaxPyramidLevel ? kMaxPyramidLevel : l);
+}
 
 /// Level-l buckets needed to hold n samples (ceiling division).
 constexpr u64 buckets_for(u64 n, u32 l) {
@@ -72,11 +76,13 @@ void cover_buckets(const MinMaxPyramid& p, u64 b0, u64 b1, Fn&& fn) {
 }
 
 /// Folds the decomposition of [b0, b1) into a min/max Range. Returns a
-/// zero-span Range when there is nothing to fold.
+/// zero-span Range when there is nothing to fold. Buckets with no finite
+/// sample (count 0) are absent, not zero-valued, and are skipped.
 Range fold_range(const MinMaxPyramid& p, u64 b0, u64 b1) {
   Range r{};
   bool first = true;
   cover_buckets(p, b0, b1, [&](u32 l, u64 i) {
+    if (p.bucket_count(l, i) == 0) return;
     const MinMax m = p.bucket(l, i);
     if (first) {
       r.min = f64(m.min);
@@ -96,10 +102,13 @@ void MinMaxPyramid::add_level() { levels_.emplace_back(); }
 
 void MinMaxPyramid::reserve(u64 n) {
   // Materialise every level n samples can need -- level 0 plus one per doubling
-  // of the bucket -- so a run of appends never grows the level vector. See the
-  // header for why the bucket deques themselves cannot be pre-sized.
+  // of the bucket, capped at kMaxPyramidLevel -- so a run of appends never grows
+  // the level vector. See the header for why the bucket deques themselves cannot
+  // be pre-sized.
   u32 want = 1;
-  for (u64 span = level_span(0); span <= n && want < 63; span <<= 1) ++want;
+  for (u64 span = level_span(0); span <= n && want <= kMaxPyramidLevel; span <<= 1) {
+    ++want;
+  }
   if (levels_.size() < want) levels_.resize(want);
 }
 
@@ -115,20 +124,25 @@ void MinMaxPyramid::push(u32 l, u64 k, const Entry& e) {
 }
 
 void MinMaxPyramid::append(f32 v) {
-  const f64 vd = f64(v);
   // The new sample always lands in the in-progress level-0 bucket, which is the
   // only bucket any append ever touches: a bucket becomes an entry exactly once,
   // complete, and is never rewritten.
-  if (count_ % kBucket == 0) {
-    pending_.mm.min = v;
-    pending_.mm.max = v;
-    pending_.sum = vd;
-    pending_.sumsq = vd * vd;
-  } else {
-    pending_.mm.min = std::min(pending_.mm.min, v);
-    pending_.mm.max = std::max(pending_.mm.max, v);
+  if (count_ % kBucket == 0) pending_ = Entry{};
+  // Non-finite samples occupy their absolute position -- bucket boundaries are
+  // positional, so NaN or not the sample advances count_ and completes its
+  // bucket -- but they are excluded from every aggregate (see the header).
+  if (std::isfinite(v)) {
+    const f64 vd = f64(v);
+    if (pending_.count == 0) {
+      pending_.mm.min = v;
+      pending_.mm.max = v;
+    } else {
+      pending_.mm.min = std::min(pending_.mm.min, v);
+      pending_.mm.max = std::max(pending_.mm.max, v);
+    }
     pending_.sum += vd;
     pending_.sumsq += vd * vd;
+    ++pending_.count;
   }
   ++count_;
   if (count_ % kBucket != 0) return;   // the bucket is still partial: nothing to push
@@ -141,7 +155,8 @@ void MinMaxPyramid::append(f32 v) {
   // Cascade: level l gains an entry exactly when kBucket << l divides the sample
   // count, so the walk stops at the first level that gained nothing -- amortised
   // O(1) per sample (1/kBucket + 1/(2*kBucket) + ... = 1/(kBucket/2) merges).
-  for (u32 l = 1; l < 63; ++l) {
+  // Capped at kMaxPyramidLevel: past it the span shift would overflow.
+  for (u32 l = 1; l <= kMaxPyramidLevel; ++l) {
     const u64 span = level_span(l);
     if (count_ % span != 0) break;
     const u64 k = count_ / span - 1;        // the level-l bucket that just completed
@@ -152,10 +167,14 @@ void MinMaxPyramid::append(f32 v) {
     const Entry& a = at(l - 1, child);
     const Entry& b = at(l - 1, child + 1);
     Entry m;
-    m.mm.min = std::min(a.mm.min, b.mm.min);
-    m.mm.max = std::max(a.mm.max, b.mm.max);
+    // An empty child (count 0) has zero sums and a meaningless mm: it must not
+    // vote 0 into the merge, so a merge with it is just the other child.
+    m.mm = a.count == 0 ? b.mm : (b.count == 0 ? a.mm
+                                               : MinMax{std::min(a.mm.min, b.mm.min),
+                                                        std::max(a.mm.max, b.mm.max)});
     m.sum = a.sum + b.sum;
     m.sumsq = a.sumsq + b.sumsq;
+    m.count = a.count + b.count;
     push(l, k, m);
   }
 }
@@ -225,6 +244,12 @@ u64 MinMaxPyramid::level_size(u32 l) const noexcept {
 
 MinMax MinMaxPyramid::bucket(u32 l, u64 i) const { return at(l, i).mm; }
 
+f64 MinMaxPyramid::bucket_sum(u32 l, u64 i) const { return at(l, i).sum; }
+
+f64 MinMaxPyramid::bucket_sumsq(u32 l, u64 i) const { return at(l, i).sumsq; }
+
+u32 MinMaxPyramid::bucket_count(u32 l, u64 i) const { return at(l, i).count; }
+
 Range MinMaxPyramid::reduce_buckets(u64 begin, u64 end) const {
   const u64 e = std::min(end, size());
   if (begin >= e) return Range{0.0, 0.0};
@@ -265,7 +290,7 @@ u32 MinMaxPyramid::level_for(u64 n, f64 samples_per_pixel) const {
   const f64 ratio = samples_per_pixel / f64(kBucket);
   if (n == 0 || !(ratio > 1.0)) return 0;
   const f64 lg = std::floor(std::log2(ratio));
-  u32 l = lg >= f64(62) ? 62u : static_cast<u32>(lg);
+  u32 l = lg >= f64(kMaxPyramidLevel) ? kMaxPyramidLevel : static_cast<u32>(lg);
   while (l > 0) {
     const bool exists = l < level_count() && level_size(l) >= 2;
     if (exists && buckets_for(n, l) >= 2) break;

src/data/series.cpp

@@ -4,6 +4,7 @@
 #include <plot/data/series.hpp>
 
 #include <algorithm>
+#include <cmath>
 #include <cstddef>
 
 namespace plot::data {
@@ -13,6 +14,9 @@ namespace {
 /// gather path never allocates, and large enough to amortise the call.
 constexpr u64 kGatherChunk = 256;
 
+/// Ceiling division: first multiple of `d` at or after `v`, in `d` units.
+constexpr u64 ceil_div(u64 v, u64 d) { return v / d + (v % d == 0 ? u64{0} : u64{1}); }
+
 }  // namespace
 
 Series::QueryParts Series::split_query(u64 begin, u64 end) const {
@@ -75,6 +79,7 @@ Range Series::reduce(u64 begin, u64 end) const {
   const u64 n = copy_edges(p, edge);
   for (u64 i = 0; i < n; ++i) {
     const f64 v = f64(edge[i]);
+    if (!std::isfinite(v)) continue;   // non-finite samples are excluded (B7)
     if (first) {
       r.min = v;
       r.max = v;
@@ -84,6 +89,8 @@ Range Series::reduce(u64 begin, u64 end) const {
       r.max = std::max(r.max, v);
     }
   }
+  // No finite sample at all (an all-NaN window): a zero-span Range, per the
+  // library-wide NaN policy.
   return first ? Range{0.0, 0.0} : r;
 }
 
@@ -98,7 +105,10 @@ f64 Series::sum(u64 begin, u64 end) const {
   }
   f32 edge[2 * kBucket];
   const u64 n = copy_edges(p, edge);
-  for (u64 i = 0; i < n; ++i) total += f64(edge[i]);
+  for (u64 i = 0; i < n; ++i) {
+    const f64 v = f64(edge[i]);
+    if (std::isfinite(v)) total += v;   // non-finite samples are excluded (B7)
+  }
   return total;
 }
 
@@ -115,27 +125,73 @@ f64 Series::sumsq(u64 begin, u64 end) const {
   const u64 n = copy_edges(p, edge);
   for (u64 i = 0; i < n; ++i) {
     const f64 v = f64(edge[i]);
-    total += v * v;
+    if (std::isfinite(v)) total += v * v;   // non-finite samples are excluded (B7)
   }
   return total;
 }
 
+f64 Series::x_at(u64 i) const { return x0() + f64(i) * dx(); }
+
+bool Series::neighbours(f64 x, u64& i0, u64& i1) const {
+  const u64 n = size();
+  if (n == 0) return false;
+  const f64 lo = x_at(0);
+  const f64 hi = x_at(n - 1);
+  if (!(x >= lo && x <= hi)) return false;
+  const f64 step = dx();
+  if (!(step > 0.0)) {
+    i0 = 0;
+    i1 = 0;
+    return true;
+  }
+  const f64 t = (x - lo) / step;
+  const u64 k = x >= hi ? n - 1 : static_cast<u64>(t);   // floor, in range
+  // An exact hit collapses to one index, whatever the division above rounded
+  // to: compare against the samples themselves, not against t's fraction.
+  if (x_at(k) == x) {
+    i0 = k;
+    i1 = k;
+    return true;
+  }
+  if (k + 1 < n && x_at(k + 1) == x) {
+    i0 = k + 1;
+    i1 = k + 1;
+    return true;
+  }
+  i0 = k;
+  i1 = k + 1 < n ? k + 1 : k;
+  return true;
+}
+
+u64 Series::snap_index(f64 x) const {
+  const u64 n = size();
+  if (n == 0) return 0;
+  const f64 step = dx();
+  if (!(step > 0.0)) return 0;
+  const f64 k = std::round((x - x0()) / step);
+  // The first test also rejects NaN (every comparison with it is false), which
+  // would otherwise reach the u64 cast undefined.
+  if (!(k > 0.0)) return 0;
+  if (k >= f64(n)) return n - 1;
+  return static_cast<u64>(k);
+}
+
 void Series::gather_raw(u64 begin, u64 end, std::vector<f32>& out_xy) const {
-  const f64 x_0 = x0();
   const f64 step = dx();
   f32 raw[kGatherChunk];
   for (u64 i = begin; i < end;) {
     const u64 take = std::min<u64>(kGatherChunk, end - i);
     copy_raw(i, i + take, raw);
     for (u64 k = 0; k < take; ++k) {
-      out_xy.push_back(f32(x_0 + f64(i + k) * step));
+      out_xy.push_back(f32(f64(i + k) * step));   // x relative to x0(): see gather()
       out_xy.push_back(raw[k]);
     }
     i += take;
   }
 }
 
-void Series::gather_impl(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy) const {
+void Series::gather_impl(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy,
+                         GatherMode mode) const {
   const u64 n = size();
   const u64 b = std::min(begin, n);
   const u64 e = std::min(std::max(end, b), n);
@@ -145,28 +201,37 @@ void Series::gather_impl(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy
     gather_raw(b, e, out_xy);
     return;
   }
+  // Public levels clamp to the deepest representable one (R3): past
+  // kMaxPyramidLevel the bucket-span shift would overflow, and the widest
+  // bucket there is is already wider than any window.
+  level = std::min(level, kMaxPyramidLevel);
 
-  // Level >= 1: one envelope pair per *retained* bucket the range overlaps, x at
-  // the bucket's first sample (min) and at its last sample (max), which keeps x
-  // monotonic while covering the bucket's span. The pyramid's buckets are
-  // absolute, so map the window range onto its grid and clamp to the buckets that
-  // are both complete and wholly inside the window: a bucket that is only partly
-  // retained aggregates samples the window no longer has, and a partial trailing
-  // bucket is not stored at all.
+  // Level >= 1: one geometry element per *retained* bucket the range overlaps.
+  // The pyramid's buckets are absolute, so map the window range onto its grid
+  // and clamp to the buckets that are both complete and wholly inside the
+  // requested range: `first` is the first bucket whose span starts at or after
+  // `begin` (ceiling, so the bucket cannot reach left of the range) and `last`
+  // is one past the last bucket whose span ends at or before `end` (floor, so
+  // it cannot reach right of it). This is the B3 fix: a floor on `first` (or a
+  // bucket containing `end - 1`) emitted aggregates that covered samples
+  // outside [begin, end), so the envelope was wrong for any unaligned range.
+  // Buckets that are only partly *retained* are also excluded by construction:
+  // stored entries are complete aggregates of their own span, and a partial
+  // trailing bucket is never stored.
   //
-  // Those two excluded buckets are still part of the range, and one of them holds
-  // the newest samples -- for a live trace, the part being watched. They are drawn
-  // from the raw samples instead: at most one bucket at each end, about a pixel
-  // each at the level level_for() picks, so the envelope path stays O(buckets)
-  // and the geometry still spans the requested range exactly.
-  const f64 x_0 = x0();
+  // The two excluded spans at the edges -- [b, lead) and [trail, e) -- are part
+  // of the range, and one of them holds the newest samples -- for a live trace,
+  // the part being watched. They are drawn from the raw samples instead: at
+  // most one bucket at each end, about a pixel each at the level level_for()
+  // picks, so the envelope path stays O(buckets) and the geometry still spans
+  // the requested range exactly, for every mode.
   const f64 step = dx();
   const u64 span = u64{kBucket} << level;
   const u64 origin = pyramid().window_base();
   const u64 lbase = pyramid().level_base(level);
   const u64 lend = lbase + pyramid().level_size(level);
-  const u64 first = std::max((origin + b) / span, lbase);
-  const u64 last = std::min((origin + e - 1) / span + 1, lend);
+  const u64 first = std::max(ceil_div(origin + b, span), lbase);
+  const u64 last = std::min((origin + e) / span, lend);
   if (first >= last) {
     // No complete bucket of this level is inside the range -- a window squeezed
     // into one bucket -- so the raw samples are the only exact geometry there is.
@@ -175,15 +240,56 @@ void Series::gather_impl(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy
   }
   const u64 lead = first * span - origin;   // window index the first emitted bucket starts at
   if (b < lead) gather_raw(b, std::min(lead, e), out_xy);
-  for (u64 bi = first; bi < last; ++bi) {
-    const MinMax m = pyramid().bucket(level, bi);
-    const u64 first_sample = bi * span - origin;   // >= 0: stored buckets start inside the window
-    const u64 last_sample = std::min((bi + 1) * span, origin + e) - 1 - origin;
-    out_xy.push_back(f32(x_0 + f64(first_sample) * step));
-    out_xy.push_back(m.min);
-    out_xy.push_back(f32(x_0 + f64(last_sample) * step));
-    out_xy.push_back(m.max);
+
+  switch (mode) {
+    case GatherMode::Envelope: {
+      // One (min, max) pair per bucket, x at the bucket's first sample (min)
+      // and at its last sample (max), which keeps x monotonic while covering
+      // the bucket's span. A bucket with no finite sample is absent, not
+      // zero-valued, and emits nothing.
+      for (u64 bi = first; bi < last; ++bi) {
+        if (pyramid().bucket_count(level, bi) == 0) continue;
+        const MinMax m = pyramid().bucket(level, bi);
+        const u64 first_sample = bi * span - origin;   // >= 0: stored buckets start inside the window
+        const u64 last_sample = std::min((bi + 1) * span, origin + e) - 1 - origin;
+        out_xy.push_back(f32(f64(first_sample) * step));   // x relative to x0()
+        out_xy.push_back(m.min);
+        out_xy.push_back(f32(f64(last_sample) * step));
+        out_xy.push_back(m.max);
+      }
+      break;
+    }
+    case GatherMode::Nearest: {
+      // One raw sample per bucket, picked the way pyramid().snap() would pick
+      // it: the sample nearest the bucket's centre, which on the fixed grid is
+      // the centre sample itself. x is at the sample; the value is raw, so a
+      // bucket whose centre sample is non-finite contributes that NaN, exactly
+      // as level 0 would have drawn it.
+      for (u64 bi = first; bi < last; ++bi) {
+        const u64 centre = bi * span + span / 2 - origin;   // inside [b, e): the bucket is wholly inside
+        f32 v = 0.0f;
+        copy_raw(centre, centre + 1, &v);
+        out_xy.push_back(f32(f64(centre) * step));   // x relative to x0()
+        out_xy.push_back(v);
+      }
+      break;
+    }
+    case GatherMode::Mean: {
+      // One point per bucket, y = the bucket's finite samples' mean (the exact
+      // sum the bucket stores, divided by its finite count) and x at the
+      // bucket's centre. A bucket with no finite sample has no mean and emits
+      // nothing.
+      for (u64 bi = first; bi < last; ++bi) {
+        const u32 count = pyramid().bucket_count(level, bi);
+        if (count == 0) continue;
+        const u64 centre = bi * span + span / 2 - origin;
+        out_xy.push_back(f32(f64(centre) * step));   // x relative to x0()
+        out_xy.push_back(f32(pyramid().bucket_sum(level, bi) / f64(count)));
+      }
+      break;
+    }
   }
+
   const u64 trail = last * span - origin;   // one past the last emitted bucket's span
   if (trail < e) gather_raw(trail, e, out_xy);
 }

src/data/stream_series.cpp

@@ -18,8 +18,11 @@ constexpr u64 kReadChunk = 256;
 StreamSeries::StreamSeries(u64 capacity, f64 x0, f64 dx)
     : ring_(capacity), x0_(x0), dx_(dx) {
   // Size the pyramid's level table for a full window up front: the ring never
-  // holds more than capacity() samples, so appending never grows it.
-  pyramid_.reserve(capacity);
+  // holds more than capacity() samples, so appending never grows it. The ring
+  // rounded the request up to a power of two, and the window it will hold is
+  // the *rounded* capacity -- reserving the raw argument would under-size a
+  // non-power-of-two request exactly when the stream saturates (R4).
+  pyramid_.reserve(ring_.capacity());
 }
 
 void StreamSeries::push(f32 y) { ring_.push(y); }
@@ -60,6 +63,15 @@ void StreamSeries::acquire() {
   y_bounds_ = reduce(0, size());
 }
 
+ArraySeries StreamSeries::freeze() const {
+  // The window of the last acquire(), copied out once: the frozen series owns
+  // its samples, so nothing the producer does afterwards can move it.
+  const u64 n = size();
+  std::vector<f32> y(static_cast<usize>(n));
+  if (n > 0) copy_raw(0, n, y.data());
+  return ArraySeries(std::move(y), x0(), dx());
+}
+
 u64 StreamSeries::size() const { return pyramid_.size(); }
 
 f64 StreamSeries::x0() const { return x0_ + f64(pyramid_.window_base()) * dx_; }
@@ -75,8 +87,9 @@ Range StreamSeries::y_bounds() const { return y_bounds_; }
 
 const MinMaxPyramid& StreamSeries::pyramid() const { return pyramid_; }
 
-void StreamSeries::gather(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy) const {
-  gather_impl(level, begin, end, out_xy);
+void StreamSeries::gather(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy,
+                          GatherMode mode) const {
+  gather_impl(level, begin, end, out_xy, mode);
 }
 
 void StreamSeries::copy_raw(u64 begin, u64 end, f32* out) const {

src/data/xy_series.cpp

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#include <plot/data/xy_series.hpp>
+
+#include <algorithm>
+#include <cassert>
+#include <cmath>
+#include <cstddef>
+#include <utility>
+
+namespace plot::data {
+namespace {
+
+/// Ceiling division: the first level-`l` bucket whose whole span starts at or
+/// after `v` samples (in bucket units).
+constexpr u64 ceil_div(u64 v, u64 d) { return v / d + (v % d == 0 ? u64{0} : u64{1}); }
+
+}  // namespace
+
+XYSeries::XYSeries(std::vector<f64> x, std::vector<f32> y) { reset(std::move(x), std::move(y)); }
+
+void XYSeries::reset(std::vector<f64> x, std::vector<f32> y) {
+  // The binary searches below (and every O(log n) consumer of them) are only
+  // correct on sorted input; see the header for the precondition.
+  assert(x.size() == y.size());
+  assert(std::is_sorted(x.begin(), x.end()) && "XYSeries requires x sorted ascending");
+  x_ = std::move(x);
+  y_ = std::move(y);
+  commit();
+}
+
+void XYSeries::commit() {
+  const u64 n = static_cast<u64>(y_.size());
+  pyramid_.clear();
+  pyramid_.reserve(n);
+
+  // Same NaN-aware fold as ArraySeries::commit(): non-finite y is excluded
+  // from the cached bounds, and a window with no finite sample aggregates to a
+  // zero-span Range. (The pyramid's append() applies the same policy per
+  // bucket.) The x bounds come straight from the sorted array's ends.
+  f32 lo = 0.0f, hi = 0.0f;
+  bool finite = false;
+  for (const f32 v : y_) {
+    pyramid_.append(v);
+    if (!std::isfinite(v)) continue;
+    if (finite) {
+      lo = std::min(lo, v);
+      hi = std::max(hi, v);
+    } else {
+      lo = v;
+      hi = v;
+      finite = true;
+    }
+  }
+  y_has_finite_ = finite;
+  y_bounds_ = finite ? Range{f64(lo), f64(hi)} : Range{0.0, 0.0};
+  x_bounds_ = n == 0 ? Range{0.0, 0.0} : Range{x_.front(), x_.back()};
+}
+
+u64 XYSeries::size() const { return static_cast<u64>(y_.size()); }
+
+f64 XYSeries::x0() const { return x_.empty() ? 0.0 : x_.front(); }
+
+f64 XYSeries::dx() const { return 0.0; }
+
+Range XYSeries::x_bounds() const { return x_bounds_; }
+
+Range XYSeries::y_bounds() const { return y_bounds_; }
+
+const MinMaxPyramid& XYSeries::pyramid() const { return pyramid_; }
+
+f64 XYSeries::x_at(u64 i) const { return x_[static_cast<usize>(i)]; }
+
+bool XYSeries::neighbours(f64 x, u64& i0, u64& i1) const {
+  const u64 n = size();
+  if (n == 0) return false;
+  // Also rejects NaN: every comparison with it is false.
+  if (!(x >= x_.front() && x <= x_.back())) return false;
+  // Last sample at or left of x, first at or right of it. Both searches are in
+  // range: x >= front puts a lower_bound hit at index >= 1's predecessor at 0,
+  // and x <= back caps upper_bound's predecessor at n - 1.
+  const auto up = std::upper_bound(x_.begin(), x_.end(), x);
+  const auto lo = std::lower_bound(x_.begin(), x_.end(), x);
+  i0 = static_cast<u64>(up - x_.begin()) - 1;
+  i1 = static_cast<u64>(lo - x_.begin());
+  return true;
+}
+
+u64 XYSeries::snap_index(f64 x) const {
+  const u64 n = size();
+  if (n == 0) return 0;
+  if (!(x > x_.front())) return 0;      // at or left of the first sample; NaN too
+  if (x >= x_.back()) return n - 1;
+  const auto it = std::lower_bound(x_.begin(), x_.end(), x);
+  const u64 hi = static_cast<u64>(it - x_.begin());
+  const u64 lo = hi - 1;                // hi >= 1: x is strictly past x_.front()
+  return (x - x_[static_cast<usize>(lo)]) <= (x_[static_cast<usize>(hi)] - x)
+             ? lo
+             : hi;                      // ties go to the lower index
+}
+
+void XYSeries::gather(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy,
+                      GatherMode mode) const {
+  const u64 n = size();
+  const u64 b = std::min(begin, n);
+  const u64 e = std::min(std::max(end, b), n);
+  if (b >= e) return;
+
+  // x emitted relative to x0(): see Series::gather(). The x array is f64, so
+  // the subtraction happens wide and only the small, exact offset narrows.
+  const f64 origin = x0();
+
+  if (level == 0) {
+    for (u64 i = b; i < e; ++i) {
+      out_xy.push_back(f32(x_[static_cast<usize>(i)] - origin));
+      out_xy.push_back(y_[static_cast<usize>(i)]);
+    }
+    return;
+  }
+  level = std::min(level, kMaxPyramidLevel);
+
+  // The bucket grid is the sample index, exactly as for a uniform series, and
+  // an XYSeries never slides its window, so the pyramid's base is 0 and the
+  // window range needs no origin shift. Bucket selection is the B3-correct
+  // ceil/floor: `first` is the first bucket whose samples all sit at or after
+  // `begin`, `last` one past the last bucket wholly before `end`, and the two
+  // edge spans around them are read from the raw arrays -- so no emitted
+  // geometry comes from outside [begin, end), and the emitted x values are the
+  // array's own coordinates relative to x0().
+  const u64 span = u64{kBucket} << level;
+  const u64 lend = pyramid().level_size(level);
+  const u64 first = std::min(ceil_div(b, span), lend);
+  const u64 last = std::min(e / span, lend);
+  if (first >= last) {
+    for (u64 i = b; i < e; ++i) {
+      out_xy.push_back(f32(x_[static_cast<usize>(i)] - origin));
+      out_xy.push_back(y_[static_cast<usize>(i)]);
+    }
+    return;
+  }
+  const u64 lead = first * span;
+  for (u64 i = b; i < lead; ++i) {
+    out_xy.push_back(f32(x_[static_cast<usize>(i)] - origin));
+    out_xy.push_back(y_[static_cast<usize>(i)]);
+  }
+
+  switch (mode) {
+    case GatherMode::Envelope: {
+      for (u64 bi = first; bi < last; ++bi) {
+        if (pyramid().bucket_count(level, bi) == 0) continue;
+        const MinMax m = pyramid().bucket(level, bi);
+        const u64 lo = bi * span;                          // the bucket's first sample
+        const u64 hi = std::min((bi + 1) * span, e) - 1;   // its last sample inside the range
+        out_xy.push_back(f32(x_[static_cast<usize>(lo)] - origin));
+        out_xy.push_back(m.min);
+        out_xy.push_back(f32(x_[static_cast<usize>(hi)] - origin));
+        out_xy.push_back(m.max);
+      }
+      break;
+    }
+    case GatherMode::Nearest: {
+      for (u64 bi = first; bi < last; ++bi) {
+        const u64 centre = bi * span + span / 2;   // inside the bucket, hence inside [b, e)
+        out_xy.push_back(f32(x_[static_cast<usize>(centre)] - origin));
+        out_xy.push_back(y_[static_cast<usize>(centre)]);
+      }
+      break;
+    }
+    case GatherMode::Mean: {
+      for (u64 bi = first; bi < last; ++bi) {
+        const u32 count = pyramid().bucket_count(level, bi);
+        if (count == 0) continue;
+        const u64 centre = bi * span + span / 2;
+        out_xy.push_back(f32(x_[static_cast<usize>(centre)] - origin));
+        out_xy.push_back(f32(pyramid().bucket_sum(level, bi) / f64(count)));
+      }
+      break;
+    }
+  }
+
+  const u64 trail = last * span;
+  for (u64 i = trail; i < e; ++i) {
+    out_xy.push_back(f32(x_[static_cast<usize>(i)] - origin));
+    out_xy.push_back(y_[static_cast<usize>(i)]);
+  }
+}
+
+void XYSeries::copy_raw(u64 begin, u64 end, f32* out) const {
+  const u64 want = end > begin ? end - begin : 0;
+  if (want == 0) return;
+  const u64 n = size();
+  const u64 b = std::min(begin, n);
+  const u64 e = std::min(std::max(end, b), n);
+  std::copy(y_.begin() + static_cast<std::ptrdiff_t>(b),
+            y_.begin() + static_cast<std::ptrdiff_t>(e), out);
+  std::fill(out + static_cast<std::ptrdiff_t>(e - b),
+            out + static_cast<std::ptrdiff_t>(want), 0.0f);
+}
+
+}  // namespace plot::data