@pond-ts/charts 0.49.0 → 0.51.0

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 } 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
@@ -190,4 +226,83 @@ export declare function m4Polyline(edges: Float64Array, mn: Float64Array, mx: Fl
  * band segment that no single sample carried.
  */
 export declare function decimateBand(band: BandSeries, xScale: Scale, ctx: CanvasRenderingContext2D, k?: number): BandSeries;
+/**
+ * Decimate an {@link OhlcSeries} to one **aggregate candle per device-pixel
+ * column** — `open = first`, `high = max`, `low = min`, `close = last` over the
+ * candles that fall in the column. This is exactly a candle re-bucketed to a
+ * **coarser timeframe** (the pixel-column's time range): it is never *wrong* —
+ * it is the true OHLC of that span — so a dense chart that zooms out reads as
+ * fewer, wider aggregate candles, the trading-UI convention (decimator
+ * assessment §2.4). Auto-on with an opt-out; a consumer wanting fixed-timeframe
+ * candles pre-aggregates upstream and passes `decimate={false}`.
+ *
+ * Returns the **same object** when decimation doesn't apply (sparse series,
+ * domainless / non-invertible scale, no canvas width). The slot of each
+ * aggregate candle is its pixel column `[edges[b], edges[b+1]]`; an empty column
+ * (no candles) reduces to `NaN` on all channels — `drawCandles` skips it. No
+ * session-break union is needed: candles are independent marks (they never
+ * connect), and a trading-axis closed period is simply an empty column.
+ */
+export declare function decimateOhlc(ohlc: OhlcSeries, xScale: Scale, ctx: CanvasRenderingContext2D, k?: number, visibleCount?: number): OhlcSeries;
+/**
+ * Decimate a {@link BoxSeries} to one **aggregate box per device-pixel column** —
+ * the interval-mark sibling of {@link decimateOhlc}. Each channel is binned over
+ * the column: the whiskers widen to the column's full reach (`lower = min(lower)`,
+ * `upper = max(upper)`, exactly {@link decimateBand}'s envelope), the body to the
+ * column's **IQR envelope** (`q1 = min(q1)`, `q3 = max(q3)`), and the centre line
+ * to the **first** box's `median` in the column (a real median value, not an
+ * average — `binBy` carries no mean; it stays within the aggregate body since the
+ * first box's `[q1, q3]` ⊆ the envelope). So a dense per-x distribution chart
+ * that zooms out reads as fewer, wider boxes summarising each column's spread.
+ *
+ * Gates on the **visible** box count (a box's width is its slot — decimating a
+ * handful of deep-zoomed boxes would render 1px slivers, the same trap the candle
+ * path has). Returns the **same object** when decimation doesn't apply (below the
+ * visible-density threshold, domainless / non-invertible scale, no canvas width).
+ * The `hasBox` / `hasMedian` flags carry through, so a **range-only** box (all-NaN
+ * `q1`/`q3`) stays range-only (its binned body is NaN throughout). An empty column
+ * 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();
 /**
@@ -356,4 +424,186 @@ export function decimateBand(band, xScale, ctx, k = 2) {
     }
     return { x, lower, upper, length: W };
 }
+/**
+ * Decimate an {@link OhlcSeries} to one **aggregate candle per device-pixel
+ * column** — `open = first`, `high = max`, `low = min`, `close = last` over the
+ * candles that fall in the column. This is exactly a candle re-bucketed to a
+ * **coarser timeframe** (the pixel-column's time range): it is never *wrong* —
+ * it is the true OHLC of that span — so a dense chart that zooms out reads as
+ * fewer, wider aggregate candles, the trading-UI convention (decimator
+ * assessment §2.4). Auto-on with an opt-out; a consumer wanting fixed-timeframe
+ * candles pre-aggregates upstream and passes `decimate={false}`.
+ *
+ * Returns the **same object** when decimation doesn't apply (sparse series,
+ * domainless / non-invertible scale, no canvas width). The slot of each
+ * aggregate candle is its pixel column `[edges[b], edges[b+1]]`; an empty column
+ * (no candles) reduces to `NaN` on all channels — `drawCandles` skips it. No
+ * session-break union is needed: candles are independent marks (they never
+ * connect), and a trading-axis closed period is simply an empty column.
+ */
+export function decimateOhlc(ohlc, xScale, ctx, k = 2, visibleCount = ohlc.length) {
+    // Gate on the number of candles *in view*, not the whole series: a candle's
+    // width is its pixel-column slot, so re-slotting a handful of deep-zoomed
+    // candles to one column each would render them as 1px slivers. Below the
+    // visible-density threshold the loop-bound cull draws them at full width.
+    if (!shouldDecimateCount(visibleCount, ctx, k))
+        return ohlc;
+    const dom = scaleDomain(xScale);
+    if (dom === null || dom[1] <= dom[0])
+        return ohlc;
+    const invert = scaleInvert(xScale);
+    const plotWidthCss = scaleRangeWidth(xScale);
+    if (invert === null || plotWidthCss === null)
+        return ohlc;
+    const W = deviceBucketCount(ctx);
+    const edges = pixelEdges(invert, plotWidthCss, W);
+    // Bin each channel over the candles' (monotonic) left-edge key. open/close need
+    // the first/last channels (only `'minMaxFirstLast'` carries them); high/low are
+    // the scalar max/min. Four O(n) walks — candle counts are modest.
+    const key = ohlc.x;
+    const openCh = new Float64Column(ohlc.open, ohlc.length).binBy(key, edges, 'minMaxFirstLast').first;
+    const closeCh = new Float64Column(ohlc.close, ohlc.length).binBy(key, edges, 'minMaxFirstLast').last;
+    const highCh = new Float64Column(ohlc.high, ohlc.length).binBy(key, edges, 'max');
+    const lowCh = new Float64Column(ohlc.low, ohlc.length).binBy(key, edges, 'min');
+    const x = new Float64Array(W);
+    const xEnd = new Float64Array(W);
+    for (let b = 0; b < W; b += 1) {
+        x[b] = edges[b]; // the aggregate candle's slot IS its pixel column
+        xEnd[b] = edges[b + 1];
+    }
+    return {
+        x,
+        xEnd,
+        open: openCh,
+        high: highCh,
+        low: lowCh,
+        close: closeCh,
+        length: W,
+    };
+}
+/**
+ * Decimate a {@link BoxSeries} to one **aggregate box per device-pixel column** —
+ * the interval-mark sibling of {@link decimateOhlc}. Each channel is binned over
+ * the column: the whiskers widen to the column's full reach (`lower = min(lower)`,
+ * `upper = max(upper)`, exactly {@link decimateBand}'s envelope), the body to the
+ * column's **IQR envelope** (`q1 = min(q1)`, `q3 = max(q3)`), and the centre line
+ * to the **first** box's `median` in the column (a real median value, not an
+ * average — `binBy` carries no mean; it stays within the aggregate body since the
+ * first box's `[q1, q3]` ⊆ the envelope). So a dense per-x distribution chart
+ * that zooms out reads as fewer, wider boxes summarising each column's spread.
+ *
+ * Gates on the **visible** box count (a box's width is its slot — decimating a
+ * handful of deep-zoomed boxes would render 1px slivers, the same trap the candle
+ * path has). Returns the **same object** when decimation doesn't apply (below the
+ * visible-density threshold, domainless / non-invertible scale, no canvas width).
+ * The `hasBox` / `hasMedian` flags carry through, so a **range-only** box (all-NaN
+ * `q1`/`q3`) stays range-only (its binned body is NaN throughout). An empty column
+ * reduces to `NaN` on every channel — `drawBox` skips it via `isFiniteBox`.
+ */
+export function decimateBox(box, xScale, ctx, k = 2, visibleCount = box.length) {
+    if (!shouldDecimateCount(visibleCount, ctx, k))
+        return box;
+    const dom = scaleDomain(xScale);
+    if (dom === null || dom[1] <= dom[0])
+        return box;
+    const invert = scaleInvert(xScale);
+    const plotWidthCss = scaleRangeWidth(xScale);
+    if (invert === null || plotWidthCss === null)
+        return box;
+    const W = deviceBucketCount(ctx);
+    const edges = pixelEdges(invert, plotWidthCss, W);
+    const key = box.x;
+    const n = box.length;
+    // Envelope whiskers + IQR body (scalar min/max); centre line = the first box's
+    // median (only `'minMaxFirstLast'` carries `first`). Five O(n) walks — box
+    // counts are modest, like candles.
+    const lowerCh = new Float64Column(box.lower, n).binBy(key, edges, 'min');
+    const upperCh = new Float64Column(box.upper, n).binBy(key, edges, 'max');
+    const q1Ch = new Float64Column(box.q1, n).binBy(key, edges, 'min');
+    const q3Ch = new Float64Column(box.q3, n).binBy(key, edges, 'max');
+    const medianCh = new Float64Column(box.median, n).binBy(key, edges, 'minMaxFirstLast').first;
+    const x = new Float64Array(W);
+    const xEnd = new Float64Array(W);
+    for (let b = 0; b < W; b += 1) {
+        x[b] = edges[b]; // the aggregate box's slot IS its pixel column
+        xEnd[b] = edges[b + 1];
+    }
+    return {
+        x,
+        xEnd,
+        lower: lowerCh,
+        q1: q1Ch,
+        median: medianCh,
+        q3: q3Ch,
+        upper: upperCh,
+        length: W,
+        // Carry the flags through so a range-only / no-median box stays that way;
+        // omit (not `undefined`) when unset, per `exactOptionalPropertyTypes`.
+        ...(box.hasBox !== undefined ? { hasBox: box.hasBox } : {}),
+        ...(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

package/dist/index.d.ts

@@ -3,9 +3,11 @@
  *
  * Canvas-rendered, streaming-first time-series charts with a
  * react-timeseries-charts-style declarative layout. The architecture (hard
- * layers: adapter → typed-array store → decimator → chunked Path2D cache →
- * canvas renderer → React shell) is documented in the charts RFC at
- * `docs/rfcs/charts.md`; the milestone plan lives in `PLAN.md`.
+ * layers: adapter → typed-array store → decimator → canvas renderer → React
+ * shell) is documented in the charts RFC at `docs/rfcs/charts.md`; the
+ * milestone plan lives in `PLAN.md`. (A Path2D path cache was explored and
+ * deferred — it doesn't help the pan case, which re-decimates every frame; see
+ * the [PND-DECIM] floor decision.)
  *
  * **M1 — rendering spine.** The layout shell + the first draw layer:
  * `<ChartContainer>` (time axis) → `<ChartRow>` (y-axis + canvas) →
@@ -75,4 +77,5 @@ export type { ChartThemeOverrides, VarReader } from './css-theme.js';
 export { useChartTheme } from './useChartTheme.js';
 export type { UseChartThemeOptions } from './useChartTheme.js';
 export type { CursorMode, TrackerInfo, TrackerSample, SelectInfo, } from './context.js';
+export type { DrawStatsFrame, LayerDrawInfo } from './context.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -3,9 +3,11 @@
  *
  * Canvas-rendered, streaming-first time-series charts with a
  * react-timeseries-charts-style declarative layout. The architecture (hard
- * layers: adapter → typed-array store → decimator → chunked Path2D cache →
- * canvas renderer → React shell) is documented in the charts RFC at
- * `docs/rfcs/charts.md`; the milestone plan lives in `PLAN.md`.
+ * layers: adapter → typed-array store → decimator → canvas renderer → React
+ * shell) is documented in the charts RFC at `docs/rfcs/charts.md`; the
+ * milestone plan lives in `PLAN.md`. (A Path2D path cache was explored and
+ * deferred — it doesn't help the pan case, which re-decimates every frame; see
+ * the [PND-DECIM] floor decision.)
  *
  * **M1 — rendering spine.** The layout shell + the first draw layer:
  * `<ChartContainer>` (time axis) → `<ChartRow>` (y-axis + canvas) →