@pond-ts/charts 0.49.0 → 0.50.0

package/CHANGELOG.md

@@ -8,7 +8,8 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 tag, so this file covers them all. Pre-1.0: minor bumps may include new features
 and type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pond-ts/pond/compare/v0.49.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.50.0...HEAD
+[0.50.0]: https://github.com/pond-ts/pond/compare/v0.49.0...v0.50.0
 [0.49.0]: https://github.com/pond-ts/pond/compare/v0.48.1...v0.49.0
 [0.48.1]: https://github.com/pond-ts/pond/compare/v0.48.0...v0.48.1
 [0.48.0]: https://github.com/pond-ts/pond/compare/v0.47.0...v0.48.0
@@ -49,6 +50,30 @@ and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.50.0] — 2026-07-21
+
+### Added
+
+- **charts:** M4 decimation extended to **`<Candlestick>`** (same auto-on
+  `decimate` prop). Dense candles are drawn as per-pixel-column **aggregate
+  candles** — `open=first`, `high=max`, `low=min`, `close=last` over the column —
+  i.e. re-bucketed to the pixel-column timeframe, the way a trading chart shows
+  fewer, wider candles as you zoom out (decimator §2.4). It is a faithful OHLC of
+  each column's span, never a distortion; the hover readout still reads the
+  **source** candle at the cursor (§2.3). Decimation gates on the **visible**
+  candle count, so a deep zoom into a large series still draws full-width
+  candles. Pass `decimate={false}` (and pre-aggregate upstream) for
+  fixed-timeframe candles.
+- **charts:** M4 decimation extended to **`<BoxPlot>`** (same auto-on `decimate`
+  prop) — the interval-mark sibling of the candle. Dense boxes are drawn as
+  per-pixel-column **aggregate boxes**: the whiskers widen to the column's reach
+  (`min(lower)`/`max(upper)`), the body to its IQR envelope
+  (`min(q1)`/`max(q3)`), the centre line to the first box's median. Gates on the
+  **visible** box count (a deep zoom still draws full-width boxes); the
+  `hasBox`/`hasMedian` flags carry through, so a range-only box stays range-only.
+  Interaction is unaffected — hit-testing reads the source boxes (§2.3). Pass
+  `decimate={false}` to draw every box at its own slot.
+
 ## [0.49.0] — 2026-07-21
 
 ### Added

package/dist/BoxPlot.d.ts

@@ -1,6 +1,7 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
 import { type BoxShape } from './box.js';
+import type { DecimateOption } from './decimate.js';
 export interface BoxPlotProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
      * The source series. A `TimeSeries` plots against the time axis; a `ValueSeries`
@@ -98,6 +99,16 @@ export interface BoxPlotProps<S extends SeriesSchema = SeriesSchema, VS extends
      * (its `begin`).
      */
     id?: string;
+    /**
+     * **M4 viewport decimation** (charts decimator wave). **Omitted ⇒ `true`**:
+     * once the visible boxes are denser than ~2 per device pixel, they are drawn as
+     * per-pixel-column **aggregate boxes** — whiskers widen to the column's reach
+     * (`min(lower)`/`max(upper)`), the body to its IQR envelope
+     * (`min(q1)`/`max(q3)`), the centre line to the first box's median. Pass `false`
+     * to draw every box at its own slot. Interaction is unaffected (hit-testing
+     * reads the source boxes). Shares {@link LineChart}'s `DecimateOption`.
+     */
+    decimate?: DecimateOption;
     /**
      * This layer's `<Legend>` row: `false` ⇒ no row (opt out), a string ⇒ the
      * row's display name. **Omitted ⇒ a row named by the layer's readout
@@ -142,5 +153,5 @@ export interface BoxPlotProps<S extends SeriesSchema = SeriesSchema, VS extends
  * </Layers>
  * ```
  */
-export declare function BoxPlot<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, lower, q1, median, q3, upper, as: semantic, axis, gap, shape, showMedian, offset, capWidth, id, legend, index, }: BoxPlotProps<S, VS>): null;
+export declare function BoxPlot<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, lower, q1, median, q3, upper, as: semantic, axis, gap, shape, showMedian, offset, capWidth, id, decimate, legend, index, }: BoxPlotProps<S, VS>): null;
 //# sourceMappingURL=BoxPlot.d.ts.map

package/dist/BoxPlot.js

@@ -38,7 +38,7 @@ const MIN_BOX_WIDTH_PX = 1;
  * </Layers>
  * ```
  */
-export function BoxPlot({ series, lower, q1, median, q3, upper, as: semantic, axis, gap = 0, shape = 'whisker', showMedian = true, offset = 0, capWidth, id, legend, index = 0, }) {
+export function BoxPlot({ series, lower, q1, median, q3, upper, as: semantic, axis, gap = 0, shape = 'whisker', showMedian = true, offset = 0, capWidth, id, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<BoxPlot> must be rendered inside a <ChartContainer>');
@@ -142,7 +142,7 @@ export function BoxPlot({ series, lower, q1, median, q3, upper, as: semantic, ax
                         return { id, key: begin, value, color: style.whisker, label };
                     },
                 }),
-            draw: (ctx, xScale, yScale) => drawBox(ctx, bx, xScale, yScale, style, gap, MIN_BOX_WIDTH_PX, shape, showMedian, offset, capWidth, selectedKey, hoveredKey),
+            draw: (ctx, xScale, yScale) => drawBox(ctx, bx, xScale, yScale, style, gap, MIN_BOX_WIDTH_PX, shape, showMedian, offset, capWidth, selectedKey, hoveredKey, decimate),
         },
         axisId: axis,
         index,
@@ -166,6 +166,7 @@ export function BoxPlot({ series, lower, q1, median, q3, upper, as: semantic, ax
         label,
         selectedKey,
         hoveredKey,
+        decimate,
         axis,
         index,
     ]);

package/dist/Candlestick.d.ts

@@ -1,4 +1,5 @@
 import type { SeriesSchema, TimeSeries } from 'pond-ts';
+import type { DecimateOption } from './decimate.js';
 import { type CandleVariant, type ColorBy } from './ohlc.js';
 export interface CandlestickProps<S extends SeriesSchema> {
     /**
@@ -56,6 +57,18 @@ export interface CandlestickProps<S extends SeriesSchema> {
      * for a compact legend; the full quote is opt-in for a dense hover readout.
      */
     showOHLC?: boolean;
+    /**
+     * **M4 viewport decimation** (charts decimator wave). **Omitted ⇒ `true`**:
+     * once the visible candles are denser than ~2 per device pixel, they are drawn
+     * as per-pixel-column **aggregate candles** (`open=first`, `high=max`,
+     * `low=min`, `close=last`) — i.e. re-bucketed to the pixel-column timeframe, the
+     * way a trading chart shows fewer, wider candles as you zoom out. It is a
+     * faithful OHLC of each column's span (never a distortion), just at a coarser
+     * timeframe. Pass `false` to draw every candle at its own slot (and
+     * pre-aggregate upstream if you need a fixed timeframe). Shares
+     * {@link LineChart}'s `DecimateOption`.
+     */
+    decimate?: DecimateOption;
     /**
      * This layer's `<Legend>` row: `false` ⇒ no row (opt out), a string ⇒ the
      * row's display name. **Omitted ⇒ a row named by the layer's readout
@@ -96,5 +109,5 @@ export interface CandlestickProps<S extends SeriesSchema> {
  * </Layers>
  * ```
  */
-export declare function Candlestick<S extends SeriesSchema>({ series, open, high, low, close, as: semantic, axis, variant, colorBy, gap, showOHLC, legend, index, }: CandlestickProps<S>): null;
+export declare function Candlestick<S extends SeriesSchema>({ series, open, high, low, close, as: semantic, axis, variant, colorBy, gap, showOHLC, decimate, legend, index, }: CandlestickProps<S>): null;
 //# sourceMappingURL=Candlestick.d.ts.map

package/dist/Candlestick.js

@@ -31,7 +31,7 @@ import { useSlotKey } from './use-slot-key.js';
  * </Layers>
  * ```
  */
-export function Candlestick({ series, open = 'open', high = 'high', low = 'low', close = 'close', as: semantic, axis, variant = 'candle', colorBy = 'direction', gap = 0, showOHLC = false, legend, index = 0, }) {
+export function Candlestick({ series, open = 'open', high = 'high', low = 'low', close = 'close', as: semantic, axis, variant = 'candle', colorBy = 'direction', gap = 0, showOHLC = false, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<Candlestick> must be rendered inside a <ChartContainer>');
@@ -83,7 +83,7 @@ export function Candlestick({ series, open = 'open', high = 'high', low = 'low',
                 ];
                 return samples;
             },
-            draw: (ctx, xScale, yScale) => drawCandles(ctx, ohlc, xScale, yScale, style, variant, colorBy, gap),
+            draw: (ctx, xScale, yScale) => drawCandles(ctx, ohlc, xScale, yScale, style, variant, colorBy, gap, undefined, decimate),
         },
         axisId: axis,
         index,
@@ -96,6 +96,7 @@ export function Candlestick({ series, open = 'open', high = 'high', low = 'low',
         colorBy,
         gap,
         showOHLC,
+        decimate,
         axis,
         index,
     ]);

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

package/dist/box.js

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

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 } from './data.js';
 import type { Scale } from './line.js';
 /**
  * A line layer's M4-decimation control (`<LineChart decimate>`). **Default
@@ -190,4 +190,42 @@ 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;
 //# sourceMappingURL=decimate.d.ts.map

package/dist/decimate.js

@@ -356,4 +356,123 @@ 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 } : {}),
+    };
+}
 //# sourceMappingURL=decimate.js.map

package/dist/ohlc.d.ts

@@ -1,6 +1,7 @@
 import type { OhlcSeries } from './data.js';
 import type { Scale } from './line.js';
 import type { CandleStyle } from './theme.js';
+import { type DecimateOption } from './decimate.js';
 /**
  * How an OHLC mark renders (pjm17971's fork 2 — bundled as one component, like
  * {@link BoxShape}, not split into a separate `<OHLCBar>`):
@@ -77,5 +78,5 @@ export declare function resolveCandleStyle(style: CandleStyle, open: number, clo
  * O(N) over the keys, a fixed number of path ops each — no per-key allocation
  * beyond the `barSpanPx` tuple.
  */
-export declare function drawCandles(ctx: CanvasRenderingContext2D, ohlc: OhlcSeries, xScale: Scale, yScale: Scale, style: CandleStyle, variant?: CandleVariant, colorBy?: ColorBy, gapPx?: number, minWidthPx?: number): void;
+export declare function drawCandles(ctx: CanvasRenderingContext2D, ohlc: OhlcSeries, xScale: Scale, yScale: Scale, style: CandleStyle, variant?: CandleVariant, colorBy?: ColorBy, gapPx?: number, minWidthPx?: number, decimate?: DecimateOption): void;
 //# sourceMappingURL=ohlc.d.ts.map

package/dist/ohlc.js

@@ -1,5 +1,6 @@
 import { barSpanPx } from './range.js';
 import { visibleSpanRange } from './culling.js';
+import { decimateOhlc } from './decimate.js';
 /** Default body width as a fraction of the candle slot when the style omits one. */
 const DEFAULT_BODY_WIDTH = 0.8;
 /** Minimum body height in px so a doji (open === close) still shows a mark. */
@@ -89,12 +90,27 @@ export function resolveCandleStyle(style, open, close, colorBy) {
  * O(N) over the keys, a fixed number of path ops each — no per-key allocation
  * beyond the `barSpanPx` tuple.
  */
-export function drawCandles(ctx, ohlc, xScale, yScale, style, variant = 'candle', colorBy = 'direction', gapPx = 0, minWidthPx = 1) {
+export function drawCandles(ctx, ohlc, xScale, yScale, style, variant = 'candle', colorBy = 'direction', gapPx = 0, minWidthPx = 1, decimate = true) {
     const bodyFraction = style.bodyWidth ?? DEFAULT_BODY_WIDTH;
-    // Viewport culling (Phase 2): draw only the candles whose span overlaps the
-    // visible x-window (+1 each side); the loop keeps the original index `i`. Full
-    // range when `xScale` has no domain (a test stub).
-    const [vStart, vEnd] = visibleSpanRange(ohlc.x, ohlc.xEnd, ohlc.length, xScale);
+    // Viewport cull first (Phase 2): the [vStart, vEnd) candles whose span overlaps
+    // the window (+1 each side). Full range when `xScale` has no domain (a stub).
+    let [vStart, vEnd] = visibleSpanRange(ohlc.x, ohlc.xEnd, ohlc.length, xScale);
+    // M4 candle decimation (Phase 5): once the *visible* candles are denser than ~2
+    // per device pixel, replace them with per-column **aggregate candles**
+    // (open=first, high=max, low=min, close=last — a coarser-timeframe candle;
+    // {@link decimateOhlc}). Gate on the visible count, NOT `ohlc.length`: a candle's
+    // width is its slot, so decimating when only a handful are on screen (deep zoom
+    // into a large series) would re-slot each to a 1px sliver. `decimateOhlc` no-ops
+    // (returns the same object) below the visible-density threshold or on a
+    // domainless scale, leaving the loop-bound cull above.
+    const decimated = decimate !== false
+        ? decimateOhlc(ohlc, xScale, ctx, 2, vEnd - vStart)
+        : ohlc;
+    if (decimated !== ohlc) {
+        ohlc = decimated; // aggregate candles are already the visible set
+        vStart = 0;
+        vEnd = ohlc.length;
+    }
     for (let i = vStart; i < vEnd; i += 1) {
         if (!isFiniteOhlc(ohlc, i))
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "private": false,
   "description": "Canvas-rendered, streaming-first time-series charts for pond-ts",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "perf": "PERF_BENCH=1 playwright test perf.spec.ts --workers=1"
   },
   "peerDependencies": {
-    "@pond-ts/react": "^0.49.0",
-    "pond-ts": "^0.49.0",
+    "@pond-ts/react": "^0.50.0",
+    "pond-ts": "^0.50.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {