@pond-ts/charts 0.50.0 → 0.52.0

package/dist/line.js

@@ -1,10 +1,41 @@
 import { line as d3line, curveLinear } from 'd3-shape';
 import { cullChartSeries } from './culling.js';
-import { decimateM4 } from './decimate.js';
+import { decimateM4Cached } from './decimate.js';
+import { affineOf } from './affine.js';
 import { bridgeGaps, collectGapEdges, drawGapBridges, drawGapFades, drawGapSteps, DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
 /** Shared empty boundary list — passed to `sessionRuns` when a decimated series
  *  already carries its session breaks as baked-in `NaN` points. */
 const EMPTY_BOUNDARIES = [];
+/**
+ * Stroke one run of `ys` (aligned index-for-index with `xs`) through the affine
+ * pixel maps `ax` / `ay` — the [PND-AFFINE] fast path. Replicates d3-shape's
+ * `curveLinear` + `.defined(Number.isFinite)` behaviour exactly: a non-finite
+ * value lifts the pen (the next finite point `moveTo`s a fresh subpath), a
+ * finite value `lineTo`s (or `moveTo`s when the pen is up), so a gap breaks and
+ * a lone point draws nothing — the same op sequence the generator emits, minus
+ * the per-point `scale()` + d3-shape closures. The caller brackets
+ * `beginPath`/`stroke`; `xs`/`ys` are the run (a `subarray` view, so index 0 is
+ * the run start). Used for lines and for the area outline.
+ */
+export function strokeAffinePolyline(ctx, xs, ys, ax, ay) {
+    const n = ys.length;
+    let penDown = false;
+    for (let j = 0; j < n; j += 1) {
+        const v = ys[j];
+        if (!Number.isFinite(v)) {
+            penDown = false;
+            continue;
+        }
+        const px = ax.k * xs[j] + ax.b;
+        const py = ay.k * v + ay.b;
+        if (penDown)
+            ctx.lineTo(px, py);
+        else {
+            ctx.moveTo(px, py);
+            penDown = true;
+        }
+    }
+}
 /**
  * The y-scale's domain lower bound (the axis floor) in pixels — where the
  * `step` / `fade` gap bridges drop to. The runtime `yScale` is a d3
@@ -68,31 +99,37 @@ export function yExtent(cs) {
  * output is identical to a single-pass draw.
  */
 export function drawLine(ctx, cs, xScale, yScale, style, curve = curveLinear, gaps = DEFAULT_GAP_MODE, gapConnectorOpacity = DEFAULT_GAP_CONNECTOR_OPACITY, boundaries = [], decimate = true) {
-    // Viewport culling (Phase 2): clip to the visible slice (+1 entry/exit point)
-    // before any path work, so a pan repaint strokes O(visible), not O(N). A no-op
-    // — the same `cs` object back — when the whole series is in view or `xScale`
-    // exposes no domain (a bare test stub), keeping the fully-visible hot path
-    // byte-identical. Everything below indexes `cs` relatively, so the zero-copy
-    // subarray view drops in transparently; `boundaries` are absolute instants that
-    // `sessionRuns` bisects by value, so they still cut the slice correctly.
-    cs = cullChartSeries(cs, xScale);
-    // M4 decimation (Phase 3): once the culled slice is still denser than ~2
-    // samples per device pixel, replace it with the pixel-dense M4 polyline
-    // ({@link decimateM4}) — O(devicePlotWidth) points that rasterize identically.
-    // The edge union makes the decimated series break at exactly the real gaps
-    // (gap-mode connectors compose unchanged) **and** aligns a bucket edge to each
-    // session break in `boundaries`, so `sessionRuns` below still splits the
-    // decimated series into clean per-session subpaths. Only a non-linear **curve**
-    // stays gated (a smoothing curve would distort the 4-points-per-column
-    // polyline) — that draws full-resolution. Off (`decimate === false`) or a curve
-    // set ⇒ the full culled slice draws. `decimateM4` itself no-ops on a sparse
-    // slice or a domainless test scale, so this stays byte-identical there.
+    const sourceCount = cs.length; // pre-cull, pre-decimation (for draw stats)
+    const source = cs; // pre-cull source — the decimation cache key ([PND-DECKEY])
+    // Two paths clip `cs` to what actually draws:
+    //  - **Decimated** (linear curve, `decimate !== false`): cull to the visible
+    //    slice, then replace it with the pixel-dense M4 polyline ({@link decimateM4})
+    //    — O(devicePlotWidth) points that rasterize identically. The edge union
+    //    breaks the decimated series at exactly the real gaps (gap-mode connectors
+    //    compose unchanged) **and** aligns a bucket edge to each session break in
+    //    `boundaries`, so `sessionRuns` below still splits it into clean per-session
+    //    subpaths. Cull + decimate are **memoized per source** ({@link
+    //    decimateM4Cached}) so a y-zoom / y-autorange frame reuses the prior
+    //    polyline instead of re-binning O(N) — the decimation output never depends
+    //    on the y-scale (finding 3). `decimateM4` no-ops on a sparse slice or a
+    //    domainless test scale, so this stays byte-identical there.
+    //  - **Full-resolution** (a smoothing curve would distort the 4-points-per-
+    //    column polyline, or `decimate === false`): just cull to the visible slice
+    //    (+1 entry/exit point) so a pan repaint strokes O(visible), not O(N). A
+    //    no-op — the same `cs` back — when the whole series is in view or `xScale`
+    //    exposes no domain (a bare test stub), keeping that hot path byte-identical.
+    // Everything below indexes `cs` relatively, so the zero-copy subarray view drops
+    // in transparently; `boundaries` are absolute instants that `sessionRuns`
+    // bisects by value, so they still cut the slice correctly.
     let decimated = false;
     if (decimate !== false && curve === curveLinear) {
         const k = typeof decimate === 'object' ? decimate.threshold : undefined;
-        const before = cs;
-        cs = decimateM4(cs, xScale, ctx, k, boundaries);
-        decimated = cs !== before;
+        const r = decimateM4Cached(source, xScale, ctx, k, boundaries);
+        cs = r.series;
+        decimated = r.decimated;
+    }
+    else {
+        cs = cullChartSeries(source, xScale);
     }
     // Split into independent index runs at each boundary; no boundary inside the
     // data ⇒ one run over the whole series (the hot path — no slicing, so the draw
@@ -103,6 +140,14 @@ export function drawLine(ctx, cs, xScale, yScale, style, curve = curveLinear, ga
     // the sessions.
     const runs = sessionRuns(cs.x, cs.length, decimated ? EMPTY_BOUNDARIES : boundaries);
     const singleRun = runs.length === 1;
+    // [PND-AFFINE] fast path: when the curve is linear and **both** scales are
+    // affine (every y axis is `scaleLinear`; x is `scaleLinear` / `scaleTime` /
+    // the gap-free default trading axis — a real-gap trading scale probes
+    // non-affine and is rejected), stroke each run with an inline multiply-add over
+    // the typed arrays, skipping the per-point d3-scale + d3-shape closures. Any
+    // other case (smoothing curve, non-affine x) keeps the exact d3-shape path.
+    const ax = curve === curveLinear ? affineOf(xScale) : null;
+    const ay = ax !== null ? affineOf(yScale) : null;
     // Solid pass: one path across every run. Each run's generator opens with its
     // own moveTo, so a run boundary is a clean pen-up — the session break.
     ctx.beginPath();
@@ -113,13 +158,19 @@ export function drawLine(ctx, cs, xScale, yScale, style, curve = curveLinear, ga
         // bridge, if any, is a separate overlay pass below).
         const seg = singleRun ? cs.y : cs.y.subarray(s, e);
         const ys = gaps === 'none' ? bridgeGaps(seg, e - s) : seg;
-        const gen = d3line()
-            .defined((v) => Number.isFinite(v))
-            .x((_, j) => xScale(cs.x[s + j]))
-            .y((v) => yScale(v))
-            .curve(curve)
-            .context(ctx);
-        gen(ys);
+        if (ax !== null && ay !== null) {
+            const xs = singleRun ? cs.x : cs.x.subarray(s, e);
+            strokeAffinePolyline(ctx, xs, ys, ax, ay);
+        }
+        else {
+            const gen = d3line()
+                .defined((v) => Number.isFinite(v))
+                .x((_, j) => xScale(cs.x[s + j]))
+                .y((v) => yScale(v))
+                .curve(curve)
+                .context(ctx);
+            gen(ys);
+        }
     }
     ctx.strokeStyle = style.color;
     ctx.lineWidth = style.width;
@@ -157,6 +208,9 @@ export function drawLine(ctx, cs, xScale, yScale, style, curve = curveLinear, ga
             drawGapFades(ctx, edges, baselinePxFromScale(yScale), style.color, style.width);
         }
     }
+    // `drawnCount` = points actually stroked (culled slice, or the M4 polyline when
+    // decimation engaged); `sourceCount` = the full series it started from.
+    return { sourceCount, drawnCount: cs.length, decimated };
 }
 /**
  * Split a sorted columnar x-axis into contiguous index runs `[start, endEx)`,

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 { LayerDrawStats } from './context.js';
 import { type DecimateOption } from './decimate.js';
 /**
  * How an OHLC mark renders (pjm17971's fork 2 — bundled as one component, like
@@ -78,5 +79,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, decimate?: DecimateOption): 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): LayerDrawStats;
 //# sourceMappingURL=ohlc.d.ts.map

package/dist/ohlc.js

@@ -92,6 +92,7 @@ export function resolveCandleStyle(style, open, close, colorBy) {
  */
 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;
+    const sourceCount = ohlc.length; // pre-cull, pre-decimation (for draw stats)
     // 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);
@@ -103,11 +104,12 @@ export function drawCandles(ctx, ohlc, xScale, yScale, style, variant = 'candle'
     // 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
+    const decimatedOhlc = decimate !== false
         ? decimateOhlc(ohlc, xScale, ctx, 2, vEnd - vStart)
         : ohlc;
-    if (decimated !== ohlc) {
-        ohlc = decimated; // aggregate candles are already the visible set
+    const decimated = decimatedOhlc !== ohlc;
+    if (decimated) {
+        ohlc = decimatedOhlc; // aggregate candles are already the visible set
         vStart = 0;
         vEnd = ohlc.length;
     }
@@ -170,5 +172,8 @@ export function drawCandles(ctx, ohlc, xScale, yScale, style, variant = 'candle'
             ctx.fillRect(bx0, top, bodyW, h);
         }
     }
+    // `drawnCount` = candle slots iterated (visible span, or the aggregate set when
+    // decimation engaged); `sourceCount` = the raw candle count it started from.
+    return { sourceCount, drawnCount: vEnd - vStart, decimated };
 }
 //# sourceMappingURL=ohlc.js.map

package/dist/scatter.d.ts

@@ -2,7 +2,8 @@ import type { ChartSeries } from './data.js';
 import type { Scale } from './line.js';
 import type { ScatterStyle } from './theme.js';
 import type { ResolvedEncoding } from './encoding.js';
-import type { SelectInfo } from './context.js';
+import type { SelectInfo, LayerDrawStats } from './context.js';
+import { type DecimateOption } from './decimate.js';
 /**
  * Index of the point in `cs` **nearest** `time` by `|x − time|`, restricted to
  * finite points, or `-1` if none. `cs.x` is the sorted time axis, so a binary
@@ -52,7 +53,7 @@ export declare function scatterExtent(cs: ChartSeries): [number, number] | null;
 export declare function drawScatter(ctx: CanvasRenderingContext2D, cs: ChartSeries, xScale: Scale, yScale: Scale, style: ScatterStyle, encoding: ResolvedEncoding, keyAt: (i: number) => number, labelAt: ((i: number) => string | undefined) | undefined, font: {
     readonly family: string;
     readonly size: number;
-}, selected: SelectInfo | null, seriesId: string | undefined, offsetPx?: number): void;
+}, selected: SelectInfo | null, seriesId: string | undefined, offsetPx?: number, decimate?: DecimateOption): LayerDrawStats;
 /**
  * Hit-test plot-pixel `(qx, qy)` against the scatter's points — the topmost
  * point whose circle contains the click, or `null`. "Topmost" = the

package/dist/scatter.js

@@ -1,4 +1,5 @@
 import { visiblePointRange } from './culling.js';
+import { shouldDecimateCount, decimateScatter, isOpaqueColor, } from './decimate.js';
 /**
  * Scatter geometry + the canvas draw — pure, like {@link drawLine} /
  * {@link drawBand}, so the recording-mock tests assert the op sequence and the
@@ -117,7 +118,7 @@ export function scatterExtent(cs) {
  *                of the selection match. A point lights only when the selection's
  *                `id` matches, keyed to the sample by its `key`.
  */
-export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, selected, seriesId, offsetPx = 0) {
+export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, selected, seriesId, offsetPx = 0, decimate = true) {
     ctx.save();
     // The selection only lights up a point of *this* series; resolve the key once.
     // A no-id (non-selectable) layer passes `undefined` and never matches.
@@ -158,9 +159,64 @@ export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, lab
     const [vStart, vEnd] = pad > 0
         ? visiblePointRange(cs.x, cs.length, xScale, pad)
         : [w0Start, w0End];
+    // [PND-MARKDEC] scatter decimation. When the marks are **uniform** (fixed
+    // size + colour), **opaque**, and denser than the pixel grid, collapse each
+    // overlapping cluster to one representative per mark-radius cell (2D
+    // occupancy — {@link decimateScatter}). Visually lossless at that density, and
+    // O(visible). Interaction is unaffected ({@link hitTestScatter} still walks
+    // every source point); the selection ring and per-point labels are dropped on
+    // this path — both are illegible under a dense blob — matching the decimated
+    // bar path. Data-driven size/colour (`!encoding.uniform`) or a translucent
+    // fill (density-encoded, where overlap *should* build up) keep the full draw.
+    const visibleCount = vEnd - vStart;
+    const k = typeof decimate === 'object' && decimate.threshold !== undefined
+        ? decimate.threshold
+        : 2;
+    if (decimate !== false &&
+        encoding.uniform &&
+        shouldDecimateCount(visibleCount, ctx, k) &&
+        isOpaqueColor(encoding.colorAt(vStart))) {
+        const r = encoding.radiusAt(vStart);
+        const dec = decimateScatter(cs, xScale, yScale, Math.max(1, r), vStart, vEnd);
+        // Only take the decimated pass if it actually shrank the work (a sparse-in-y
+        // scatter over the threshold may not overlap — then the full draw is fine,
+        // and keeps its selection ring + labels). Compare against the **finite**
+        // visible count, not `vEnd - vStart`: `decimateScatter` skips gaps, so the
+        // raw span would falsely read as a reduction on any gappy series (and wrongly
+        // suppress the ring / labels with zero cell collisions).
+        let finite = 0;
+        for (let i = vStart; i < vEnd; i += 1)
+            if (isPoint(cs, i))
+                finite += 1;
+        if (dec.length < finite) {
+            ctx.fillStyle = encoding.colorAt(vStart);
+            const outlined = style.outlineWidth > 0;
+            if (outlined) {
+                ctx.lineWidth = style.outlineWidth;
+                ctx.strokeStyle = style.outline;
+            }
+            for (let j = 0; j < dec.length; j += 1) {
+                const px = xScale(dec.x[j]) + offsetPx;
+                const py = yScale(dec.y[j]);
+                ctx.beginPath();
+                ctx.arc(px, py, r, 0, Math.PI * 2);
+                ctx.fill();
+                if (outlined)
+                    ctx.stroke();
+            }
+            ctx.restore();
+            return {
+                sourceCount: cs.length,
+                drawnCount: dec.length,
+                decimated: true,
+            };
+        }
+    }
+    let drawn = 0;
     for (let i = vStart; i < vEnd; i += 1) {
         if (!isPoint(cs, i))
             continue;
+        drawn += 1;
         // `offsetPx` nudges the whole scatter in pixel space (zoom-stable) — for
         // pairing same-key marks (call/put at one strike) beside each other.
         const px = xScale(cs.x[i]) + offsetPx;
@@ -212,6 +268,10 @@ export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, lab
         }
     }
     ctx.restore();
+    // Full draw (no decimation): every finite mark in the visible window drew.
+    // `drawnCount < sourceCount` here reflects viewport **culling**, not
+    // decimation (`decimated: false`).
+    return { sourceCount: cs.length, drawnCount: drawn, decimated: false };
 }
 /** Gap (px) between a point's edge and its label text. */
 const LABEL_GAP = 4;

package/dist/tracker.d.ts

@@ -58,10 +58,23 @@ export declare function cursorParts(mode: CursorMode): {
     readonly band: boolean;
 };
 /**
- * The crosshair's plot-pixel x from the tracker inputs. A controlled
- * `trackerPosition` (epoch ms) maps through `xScale`, so a pinned time rides with
- * the data; `null` hides it; `undefined` (uncontrolled) uses the stored hover
- * pixel, so a still cursor stays put while a live window slides under it.
+ * The crosshair's plot-pixel x from the tracker inputs. **A live local pointer
+ * always wins:** a chart the user is actively hovering (`hoverX` non-null) shows
+ * its own cursor, even when a controlled `trackerPosition` is also supplied.
+ * With no local pointer, a controlled `trackerPosition` (epoch ms) maps through
+ * this chart's `xScale` — so a pinned/synced time rides with the data and lands
+ * at the right pixel even under a different zoom — else there's no cursor.
+ *
+ * This ordering is what makes **cross-chart cursor sync** compose from the plain
+ * props: give every chart the same `trackerPosition={sharedTime}` and wire
+ * `onTrackerChanged` back to `sharedTime`. The chart under the pointer favors its
+ * own hover (it's the source, and reports out); every other chart has no local
+ * pointer, so it follows the shared time. No "which chart is active" bookkeeping.
+ *
+ * `null` and `undefined` are **equivalent** — both mean "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 at all, use `cursor="none"`, not
+ * `trackerPosition={null}`.
  */
 export declare function resolveCursorX(trackerPosition: number | null | undefined, hoverX: number | null, xScale: (time: number) => number): number | null;
 //# sourceMappingURL=tracker.d.ts.map

package/dist/tracker.js

@@ -105,15 +105,28 @@ export function cursorParts(mode) {
     }
 }
 /**
- * The crosshair's plot-pixel x from the tracker inputs. A controlled
- * `trackerPosition` (epoch ms) maps through `xScale`, so a pinned time rides with
- * the data; `null` hides it; `undefined` (uncontrolled) uses the stored hover
- * pixel, so a still cursor stays put while a live window slides under it.
+ * The crosshair's plot-pixel x from the tracker inputs. **A live local pointer
+ * always wins:** a chart the user is actively hovering (`hoverX` non-null) shows
+ * its own cursor, even when a controlled `trackerPosition` is also supplied.
+ * With no local pointer, a controlled `trackerPosition` (epoch ms) maps through
+ * this chart's `xScale` — so a pinned/synced time rides with the data and lands
+ * at the right pixel even under a different zoom — else there's no cursor.
+ *
+ * This ordering is what makes **cross-chart cursor sync** compose from the plain
+ * props: give every chart the same `trackerPosition={sharedTime}` and wire
+ * `onTrackerChanged` back to `sharedTime`. The chart under the pointer favors its
+ * own hover (it's the source, and reports out); every other chart has no local
+ * pointer, so it follows the shared time. No "which chart is active" bookkeeping.
+ *
+ * `null` and `undefined` are **equivalent** — both mean "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 at all, use `cursor="none"`, not
+ * `trackerPosition={null}`.
  */
 export function resolveCursorX(trackerPosition, hoverX, xScale) {
-    if (trackerPosition === undefined)
+    if (hoverX !== null)
         return hoverX;
-    if (trackerPosition === null)
+    if (trackerPosition == null)
         return null;
     return xScale(trackerPosition);
 }

package/dist/useChartLegend.d.ts

@@ -1,4 +1,4 @@
-import { type ContainerFrame } from './context.js';
+import { type ContainerFrame, type CursorFrame } from './context.js';
 import type { SelectInfo } from './context.js';
 import { type LegendItemInput, type SwatchSpec } from './swatch.js';
 /** One legend **item** as {@link useChartLegend} serves it — a series entry:
@@ -74,7 +74,7 @@ export declare function swatchColor(s: SwatchSpec): string;
  *  card can never disagree about rows or sync semantics. Pass a `rowKey` to
  *  **scope** the rows to a single chart row (the layers registered under it);
  *  omit it for the whole container. */
-export declare function buildChartLegend(container: ContainerFrame, rowKey?: symbol): ChartLegend;
+export declare function buildChartLegend(container: ContainerFrame, cursor: CursorFrame, rowKey?: symbol): ChartLegend;
 /**
  * **Headless legend** — the registry `<Legend>` renders, as data, plus the
  * hover/select verbs already wired to the chart. For consumers whose legend

package/dist/useChartLegend.js

@@ -1,5 +1,5 @@
 import { useContext, useMemo } from 'react';
-import { ContainerContext, RowContext, } from './context.js';
+import { ContainerContext, CursorContext, RowContext, } from './context.js';
 import { orderLegendItems, } from './swatch.js';
 /** The series-scoped {@link SelectInfo} a legend interaction reports: no
  *  sample under it, so `key`/`value` are deliberately `NaN` (see the
@@ -38,7 +38,7 @@ export function swatchColor(s) {
  *  card can never disagree about rows or sync semantics. Pass a `rowKey` to
  *  **scope** the rows to a single chart row (the layers registered under it);
  *  omit it for the whole container. */
-export function buildChartLegend(container, rowKey) {
+export function buildChartLegend(container, cursor, rowKey) {
     const scoped = Array.from(container.legendItems.values()).filter((it) => rowKey === undefined || it.rowKey === rowKey);
     // Ordered + deduped specs (chart-row first), each carrying its `rowKey`;
     // group consecutive same-row specs into a LegendRow, mapping spec → item.
@@ -61,10 +61,10 @@ export function buildChartLegend(container, rowKey) {
     }
     // The cursor pixel → axis units, exactly as the tracker fan-in resolves it
     // (in-bounds guard included, so an off-plot cursor reads as "no cursor").
-    const cursorTime = container.cursorX !== null &&
-        container.cursorX >= 0 &&
-        container.cursorX <= container.plotWidth
-        ? +container.xScale.invert(container.cursorX)
+    const cursorTime = cursor.cursorX !== null &&
+        cursor.cursorX >= 0 &&
+        cursor.cursorX <= container.plotWidth
+        ? +container.xScale.invert(cursor.cursorX)
         : null;
     return {
         rows,
@@ -115,8 +115,9 @@ export function useChartLegend() {
     if (container === null) {
         throw new Error('useChartLegend() must be used inside a <ChartContainer>');
     }
+    const cursor = useContext(CursorContext);
     // A RowContext in scope (rendered inside a <Layers>) narrows to that row.
     const rowKey = useContext(RowContext)?.rowKey;
-    return useMemo(() => buildChartLegend(container, rowKey), [container, rowKey]);
+    return useMemo(() => buildChartLegend(container, cursor, rowKey), [container, cursor, rowKey]);
 }
 //# sourceMappingURL=useChartLegend.js.map

package/dist/viewport.d.ts

@@ -5,6 +5,25 @@
  * the geometry is unit-tested directly, like {@link maxSlotWidths} / the tracker.
  */
 export type TimeRange = readonly [number, number];
+/**
+ * Clamp a view range to an **outer extent** `bounds` — the pan/zoom limit, so
+ * the view can never show time outside `[bounds[0], bounds[1]]`. Applied at the
+ * range choke point (`applyRange`) so it constrains **every** gesture (pan,
+ * zoom-out) and any programmatic range in one place:
+ *
+ * - **Wider than the extent** (zoomed out past the whole span) → clamp to the
+ *   full `bounds` (you can't zoom out beyond the total). This makes `bounds`'s
+ *   width the zoom-**out** ceiling, the outer companion to the `minDuration`
+ *   zoom-**in** floor.
+ * - **Panned past an edge** → slide back so the nearer edge sits on the bound,
+ *   **preserving the span** (a pan into the boundary stops rather than shrinking
+ *   the window).
+ * - **Already inside** → unchanged.
+ *
+ * A degenerate `bounds` (`hi <= lo`) is treated as "no constraint" (returns the
+ * range untouched) so a mis-specified extent can't collapse the view.
+ */
+export declare function clampToBounds(range: TimeRange, bounds: TimeRange): [number, number];
 /**
  * Shift a range by `dt` ms (drag-pan). The caller signs `dt` from the gesture —
  * dragging the plot right reveals earlier data, i.e. a negative `dt`.

package/dist/viewport.js

@@ -4,6 +4,38 @@
  * `Layers` supplies the pixel→time deltas). Kept pure + free of React/canvas so
  * the geometry is unit-tested directly, like {@link maxSlotWidths} / the tracker.
  */
+/**
+ * Clamp a view range to an **outer extent** `bounds` — the pan/zoom limit, so
+ * the view can never show time outside `[bounds[0], bounds[1]]`. Applied at the
+ * range choke point (`applyRange`) so it constrains **every** gesture (pan,
+ * zoom-out) and any programmatic range in one place:
+ *
+ * - **Wider than the extent** (zoomed out past the whole span) → clamp to the
+ *   full `bounds` (you can't zoom out beyond the total). This makes `bounds`'s
+ *   width the zoom-**out** ceiling, the outer companion to the `minDuration`
+ *   zoom-**in** floor.
+ * - **Panned past an edge** → slide back so the nearer edge sits on the bound,
+ *   **preserving the span** (a pan into the boundary stops rather than shrinking
+ *   the window).
+ * - **Already inside** → unchanged.
+ *
+ * A degenerate `bounds` (`hi <= lo`) is treated as "no constraint" (returns the
+ * range untouched) so a mis-specified extent can't collapse the view.
+ */
+export function clampToBounds(range, bounds) {
+    const [lo, hi] = bounds;
+    const maxSpan = hi - lo;
+    if (!(maxSpan > 0))
+        return [range[0], range[1]];
+    const span = range[1] - range[0];
+    if (span >= maxSpan)
+        return [lo, hi];
+    if (range[0] < lo)
+        return [lo, lo + span];
+    if (range[1] > hi)
+        return [hi - span, hi];
+    return [range[0], range[1]];
+}
 /**
  * Shift a range by `dt` ms (drag-pan). The caller signs `dt` from the gesture —
  * dragging the plot right reveals earlier data, i.e. a negative `dt`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.50.0",
+  "version": "0.52.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.50.0",
-    "pond-ts": "^0.50.0",
+    "@pond-ts/react": "^0.52.0",
+    "pond-ts": "^0.52.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {