@pond-ts/charts 0.69.0 → 0.71.0

package/dist/cursors.js

@@ -1,21 +1,24 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useContext, useEffect, useMemo } from 'react';
+import { useContext, useEffect, useLayoutEffect, useMemo, useRef, } from 'react';
 import { ContainerContext, RowContext, } from './context.js';
 import { renderBrushBand } from './brush.js';
 import { flagChipStyle, flagChipX, axisPillStyle, axisPillX, axisPillConnector, } from './chip.js';
 import { useSlotKey } from './use-slot-key.js';
 import { isDev } from './dev.js';
 /**
- * Cursor **presets** — the mounted-component successors of the `cursor` string
- * modes (interaction RFC §4 / A4.1): `<LineCursor>`, `<PointCursor>`,
- * `<InlineCursor>`, `<FlagCursor>`, `<CrosshairCursor>`, `<RangeCursor>`.
+ * Cursor **presets** (interaction RFC §4 / A4.1): `<LineCursor>`,
+ * `<PointCursor>`, `<InlineCursor>`, `<FlagCursor>`, `<CrosshairCursor>`,
+ * `<RangeCursor>`. **A chart shows a cursor only when one is mounted** —
+ * mounting none means no in-chart cursor (hover still reports through
+ * `onTrackerChanged`).
  *
  * Each preset registers a `CursorSpec` with the container (the
  * `registerAxis` / `registerLayer` idiom): **declared** snap plus render slots
  * taking resolved geometry. The container resolves — the x-snap, the
  * per-sample measurements, the band — and the slots draw (RFC A2.3). Mount a
  * preset as a child of `<ChartContainer>` (the default for every row) or
- * inside a `<ChartRow>` (the per-row override, replacing `<ChartRow cursor>`).
+ * inside a `<ChartRow>` (the per-row override: a row with its own mounts
+ * ignores the container's).
  *
  * Render-only presets may stack; **one cursor owns snap and gesture per
  * scope**, resolved to the hovered row's innermost mount (RFC A2.5) — the
@@ -78,12 +81,13 @@ function cursorLine(f) {
 }
 const NO_WANTS = {
     samples: false,
+    reticle: false,
     flags: false,
     band: false,
     pointer: false,
     time: false,
 };
-/** `cursor="line"` as a spec: the synced vertical line only (+ optional time). */
+/** `<LineCursor>` as a spec: the synced vertical line only (+ optional time). */
 function buildLineCursor(o) {
     return {
         spec: {
@@ -95,9 +99,10 @@ function buildLineCursor(o) {
         },
         wants: { ...NO_WANTS, time: o.showTime },
         ownsGesture: false,
+        format: o.format,
     };
 }
-/** `cursor="point"` as a spec: a dot on each series, no line. */
+/** `<PointCursor>` as a spec: a dot on each series, no line. */
 function buildPointCursor(o) {
     return {
         spec: {
@@ -109,9 +114,10 @@ function buildPointCursor(o) {
         },
         wants: { ...NO_WANTS, samples: true, time: o.showTime },
         ownsGesture: false,
+        format: o.format,
     };
 }
-/** `cursor="inline"` as a spec: dots + a value chip beside each, clamped
+/** `<InlineCursor>` as a spec: dots + a value chip beside each, clamped
  *  within the row and flipped left near the right edge. */
 function buildInlineCursor(o) {
     return {
@@ -137,9 +143,10 @@ function buildInlineCursor(o) {
         },
         wants: { ...NO_WANTS, samples: true, time: o.showTime },
         ownsGesture: false,
+        format: o.format,
     };
 }
-/** `cursor="flag"` as a spec: dots + staffed value flags stacked near the top
+/** `<FlagCursor>` as a spec: dots + staffed value flags stacked near the top
  *  of the row, plus the consolidated one-chip flag for `cursorFlag` layers
  *  (BoxPlot). The time readout (when shown, first row) tops the stack and the
  *  staffs start just below it. */
@@ -181,13 +188,29 @@ function buildFlagCursor(o) {
         },
         wants: { ...NO_WANTS, samples: true, flags: true, time: o.showTime },
         ownsGesture: false,
+        format: o.format,
     };
 }
+/**
+ * The sample the snapping crosshair centres on in a row: the one nearest the
+ * pointer y in the hovered row — or the first sample when nothing is hovered
+ * (a pinned tracker shows a reticle in every row). `null` in a row that isn't
+ * hovered while another is, or when there is nothing to snap to.
+ */
+function snappedSample(f) {
+    const samples = f.reticleSamples;
+    if (inBoundsX(f) === null || samples.length === 0)
+        return null;
+    const cy = f.cursorY;
+    if (f.hoveredRowKey === f.rowKey && cy !== null) {
+        return samples.reduce((a, b) => Math.abs(b.py - cy) < Math.abs(a.py - cy) ? b : a);
+    }
+    return f.hoveredRowKey === null ? samples[0] : null;
+}
 /**
  * The crosshair's single reticle centre for a row: with `snap` (default) the
- * sample nearest the pointer y in the hovered row — or the first sample when
- * nothing is hovered (a pinned tracker shows a reticle in every row); free
- * mode reads the container-resolved raw-pointer measurement.
+ * {@link snappedSample}; free mode reads the container-resolved raw-pointer
+ * measurement.
  *
  * It carries the picked sample's **axis placement** (side + gutter offset +
  * axis ink) as well as its value, because the reticle reads one series and its
@@ -199,16 +222,8 @@ function crosshairPick(f, snap) {
     if (inBoundsX(f) === null)
         return null;
     if (!snap)
-        return f.pointer;
-    if (f.samples.length === 0)
-        return null;
-    const hoveredRow = f.hoveredRowKey === f.rowKey;
-    const cy = f.cursorY;
-    const pick = hoveredRow && cy !== null
-        ? f.samples.reduce((a, b) => Math.abs(b.py - cy) < Math.abs(a.py - cy) ? b : a)
-        : f.hoveredRowKey === null
-            ? f.samples[0]
-            : null;
+        return f.pointer && { ...f.pointer, color: undefined };
+    const pick = snappedSample(f);
     return pick
         ? {
             py: pick.py,
@@ -216,10 +231,60 @@ function crosshairPick(f, snap) {
             side: pick.side,
             axisOffset: pick.axisOffset,
             axisColor: pick.axisColor,
+            color: pick.color,
         }
         : null;
 }
-/** `cursor="crosshair"` as a spec: the dashed reticle (renderPlot), the axis
+/** The consumer-facing {@link CursorSnap} for a resolved sample. */
+function toCursorSnap(s) {
+    return {
+        x: s.x,
+        value: s.value,
+        color: s.color,
+        label: s.label,
+        ...(s.readout !== undefined ? { readout: s.readout } : {}),
+        axisId: s.axisId,
+        formatted: s.formatted,
+    };
+}
+/** A {@link CursorSnap}'s identity for change detection — every field, so a
+ *  new axis format under a still pointer (same point, new `formatted`) is a
+ *  change the consumer hears about too. */
+function snapKey(s) {
+    return s === null
+        ? null
+        : [s.axisId, s.label, s.x, s.value, s.readout, s.color, s.formatted].join('\u0000');
+}
+/**
+ * The crosshair's snap reporter: picks the snapped sample from a hovered row's
+ * frame (`null` = nothing snapped) and calls the consumer only when the pick
+ * **changes** — rows re-render on every pointer move, and a callback that fired
+ * per move while the reticle sat still would make every consumer dedupe.
+ *
+ * Its state belongs to the mounted `<CrosshairCursor>`, not to this reporter:
+ * the reporter is rebuilt whenever `snap` / `showTime` / `format` change, and
+ * a fresh "last reported" would swallow the `null` that toggling to free mode
+ * owes a consumer still holding a point. `live` goes false on unmount, so a
+ * row still holding the old registration for one more commit can't report a
+ * point after the unmount's final `null`. The callback is read through a ref
+ * so an inline `onSnap` doesn't rebuild the cursor spec on every parent render.
+ */
+function snapReporter(onSnapRef, state, snap) {
+    return (f) => {
+        const st = state.current;
+        if (!st.live)
+            return;
+        // Free mode follows the pointer, not a series: there is nothing to report.
+        const pick = f !== null && snap ? snappedSample(f) : null;
+        const info = pick === null ? null : toCursorSnap(pick);
+        const key = snapKey(info);
+        if (key === st.last)
+            return;
+        st.last = key;
+        onSnapRef.current?.(info);
+    };
+}
+/** `<CrosshairCursor>` as a spec: the dashed reticle (renderPlot), the axis
  *  value pill (renderYGutter), and the x-axis time pill (renderXAxis). Declares
  *  `snapX: 'sample'` — the container snaps the shared cursorX to the data grid. */
 function buildCrosshairCursor(o) {
@@ -233,7 +298,7 @@ function buildCrosshairCursor(o) {
                 const ink = cursorInk(f.theme);
                 const background = f.theme.background;
                 const reticle = crosshairPick(f, o.snap);
-                return (_jsxs(_Fragment, { children: [_jsx("line", { x1: Math.round(x), y1: 0, x2: Math.round(x), y2: f.rowHeight, stroke: ink, strokeWidth: 1, strokeDasharray: "3 3", shapeRendering: "crispEdges" }), reticle && (_jsxs(_Fragment, { children: [_jsx("line", { x1: 0, y1: Math.round(reticle.py), x2: f.plotWidth, y2: Math.round(reticle.py), stroke: ink, strokeWidth: 1, strokeDasharray: "3 3", shapeRendering: "crispEdges" }), _jsx("circle", { cx: x, cy: reticle.py, r: 3, fill: ink, stroke: background, strokeWidth: background ? 1 : 0 })] }))] }));
+                return (_jsxs(_Fragment, { children: [_jsx("line", { x1: Math.round(x), y1: 0, x2: Math.round(x), y2: f.rowHeight, stroke: ink, strokeWidth: 1, strokeDasharray: "3 3", shapeRendering: "crispEdges" }), reticle && (_jsxs(_Fragment, { children: [_jsx("line", { x1: 0, y1: Math.round(reticle.py), x2: f.plotWidth, y2: Math.round(reticle.py), stroke: ink, strokeWidth: 1, strokeDasharray: "3 3", shapeRendering: "crispEdges" }), _jsx("circle", { cx: x, cy: reticle.py, r: 3, fill: reticle.color ?? ink, stroke: background, strokeWidth: background ? 1 : 0 })] }))] }));
             },
             // The value pill goes **on the reticle's own axis**: its side, its offset
             // out into that gutter (so a second axis on a side gets its own pill
@@ -287,12 +352,13 @@ function buildCrosshairCursor(o) {
                 }
                 : {}),
         },
-        wants: { ...NO_WANTS, samples: true, pointer: !o.snap },
+        wants: { ...NO_WANTS, reticle: true, pointer: !o.snap },
         ownsGesture: true,
         format: o.format,
+        reportSnap: o.reportSnap,
     };
 }
-/** `cursor="region"` as a spec: the hover-time **band** — the bucket under the
+/** `<RangeCursor>` as a spec: the hover-time **band** — the bucket under the
  *  pointer (sequence-snapped; freeform = a plain line until a drag shades the
  *  raw span) — plus the drag registration the brush recognizer reads
  *  (`resolveRangeDrag`). The container resolves the band; the shared
@@ -320,10 +386,7 @@ function buildRangeCursor(o) {
  * Update-in-place on a prop change (the entry memo), unregister on unmount —
  * the `registerAxis` discipline.
  */
-function useCursorMount(built, legacy, 
-/** The container shim's un-asked-for `'line'` default (see
- *  {@link CursorEntry.implicit}) — never set by component mounts. */
-implicit = false) {
+function useCursorMount(built) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('cursor components must be mounted inside a <ChartContainer> (as a ' +
@@ -343,10 +406,9 @@ implicit = false) {
             onDragRelease: built.onDragRelease,
             enableDrag: built.enableDrag,
             dragModifier: built.dragModifier,
+            reportSnap: built.reportSnap,
             rowKey,
-            legacy,
-            ...(implicit ? { implicit } : {}),
-        }, [built, rowKey, legacy, implicit]);
+        }, [built, rowKey]);
     const { registerCursor, unregisterCursor } = container;
     useEffect(() => {
         if (entry === null) {
@@ -357,98 +419,100 @@ implicit = false) {
     }, [registerCursor, unregisterCursor, key, entry]);
     useEffect(() => () => unregisterCursor(key), [unregisterCursor, key]);
 }
-/** The synced vertical cursor **line** — `cursor="line"` as a component (the
- *  container default during the deprecation window). Pair with an off-chart
- *  readout via `onTrackerChanged`. */
-export function LineCursor({ showTime = false } = {}) {
-    useCursorMount(useMemo(() => buildLineCursor({ showTime }), [showTime]), false);
+/** The synced vertical cursor **line**. Pair with an off-chart readout via
+ *  `onTrackerChanged`. */
+export function LineCursor({ showTime = false, format } = {}) {
+    useCursorMount(useMemo(() => buildLineCursor({ showTime, format }), [showTime, format]));
     return null;
 }
-/** A **dot on each series** at the cursor, no line — `cursor="point"`. */
-export function PointCursor({ showTime = false } = {}) {
-    useCursorMount(useMemo(() => buildPointCursor({ showTime }), [showTime]), false);
+/** A **dot on each series** at the cursor, no line. */
+export function PointCursor({ showTime = false, format, } = {}) {
+    useCursorMount(useMemo(() => buildPointCursor({ showTime, format }), [showTime, format]));
     return null;
 }
-/** Dots **plus a value chip beside each** — `cursor="inline"`. */
-export function InlineCursor({ showTime = false } = {}) {
-    useCursorMount(useMemo(() => buildInlineCursor({ showTime }), [showTime]), false);
+/** Dots **plus a value chip beside each**. */
+export function InlineCursor({ showTime = false, format, } = {}) {
+    useCursorMount(useMemo(() => buildInlineCursor({ showTime, format }), [showTime, format]));
     return null;
 }
-/** Dots + **staffed value flags** stacked near the top of the row —
- *  `cursor="flag"`. A `cursorFlag` layer (BoxPlot) consolidates onto one flag. */
-export function FlagCursor({ showTime = false } = {}) {
-    useCursorMount(useMemo(() => buildFlagCursor({ showTime }), [showTime]), false);
+/** Dots + **staffed value flags** stacked near the top of the row — a `cursorFlag` layer (BoxPlot)
+ *  consolidates onto one flag. */
+export function FlagCursor({ showTime = false, format } = {}) {
+    useCursorMount(useMemo(() => buildFlagCursor({ showTime, format }), [showTime, format]));
     return null;
 }
-/** The inspection **reticle** — `cursor="crosshair"`: dashed cross lines, a
- *  centre dot, the value pinned to its y axis, the time pinned to the x axis. */
-export function CrosshairCursor({ snap = true, showTime = true, format, } = {}) {
-    useCursorMount(useMemo(() => buildCrosshairCursor({ snap, showTime, format }), [snap, showTime, format]), false);
+/** The inspection **reticle**: dashed cross lines, a
+ *  centre dot in the snapped series' colour, the value pinned to its y axis,
+ *  the time pinned to the x axis. */
+export function CrosshairCursor({ snap = true, showTime = true, format, onSnap, } = {}) {
+    // Latest callback in a ref, so an inline `onSnap` doesn't re-register the
+    // cursor on every parent render; the spec is rebuilt only when a callback
+    // appears or goes away. Written in a *layout* effect: the rows report from
+    // passive effects, and every layout effect in a commit runs before any
+    // passive one — so a row always calls this commit's callback, wherever the
+    // cursor sits in the tree relative to the rows.
+    const onSnapRef = useRef(onSnap);
+    useLayoutEffect(() => {
+        onSnapRef.current = onSnap;
+    });
+    // What the consumer was last told, shared across reporter rebuilds (see
+    // `snapReporter`).
+    const reportState = useRef({ last: null, live: true });
+    const listening = onSnap !== undefined;
+    // A consumer who stops listening is owed nothing more; a fresh listener
+    // starts from "nothing reported yet".
+    if (!listening)
+        reportState.current.last = null;
+    // Unmounting while snapped lets go of the point, the same as the pointer
+    // leaving would. (`live` is re-set on mount for StrictMode's
+    // unmount-remount.)
+    useEffect(() => {
+        const st = reportState.current;
+        st.live = true;
+        return () => {
+            st.live = false;
+            if (st.last === null)
+                return;
+            st.last = null;
+            onSnapRef.current?.(null);
+        };
+    }, []);
+    useCursorMount(useMemo(() => buildCrosshairCursor({
+        snap,
+        showTime,
+        format,
+        reportSnap: listening
+            ? snapReporter(onSnapRef, reportState, snap)
+            : undefined,
+    }), [snap, showTime, format, listening]));
     return null;
 }
 /**
- * The **range** cursor — `cursor="region"` as a component (RFC A4.1 renames
+ * The **range** cursor (RFC A4.1 names
  * it for what it emits: a live extent — and, dragged, exactly what
  * `ChartContainer.range` accepts — against the annotation `<Region>`'s fixed
- * mark). Hover shades the bucket under the pointer; wiring
+ * mark). Hover shades the bucket under the pointer (on a category axis, the
+ * slot); wiring
  * {@link RangeCursorProps.onDragRelease} adds the drag, which fires once on
  * release and reverts (RFC §6: a region is deliberately a cursor **and** a
  * drag that fires and resets). The gesture rides the shared brush recognizer
  * (`brush.tsx`) — one engine arbitrating every drag claim on the plot.
  */
 export function RangeCursor({ sequence, onDragRelease, enableDrag, dragModifier, } = {}) {
-    useCursorMount(useMemo(() => buildRangeCursor({ sequence, onDragRelease, enableDrag, dragModifier }), [sequence, onDragRelease, enableDrag, dragModifier]), false);
+    useCursorMount(useMemo(() => buildRangeCursor({ sequence, onDragRelease, enableDrag, dragModifier }), [sequence, onDragRelease, enableDrag, dragModifier]));
     return null;
 }
-/**
- * The deprecation shim (internal): synthesizes the preset equivalent of a
- * legacy `cursor` string — the container's `cursor` prop (or its `'line'`
- * default), and `<ChartRow cursor>` inside a row. Registers as `legacy`, so a
- * component-mounted cursor in the same scope overrides it.
- */
-export function LegacyCursor({ mode, showTime, snap, sequence, implicit = false, }) {
-    const built = useMemo(() => {
-        switch (mode) {
-            case 'line':
-                return buildLineCursor({ showTime });
-            case 'point':
-                return buildPointCursor({ showTime });
-            case 'inline':
-                return buildInlineCursor({ showTime });
-            case 'flag':
-                return buildFlagCursor({ showTime });
-            case 'crosshair':
-                // The legacy crosshair always pins the time to the x axis; its y-snap
-                // is the container's `crosshairSnap`. (`cursorTime` is deliberately
-                // NOT forwarded — crosshair has no per-row time chip.)
-                return buildCrosshairCursor({ snap, showTime: true });
-            case 'region':
-                return buildRangeCursor({ sequence });
-            case 'none':
-                return null;
-        }
-    }, [mode, showTime, snap, sequence]);
-    useCursorMount(built, true, implicit);
-    return null;
-}
-/** Drop a scope's legacy (shim-synthesized) entries when the scope also has a
- *  component-mounted cursor — mounting a component overrides the string prop. */
-function dropShadowedLegacy(entries) {
-    return entries.some((e) => !e.legacy)
-        ? entries.filter((e) => !e.legacy)
-        : entries;
-}
 /**
  * The cursors in effect for a row: the row's own mounts when it has any (the
- * per-row override — nearest mount wins, exactly `row.cursor ?? container
- * .cursor`'s semantics), else the container-scoped mounts. Within a scope,
- * component mounts shadow the legacy shim.
+ * per-row override — nearest mount wins), else the container-scoped mounts.
+ * A row that wants no cursor while its siblings have one mounts the cursors
+ * per row rather than at the container.
  */
 export function effectiveCursorEntries(all, rowKey) {
     const rowEntries = all.filter((e) => e.rowKey === rowKey);
     if (rowEntries.length > 0)
-        return dropShadowedLegacy(rowEntries);
-    return dropShadowedLegacy(all.filter((e) => e.rowKey === null));
+        return rowEntries;
+    return all.filter((e) => e.rowKey === null);
 }
 /** The scope's single snap/gesture owner (RFC A2.5) — first mount wins; the
  *  container dev-warns when a scope has two. */
@@ -467,7 +531,7 @@ export function xAxisCursorEntries(all, hoveredRowKey) {
         return effectiveCursorEntries(all, hoveredRowKey);
     const out = [];
     const seenRows = new Set();
-    out.push(...dropShadowedLegacy(all.filter((e) => e.rowKey === null)));
+    out.push(...all.filter((e) => e.rowKey === null));
     for (const e of all) {
         if (e.rowKey === null || seenRows.has(e.rowKey))
             continue;
@@ -486,7 +550,7 @@ export function warnOnDuplicateGestureOwners(all, warned) {
         return;
     const scopes = new Set(all.map((e) => e.rowKey));
     for (const scope of scopes) {
-        const entries = dropShadowedLegacy(all.filter((e) => e.rowKey === scope));
+        const entries = all.filter((e) => e.rowKey === scope);
         if (entries.filter((e) => e.ownsGesture).length > 1) {
             warned.current = true;
             console.warn('[pond-charts] two gesture-owning cursors (<CrosshairCursor> / ' +
@@ -498,31 +562,4 @@ export function warnOnDuplicateGestureOwners(all, warned) {
         }
     }
 }
-/** @internal The dev deprecation notice for a legacy cursor prop — one line
- *  naming the replacement, shared by the container and row shims. */
-export function legacyCursorWarning(lines) {
-    return ('[pond-charts] deprecated cursor props (they keep working this minor, ' +
-        'removed next): ' +
-        lines.join('; ') +
-        '. Mount a cursor component instead (docs/rfcs/interaction.md §9).');
-}
-/** @internal The preset name a legacy `cursor` mode maps to (for warnings). */
-export function presetNameFor(mode) {
-    switch (mode) {
-        case 'line':
-            return '<LineCursor>';
-        case 'point':
-            return '<PointCursor>';
-        case 'inline':
-            return '<InlineCursor>';
-        case 'flag':
-            return '<FlagCursor>';
-        case 'crosshair':
-            return '<CrosshairCursor>';
-        case 'region':
-            return '<RangeCursor>';
-        case 'none':
-            return 'nothing (mount no cursor)';
-    }
-}
 //# sourceMappingURL=cursors.js.map

package/dist/decimate.d.ts

@@ -224,8 +224,17 @@ export declare function m4Polyline(edges: Float64Array, mn: Float64Array, mx: Fl
  * `upper` are finite **together** per sample (the paired-percentile shape bands
  * are built from); a column where only one edge has finite samples would bin a
  * band segment that no single sample carried.
+ *
+ * `boundaries` are trading-axis session-break instants (`<BandChart
+ * sessionBreaks>`), handled exactly as {@link decimateM4} does for a line: each
+ * in-domain instant is unioned into the bucket edges so no column merges two
+ * sessions' envelopes across the discontinuity, **and** a `NaN` sample is
+ * emitted at the instant so the fill ends at the close and re-starts at the
+ * open — otherwise the closing and opening columns would sit as adjacent finite
+ * samples and the envelope would flow straight across the collapsed gap. The
+ * caller's `sessionRuns` then sees the break baked in and passes no boundaries.
  */
-export declare function decimateBand(band: BandSeries, xScale: Scale, ctx: CanvasRenderingContext2D, k?: number): BandSeries;
+export declare function decimateBand(band: BandSeries, xScale: Scale, ctx: CanvasRenderingContext2D, k?: number, boundaries?: readonly number[]): BandSeries;
 /**
  * Decimate an {@link OhlcSeries} to one **aggregate candle per device-pixel
  * column** — `open = first`, `high = max`, `low = min`, `close = last` over the

package/dist/decimate.js

@@ -400,8 +400,17 @@ export function m4Polyline(edges, mn, mx, first, last, W, breakAt = NO_BREAKS) {
  * `upper` are finite **together** per sample (the paired-percentile shape bands
  * are built from); a column where only one edge has finite samples would bin a
  * band segment that no single sample carried.
+ *
+ * `boundaries` are trading-axis session-break instants (`<BandChart
+ * sessionBreaks>`), handled exactly as {@link decimateM4} does for a line: each
+ * in-domain instant is unioned into the bucket edges so no column merges two
+ * sessions' envelopes across the discontinuity, **and** a `NaN` sample is
+ * emitted at the instant so the fill ends at the close and re-starts at the
+ * open — otherwise the closing and opening columns would sit as adjacent finite
+ * samples and the envelope would flow straight across the collapsed gap. The
+ * caller's `sessionRuns` then sees the break baked in and passes no boundaries.
  */
-export function decimateBand(band, xScale, ctx, k = 2) {
+export function decimateBand(band, xScale, ctx, k = 2, boundaries = []) {
     if (!shouldDecimateCount(band.length, ctx, k))
         return band;
     const dom = scaleDomain(xScale);
@@ -412,18 +421,50 @@ export function decimateBand(band, xScale, ctx, k = 2) {
     if (invert === null || plotWidthCss === null)
         return band;
     const W = deviceBucketCount(ctx);
-    const edges = pixelEdges(invert, plotWidthCss, W);
+    const pixels = pixelEdges(invert, plotWidthCss, W);
+    // Session-break instants inside the visible domain — unioned into the edges
+    // (so a column never straddles a break) AND marked as explicit break samples.
+    // `mergeGapEdges` keeps their exact values, so the set matches the edges.
+    const breaks = boundaries.length > 0
+        ? boundaries.filter((b) => b > dom[0] && b < dom[1])
+        : [];
+    const edges = breaks.length > 0 ? mergeGapEdges(pixels, breaks, dom[0], dom[1]) : pixels;
+    const buckets = edges.length - 1;
     const lowerMin = new Float64Column(band.lower, band.length).binBy(band.x, edges, 'min');
     const upperMax = new Float64Column(band.upper, band.length).binBy(band.x, edges, 'max');
-    const x = new Float64Array(W);
-    const lower = new Float64Array(W);
-    const upper = new Float64Array(W);
-    for (let b = 0; b < W; b += 1) {
-        x[b] = (edges[b] + edges[b + 1]) / 2; // column centre
-        lower[b] = lowerMin[b]; // NaN on an empty column → the fill break
-        upper[b] = upperMax[b];
+    const breakAt = breaks.length > 0 ? new Set(breaks) : null;
+    // One sample per column + one NaN break slot per session break. `breaks` are
+    // strictly inside the domain and `mergeGapEdges` keeps every one, so each
+    // lands on some `edges[b]` with `b > 0` and the arrays fill exactly; the
+    // subarray trim below is a guard against a provider instant that sorts ahead
+    // of the first pixel edge under float rounding, not an expected path.
+    const cap = buckets + (breakAt === null ? 0 : breakAt.size);
+    const x = new Float64Array(cap);
+    const lower = new Float64Array(cap);
+    const upper = new Float64Array(cap);
+    let n = 0;
+    for (let b = 0; b < buckets; b += 1) {
+        // Explicit session break: this column opens a new session → end the fill
+        // first. A NaN on both edges is the band's own gap signal (`.defined`).
+        if (breakAt !== null && b > 0 && breakAt.has(edges[b])) {
+            x[n] = edges[b];
+            lower[n] = NaN;
+            upper[n] = NaN;
+            n += 1;
+        }
+        x[n] = (edges[b] + edges[b + 1]) / 2; // column centre
+        lower[n] = lowerMin[b]; // NaN on an empty column → the fill break
+        upper[n] = upperMax[b];
+        n += 1;
     }
-    return { x, lower, upper, length: W };
+    return n === cap
+        ? { x, lower, upper, length: n }
+        : {
+            x: x.subarray(0, n),
+            lower: lower.subarray(0, n),
+            upper: upper.subarray(0, n),
+            length: n,
+        };
 }
 /**
  * Decimate an {@link OhlcSeries} to one **aggregate candle per device-pixel

package/dist/elapsed.d.ts

@@ -6,7 +6,7 @@
  *
  * Two things change, and only these two: **where the ticks sit** and **what they
  * say**. The pixel mapping is untouched, and so are the data coordinates — a
- * mark's `at`, the container's `range`, an `onRegionSelect` span are all still
+ * mark's `at`, the container's `range`, a `<RangeCursor onDragRelease>` span are all still
  * absolute axis units. Relabeling only.
  *
  * Where the ticks sit is the part that can't be done with `<XAxis transform>`:

package/dist/elapsed.js

@@ -6,7 +6,7 @@
  *
  * Two things change, and only these two: **where the ticks sit** and **what they
  * say**. The pixel mapping is untouched, and so are the data coordinates — a
- * mark's `at`, the container's `range`, an `onRegionSelect` span are all still
+ * mark's `at`, the container's `range`, a `<RangeCursor onDragRelease>` span are all still
  * absolute axis units. Relabeling only.
  *
  * Where the ticks sit is the part that can't be done with `<XAxis transform>`:

package/dist/format.d.ts

@@ -15,7 +15,8 @@ import type { TimeGrain } from './tickLadder.js';
 export type AxisFormat = string | ((value: number) => string);
 /**
  * How to format the **cursor / marker readout** on the x axis
- * ({@link ChartContainerProps.cursorFormat}) — time or value kind. Either:
+ * (the `format` prop on a cursor such as `<CrosshairCursor>`) — time or
+ * value kind. Either:
  *
  * - a d3 specifier **string** applied uniformly: a [time specifier]
  *   (https://github.com/d3/d3-time-format#locale_format) on a time axis

package/dist/index.d.ts

@@ -94,7 +94,7 @@ export { LineCursor, PointCursor, InlineCursor, FlagCursor, CrosshairCursor, Ran
 export type { LineCursorProps, PointCursorProps, InlineCursorProps, FlagCursorProps, CrosshairCursorProps, RangeCursorProps, } from './cursors.js';
 export { Selector, MultiSelector } from './selectors.js';
 export type { SelectorProps, MultiSelectorProps } from './selectors.js';
-export type { CursorMode, TrackerInfo, TrackerSample, SelectInfo, SelectModifiers, RangeSpan, SpanSelection, SelectionEntry, } from './context.js';
+export type { CursorSnap, TrackerInfo, TrackerSample, SelectInfo, SelectModifiers, RangeSpan, SpanSelection, SelectionEntry, } from './context.js';
 export { selectionContains, isSpanSelection, sameMark } from './span.js';
 export type { DrawStatsFrame, LayerDrawInfo } from './context.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/selection-fixtures.d.ts

@@ -19,10 +19,11 @@ import type { SelectInfo } from './context.js';
  *
  * That is not hypothetical: half a built matrix already surfaced two defects —
  * categorical hover being ink-only where the time axis claims the whole slot,
- * and `<RangeCursor>` on an ordinal axis suppressing the row's cursor entirely.
+ * and `<RangeCursor>` on an ordinal axis suppressing the row's cursor entirely
+ * (since fixed: it shades the slot there, [PND-ORDCURSOR]).
  *
- * **Capabilities are declared, not assumed.** `sequence` and `rangeCursor` are
- * absent on fixtures that cannot support them, so the factory omits those
+ * **Capabilities are declared, not assumed.** `sequence` is absent on
+ * fixtures that cannot support it, so the factory omits those
  * stories rather than generating one that silently does nothing. A gap in the
  * matrix is information; a story that renders nothing is a trap.
  */
@@ -72,10 +73,6 @@ export interface ChartFixture {
     readonly sweep: boolean;
     /** A snapping sequence, where the axis has one. Ordinal axes do not. */
     readonly sequence?: () => Sequence | BoundedSequence;
-    /** Whether `<RangeCursor>` draws here — it gates on a continuous x
-     *  (`brush.tsx`), so mounting one on a category axis is not just inert, it
-     *  takes the row's cursor with it. */
-    readonly rangeCursor: boolean;
     /**
      * Present only where the x axis **collapses closed-market time**, which is
      * what makes a snap block's relationship to the session grid a question at