@pond-ts/charts 0.50.0 → 0.52.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.50.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.52.0...HEAD
+[0.52.0]: https://github.com/pond-ts/pond/compare/v0.51.0...v0.52.0
+[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
@@ -50,6 +52,190 @@ and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.52.0] — 2026-07-23
+
+### Changed
+
+- **core / financial:** **Market-scale studies are now typed-array fast**
+  (the "SMA/EMA at 1M bars costs hundreds of ms" report). Three cuts along
+  the same path, all behaviour-preserving (identical values, warm-ups,
+  missing-cell semantics, and rejection errors; every fast path falls back
+  to the original sweep when it doesn't apply):
+  - **`smooth('ema')` columnar fast path** — on a packed numeric source
+    column the EMA recurrence runs straight off the typed buffer into a
+    typed result column via trusted construction (key + untouched columns
+    pass through zero-copy), replacing the per-row Event/tuple rebuild +
+    full-series intake re-pack. 1M rows: **530 ms → 4.4 ms (~120×)**.
+  - **`rolling({ count })` numeric fast path** — an all-built-in numeric
+    mapping over packed sources feeds the shared incremental reducer states
+    directly from the typed buffers and writes snapshots into typed columns
+    (no per-row snapshot arrays, no boxed accumulators, no post-pass
+    assert/re-pack). 1M rows, `avg`: **135 ms → 32 ms (~4×)**.
+  - **financial kernel reads columns, not events** — `rollingColumns` /
+    `columnValues` now read study inputs/outputs off the public column API
+    instead of materializing `series.events` (an Event + data object per
+    row, ~400 ms of pure overhead at 1M rows).
+  - End-to-end at 1M bars: `ema()` **603 ms → 2.5 ms (~240×)**, `sma()`
+    **569 ms → 56 ms (~10×)**, `bollinger()` **748 ms → 162 ms (~4.6×)**.
+    Durable benchmarks: `packages/core/scripts/perf-smooth-ema.mjs`,
+    `packages/financial/scripts/perf-studies.mjs`.
+
+### Added
+
+- **core:** **`TimeSeries.fromArrow(table, options?)` — ingest a decoded Apache
+  Arrow `Table`.** pond stays zero-dependency: bring your own Arrow
+  (`tableFromIPC(...)`) and hand the `Table` in; the input is duck-typed against
+  a small structural surface (`ArrowTableLike` / `ArrowVectorLike` / …, all
+  exported). Ingest is the zero-copy path — every `Float64` column's backing
+  `Float64Array` is adopted as-is (`Float32`/int columns convert; int64 value
+  columns recombine BigInt-free), and the schema is derived from the Arrow
+  fields. The time key is converted **BigInt-free**: Arrow's idiomatic int64
+  timestamps are recombined from their two int32 halves rather than
+  `Number(bigint)` per row — measured **~11× faster** on the time column (0.6ms
+  vs 6.8ms at 500k rows; `scripts/perf-from-arrow.mjs`). Options: `time` (key
+  column, default the `'time'` field), `timeUnit` (default read from the Arrow
+  Arrow type family — a `Timestamp`'s raw-unit int64 is scaled by its
+  `TimeUnit`; `Date32`/`Date64` arrive already normalized to epoch-ms and pass
+  through; overridable), `columns` (subset, in order), `name`, `sort`. Numeric
+  **and string** columns are supported — string columns (Arrow
+  `Utf8`) become dict-encoded `StringColumn`s; any other Arrow type
+  (list/struct) throws, naming it. A null time key throws; numeric nulls map to
+  `NaN` and string nulls to missing.
+- **core:** **`TimeSeries.fromColumns` / `ValueSeries.fromColumns` now accept
+  `string` value columns** (previously numeric-only), packed to dict-encoded
+  `StringColumn`s (`null`/`undefined` → missing) — the shared columnar-ingress
+  engine now dispatches on the schema kind. Other value kinds (`boolean`,
+  arrays) still throw.
+- **charts:** **`<ScatterChart decimate>` — dense scatter plots now decimate**
+  (PND-MARKDEC scatter half — the last un-decimated mark type). **Default
+  `true`.** When the marks are **uniform** (fixed size + colour, no data-driven
+  `radius`/`color`), **opaque**, and denser than the pixel grid, overlapping
+  marks collapse to one representative per **mark-radius cell** via a 2D
+  pixel-**occupancy** sweep. Scatter has no fill, so a line/bar's per-column
+  `[min, max]` envelope would erase interior points — the occupancy grid keeps
+  one mark per occupied cell instead, which is **visually lossless** for uniform
+  opaque marks at that density (same-cell marks overlap). Interaction (hover /
+  click / tracker) still reads **every source point**; the per-point selection
+  ring + labels are suppressed only on the decimated (dense) path. A
+  **translucent** fill (density-encoded — overlap _should_ build up) or a
+  data-driven size/colour keeps the full draw. `decimate={false}` draws every
+  mark; `{ threshold }` tunes the trigger. The occupancy sweep uses the affine
+  fast path for the per-point pixel mapping. Measured (SciChart-suite
+  point-update, real browser): **100k 18 → 73 fps (4×)**, and the ladder now
+  runs to **10M** points (previously dead by 1M). `drawScatter` now returns
+  `LayerDrawStats` (visible via `onDrawStats`).
+
+## [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

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.js

@@ -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.

package/dist/Candlestick.js

@@ -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]],

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

package/dist/ChartContainer.js

@@ -4,10 +4,11 @@ import { scaleLinear } from 'd3-scale';
 import { identityProvider, scaleTradingTime, } from './tradingTimeScale.js';
 import { scaleBand } from './bandScale.js';
 import { Sequence } from 'pond-ts';
-import { ContainerContext, } from './context.js';
+import { ContainerContext, CursorContext, } from './context.js';
 import { maxSlotWidths, sum } from './slots.js';
 import { computeLabelLanes } from './annotations.js';
 import { resolveCursorX, DEFAULT_CURSOR_MODE } from './tracker.js';
+import { clampToBounds } from './viewport.js';
 import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
 import { TimeAxis } from './TimeAxis.js';
 import { defaultTheme } from './theme.js';
@@ -43,7 +44,15 @@ function normalizeRange(range) {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat, theme, discontinuities, calendar, spacing, grid = true, sessionDividers = 'none', children, }) {
+export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom = false, bounds, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat, theme, discontinuities, calendar, spacing, grid = true, sessionDividers = 'none', children, }) {
+    // Normalize the `panZoom` mode (boolean shorthand or the three-way string)
+    // into the two gesture flags the event surface reads. `true` ⇒ both; `'pan'`
+    // ⇒ drag only; `false`/`'none'` ⇒ neither. Zoom implies pan (there is no
+    // zoom-without-pan mode), so `interactive` (holds an internal view) tracks
+    // whichever is on.
+    const panEnabled = panZoom === true || panZoom === 'pan' || panZoom === 'panZoom';
+    const zoomEnabled = panZoom === true || panZoom === 'panZoom';
+    const interactive = panEnabled || zoomEnabled;
     // The explicit base domain from `range` (a tuple or a TimeRange). `undefined`
     // ⇒ auto-fit (resolved from the layers below). Pan/zoom seeds from it; `seed`
     // is the placeholder while auto-fitting.
@@ -57,7 +66,7 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         seed[0],
         seed[1],
     ]);
-    const uncontrolled = panZoom && onTimeRangeChange === undefined;
+    const uncontrolled = interactive && onTimeRangeChange === undefined;
     // While the internal view isn't in use (not uncontrolled), keep it synced to
     // the prop — so *entering* uncontrolled pan/zoom (toggling panZoom on, or a
     // controlled→uncontrolled switch) starts from the current range, not the
@@ -78,12 +87,20 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
     useLayoutEffect(() => {
         onRangeRef.current = onTimeRangeChange;
     });
+    // Latest `bounds` in a ref too, so `applyRange` clamps to the current extent
+    // while staying identity-stable (it's a frame field + a gesture callback dep).
+    const boundsRef = useRef(bounds);
+    useLayoutEffect(() => {
+        boundsRef.current = bounds;
+    });
     const applyRange = useCallback((range) => {
+        const b = boundsRef.current;
+        const next = b ? clampToBounds(range, b) : range;
         const cb = onRangeRef.current;
         if (cb)
-            cb(range);
+            cb(next);
         else
-            setInternalRange(range);
+            setInternalRange(next);
     }, []);
     // Cross-row tracker. We store the cursor's plot-pixel x (not a timestamp), so a
     // still cursor stays put while a live window slides under it; a controlled
@@ -222,6 +239,18 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
     }, [sources]);
     const onTrackerRef = useRef(onTrackerChanged);
     onTrackerRef.current = onTrackerChanged;
+    // Draw-stats sink: hold the latest `onDrawStats` in a ref and expose a *stable*
+    // reporter that reads it, so an inline arrow doesn't re-identify the context
+    // (which would thrash every row's draw memo). The reporter is `undefined` when
+    // there's no subscriber — the signal for `Layers` to skip per-layer timing
+    // entirely (zero overhead when unused). Its identity flips only when the
+    // presence of `onDrawStats` toggles, not on every render.
+    const onDrawStatsRef = useRef(onDrawStats);
+    onDrawStatsRef.current = onDrawStats;
+    const hasDrawStats = onDrawStats !== undefined;
+    const reportDrawStats = useMemo(() => hasDrawStats
+        ? (frame) => onDrawStatsRef.current?.(frame)
+        : undefined, [hasDrawStats]);
     // Selection: controlled (`selected` prop) or uncontrolled (internal). A click
     // on a selectable layer calls `select()` after hit-testing; `onSelect` notifies
     // in both modes, the internal state is managed only when uncontrolled. The full
@@ -531,8 +560,28 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
     // Pack overlapping top-flag labels (markers + regions) into stacked lanes so
     // close-in-x labels don't collide; chips read their lane back off the frame.
     const labelLanes = useMemo(() => computeLabelLanes(annotations, (v) => xScale(v), draggingKey, plotWidth), [annotations, xScale, draggingKey]);
+    // The frame's `[d0, d1]` tuple, identity-stable on the endpoints. The frame
+    // memo rebuilds whenever any of its (many) fields change — a `hovered`
+    // transition, a selection, an annotation edit, a range change — so an inline
+    // `[d0, d1]` literal there would mint a fresh array on any such rebuild, and
+    // every draw callback listing `container.timeRange` in its deps (Layers'
+    // data-canvas draw) would read that as a domain change and replot the row
+    // canvas. Memoizing on the endpoints keeps the draw stable across those
+    // unrelated rebuilds. (Cursor *position* no longer rebuilds the frame at all —
+    // it lives in `cursorFrame` below, [PND-HOVCTX] — but the tuple stays a memo
+    // to hold the line for every other rebuild path.)
+    const timeRangeTuple = useMemo(() => [d0, d1], [d0, d1]);
+    // The per-move cursor state, split into its own context so a mousemove
+    // re-identifies only this small object — not the ~50-field frame below, which
+    // stays stable across hovers so `YAxis` / `Bar` / `Box` don't re-render. See
+    // [PND-HOVCTX] / {@link CursorContext}.
+    const cursorFrame = useMemo(() => ({
+        cursorX,
+        cursorY: hoverPoint?.y ?? null,
+        cursorRowKey: hoverPoint?.rowKey ?? null,
+    }), [cursorX, hoverPoint]);
     const frame = useMemo(() => ({
-        timeRange: [d0, d1],
+        timeRange: timeRangeTuple,
         width,
         theme: theme ?? defaultTheme,
         plotWidth,
@@ -541,16 +590,14 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         leftGutter,
         rightGutter,
         rowGap,
-        cursorX,
         setHoverX,
-        cursorY: hoverPoint?.y ?? null,
-        cursorRowKey: hoverPoint?.rowKey ?? null,
         setHoverY,
         crosshairSnap,
         cursorBuckets,
         regionAnchor,
         setRegionAnchor,
         onRegionSelect,
+        reportDrawStats,
         regionSelectModifier,
         draggingKey,
         setDragging,
@@ -588,15 +635,15 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         discontinuities: xDiscontinuities,
         grid,
         sessionDividers,
-        panZoom,
+        panEnabled,
+        zoomEnabled,
         minDuration,
         applyRange,
         registerGutter,
         registerRow,
         firstRowKey,
     }), [
-        d0,
-        d1,
+        timeRangeTuple,
         width,
         theme,
         plotWidth,
@@ -605,14 +652,13 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         leftGutter,
         rightGutter,
         rowGap,
-        cursorX,
-        hoverPoint,
         setHoverY,
         crosshairSnap,
         cursorBuckets,
         regionAnchor,
         setRegionAnchor,
         onRegionSelect,
+        reportDrawStats,
         regionSelectModifier,
         draggingKey,
         setDragging,
@@ -650,20 +696,21 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         xDiscontinuities,
         grid,
         sessionDividers,
-        panZoom,
+        panEnabled,
+        zoomEnabled,
         minDuration,
         applyRange,
         registerGutter,
         registerRow,
         firstRowKey,
     ]);
-    return (_jsx(ContainerContext.Provider, { value: frame, children: _jsxs("div", { style: { width: `${width}px` }, children: [_jsx("div", { style: {
-                        display: 'flex',
-                        flexDirection: 'column',
-                        gap: `${rowGap}px`,
-                        // The positioned ancestor for overlay chrome (`<Legend>`): the
-                        // card anchors to the rows block, never the axis strip below.
-                        position: 'relative',
-                    }, children: children }), showAxis && _jsx(TimeAxis, {})] }) }));
+    return (_jsx(ContainerContext.Provider, { value: frame, children: _jsx(CursorContext.Provider, { value: cursorFrame, children: _jsxs("div", { style: { width: `${width}px` }, children: [_jsx("div", { style: {
+                            display: 'flex',
+                            flexDirection: 'column',
+                            gap: `${rowGap}px`,
+                            // The positioned ancestor for overlay chrome (`<Legend>`): the
+                            // card anchors to the rows block, never the axis strip below.
+                            position: 'relative',
+                        }, children: children }), showAxis && _jsx(TimeAxis, {})] }) }) }));
 }
 //# sourceMappingURL=ChartContainer.js.map