@pond-ts/charts 0.49.0 → 0.51.0

package/CHANGELOG.md

@@ -8,7 +8,9 @@ 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.51.0...HEAD
+[0.51.0]: https://github.com/pond-ts/pond/compare/v0.50.0...v0.51.0
+[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 +51,141 @@ and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.51.0] — 2026-07-22
+
+### Changed
+
+- **charts:** **`trackerPosition` is now a _followed_ position, not a hard pin —
+  enabling cross-chart cursor sync.** A live local hover wins over
+  `trackerPosition`, so the chart under the pointer shows its own cursor while
+  any chart without a local pointer follows the controlled time (mapped through
+  its own `xScale`, so it's correct across different zooms). This makes
+  **multi-chart dashboard cursor sync** fall out of the plain props: give every
+  `<ChartContainer>` the same `trackerPosition={sharedTime}` and set `sharedTime`
+  from each one's `onTrackerChanged` (clear it to `null` on the group's
+  `onPointerLeave`) — no "which chart is active" bookkeeping. **Behaviour
+  change:** previously a numeric `trackerPosition` overrode local hover, and
+  `trackerPosition={null}` force-hid the cursor; now `null` and `undefined` are
+  equivalent ("no controlled position") and a hovered chart always tracks its
+  pointer. To force a chart to never show a cursor, use `cursor="none"`. See the
+  "Synced cursors across charts" story. No type change (`number | null`).
+- **charts:** **Line / area draw is ~3× faster on stroke-bound frames**
+  (PND-AFFINE / PND-GRADX; 2026-07 external-bench profile). When the curve is
+  linear and both scales are affine (every y axis is `scaleLinear`; x is
+  `scaleLinear` / `scaleTime` / the gap-free default time axis), `drawLine` and
+  `drawArea` now map points with an inline `k·v + b` over the typed arrays
+  instead of a per-point d3-scale closure + d3-shape generator — a **visually
+  identical** draw (guarded by the decimation pixel-identity and per-layer
+  visual-regression e2e). A real-gap trading-time axis, or a non-linear curve,
+  transparently keeps the exact d3 path. Measured on a JS-only micro-bench
+  (`scripts/perf-affine.mjs`): line 1M 60.4 → 19.0 ms (3.2×), area 1M 132 →
+  38 ms (3.5×). Separately, the area fill gradient's full-series value extent is
+  now memoized per column buffer, so a y-zoom / pan repaint no longer re-walks
+  the whole series to find the gradient span. No API change.
+- **charts:** **A y-zoom / y-autorange repaint no longer re-decimates line /
+  area layers** (PND-DECKEY; same 2026-07 profile, finding 3). The M4
+  decimation output is a pure function of the source data, x-domain, device
+  width, threshold, and session breaks — it never reads the y-scale — so it is
+  identical across every y-only frame. `drawLine` / `drawArea` now memoize the
+  cull+decimate result per source series (one entry, keyed on the x-scale
+  object + width + threshold + breaks), so a y-zoom / live y-autorange frame
+  reuses the prior polyline instead of re-binning O(N) points; a pan / x-zoom
+  mints a fresh x-scale and correctly recomputes. Measured
+  (`scripts/perf-deckey.mjs`): the ~5 ms/frame decimation walk at 1M points is
+  eliminated on every y-only frame. No API change.
+
+### Added
+
+- **charts:** **`<BarChart decimate>` — dense column charts now decimate**
+  (PND-MARKDEC; 2026-07 profile, finding 4 — "column dead by 5M"). **Default
+  `true`**: once the visible **single-series** bars are denser than ~2 per device
+  pixel (each slot < ~1px), they're drawn as one per-column **envelope** rect —
+  the exact painted union `[min(value, baseline), max(value, baseline)]` of each
+  pixel column — instead of every bar, so a 100k–5M-bar column chart stays
+  interactive. **Visually lossless** at that density (a perf knob, not a style);
+  interaction still reads the source bars (`barAt`), and the per-bar
+  selection/hover highlight is suppressed only when decimated (a <1px bar's ring
+  isn't visible anyway). `decimate={false}` draws every bar; `{ threshold }`
+  tunes the samples-per-pixel factor. No-op for a stacked / multi-group
+  histogram (the low-count categorical path). `drawBars` now returns
+  `LayerDrawStats` (visible via `onDrawStats`). Measured
+  (`scripts/perf-markdec.mjs`, JS-only): the bar draw at 5M points drops
+  485 → 26 ms (18.9×), 100k drops 9.7 → 0.9 ms (10.7×) — with the larger
+  rasterization win on top, browser-side.
+- **charts:** **`panZoom` is now a three-way mode + a `bounds` extent.**
+  `<ChartContainer panZoom>` takes `'none'` / `'pan'` / `'panZoom'` (drag-only
+  vs. drag+wheel), with the old boolean kept as shorthand (`true` ⇒ `'panZoom'`,
+  `false` ⇒ `'none'`) — so existing charts are unchanged. A new `bounds`
+  (`[min, max]`) prop fences pan/zoom to an **outer** extent (panning into an
+  edge stops there keeping its span; zoom-out is capped at the whole span), the
+  companion
+  to the existing `minDuration` zoom-in floor — together they pin the reachable
+  window between an inner and outer bound. On a trading-time axis `bounds`
+  clamps in wall-clock ms. Purely additive; no type narrowing.
+- **charts:** **Draw-cost + decimation observability** — `<ChartContainer
+onDrawStats>` (PND-DECOBS; dashboard A/B friction, 2026-07-21). Fires a
+  `DrawStatsFrame` once per row-canvas repaint (keyed by an opaque `rowKey` for
+  multi-row attribution), one `LayerDrawInfo` per layer carrying its `as`,
+  measured `drawMs`, and — for a decimating layer (line / area / band / candle /
+  box) — `sourceCount` / `drawnCount` / `decimated`.
+  Compare `drawnCount` to `sourceCount` to see whether M4 engaged; read `drawMs`
+  for per-layer render cost. **Zero-overhead when unused** — the render loop
+  skips per-layer timing entirely unless a consumer subscribes. New exports:
+  `DrawStatsFrame`, `LayerDrawInfo`.
+
+### Fixed
+
+- **charts:** hovering no longer repaints the row data canvas on every cursor
+  mousemove. The container frame minted a fresh `timeRange` array identity per
+  rebuild (and the frame rebuilds per cursor move), which the Layers draw
+  callback — depending on `container.timeRange` — read as a domain change:
+  each hover frame re-fired the canvas draw effect, including per-layer M4
+  re-decimation (measured 105 repaints per 122 mousemove events; with
+  `decimate` off, hover fell to ~10 fps). The tuple is now identity-stable on
+  its endpoints, restoring the SVG-overlay cursor contract (0 repaints, full
+  frame rate while hovering). Found running uPlot's bench protocol against
+  pond-charts; guarded by a new hover-sweep perf invariant in
+  `e2e/perf-invariants.spec.ts`.
+- **charts:** hovering no longer re-renders cursor-independent components
+  (both `YAxis`, `Bar`/`Box`). The cursor position was a `ContainerFrame`
+  field, so every mousemove re-identified the whole (~50-field) frame and
+  re-rendered **all** its context consumers — even ones that never read the
+  cursor. The per-move cursor state (`cursorX`/`cursorY`/`cursorRowKey`) now
+  lives in a dedicated `CursorContext`; the frame stays identity-stable across
+  a hover, so only the genuine cursor consumers (the `Layers` overlay,
+  `XAxis` crosshair pill, `Legend` values) re-render. Measured: 4 → 2 React
+  commits per mousemove, ~25% less hover script time on the uPlot-bench
+  workload (the win scales with axis/row count). No API change — the split
+  types are internal (`PND-HOVCTX`, follow-up to the repaint fix above).
+- **charts:** corrected the `@pond-ts/charts` package-header doc comment, which
+  described a "chunked Path2D cache" render stage that was explored and
+  **deferred**, never built (it doesn't help the pan case, which re-decimates
+  every frame). The stale comment had misled a consumer's perf investigation.
+
+## [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/AreaChart.js

@@ -59,6 +59,7 @@ export function AreaChart({ series, column, as: semantic, axis, baseline, curve,
     const gapConnectorOpacity = container.theme.gap?.connectorOpacity ?? DEFAULT_GAP_CONNECTOR_OPACITY;
     const entry = useMemo(() => ({
         layer: {
+            as: semantic,
             yExtent: () => areaExtent(cs, baseline),
             // The container infers the shared x scale's kind from its layers — a
             // ValueSeries plots on a value axis, a TimeSeries on time.

package/dist/BandChart.js

@@ -49,6 +49,7 @@ export function BandChart({ series, lower, upper, as: semantic, axis, curve, dec
     }, [semantic]);
     const entry = useMemo(() => ({
         layer: {
+            as: semantic,
             yExtent: () => bandExtent(bs),
             // The container infers the shared x scale's kind from its layers — a
             // ValueSeries plots on a value axis, a TimeSeries on time.

package/dist/BarChart.d.ts

@@ -2,6 +2,7 @@ import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
 import { type BinRecord, type CategoryDatum } from './data.js';
 import { type Orientation } from './bars.js';
+import type { DecimateOption } from './decimate.js';
 export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
      * The source series. Provide **exactly one** of `series` or `bins`.
@@ -120,6 +121,18 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
      * would invert collapses to the style's `minWidth`.
      */
     gap?: number;
+    /**
+     * **M4 column decimation** (charts decimator wave). **Omitted ⇒ `true`**: once
+     * the visible bars are denser than ~2 per device pixel (each slot < ~1px), the
+     * **single-series** bars are drawn as one per-column **envelope** rect — the
+     * exact painted union `[min, max]` of each pixel column's bars — instead of every
+     * bar, so a 100k-bar column chart stays interactive. It is **visually lossless**
+     * at that density (a perf knob, not a style); interaction still reads the source
+     * bars. Pass `false` to always draw every bar, or `{ threshold }` to tune the
+     * samples-per-pixel factor. **No-op for a stacked / multi-group histogram** (the
+     * categorical case is low-count; only the single-series path decimates).
+     */
+    decimate?: DecimateOption;
     /**
      * This layer's `<Legend>` row(s): `false` ⇒ none (opt out), a string ⇒ the
      * display name of a **one-row** layer. **Omitted ⇒** the single path (and a
@@ -180,5 +193,5 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
  * </Layers>
  * ```
  */
-export declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, bins, categories, column, columns, as: semantic, colors, binColors, orientation, ordinal, id, axis, gap, legend, index, }: BarChartProps<S, VS>): null;
+export declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, bins, categories, column, columns, as: semantic, colors, binColors, orientation, ordinal, id, axis, gap, decimate, legend, index, }: BarChartProps<S, VS>): null;
 //# sourceMappingURL=BarChart.d.ts.map

package/dist/BarChart.js

@@ -48,7 +48,7 @@ import { useSlotKey } from './use-slot-key.js';
  * </Layers>
  * ```
  */
-export function BarChart({ series, bins, categories, column, columns, as: semantic, colors, binColors, orientation = 'vertical', ordinal = false, id, axis, gap, legend, index = 0, }) {
+export function BarChart({ series, bins, categories, column, columns, as: semantic, colors, binColors, orientation = 'vertical', ordinal = false, id, axis, gap, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<BarChart> must be rendered inside a <ChartContainer>');
@@ -226,6 +226,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
             const bs = shape.bs;
             return {
                 layer: {
+                    as: semantic,
                     yExtent: () => barExtent(bs),
                     xKind: binAxisKind,
                     xExtent: () => bs.length === 0 ? null : [bs.begin[0], bs.end[bs.length - 1]],
@@ -266,7 +267,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                                 };
                             },
                         }),
-                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover),
+                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover, decimate),
                 },
                 axisId: axis,
                 index,
@@ -279,6 +280,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         const vertical = orientation === 'vertical';
         return {
             layer: {
+                as: semantic,
                 // Horizontal puts the value on the shared x (always 'value'); vertical
                 // keeps the bin axis on x. The bin axis on the *other* side is a linear
                 // numeric scale either way (time ms label via <YAxis ticks>).
@@ -336,6 +338,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         label,
         id,
         gapPx,
+        decimate,
         stackMinWidth,
         selection,
         hover,

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>');
@@ -73,6 +73,7 @@ export function BoxPlot({ series, lower, q1, median, q3, upper, as: semantic, ax
     const hoveredKey = id !== undefined && hov !== null && hov.id === id ? hov.key : null;
     const entry = useMemo(() => ({
         layer: {
+            as: semantic,
             yExtent: () => boxExtent(bx),
             // A ValueSeries plots on a value axis, a TimeSeries on time; the container
             // infers the shared x kind from its layers.
@@ -142,7 +143,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 +167,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>');
@@ -49,6 +49,7 @@ export function Candlestick({ series, open = 'open', high = 'high', low = 'low',
     const label = semantic ?? close;
     const entry = useMemo(() => ({
         layer: {
+            as: semantic,
             yExtent: () => ohlcExtent(ohlc),
             xKind: 'time',
             xExtent: () => ohlc.length === 0 ? null : [ohlc.x[0], ohlc.xEnd[ohlc.length - 1]],
@@ -83,7 +84,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 +97,7 @@ export function Candlestick({ series, open = 'open', high = 'high', low = 'low',
         colorBy,
         gap,
         showOHLC,
+        decimate,
         axis,
         index,
     ]);

package/dist/ChartContainer.d.ts

@@ -2,7 +2,7 @@ import { type ReactNode } from 'react';
 import { type DiscontinuityProvider, type TradingCalendarLike } from './tradingTimeScale.js';
 import { Sequence, BoundedSequence } from 'pond-ts';
 import type { TimeRange } from 'pond-ts';
-import { type AnnotationKind, type CreateSpec, type CursorMode, type SelectInfo, type TrackerInfo } from './context.js';
+import { type AnnotationKind, type CreateSpec, type CursorMode, type SelectInfo, type TrackerInfo, type DrawStatsFrame } from './context.js';
 import { type AxisFormat, type CursorFormat } from './format.js';
 import { type ChartTheme } from './theme.js';
 export interface ChartContainerProps {
@@ -94,9 +94,25 @@ export interface ChartContainerProps {
      */
     showAxis?: boolean;
     /**
-     * Controlled tracker position (epoch ms) — pins the synced crosshair across
-     * rows. Omit for uncontrolled (the chart tracks the pointer itself); pass
-     * `null` to force it hidden. See {@link onTrackerChanged}.
+     * Controlled tracker position (epoch ms) — where to show the synced crosshair
+     * **when this chart isn't the one under the pointer**. A live local hover
+     * always wins over it, so this is a *followed* position, not a hard pin:
+     * supply it to drive the cursor from outside (a scrubber, a playback head, or
+     * — the main use — **cross-chart sync**). Maps through this chart's own
+     * `xScale`, so it lands at the right pixel even under a different zoom.
+     *
+     * **Multi-chart sync** falls out of this plus {@link onTrackerChanged}: give
+     * every `<ChartContainer>` the same `trackerPosition={sharedTime}` and set
+     * `sharedTime` from each one's `onTrackerChanged`. The hovered chart favors its
+     * own pointer (and reports the time out); the others follow. Clear `sharedTime`
+     * to `null` on the group's `onPointerLeave` so the crosshair lifts when the
+     * pointer leaves every chart. (See the "Synced cursors across charts" story /
+     * dashboard guide.)
+     *
+     * **Omit or pass `null`** (equivalent) for no controlled position — a hovered
+     * chart still tracks its pointer, a non-hovered one shows nothing. To force a
+     * chart to *never* show a cursor, use `cursor="none"`, not `trackerPosition`.
+     * See {@link onTrackerChanged}.
      */
     trackerPosition?: number | null;
     /**
@@ -154,9 +170,10 @@ export interface ChartContainerProps {
     onRegionSelect?: (range: readonly [number, number]) => void;
     /**
      * Which modifier a region-drag needs — set `'shift'` when you also enable
-     * `panZoom` and want **plain drag to pan, shift-drag to select**. It's only
-     * enforced while `panZoom` is on (with pan off there's no gesture conflict, so
-     * shift is optional — either drag selects). **Omitted** ⇒ a region-drag
+     * **pan** (`panZoom="pan"` or `"panZoom"`) and want **plain drag to pan,
+     * shift-drag to select**. It's only enforced while pan is enabled (with pan
+     * off there's no gesture conflict, so shift is optional — either drag
+     * selects). **Omitted** ⇒ a region-drag
      * **preempts** pan (drag always selects; document that precedence for users).
      * Wheel-zoom is unaffected in every case.
      */
@@ -166,6 +183,17 @@ export interface ChartContainerProps {
      * you can render a readout outside the chart), and `null` on leave.
      */
     onTrackerChanged?: (info: TrackerInfo | null) => void;
+    /**
+     * Draw-cost + decimation observability. Fires **once per row-canvas repaint**
+     * with a {@link DrawStatsFrame} — one {@link LayerDrawInfo} per layer in that
+     * row carrying its `as`, `drawMs`, and (for a decimating layer) `sourceCount`
+     * / `drawnCount` / `decimated`. Compare `drawnCount` to `sourceCount` to see
+     * whether M4 engaged; read `drawMs` for per-layer render cost. **Omitted ⇒ no
+     * measurement** — the render loop skips per-layer timing entirely, so this is
+     * zero-overhead when unused. Keep the callback cheap (it runs inside the draw
+     * frame); route it to a ref/store rather than doing React state work per frame.
+     */
+    onDrawStats?: (frame: DrawStatsFrame) => void;
     /**
      * Controlled selection — the selected mark (echo the `onSelect` arg back), or
      * `null`. **Omitted ⇒ uncontrolled** (a click on a selectable layer manages it
@@ -212,10 +240,32 @@ export interface ChartContainerProps {
      */
     onHover?: (hit: SelectInfo | null) => void;
     /**
-     * Enable pan/zoom: drag the plot to pan the time range, wheel to zoom around
-     * the cursor. **Default off** — so it doesn't capture drag/scroll unless asked.
+     * Which pan/zoom gestures the plot captures:
+     *
+     * - `'none'` (or `false`, the **default**) — neither; the plot doesn't capture
+     *   drag or scroll.
+     * - `'pan'` — drag to pan the time range, **no** wheel-zoom (scroll still
+     *   scrolls the page).
+     * - `'panZoom'` (or `true`) — drag to pan **and** wheel to zoom around the
+     *   cursor.
+     *
+     * The boolean form is the back-compat shorthand (`true` ⇒ `'panZoom'`,
+     * `false` ⇒ `'none'`). Bound the reachable range with {@link bounds}
+     * (zoom-out / pan extent) and {@link minDuration} (zoom-in floor).
+     */
+    panZoom?: boolean | 'none' | 'pan' | 'panZoom';
+    /**
+     * **Outer pan/zoom extent** — `[min, max]` (same units as {@link range}) the
+     * view can never move outside. Panning into an edge stops there (the window
+     * keeps its span); zooming out is capped at this width, so `bounds` is the
+     * zoom-**out** ceiling that pairs with the {@link minDuration} zoom-**in**
+     * floor. **Omit for no limit** (pan/zoom is unbounded). Constrains gestures
+     * (and any range routed through the container); seed {@link range} within it.
+     * On a trading-time axis the clamp is in wall-clock ms (a sensible outer
+     * limit; the per-session pan/zoom math already holds the trading span at each
+     * calendar edge).
      */
-    panZoom?: boolean;
+    bounds?: readonly [number, number];
     /**
      * Controlled view range — fires on pan/zoom with the new `[start, end]`. Wire
      * it back to `range` for a controlled chart; omit for uncontrolled (the
@@ -340,5 +390,5 @@ export interface ChartContainerProps {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom, onTimeRangeChange, minDuration, cursor, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, cursorFormat, theme, discontinuities, calendar, spacing, grid, sessionDividers, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom, bounds, onTimeRangeChange, minDuration, cursor, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, cursorFormat, theme, discontinuities, calendar, spacing, grid, sessionDividers, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartContainer.d.ts.map