@pond-ts/charts 0.49.0 → 0.51.0

package/dist/area.js

@@ -1,7 +1,90 @@
 import { area as d3area, curveLinear } from 'd3-shape';
+import { strokeAffinePolyline } from './line.js';
 import { bridgeGaps, collectGapEdges, drawGapBridges, drawGapFades, drawGapSteps, withAlpha, DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
 import { cullChartSeries } from './culling.js';
-import { decimateM4 } from './decimate.js';
+import { decimateM4Cached } from './decimate.js';
+import { affineOf } from './affine.js';
+/**
+ * Per-buffer cache of a column's finite `[min, max]` value extent ([PND-GRADX]).
+ * The area fill gradient spans the **full** series' vertical pixel extent (so a
+ * culled/zoomed view still shades identically — see {@link buildGradient}), which
+ * previously meant an O(N) min/max walk on **every** repaint, including each
+ * y-zoom / y-autorange frame where the data hasn't changed (the 2026-07 bench
+ * profile's mountain@1M ceiling; see
+ * `docs/notes/charts-bench-vs-scichart-suite-2026-07.md`, finding 2).
+ *
+ * The extent is a pure function of the value buffer, so it is memoized on the
+ * `y` `Float64Array` (immutable by the {@link ChartSeries} contract): a y-zoom /
+ * pan reuses the same buffer → cache hit (no walk); a live re-materialization
+ * mints a new buffer → recompute once. The `WeakMap` evicts with the buffer, so
+ * there is no leak. Callers pass the full-series `length` (the buffer's logical
+ * length); a `subarray` view is never the cache key here (the gradient reads the
+ * pre-cull full series).
+ *
+ * NaN (the gap signal) is ignored — matching {@link areaExtent} / `yExtent` — so
+ * a coast doesn't drag the span. `null` when nothing is finite (the caller then
+ * falls back to a flat fill).
+ */
+const columnExtentCache = new WeakMap();
+export function columnFiniteExtent(y, length) {
+    const cached = columnExtentCache.get(y);
+    if (cached !== undefined)
+        return cached;
+    let min = Infinity;
+    let max = -Infinity;
+    for (let i = 0; i < length; i += 1) {
+        const v = y[i];
+        if (Number.isFinite(v)) {
+            if (v < min)
+                min = v;
+            if (v > max)
+                max = v;
+        }
+    }
+    const extent = min === Infinity ? null : [min, max];
+    columnExtentCache.set(y, extent);
+    return extent;
+}
+/**
+ * Fill the area between an affine-mapped value polyline and a constant baseline
+ * pixel — the [PND-AFFINE] fast path for {@link drawArea}'s fill, the counterpart
+ * to {@link strokeAffinePolyline} for its outline. Emits one **independent closed
+ * polygon per finite run** (matching `d3.area`'s `.defined(Number.isFinite)`
+ * segmentation for a linear curve + constant `y0`): per run `[a, b)`,
+ * `moveTo(top_a)` → `lineTo(top…)` along the value edge → `lineTo(x_{b-1}, base)`
+ * → `lineTo(x_a, base)` → `closePath`. That is the same filled region `d3.area`
+ * draws — its flat backward baseline edge only adds collinear interior vertices,
+ * which don't change the fill — without the per-point `scale()` / d3-shape
+ * closures. A signed value edge crossing the baseline stays one polygon (no NaN),
+ * filled correctly on both sides. The caller brackets `beginPath`/`fill`;
+ * `xs`/`ys` are aligned index-for-index.
+ */
+export function fillAffineArea(ctx, xs, ys, baselinePx, ax, ay) {
+    const n = ys.length;
+    let runStart = -1; // index of the current finite run's first point, or -1
+    for (let j = 0; j <= n; j += 1) {
+        const finite = j < n && Number.isFinite(ys[j]);
+        if (finite) {
+            const px = ax.k * xs[j] + ax.b;
+            const py = ay.k * ys[j] + ay.b;
+            if (runStart < 0) {
+                runStart = j;
+                ctx.moveTo(px, py);
+            }
+            else {
+                ctx.lineTo(px, py);
+            }
+        }
+        else if (runStart >= 0) {
+            // Close the run: drop to the baseline under the last point, run flat back
+            // to the first point's x, close. (j-1 is the run's last finite index.)
+            ctx.lineTo(ax.k * xs[j - 1] + ax.b, baselinePx);
+            ctx.lineTo(ax.k * xs[runStart] + ax.b, baselinePx);
+            ctx.closePath();
+            runStart = -1;
+        }
+    }
+}
 /**
  * The `[min, max]` vertical extent an area occupies — the finite values of
  * `cs.y` widened to include `baseline`, since the fill spans from each value to
@@ -73,41 +156,51 @@ export function areaExtent(cs, baseline) {
  * are collected by one O(N) walk ({@link collectGapEdges}).
  */
 export function drawArea(ctx, cs, xScale, yScale, style, baselineValue, curve = curveLinear, gaps = DEFAULT_GAP_MODE, gapConnectorOpacity = DEFAULT_GAP_CONNECTOR_OPACITY, decimate = true) {
+    const sourceCount = cs.length; // pre-cull, pre-decimation (for draw stats)
     const baselinePx = yScale(baselineValue);
     // The fill gradient's vertical extent is computed from the **full** series (a
     // vertical, position-anchored gradient spanning the data's whole pixel extent)
     // so viewport culling stays behavior-neutral: the culled path below paints the
-    // exact same visible pixels under the same gradient. This is a cheap O(N)
-    // min/max scan; the expensive per-point path work (fill + outline) culls. (Cull
-    // the region too and the shade would drift under pan as off-screen extrema
-    // enter/leave — a visible change culling must not make.)
-    const fullYs = gaps === 'none' ? bridgeGaps(cs.y, cs.length) : cs.y;
-    const fill = buildGradient(ctx, fullYs, cs.length, yScale, baselinePx, style);
-    // Viewport culling (Phase 2): the path, outline, and gap bridges walk the
-    // visible slice (+1 entry/exit point) only. A no-op — the same `cs` back — when
-    // fully in view or `xScale` has no domain (a test stub), keeping that hot path
-    // byte-identical.
-    cs = cullChartSeries(cs, xScale);
-    // M4 decimation (Phase 3): the outline is a line, so the same {@link decimateM4}
-    // pre-pass shrinks the fill + outline + gap-bridge work to O(plot width) once
-    // dense — with the §2.2 gap-edge union so every gap mode composes. The gradient
-    // above is over the FULL series, so the decimated fill paints identical pixels
-    // under it. Gated off a smoothing `curve`; a no-op on a sparse slice / test scale.
+    // exact same visible pixels under the same gradient. (Cull the region too and
+    // the shade would drift under pan as off-screen extrema enter/leave — a visible
+    // change culling must not make.) [PND-GRADX]: the value extent is memoized per
+    // column buffer ({@link columnFiniteExtent}), so a y-zoom / pan frame reuses it
+    // instead of re-walking O(N) — the mountain@1M ceiling the bench profile
+    // flagged. A `'none'` bridge only fills interior gaps with interpolated values
+    // that stay within the finite extent, so the plain extent is exact for it too.
+    const fill = buildGradient(ctx, columnFiniteExtent(cs.y, cs.length), yScale, baselinePx, style);
+    // Clip `cs` to what draws. **Decimated** (linear curve, `decimate !== false`):
+    // cull to the visible slice, then the same {@link decimateM4} pre-pass shrinks
+    // the fill + outline + gap-bridge work to O(plot width) once dense (the §2.2
+    // gap-edge union so every gap mode composes; the FULL-series gradient above
+    // paints identical pixels under the decimated fill). Cull + decimate are
+    // **memoized per source** ({@link decimateM4Cached}) so a y-zoom / y-autorange
+    // frame reuses the prior polyline instead of re-binning O(N) — the decimation
+    // output never reads the y-scale (finding 3). **Full-resolution** (a smoothing
+    // curve, or `decimate === false`): just cull the visible slice (+1 entry/exit
+    // point); a no-op — the same `cs` back — when fully in view or `xScale` has no
+    // domain (a test stub), keeping that hot path byte-identical.
+    const source = cs; // pre-cull source — the decimation cache key ([PND-DECKEY])
+    let decimated = false;
     if (decimate !== false && curve === curveLinear) {
         const k = typeof decimate === 'object' ? decimate.threshold : undefined;
-        cs = decimateM4(cs, xScale, ctx, k);
+        const r = decimateM4Cached(source, xScale, ctx, k);
+        cs = r.series;
+        decimated = r.decimated;
+    }
+    else {
+        cs = cullChartSeries(source, xScale);
     }
     // `none` interpolates interior gaps so the fill + outline bridge them; every
     // other mode keeps NaN so d3 breaks both (the inferred line bridge, if any, is
     // a separate overlay pass below).
     const ys = gaps === 'none' ? bridgeGaps(cs.y, cs.length) : cs.y;
-    const gen = d3area()
-        .defined((v) => Number.isFinite(v))
-        .x((_, i) => xScale(cs.x[i]))
-        .y0(() => baselinePx)
-        .y1((v) => yScale(v))
-        .curve(curve)
-        .context(ctx);
+    // [PND-AFFINE] fast path: with a linear curve and both scales affine, draw the
+    // fill polygon + outline with inline multiply-add over the typed arrays, past
+    // the per-point d3-scale + d3-shape closures (finding 1/2). A smoothing curve
+    // or a non-affine (real-gap trading) x scale keeps the exact d3-area path.
+    const ax = curve === curveLinear ? affineOf(xScale) : null;
+    const ay = ax !== null ? affineOf(yScale) : null;
     ctx.save();
     // The fill: a vertical gradient anchored at the baseline pixel, opaque at the
     // line and transparent at the baseline (see buildGradient — handles both the
@@ -116,16 +209,32 @@ export function drawArea(ctx, cs, xScale, yScale, style, baselineValue, curve =
     ctx.fillStyle = fill;
     ctx.globalAlpha = style.fillOpacity;
     ctx.beginPath();
-    gen(ys);
+    // The d3-area generator (slow path only) — also the source of the outline line.
+    let outline = null;
+    if (ax !== null && ay !== null) {
+        fillAffineArea(ctx, cs.x, ys, baselinePx, ax, ay);
+    }
+    else {
+        const gen = d3area()
+            .defined((v) => Number.isFinite(v))
+            .x((_, i) => xScale(cs.x[i]))
+            .y0(() => baselinePx)
+            .y1((v) => yScale(v))
+            .curve(curve)
+            .context(ctx);
+        gen(ys);
+        outline = gen.lineY1();
+    }
     ctx.fill();
     ctx.restore();
-    // The outline on top: the area's top edge as a line (`lineY1` inherits the
-    // area's `defined`, `curve`, and `context`, so it breaks at the same gaps),
-    // at full opacity over the graded fill.
-    const outline = gen.lineY1();
+    // The outline on top: the area's top edge as a line (breaks at the same gaps
+    // as the fill), at full opacity over the graded fill.
     ctx.save();
     ctx.beginPath();
-    outline(ys);
+    if (outline !== null)
+        outline(ys);
+    else
+        strokeAffinePolyline(ctx, cs.x, ys, ax, ay);
     ctx.strokeStyle = style.color;
     ctx.lineWidth = style.width;
     ctx.stroke();
@@ -145,6 +254,7 @@ export function drawArea(ctx, cs, xScale, yScale, style, baselineValue, curve =
             drawGapFades(ctx, edges, baselinePx, style.color, style.width);
         }
     }
+    return { sourceCount, drawnCount: cs.length, decimated };
 }
 /**
  * A vertical `CanvasGradient` for the fill, spanning the drawn region's pixel
@@ -164,21 +274,17 @@ export function drawArea(ctx, cs, xScale, yScale, style, baselineValue, curve =
  * finite point, or values exactly on the baseline) — a zero-height gradient
  * would paint nothing.
  */
-function buildGradient(ctx, ys, length, yScale, baselinePx, style) {
-    let topPx = Infinity; // smallest pixel y (highest on screen)
-    let bottomPx = -Infinity; // largest pixel y (lowest on screen)
-    for (let i = 0; i < length; i += 1) {
-        const v = ys[i];
-        if (!Number.isFinite(v))
-            continue;
-        const py = yScale(v);
-        if (py < topPx)
-            topPx = py;
-        if (py > bottomPx)
-            bottomPx = py;
-    }
-    if (topPx === Infinity)
+function buildGradient(ctx, valueExtent, yScale, baselinePx, style) {
+    if (valueExtent === null)
         return style.fill; // no finite values (caller no-ops)
+    // The pixel extent is the two value extremes mapped through the (monotonic,
+    // always-`scaleLinear`) y scale; min/max them so the result is flip-agnostic,
+    // exactly as the former per-point pixel scan produced. [PND-GRADX] moved the
+    // O(N) walk into the memoized {@link columnFiniteExtent}.
+    const pa = yScale(valueExtent[0]);
+    const pb = yScale(valueExtent[1]);
+    const topPx = Math.min(pa, pb); // smallest pixel y (highest on screen)
+    const bottomPx = Math.max(pa, pb); // largest pixel y (lowest on screen)
     // The drawn region runs from the topmost of {values, baseline} to the
     // bottommost — the fill reaches the baseline, so include it.
     const regionTop = Math.min(topPx, baselinePx);

package/dist/band.d.ts

@@ -2,6 +2,7 @@ import { type CurveFactory } from 'd3-shape';
 import type { BandSeries } from './data.js';
 import type { Scale } from './line.js';
 import type { BandStyle } from './theme.js';
+import type { LayerDrawStats } from './context.js';
 import { type DecimateOption } from './decimate.js';
 /**
  * The `[min, max]` vertical extent of the **drawn** band — the lowest `lower`
@@ -28,5 +29,5 @@ export declare function bandExtent(band: BandSeries): [number, number] | null;
  * index, so there's no per-point object allocation. `globalAlpha` carries the
  * opacity and is restored so it doesn't leak into later layers.
  */
-export declare function drawBand(ctx: CanvasRenderingContext2D, band: BandSeries, xScale: Scale, yScale: Scale, style: BandStyle, curve?: CurveFactory, decimate?: DecimateOption): void;
+export declare function drawBand(ctx: CanvasRenderingContext2D, band: BandSeries, xScale: Scale, yScale: Scale, style: BandStyle, curve?: CurveFactory, decimate?: DecimateOption): LayerDrawStats;
 //# sourceMappingURL=band.d.ts.map

package/dist/band.js

@@ -41,6 +41,7 @@ export function bandExtent(band) {
  * opacity and is restored so it doesn't leak into later layers.
  */
 export function drawBand(ctx, band, xScale, yScale, style, curve = curveLinear, decimate = true) {
+    const sourceCount = band.length; // pre-cull, pre-decimation (for draw stats)
     // Viewport culling (Phase 2): clip the envelope to the visible slice (+1 each
     // side) before filling, so a pan strokes O(visible). The solid fill has no
     // cross-point state, so a zero-copy subarray view is exact; a no-op (same
@@ -52,9 +53,12 @@ export function drawBand(ctx, band, xScale, yScale, style, curve = curveLinear,
     // pixels. Gated off a smoothing `curve` (which would distort the per-column
     // envelope) and `decimate === false`; `decimateBand` itself no-ops on a sparse
     // envelope or a domainless test scale, so this stays byte-identical there.
+    let decimated = false;
     if (decimate !== false && curve === curveLinear) {
         const k = typeof decimate === 'object' ? decimate.threshold : undefined;
+        const before = band;
         band = decimateBand(band, xScale, ctx, k);
+        decimated = band !== before;
     }
     const gen = d3area()
         .defined((_, i) => Number.isFinite(band.lower[i]) && Number.isFinite(band.upper[i]))
@@ -70,5 +74,6 @@ export function drawBand(ctx, band, xScale, yScale, style, curve = curveLinear,
     gen(band.lower);
     ctx.fill();
     ctx.restore();
+    return { sourceCount, drawnCount: band.length, decimated };
 }
 //# sourceMappingURL=band.js.map

package/dist/bars.d.ts

@@ -1,6 +1,8 @@
 import type { BarSeries, StackedBarSeries } from './data.js';
 import type { Scale } from './line.js';
 import type { BarStyle } from './theme.js';
+import type { LayerDrawStats } from './context.js';
+import { type DecimateOption } from './decimate.js';
 /**
  * Bar growth direction — the histogram orientation. `'vertical'` bars grow **up**
  * from a value baseline, bins on the x axis (the column / time-bucket look);
@@ -67,6 +69,17 @@ export declare function barRect(cs: BarSeries, i: number, xScale: Scale, yScale:
  *
  * O(N) over the events, one fill (+ optional stroke) per bar, no per-bar
  * allocation beyond the rect tuple.
+ *
+ * **M4 column decimation ([PND-MARKDEC]):** once the *visible* bars are denser
+ * than ~2 per device pixel, they overplot into a solid silhouette, so
+ * `decimate !== false` replaces them with one **envelope rect per pixel column**
+ * ({@link decimateBars} — `[min(value, baseline), max(value, baseline)]`), from
+ * O(W) rects instead of O(visible). Gated on the *visible* count (a bar's width
+ * is its slot). The decimated pass draws the flat `fill` only — the aggregate
+ * columns aren't individually selectable, so per-bar selection/hover highlight is
+ * suppressed (a <1px bar's ring wouldn't be visible anyway); interaction still
+ * reads the **source** bars via {@link barAt} (§2.3). Pass `decimate={false}` to
+ * always draw every bar. Returns {@link LayerDrawStats} for `onDrawStats`.
  */
 export declare function drawBars(ctx: CanvasRenderingContext2D, cs: BarSeries, xScale: Scale, yScale: Scale, style: BarStyle, baseline: number, gapPx: number, seriesId: string | undefined, selection: {
     key: number;
@@ -74,7 +87,7 @@ export declare function drawBars(ctx: CanvasRenderingContext2D, cs: BarSeries, x
 } | null, hovered: {
     key: number;
     id: string;
-} | null): void;
+} | null, decimate?: DecimateOption): LayerDrawStats;
 /**
  * The index of the bar whose key span `[begin, end]` contains `time` — the bar
  * **under the cursor** — or `-1` if `time` falls in no bar's span. This is the

package/dist/bars.js

@@ -1,5 +1,6 @@
 import { barSpanPx } from './range.js';
 import { visibleSpanRange } from './culling.js';
+import { decimateBars } from './decimate.js';
 /**
  * The `[min, max]` vertical extent the bars occupy — the finite values of `cs.y`
  * **widened to include `0`**, since a bar spans from its value to the baseline
@@ -93,16 +94,54 @@ export function barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx) {
  *
  * O(N) over the events, one fill (+ optional stroke) per bar, no per-bar
  * allocation beyond the rect tuple.
+ *
+ * **M4 column decimation ([PND-MARKDEC]):** once the *visible* bars are denser
+ * than ~2 per device pixel, they overplot into a solid silhouette, so
+ * `decimate !== false` replaces them with one **envelope rect per pixel column**
+ * ({@link decimateBars} — `[min(value, baseline), max(value, baseline)]`), from
+ * O(W) rects instead of O(visible). Gated on the *visible* count (a bar's width
+ * is its slot). The decimated pass draws the flat `fill` only — the aggregate
+ * columns aren't individually selectable, so per-bar selection/hover highlight is
+ * suppressed (a <1px bar's ring wouldn't be visible anyway); interaction still
+ * reads the **source** bars via {@link barAt} (§2.3). Pass `decimate={false}` to
+ * always draw every bar. Returns {@link LayerDrawStats} for `onDrawStats`.
  */
-export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, seriesId, selection, hovered) {
+export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, seriesId, selection, hovered, decimate = true) {
     ctx.save();
     ctx.globalAlpha = style.opacity;
+    const sourceCount = cs.length; // pre-cull, pre-decimation (for draw stats)
     // Viewport culling (Phase 2): draw only the bars whose span overlaps the
     // visible x-window (+1 each side). The loop keeps the original index `i`, so
     // the `begin[i]` selection/hover match stays correct; full range when `xScale`
     // has no domain (a test stub). A selected/hovered bar off-screen isn't drawn
     // (its highlight would be off-screen anyway).
     const [vStart, vEnd] = visibleSpanRange(cs.begin, cs.end, cs.length, xScale);
+    // Decimate the visible bars to per-column envelope rects once dense (see the
+    // header). `null` below the visible-density threshold ⇒ the full per-bar loop.
+    // `{ threshold }` tunes the samples-per-pixel factor `k` (as line/area/band do);
+    // `undefined` ⇒ decimateBars' default (2).
+    const k = typeof decimate === 'object' ? decimate.threshold : undefined;
+    const envelope = decimate !== false
+        ? decimateBars(cs, xScale, ctx, baseline, k, vEnd - vStart)
+        : null;
+    if (envelope !== null) {
+        ctx.fillStyle = style.fill;
+        let drawn = 0;
+        for (let b = 0; b < envelope.length; b += 1) {
+            const lo = envelope.lo[b];
+            if (!Number.isFinite(lo))
+                continue; // empty column
+            const [x0, x1] = barSpanPx(envelope.begin[b], envelope.end[b], xScale, 0, // tile the column — a per-bar gapPx is invisible at <1px bars
+            style.minWidth);
+            const yTop = yScale(envelope.hi[b]);
+            const yBottom = yScale(lo);
+            ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
+            drawn += 1;
+        }
+        ctx.restore();
+        return { sourceCount, drawnCount: drawn, decimated: true };
+    }
+    let drawn = 0;
     for (let i = vStart; i < vEnd; i += 1) {
         const rect = barRect(cs, i, xScale, yScale, baseline, gapPx, style.minWidth);
         if (rect === null)
@@ -122,6 +161,7 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
             hovered.key === cs.begin[i];
         ctx.fillStyle = selected || isHovered ? style.highlight : style.fill;
         ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
+        drawn += 1;
         if (selected) {
             // The selected bar gets an outline so it reads at full strength over the
             // (alpha'd) fills. Stroke at full opacity (reset within the save bracket).
@@ -133,6 +173,7 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
         }
     }
     ctx.restore();
+    return { sourceCount, drawnCount: drawn, decimated: false };
 }
 /**
  * The index of the bar whose key span `[begin, end]` contains `time` — the bar

package/dist/box.d.ts

@@ -1,6 +1,8 @@
 import type { BoxSeries } from './data.js';
 import type { Scale } from './line.js';
 import type { BoxStyle } from './theme.js';
+import type { LayerDrawStats } from './context.js';
+import { type DecimateOption } from './decimate.js';
 /**
  * The `[min, max]` vertical extent of the **drawn** boxes — the lowest `lower`
  * whisker and highest `upper` whisker over the keys {@link isFiniteBox} draws
@@ -77,7 +79,7 @@ export type BoxShape = 'whisker' | 'solid' | 'none';
  * O(N) over the keys, a fixed number of path ops each — no per-key allocation
  * beyond the `barSpanPx` tuple.
  */
-export declare function drawBox(ctx: CanvasRenderingContext2D, box: BoxSeries, xScale: Scale, yScale: Scale, style: BoxStyle, gapPx?: number, minWidthPx?: number, shape?: BoxShape, showMedian?: boolean, offsetPx?: number, capWidthPx?: number, selectedKey?: number | null, hoveredKey?: number | null): void;
+export declare function drawBox(ctx: CanvasRenderingContext2D, box: BoxSeries, xScale: Scale, yScale: Scale, style: BoxStyle, gapPx?: number, minWidthPx?: number, shape?: BoxShape, showMedian?: boolean, offsetPx?: number, capWidthPx?: number, selectedKey?: number | null, hoveredKey?: number | null, decimate?: DecimateOption): LayerDrawStats;
 /**
  * This key is drawable — the quantiles it actually carries are all finite at `i`.
  * `lower`/`upper` (the whisker reach) are always required; `q1`/`q3` only when the

package/dist/box.js

@@ -1,5 +1,6 @@
 import { barSpanPx } from './range.js';
 import { visibleSpanRange } from './culling.js';
+import { decimateBox } from './decimate.js';
 /** Fraction of the box width the whisker end-caps span (centred on the stem). */
 const WHISKER_CAP_FRACTION = 0.5;
 /**
@@ -112,16 +113,32 @@ export function drawBox(ctx, box, xScale, yScale, style, gapPx = 0, minWidthPx =
 // the container selection's `key` by the caller). `null` ⇒ none. A selected
 // box gets a full-strength bounding outline; a hovered one a fainter one —
 // the box analog of the bar highlight, drawn without a new theme token.
-selectedKey = null, hoveredKey = null) {
+selectedKey = null, hoveredKey = null, decimate = true) {
+    const sourceCount = box.length; // pre-cull, pre-decimation (for draw stats)
+    // Viewport cull first (Phase 2): the [vStart, vEnd) boxes whose span overlaps
+    // the window (+1 each side). Full range when `xScale` has no domain (a stub);
+    // `offsetPx` is a small pixel nudge the ±1 margin absorbs.
+    let [vStart, vEnd] = visibleSpanRange(box.x, box.xEnd, box.length, xScale);
+    // M4 box decimation (Phase 5): once the *visible* boxes are denser than ~2 per
+    // device pixel, replace them with per-column **aggregate boxes** ({@link
+    // decimateBox}). Gate on the visible count, NOT `box.length`: a box's width is
+    // its slot, so decimating when only a handful are on screen (deep zoom) would
+    // re-slot each to a 1px sliver. `decimateBox` no-ops (returns the same object)
+    // below the visible-density threshold or on a domainless scale, leaving the
+    // loop-bound cull above. A selection/hover highlight keyed by the source box's
+    // `x` won't match an aggregate column edge — but per-box highlight is
+    // meaningless at decimation density, and hit-testing still reads the source.
+    const decimatedBox = decimate !== false ? decimateBox(box, xScale, ctx, 2, vEnd - vStart) : box;
+    const decimated = decimatedBox !== box;
+    if (decimated) {
+        box = decimatedBox; // aggregate boxes are already the visible set
+        vStart = 0;
+        vEnd = box.length;
+    }
     // A range-only box (bid→ask segment) has no body / median; the whisker (or the
     // solid bar) runs the full lower→upper. Flags default true (a full box).
     const hasBox = box.hasBox !== false;
     const drawMedian = showMedian && box.hasMedian !== false;
-    // Viewport culling (Phase 2): draw only the boxes whose span overlaps the
-    // visible x-window (+1 each side); the loop keeps the original index `i`. Full
-    // range when `xScale` has no domain (a test stub). `offsetPx` is a small pixel
-    // nudge the ±1 margin absorbs.
-    const [vStart, vEnd] = visibleSpanRange(box.x, box.xEnd, box.length, xScale);
     for (let i = vStart; i < vEnd; i += 1) {
         if (!isFiniteBox(box, i))
             continue;
@@ -214,6 +231,9 @@ selectedKey = null, hoveredKey = null) {
             ctx.restore();
         }
     }
+    // `drawnCount` = box slots iterated (visible span, or the aggregate set when
+    // decimation engaged); `sourceCount` = the raw box count it started from.
+    return { sourceCount, drawnCount: vEnd - vStart, decimated };
 }
 /**
  * This key is drawable — the quantiles it actually carries are all finite at `i`.