@pond-ts/charts 0.50.0 → 0.51.0

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 {

package/dist/context.js

@@ -1,5 +1,13 @@
 import { createContext } from 'react';
 export const ContainerContext = createContext(null);
+/** No-cursor default, so a consumer outside a provider reads "not hovering"
+ *  rather than needing a null guard (the container always provides a real one). */
+const NO_CURSOR = {
+    cursorX: null,
+    cursorY: null,
+    cursorRowKey: null,
+};
+export const CursorContext = createContext(NO_CURSOR);
 export const RowContext = createContext(null);
 export const LayersContext = createContext(null);
 //# sourceMappingURL=context.js.map

package/dist/data.d.ts

@@ -13,6 +13,14 @@ import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
  * column materialized to a `Float64Array`. `x` is **monotonically ascending**
  * (a series' key column is sorted) — the draw layers and the viewport bisect
  * (`culling.ts`) rely on it, as `sessionRuns` already does.
+ *
+ * **Neither buffer may be mutated in place** — not just `x`. The area fill
+ * gradient's value extent is memoized on the `y` buffer's identity
+ * (`columnFiniteExtent`, [PND-GRADX]), so a consumer that mutated a live `y`
+ * buffer's contents across frames instead of materializing a fresh column would
+ * read a stale gradient span (no crash, just a wrong shade). The built-in
+ * readers always allocate a fresh exactly-sized buffer per materialization, so
+ * buffer identity tracks data identity — hold to that.
  */
 export interface ChartSeries {
     readonly x: Float64Array;

package/dist/decimate.d.ts

@@ -45,7 +45,7 @@
  * `xScale` and breaks its subpath on `NaN`) — decimation is a pre-pass that
  * shrinks the point count, not a second renderer.
  */
-import type { ChartSeries, BandSeries, OhlcSeries, BoxSeries } from './data.js';
+import type { ChartSeries, BandSeries, OhlcSeries, BoxSeries, BarSeries } from './data.js';
 import type { Scale } from './line.js';
 /**
  * A line layer's M4-decimation control (`<LineChart decimate>`). **Default
@@ -152,6 +152,42 @@ export declare function mergeGapEdges(edges: Float64Array, gaps: number[], lo: n
  * series into per-session subpaths at exactly those instants.
  */
 export declare function decimateM4(cs: ChartSeries, xScale: Scale, ctx: CanvasRenderingContext2D, k?: number, boundaries?: readonly number[]): ChartSeries;
+/**
+ * Cull `source` to the visible window and M4-decimate it, **memoized per source
+ * series** so a y-only repaint reuses the prior frame's polyline instead of
+ * re-binning O(N) points. The decimation output is a pure function of the source
+ * data, the x mapping, the device width, the threshold, and the session breaks —
+ * it **never reads the y-scale** — so it is byte-identical across every y-zoom /
+ * y-autorange frame (the ~19% mountain@1M recompute the 2026-07 bench profile
+ * flagged, finding 3: an x-only computation re-run under y-only invalidation).
+ *
+ * The cache holds **one** entry per source: a y-only frame matches the stored
+ * key → hit; a pan / x-zoom mints a fresh `xScale` (`ChartContainer` keys the
+ * scale on the x-domain, not the y-domain — so the scale object is stable under
+ * y-zoom and fresh under pan) → miss, and the single entry is overwritten. So it
+ * **wins on y-only frames and is a no-op under pan** — bounded, never growing,
+ * the same reasoning that made Path2D caching not help pan ([PND-DECIM]).
+ *
+ * Correctness rests on the {@link ChartSeries} immutability contract: a data
+ * change mints a **new** source object (the layer re-materializes its column),
+ * so a stale entry can't be read. `boundaries` is compared by **identity** — the
+ * `<LineChart>` session-break instants are `useMemo`-stable across frames; a
+ * caller passing a fresh array each frame simply misses (safe, no benefit). `W`
+ * is `deviceBucketCount(ctx)` so a DPR / resize change re-keys. Keying on the
+ * `xScale` object (not just its `[domain, W]`) is what keeps the hit correct on
+ * a **non-affine** trading-time scale too — same scale object ⇒ identical
+ * pixel-column edges.
+ *
+ * Returns `{ series, decimated }`: `series` is the M4 polyline, or the plain
+ * culled slice when the window is too sparse to decimate ({@link decimateM4}
+ * no-ops); `decimated` says which (for the caller's draw-stats + session-run
+ * split). Callers pass the **pre-cull** source and skip their own cull — this
+ * function does it, so a cache hit skips the cull too.
+ */
+export declare function decimateM4Cached(source: ChartSeries, xScale: Scale, ctx: CanvasRenderingContext2D, k?: number, boundaries?: readonly number[]): {
+    series: ChartSeries;
+    decimated: boolean;
+};
 /**
  * Assemble the M4 polyline {@link ChartSeries} from the four binned channels.
  * Split out (pure, no canvas / pond deps) so the point emission is unit-tested
@@ -228,4 +264,45 @@ export declare function decimateOhlc(ohlc: OhlcSeries, xScale: Scale, ctx: Canva
  * reduces to `NaN` on every channel — `drawBox` skips it via `isFiniteBox`.
  */
 export declare function decimateBox(box: BoxSeries, xScale: Scale, ctx: CanvasRenderingContext2D, k?: number, visibleCount?: number): BoxSeries;
+/**
+ * One filled **envelope rect per device-pixel column** — the decimated form of a
+ * {@link BarSeries} ({@link decimateBars}). Each column `b` spans `[begin[b],
+ * end[b]]` in key space and fills the value range `[lo[b], hi[b]]`, i.e. the union
+ * of every bar in that column (their tops range over `[min, max]`, and each bar
+ * also reaches the baseline — so the union is `[min(minValue, baseline),
+ * max(maxValue, baseline)]`). An empty column carries `NaN` on `lo`/`hi` and draws
+ * nothing.
+ */
+export interface BarColumnEnvelope {
+    readonly begin: Float64Array;
+    readonly end: Float64Array;
+    readonly lo: Float64Array;
+    readonly hi: Float64Array;
+    readonly length: number;
+}
+/**
+ * Decimate a {@link BarSeries} to **one envelope rect per device-pixel column**
+ * ([PND-MARKDEC]) — the interval-mark analog of {@link decimateBand}, for the
+ * "column chart, dense in x" case (SciChart-suite finding 4: a bar column has no
+ * decimation path, so it falls off where line/area/candle don't). Once each bar's
+ * slot is narrower than ~1px (the visible bars exceed `k ×` the device-pixel
+ * column count), the individual rects overplot into a solid silhouette; this
+ * replaces them with the exact painted union: per column, `lo = min(minValue,
+ * baseline)` and `hi = max(maxValue, baseline)` — the bars' value range widened
+ * to include the baseline every bar reaches. Drawing one rect `[begin, end] ×
+ * [lo, hi]` per column reproduces that silhouette from O(W) rects instead of
+ * O(visible).
+ *
+ * Gates on the **visible** bar count (`visibleCount`, a bar's width is its slot —
+ * decimating a handful of deep-zoomed bars would render 1px slivers, the same
+ * trap the candle / box paths gate against). Returns `null` when decimation
+ * doesn't apply (below the visible-density threshold, domainless / non-invertible
+ * scale, no canvas width) — the caller then draws every visible bar. Bars are
+ * binned by their **`begin`** key (at this density `begin`/`end` sit in the same
+ * column); the envelope ignores per-bar `gapPx` and tiles the column (a few-px
+ * gap is invisible at <1px bars anyway — the standard decimation tradeoff).
+ * `baseline` is the resolved bar baseline in **value** units (from
+ * `resolveBarBaseline`), so the union is honest about the zero line.
+ */
+export declare function decimateBars(cs: BarSeries, xScale: Scale, ctx: CanvasRenderingContext2D, baseline: number, k?: number, visibleCount?: number): BarColumnEnvelope | null;
 //# sourceMappingURL=decimate.d.ts.map

package/dist/decimate.js

@@ -46,7 +46,7 @@
  * shrinks the point count, not a second renderer.
  */
 import { Float64Column } from 'pond-ts';
-import { scaleDomain } from './culling.js';
+import { scaleDomain, cullChartSeries } from './culling.js';
 /** The device-pixel bucket count for `ctx` — the backing buffer width, i.e.
  *  `plotWidthCss × DPR` (so buckets land at device-pixel resolution). Falls back
  *  to `0` when there is no sized canvas (a headless test ctx), which the caller
@@ -247,6 +247,74 @@ export function decimateM4(cs, xScale, ctx, k = 2, boundaries = []) {
     const { lo: mn, hi: mx, first, last, } = col.binBy(cs.x, edges, 'minMaxFirstLast');
     return m4Polyline(edges, mn, mx, first, last, buckets, breaks.length > 0 ? new Set(breaks) : undefined);
 }
+/**
+ * Stable empty boundary list for the (common) no-session-break decimation cache
+ * key — so an area / no-break line draw compares equal frame-to-frame instead of
+ * missing on a fresh default `[]`.
+ */
+const NO_BOUNDARIES = [];
+/**
+ * One-entry-per-source cache of the cull+M4-decimate result ([PND-DECKEY]),
+ * keyed on the source series (`WeakMap`) → the last `(xScale, W, k, boundaries)`
+ * it was drawn for. Evicts with the series (no leak); one entry per source keeps
+ * it bounded under pan (see {@link decimateM4Cached}).
+ */
+const m4Cache = new WeakMap();
+/**
+ * Cull `source` to the visible window and M4-decimate it, **memoized per source
+ * series** so a y-only repaint reuses the prior frame's polyline instead of
+ * re-binning O(N) points. The decimation output is a pure function of the source
+ * data, the x mapping, the device width, the threshold, and the session breaks —
+ * it **never reads the y-scale** — so it is byte-identical across every y-zoom /
+ * y-autorange frame (the ~19% mountain@1M recompute the 2026-07 bench profile
+ * flagged, finding 3: an x-only computation re-run under y-only invalidation).
+ *
+ * The cache holds **one** entry per source: a y-only frame matches the stored
+ * key → hit; a pan / x-zoom mints a fresh `xScale` (`ChartContainer` keys the
+ * scale on the x-domain, not the y-domain — so the scale object is stable under
+ * y-zoom and fresh under pan) → miss, and the single entry is overwritten. So it
+ * **wins on y-only frames and is a no-op under pan** — bounded, never growing,
+ * the same reasoning that made Path2D caching not help pan ([PND-DECIM]).
+ *
+ * Correctness rests on the {@link ChartSeries} immutability contract: a data
+ * change mints a **new** source object (the layer re-materializes its column),
+ * so a stale entry can't be read. `boundaries` is compared by **identity** — the
+ * `<LineChart>` session-break instants are `useMemo`-stable across frames; a
+ * caller passing a fresh array each frame simply misses (safe, no benefit). `W`
+ * is `deviceBucketCount(ctx)` so a DPR / resize change re-keys. Keying on the
+ * `xScale` object (not just its `[domain, W]`) is what keeps the hit correct on
+ * a **non-affine** trading-time scale too — same scale object ⇒ identical
+ * pixel-column edges.
+ *
+ * Returns `{ series, decimated }`: `series` is the M4 polyline, or the plain
+ * culled slice when the window is too sparse to decimate ({@link decimateM4}
+ * no-ops); `decimated` says which (for the caller's draw-stats + session-run
+ * split). Callers pass the **pre-cull** source and skip their own cull — this
+ * function does it, so a cache hit skips the cull too.
+ */
+export function decimateM4Cached(source, xScale, ctx, k, boundaries = NO_BOUNDARIES) {
+    const W = deviceBucketCount(ctx);
+    const cached = m4Cache.get(source);
+    if (cached !== undefined &&
+        cached.xScale === xScale &&
+        cached.W === W &&
+        cached.k === k &&
+        cached.boundaries === boundaries) {
+        return cached;
+    }
+    const culled = cullChartSeries(source, xScale);
+    const series = decimateM4(culled, xScale, ctx, k, boundaries);
+    const entry = {
+        xScale,
+        W,
+        k,
+        boundaries,
+        series,
+        decimated: series !== culled,
+    };
+    m4Cache.set(source, entry);
+    return entry;
+}
 /** Shared empty break-set for the common (no session-break) case. */
 const NO_BREAKS = new Set();
 /**
@@ -475,4 +543,67 @@ export function decimateBox(box, xScale, ctx, k = 2, visibleCount = box.length)
         ...(box.hasMedian !== undefined ? { hasMedian: box.hasMedian } : {}),
     };
 }
+/**
+ * Decimate a {@link BarSeries} to **one envelope rect per device-pixel column**
+ * ([PND-MARKDEC]) — the interval-mark analog of {@link decimateBand}, for the
+ * "column chart, dense in x" case (SciChart-suite finding 4: a bar column has no
+ * decimation path, so it falls off where line/area/candle don't). Once each bar's
+ * slot is narrower than ~1px (the visible bars exceed `k ×` the device-pixel
+ * column count), the individual rects overplot into a solid silhouette; this
+ * replaces them with the exact painted union: per column, `lo = min(minValue,
+ * baseline)` and `hi = max(maxValue, baseline)` — the bars' value range widened
+ * to include the baseline every bar reaches. Drawing one rect `[begin, end] ×
+ * [lo, hi]` per column reproduces that silhouette from O(W) rects instead of
+ * O(visible).
+ *
+ * Gates on the **visible** bar count (`visibleCount`, a bar's width is its slot —
+ * decimating a handful of deep-zoomed bars would render 1px slivers, the same
+ * trap the candle / box paths gate against). Returns `null` when decimation
+ * doesn't apply (below the visible-density threshold, domainless / non-invertible
+ * scale, no canvas width) — the caller then draws every visible bar. Bars are
+ * binned by their **`begin`** key (at this density `begin`/`end` sit in the same
+ * column); the envelope ignores per-bar `gapPx` and tiles the column (a few-px
+ * gap is invisible at <1px bars anyway — the standard decimation tradeoff).
+ * `baseline` is the resolved bar baseline in **value** units (from
+ * `resolveBarBaseline`), so the union is honest about the zero line.
+ */
+export function decimateBars(cs, xScale, ctx, baseline, k = 2, visibleCount = cs.length) {
+    if (!shouldDecimateCount(visibleCount, ctx, k))
+        return null;
+    const dom = scaleDomain(xScale);
+    if (dom === null || dom[1] <= dom[0])
+        return null;
+    const invert = scaleInvert(xScale);
+    const plotWidthCss = scaleRangeWidth(xScale);
+    if (invert === null || plotWidthCss === null)
+        return null;
+    const W = deviceBucketCount(ctx);
+    const edges = pixelEdges(invert, plotWidthCss, W);
+    // Per-column min/max of the bar values, binned by the bar's begin key — two O(n)
+    // walks, like decimateBand. An empty column reduces to NaN on both.
+    const col = new Float64Column(cs.y, cs.length);
+    const vMin = col.binBy(cs.begin, edges, 'min');
+    const vMax = col.binBy(cs.begin, edges, 'max');
+    const begin = new Float64Array(W);
+    const end = new Float64Array(W);
+    const lo = new Float64Array(W);
+    const hi = new Float64Array(W);
+    for (let b = 0; b < W; b += 1) {
+        begin[b] = edges[b];
+        end[b] = edges[b + 1];
+        const mn = vMin[b];
+        if (Number.isFinite(mn)) {
+            // Widen to the baseline so the rect spans exactly the painted union (each
+            // bar reaches the baseline). One-signed data ⇒ one edge is the baseline ⇒
+            // the rect is the tallest bar, unchanged.
+            lo[b] = Math.min(mn, baseline);
+            hi[b] = Math.max(vMax[b], baseline);
+        }
+        else {
+            lo[b] = NaN; // empty column — drawBars skips it
+            hi[b] = NaN;
+        }
+    }
+    return { begin, end, lo, hi, length: W };
+}
 //# sourceMappingURL=decimate.js.map