@pond-ts/charts 0.50.0 → 0.52.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,7 @@
 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`
@@ -78,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, decimate?: DecimateOption): 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

@@ -114,6 +114,7 @@ export function drawBox(ctx, box, xScale, yScale, style, gapPx = 0, minWidthPx =
 // 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, 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.
@@ -127,9 +128,10 @@ selectedKey = null, hoveredKey = null, decimate = true) {
     // 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 decimated = decimate !== false ? decimateBox(box, xScale, ctx, 2, vEnd - vStart) : box;
-    if (decimated !== box) {
-        box = decimated; // aggregate boxes are already the visible set
+    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;
     }
@@ -229,6 +231,9 @@ selectedKey = null, hoveredKey = null, decimate = true) {
             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`.

package/dist/context.d.ts

@@ -41,25 +41,12 @@ export interface ContainerFrame {
     readonly rightGutter: number;
     /** Vertical space between rows in px (not under the time axis). */
     readonly rowGap: number;
-    /**
-     * The crosshair's **plot-pixel x** (`0..plotWidth`), shared across rows so the
-     * tracker syncs, or `null` when not hovering. A *pixel*, not a timestamp — so a
-     * still cursor stays put while a live window slides under it (a stored
-     * timestamp would drift sideways as `xScale` changes). A controlled
-     * `trackerPosition` (a timestamp) resolves to a pixel here.
-     */
-    readonly cursorX: number | null;
-    /** Set the hovered plot-pixel x; a row's event surface calls this on pointer move. */
+    /** Set the hovered plot-pixel x; a row's event surface calls this on pointer move.
+     *  The value itself is on {@link CursorFrame.cursorX} ({@link CursorContext}) —
+     *  split out so a hover doesn't re-identify this frame (see [PND-HOVCTX]). */
     setHoverX(x: number | null): void;
-    /**
-     * The hovered plot-pixel **y** and the row it's in — for the free-form
-     * crosshair's horizontal line + value readout (which are row-specific, unlike
-     * the shared vertical `cursorX`). `null` when not hovering a plot. Hover-driven
-     * only (no controlled equivalent).
-     */
-    readonly cursorY: number | null;
-    readonly cursorRowKey: symbol | null;
-    /** Set the hovered plot-pixel y + its row; the event surface calls this on move. */
+    /** Set the hovered plot-pixel y + its row; the event surface calls this on move.
+     *  The values are on {@link CursorFrame} ({@link CursorContext}). */
     setHoverY(y: number | null, rowKey: symbol | null): void;
     /**
      * `cursor="crosshair"` **y** snapping. **Default `true`** — the reticle centres
@@ -98,6 +85,14 @@ export interface ContainerFrame {
      * zoom the view, or map the span onto a subscription's range params.
      */
     readonly onRegionSelect: ((range: readonly [number, number]) => void) | undefined;
+    /**
+     * A stable sink for per-repaint {@link DrawStatsFrame}s, or `undefined` when no
+     * `onDrawStats` consumer is subscribed — the `undefined` is the signal for
+     * `Layers` to skip per-layer timing entirely (zero overhead when unused). The
+     * identity is stable while subscribed (it reads a ref), so an inline
+     * `onDrawStats` arrow doesn't thrash the draw memo.
+     */
+    readonly reportDrawStats: ((frame: DrawStatsFrame) => void) | undefined;
     /**
      * Require a modifier key held to start a region-drag — set to `'shift'` to make
      * plain drag **pan** and **shift**-drag select, when `panZoom` is on. Only
@@ -250,8 +245,10 @@ export interface ContainerFrame {
      * category label), and the cursor readout to format the x position.
      */
     readonly xKind: 'time' | 'value' | 'category';
-    /** Pan/zoom enabled — the plot drag-pans and wheel-zooms the shared time range. */
-    readonly panZoom: boolean;
+    /** Drag-pan enabled (the `'pan'` and `'panZoom'` container modes). */
+    readonly panEnabled: boolean;
+    /** Wheel-zoom enabled (the `'panZoom'` container mode only). */
+    readonly zoomEnabled: boolean;
     /** Minimum visible duration (ms) — the zoom-in floor. */
     readonly minDuration: number;
     /**
@@ -398,6 +395,97 @@ export interface GutterReq {
     readonly right: readonly number[];
 }
 export declare const ContainerContext: import("react").Context<ContainerFrame | null>;
+/**
+ * The **per-move** cursor state — split out of {@link ContainerFrame} so a
+ * mousemove re-identifies only this (small) context, not the whole frame.
+ * `ContainerFrame` carries ~50 mostly-static fields; when the cursor lived
+ * there, every pointer move rebuilt it and re-rendered **all** its consumers
+ * (both `YAxis`, `Legend`, `Bar`/`Box`) even though only the SVG overlay moved.
+ * Config consumers now read the stable frame and skip hover re-renders; the
+ * genuine cursor consumers (`Layers` overlay, `XAxis` crosshair pill,
+ * `useChartLegend` values) read this. See [PND-HOVCTX] and the note it links.
+ *
+ * The cursor *time* is **not** here — each consumer derives it locally from
+ * `cursorX` + its own `xScale` (an in-bounds `xScale.invert`), as before.
+ * ({@link ContainerFrame} still carries a `cursorTime` **boolean** — the
+ * unrelated "show time in the readout" config flag.)
+ */
+export interface CursorFrame {
+    /**
+     * The crosshair's **plot-pixel x** (`0..plotWidth`), shared across rows so the
+     * tracker syncs, or `null` when not hovering. A *pixel*, not a timestamp — so a
+     * still cursor stays put while a live window slides under it (a stored
+     * timestamp would drift sideways as `xScale` changes). A controlled
+     * `trackerPosition` (a timestamp) resolves to a pixel here.
+     */
+    readonly cursorX: number | null;
+    /**
+     * The hovered plot-pixel **y** and the row it's in — for the free-form
+     * crosshair's horizontal line + value readout (which are row-specific, unlike
+     * the shared vertical `cursorX`). `null` when not hovering a plot. Hover-driven
+     * only (no controlled equivalent).
+     */
+    readonly cursorY: number | null;
+    readonly cursorRowKey: symbol | null;
+}
+export declare const CursorContext: import("react").Context<CursorFrame>;
+/**
+ * What a {@link RowLayer.draw} may return so the container can report render
+ * cost + whether M4 decimation engaged this frame ({@link
+ * ContainerProps.onDrawStats}). Optional — a layer that returns `void` reports
+ * only its `drawMs` (the render loop times every layer regardless).
+ */
+export interface LayerDrawStats {
+    /** Source series length the draw received (pre-cull, pre-decimation). */
+    readonly sourceCount: number;
+    /** Points / marks actually drawn this frame — after viewport culling and, if
+     *  it engaged, M4 decimation. `drawnCount < sourceCount` can come from **either**
+     *  culling (a zoomed-in view drops off-screen points) **or** decimation — read
+     *  `decimated` to tell which; `drawnCount === sourceCount` means everything in
+     *  view was drawn full-resolution. */
+    readonly drawnCount: number;
+    /** Whether M4 decimation engaged (vs. drew the culled slice full-resolution).
+     *  Distinguishes a decimated draw from a merely culled one — both shrink
+     *  `drawnCount`. */
+    readonly decimated: boolean;
+}
+/**
+ * One layer's line in a {@link DrawStatsFrame}: its identity + measured draw
+ * time, plus the {@link LayerDrawStats} the layer reported (`undefined` counts
+ * for a layer that returns none — e.g. a non-decimating scatter/bar, which
+ * still contributes its `drawMs`).
+ */
+export interface LayerDrawInfo {
+    /** The layer's `as` role, or `undefined` if it set none. */
+    readonly as: string | undefined;
+    /** Z-order index within the row (the `<Layers>` declaration position). */
+    readonly index: number;
+    /** Wall-clock ms spent in this layer's `draw` this frame. */
+    readonly drawMs: number;
+    readonly sourceCount: number | undefined;
+    readonly drawnCount: number | undefined;
+    readonly decimated: boolean | undefined;
+}
+/**
+ * The per-repaint draw-stats frame handed to {@link ContainerProps.onDrawStats}.
+ * Fires **once per row-canvas repaint** (rows repaint independently, so a
+ * multi-row container fires one frame per row that painted), carrying that row's
+ * layers newest-drawn. The seam the dashboard A/B asked for (2026-07-21): read
+ * `drawnCount` vs `sourceCount` to see whether M4 engaged, and `drawMs` for the
+ * per-layer render cost the packaged layer otherwise hides.
+ */
+export interface DrawStatsFrame {
+    /**
+     * Opaque, stable identity of the **row** this frame is for — rows repaint
+     * independently, so a multi-row container fires one frame per row and this is
+     * how a consumer attributes each (group frames by `rowKey`, e.g. as a `Map`
+     * key). Not human-readable; `layers[].as` labels the series within a row.
+     */
+    readonly rowKey: symbol;
+    readonly layers: readonly LayerDrawInfo[];
+    /** Total ms across this row's layer draws this frame. */
+    readonly totalDrawMs: number;
+}
 /**
  * A draw layer ({@link LineChart}, …) registered into a {@link Layers}, paired
  * with the id of the axis it scales against. The row computes a y-scale per
@@ -405,6 +493,12 @@ export declare const ContainerContext: import("react").Context<ContainerFrame |
  * domain); each layer draws with its own axis's scale.
  */
 export interface RowLayer {
+    /**
+     * The layer's `as` role (the series identity), surfaced in {@link
+     * DrawStatsFrame} so a draw-stats consumer can label each line. `undefined`
+     * when the layer was given no `as`.
+     */
+    readonly as?: string | undefined;
     /** This layer's finite-value `[min, max]`, or `null` if it has none. */
     yExtent(): [number, number] | null;
     /**
@@ -468,8 +562,13 @@ export interface RowLayer {
      * resolves the layer's axis scale, as for `draw`).
      */
     hitTest?(px: number, py: number, xScale: (value: number) => number, yScale: (value: number) => number): SelectInfo | null;
-    /** Draw into the plot canvas. `xScale`/`yScale` map data→pixels. */
-    draw(ctx: CanvasRenderingContext2D, xScale: (value: number) => number, yScale: (value: number) => number): void;
+    /**
+     * Draw into the plot canvas. `xScale`/`yScale` map data→pixels. May return
+     * {@link LayerDrawStats} (source/drawn counts + whether decimation engaged) so
+     * the container can surface them via {@link ContainerProps.onDrawStats}; a
+     * layer that returns `void` still contributes its measured `drawMs`.
+     */
+    draw(ctx: CanvasRenderingContext2D, xScale: (value: number) => number, yScale: (value: number) => number): LayerDrawStats | void;
 }
 /** One tracker readout point — a dot + value the overlay draws at the cursor. */
 export interface TrackerSample {