@pond-ts/charts 0.57.0 → 0.58.0

package/dist/ChartContainer.js

@@ -6,6 +6,9 @@ import { scaleBand } from './bandScale.js';
 import { scaleElapsed } from './elapsed.js';
 import { Sequence } from 'pond-ts';
 import { ContainerContext, CursorContext, } from './context.js';
+import { LegacyCursor, legacyCursorWarning, presetNameFor, warnOnDuplicateGestureOwners, } from './cursors.js';
+import { effectiveSelectorEntries, resolveControlledHovered, resolveControlledSelected, selectorEntryEqual, warnInertClick, } from './selectors.js';
+import { isDev } from './dev.js';
 import { maxSlotWidths, sum } from './slots.js';
 import { computeLabelLanes } from './annotations.js';
 import { resolveCursorX, DEFAULT_CURSOR_MODE } from './tracker.js';
@@ -13,6 +16,11 @@ import { clampToBounds } from './viewport.js';
 import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
 import { TimeAxis } from './TimeAxis.js';
 import { defaultTheme } from './theme.js';
+import { isSpanSelection, NO_SPANS } from './span.js';
+/** Stable identity for "nothing selected" — see the normalization below. */
+const EMPTY_SELECTION = [];
+/** Stable "no sweep in flight" identity for the span preview channel. */
+const EMPTY_PREVIEW_SPANS = [];
 /** Tick count for a **continuous** (non-trading) x axis — the `ticks(count)`
  *  request `<TimeAxis>`, the x gridlines, and the cursor-time formatter share
  *  (as the frame's `xTickCount`). */
@@ -45,14 +53,117 @@ function normalizeRange(range) {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', 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, origin, 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';
+export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, onDrawStats, panZoom = false, bounds, onTimeRangeChange, minDuration = 1, cursor: cursorProp, cursorSequence: cursorSequenceProp, onRegionSelect, regionSelectModifier, cursorTime: cursorTimeProp, crosshairSnap: crosshairSnapProp, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat: cursorFormatProp, origin, theme, discontinuities, calendar, spacing, grid = true, sessionDividers = 'none', children, }) {
+    // ── Legacy cursor props (deprecated) ───────────────────────────────────────
+    // The string surface keeps working for one minor: the resolved mode is
+    // synthesized into the equivalent mounted preset below (`<LegacyCursor>`),
+    // and a dev warning names the replacement whenever any of the props is
+    // *explicitly* set (never on the defaults). Mounted cursor components in the
+    // same scope override the shim. See docs/rfcs/interaction.md §9 / A4.4.
+    const cursor = cursorProp ?? DEFAULT_CURSOR_MODE;
+    const cursorTime = cursorTimeProp ?? false;
+    const crosshairSnap = crosshairSnapProp ?? true;
+    const warnedLegacyRef = useRef(false);
+    useEffect(() => {
+        if (!isDev || warnedLegacyRef.current)
+            return;
+        const legacy = [];
+        if (cursorProp !== undefined)
+            legacy.push(`cursor="${cursorProp}" → mount ${presetNameFor(cursorProp)}`);
+        if (crosshairSnapProp !== undefined)
+            legacy.push('crosshairSnap → <CrosshairCursor snap>');
+        if (cursorTimeProp !== undefined)
+            legacy.push('cursorTime → showTime on the mounted cursor');
+        if (cursorFormatProp !== undefined)
+            legacy.push('cursorFormat → format on <CrosshairCursor>');
+        if (cursorSequenceProp !== undefined)
+            legacy.push('cursorSequence → <RangeCursor sequence>');
+        if (onRegionSelect !== undefined)
+            legacy.push('onRegionSelect → <RangeCursor onDragRelease> (the payload becomes ' +
+                '{ x: [lo, hi] })');
+        if (regionSelectModifier !== undefined)
+            legacy.push('regionSelectModifier → <RangeCursor dragModifier>');
+        if (legacy.length === 0)
+            return;
+        warnedLegacyRef.current = true;
+        console.warn(legacyCursorWarning(legacy));
+    }, [
+        cursorProp,
+        crosshairSnapProp,
+        cursorTimeProp,
+        cursorFormatProp,
+        cursorSequenceProp,
+        onRegionSelect,
+        regionSelectModifier,
+    ]);
+    // Mounted-cursor registry ({@link ContainerFrame.registerCursor}): the
+    // presets (and the legacy shim) register their specs here; rows and
+    // `<XAxis>` render the effective set. Same per-instance-slot discipline as
+    // the tracker sources; register is idempotent under reference equality (the
+    // presets memoize their entries on props).
+    const [cursorMap, setCursorMap] = useState(() => new Map());
+    const registerCursor = useCallback((key, entry) => {
+        setCursorMap((m) => m.get(key) === entry ? m : new Map(m).set(key, entry));
+    }, []);
+    const unregisterCursor = useCallback((key) => {
+        setCursorMap((m) => {
+            if (!m.has(key))
+                return m;
+            const next = new Map(m);
+            next.delete(key);
+            return next;
+        });
+    }, []);
+    const cursors = useMemo(() => Array.from(cursorMap.values()), [cursorMap]);
+    // RFC A2.5: one snap/gesture owner per scope — warn (dev, once) on two.
+    const warnedGestureRef = useRef(false);
+    useEffect(() => {
+        warnOnDuplicateGestureOwners(cursors, warnedGestureRef);
+    }, [cursors]);
+    // The registered cursors' resolution inputs, folded into the legacy
+    // channels: a mounted `<CrosshairCursor format>` feeds the shared readout
+    // channel exactly where `cursorFormat` fed it. First **component-mounted**
+    // entry wins (the shim registers before the children mount, so a bare
+    // first-wins would let the legacy synthesis shadow a real mount); the
+    // legacy prop is the fallback during the window. (`sequence` resolves the
+    // same way, below the selector registry — a `<MultiSelector sequence>`
+    // feeds the same channel.)
+    const cursorFormat = useMemo(() => cursors.find((e) => !e.legacy && e.format !== undefined)?.format ??
+        cursorFormatProp, [cursors, cursorFormatProp]);
+    // Which axes the gestures own. **Pan follows zoom's degrees of freedom**: an
+    // axis that can be zoomed can be panned, because a zoomed axis shows less than
+    // all of itself and the reader needs to reach the rest. `'pan'` is the one
+    // exception — pan with no zoom — and it stays x-only, which is what it has
+    // always meant. `'panZoom'` and `true` are `'panZoomX'`: the original
+    // behaviour, now named for the axis it acts on.
+    const zoomX = panZoom === true ||
+        panZoom === 'panZoom' ||
+        panZoom === 'panZoomX' ||
+        panZoom === 'panZoomXY';
+    const zoomY = panZoom === 'panZoomY' || panZoom === 'panZoomXY';
+    const panX = zoomX || panZoom === 'pan';
+    const panY = zoomY;
+    const panEnabled = panX || panY;
+    const zoomEnabled = zoomX || zoomY;
+    // **The aspect ratio is fixed only when BOTH axes zoom** — one factor about
+    // the cursor, so a feature that looked square stays square. A single-axis zoom
+    // necessarily changes the ratio, which is the whole point of asking for one.
+    //
+    // This is why the modes name their axes. An earlier cut had a single
+    // `panZoom2D` that claimed both and then silently fell back to y-only wherever
+    // x was a category axis: the ratio changed and nothing said so. Spelling out
+    // the axes makes that the caller's choice instead of a hidden one.
+    const aspectLocked = zoomX && zoomY;
+    const [yTransform, setYTransform] = useState({
+        k: 1,
+        ty: 0,
+    });
+    const applyYTransform = useCallback((next) => {
+        // `k < 1` would zoom out past the axis' natural fit, leaving blank bands the
+        // reader cannot interpret; clamping at 1 makes the un-zoomed view the floor.
+        const k = Math.max(1, next.k);
+        setYTransform((prev) => prev.k === k && prev.ty === next.ty ? prev : { k, ty: next.ty });
+    }, []);
     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`
@@ -109,6 +220,11 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
     const [hoverX, setHoverX] = useState(null);
     // The region-cursor drag anchor (epoch ms) — set on press, cleared on release.
     const [regionAnchor, setRegionAnchor] = useState(null);
+    // The live sweep preview for span-only layers ([PND-TRACESEL]) — a paint
+    // mirror beside `regionAnchor`, never part of the committed selection.
+    // `EMPTY_PREVIEW_SPANS` keeps the at-rest case reference-stable so a
+    // pointer move over an unswept plot re-identifies no layer entry.
+    const [previewSpans, setPreviewSpans] = useState(EMPTY_PREVIEW_SPANS);
     // The free-form crosshair also needs the pointer's y + which row (row-specific,
     // unlike the shared x). One state object so a move updates both atomically.
     const [hoverPoint, setHoverPoint] = useState(null);
@@ -154,6 +270,48 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
         selectableRef.current = next;
         setSelectableKeys(next);
     }, []);
+    // Mounted-selector registry ({@link ContainerFrame.registerSelector}):
+    // `<Selector>` — and the legacy shim below — register here, and **the
+    // registration is what enables a plot click** (interaction RFC §7.1). Same
+    // per-instance-slot discipline as the cursors/tracker sources. Mirrored to a
+    // ref because `select` / `setHovered` are `[]`-stable callbacks that must not
+    // read a stale closure (the `onSelectRef` discipline, one level up).
+    const [selectorMap, setSelectorMap] = useState(() => new Map());
+    const registerSelector = useCallback((key, entry) => {
+        setSelectorMap((m) => {
+            // **Value-equal, not reference-equal.** Since A10.3 the entry carries the
+            // controlled `selected`/`hovered`, so a consumer's inline array mints a
+            // fresh entry every render; a reference-only guard then updates the
+            // registry every time, and any descendant that reads the container
+            // context (`useChartLegend()`) re-renders, rebuilds the array, and
+            // re-registers — an unbounded loop. Same guard, same reason, as
+            // `registerAxis`/`axisSpecEqual` in `ChartRow.tsx`.
+            const prev = m.get(key);
+            if (prev !== undefined && selectorEntryEqual(prev, entry))
+                return m;
+            return new Map(m).set(key, entry);
+        });
+    }, []);
+    const unregisterSelector = useCallback((key) => {
+        setSelectorMap((m) => {
+            if (!m.has(key))
+                return m;
+            const next = new Map(m);
+            next.delete(key);
+            return next;
+        });
+    }, []);
+    const selectors = useMemo(() => Array.from(selectorMap.values()), [selectorMap]);
+    const selectorsRef = useRef(selectors);
+    // The shared snap-bucket sequence, folded into the legacy channel exactly as
+    // `cursorFormat` is above: a component-mounted `<RangeCursor sequence>`
+    // wins, then a mounted `<MultiSelector sequence>` (its sweep extends bucket
+    // by bucket over the same realized buckets — one channel, so the band and
+    // the sweep can never snap differently), then the legacy shim / prop.
+    const cursorSequence = useMemo(() => cursors.find((e) => !e.legacy && e.sequence !== undefined)?.sequence ??
+        selectors.find((e) => e.sequence !== undefined)?.sequence ??
+        cursors.find((e) => e.sequence !== undefined)?.sequence ??
+        cursorSequenceProp, [cursors, selectors, cursorSequenceProp]);
     // Annotations register here so the container can do what a mark can't in
     // isolation: draw its guide line across other rows, order regions, serve snap
     // targets. Keyed by per-instance slot key (same discipline as the sources).
@@ -252,43 +410,147 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
     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
+    // Selection: controlled (a mounted selector's `selected`) or uncontrolled
+    // (internal). A click on a selectable layer calls `select()` after
+    // hit-testing; the mounted `<Selector>`s in scope are notified in both
+    // modes, and the internal state is managed only when uncontrolled — whether
+    // *this* container's derived state is controlled now depends on the
+    // registry, not a container prop (interaction RFC A10.3). The full
     // SelectInfo is the identity (key + series), so multi-series marks at one
     // timestamp stay distinct. Refs written after commit (not in render) so the
     // click handler never reads a callback / mode from a frame abandoned under
     // concurrent rendering.
+    // Widened past a single mark for the sweep (RFC A5.2): an uncontrolled
+    // `<MultiSelector>` release commits its compact span descriptor here, so the
+    // swept bars stay lit with no controlled prop — the sweep analog of the
+    // uncontrolled click highlight. Clicks still store the single hit.
     const [internalSelected, setInternalSelected] = useState(null);
-    const controlledSelection = selected !== undefined;
-    const selectedValue = controlledSelection
-        ? (selected ?? null)
-        : internalSelected;
-    const onSelectRef = useRef(onSelect);
+    // Controlled selection now comes from the registry (interaction RFC A10.3):
+    // whichever mounted `<Selector>`/`<MultiSelector>` declared `selected` owns
+    // it — chart-wide, not row-scoped, and independent of `gestureEnabled`
+    // (`<Selector enabled={false} selected={…}>` is a legitimate owner). Warned
+    // once if more than one mount declares it.
+    const warnedAmbiguousSelectedRef = useRef(false);
+    const controlledSelected = useMemo(() => resolveControlledSelected(selectors, warnedAmbiguousSelectedRef), [selectors]);
+    const controlledSelection = controlledSelected.present;
+    // Normalize the three accepted shapes — a single mark, a set, or nothing —
+    // into the shapes the frame carries ([PND-MULTISEL] / RFC A5.2). A mixed
+    // `SelectionEntry` array is split ONCE here into its mark entries
+    // (`selected`, the exact field every pre-span reader keeps consuming
+    // unchanged) and its span descriptors (`selectedSpans`, which only the
+    // span-aware layers read) — so a consumer who never passes a span pays
+    // nothing anywhere: the marks array is the prop's own array (no copy), the
+    // spans field is the module constant, and every downstream `length === 0`
+    // gate short-circuits as before. `EMPTY_SELECTION` / `NO_SPANS` are module
+    // constants so the common cases keep stable identities and don't
+    // re-identify the frame on every render.
+    const { selectedValue, selectedSpans } = useMemo(() => {
+        const raw = controlledSelection
+            ? controlledSelected.value
+            : internalSelected;
+        if (raw === null || raw === undefined)
+            return { selectedValue: EMPTY_SELECTION, selectedSpans: NO_SPANS };
+        if (!Array.isArray(raw))
+            return {
+                selectedValue: [raw],
+                selectedSpans: NO_SPANS,
+            };
+        const entries = raw;
+        // The overwhelmingly common case — no span entries — returns the caller's
+        // array as-is rather than partitioning into fresh ones.
+        let spanCount = 0;
+        for (let i = 0; i < entries.length; i += 1) {
+            if (isSpanSelection(entries[i]))
+                spanCount += 1;
+        }
+        if (spanCount === 0)
+            return {
+                selectedValue: entries,
+                selectedSpans: NO_SPANS,
+            };
+        const marks = [];
+        const spans = [];
+        for (let i = 0; i < entries.length; i += 1) {
+            const e = entries[i];
+            if (isSpanSelection(e))
+                spans.push(e);
+            else
+                marks.push(e);
+        }
+        return {
+            selectedValue: marks.length === 0 ? EMPTY_SELECTION : marks,
+            selectedSpans: spans,
+        };
+    }, [controlledSelection, controlledSelected.value, internalSelected]);
     const controlledSelectionRef = useRef(controlledSelection);
     useLayoutEffect(() => {
-        onSelectRef.current = onSelect;
+        selectorsRef.current = selectors;
         controlledSelectionRef.current = controlledSelection;
     });
-    const select = useCallback((hit) => {
-        onSelectRef.current?.(hit);
+    // The library applies no set arithmetic: it reports the hit plus the
+    // modifiers and, when uncontrolled, keeps the single-mark behaviour it always
+    // had. A consumer wanting add/toggle reads `modifiers.additive` and drives
+    // the controlled `selected` set — see `SelectModifiers`.
+    //
+    // `rowKey` present ⇒ a **plot gesture**, and RFC §7.1's gate applies: with no
+    // `<Selector>` in scope the click does nothing at all — it does not even
+    // commit the uncontrolled selection, which is the whole point (a chart that
+    // silently highlighted on click now doesn't). Absent ⇒ a programmatic select
+    // (a `<Legend>` chip), which is intentional by construction and stays
+    // ungated.
+    const warnedInertClickRef = useRef(false);
+    const select = useCallback((hit, modifiers, rowKey) => {
+        const entries = effectiveSelectorEntries(selectorsRef.current, rowKey ?? null);
+        if (rowKey !== undefined && entries.length === 0) {
+            // A2.6: suppress when controlled `selected` is in effect — that is
+            // the signature of the *endorsed* controlled-highlight setup
+            // (`<Selector enabled={false} selected={…}>`), not of a consumer who
+            // lost their click.
+            if (isDev && hit !== null && !controlledSelectionRef.current)
+                warnInertClick(warnedInertClickRef);
+            return;
+        }
+        // Pass the second argument only when there is one. Calling
+        // `onSelect(hit, undefined)` unconditionally would change the observed
+        // arity for every existing consumer — enough to break a
+        // `toHaveBeenCalledWith(hit)` assertion, which is a silly thing to break
+        // for a purely additive feature.
+        for (const e of entries) {
+            if (modifiers === undefined)
+                e.onSelect?.(hit);
+            else
+                e.onSelect?.(hit, modifiers);
+            // A mounted <MultiSelector> hears the same click in its own currency
+            // (RFC §8: everything <Selector> does): 0/1 hits, no span — a click
+            // produces marks, only a sweep produces a span (A5.2).
+            e.onSelectMany?.(hit === null ? EMPTY_SELECTION : [hit], modifiers, EMPTY_PREVIEW_SPANS);
+        }
         if (!controlledSelectionRef.current)
             setInternalSelected(hit);
     }, []);
-    // Dev-warn: selection is wired (`selected` and/or `onSelect`) but no layer
-    // carries an `id`, so nothing is selectable — `id` gates interactivity, so a
-    // consumer who forgot it gets a silent no-op click without this nudge. Fires
-    // once per wired-but-empty transition (guarded by a ref); child layers
-    // register before this parent effect runs, so the set is settled here.
-    const selectionWired = controlledSelection || onSelect !== undefined;
+    // Dev-warn: selection is wired (a controlled `selected`, or a mounted
+    // `<Selector>`/`<MultiSelector>` at all — mounting is itself wiring, even
+    // with no callbacks) but no layer carries an `id`, so nothing is
+    // selectable — `id` gates interactivity, so a consumer who forgot it gets a
+    // silent no-op click without this nudge. Fires once per wired-but-empty
+    // transition (guarded by a ref); child layers register before this parent
+    // effect runs, so the set is settled here.
+    // "Wired" means a gesture is armed, or state is being driven. A selector
+    // whose gesture is off AND which declares no state is wired to nothing — it
+    // would be a strange thing to mount, but accusing it of a missing `id` is a
+    // false positive, so it doesn't count (reviewer finding on #638).
+    const selectionWired = controlledSelection ||
+        selectors.some((e) => e.gestureEnabled || e.declaresSelected || e.declaresHovered);
     const warnedNoSelectableRef = useRef(false);
     useEffect(() => {
         if (selectionWired && selectableRef.current.size === 0) {
             if (!warnedNoSelectableRef.current) {
                 warnedNoSelectableRef.current = true;
-                console.warn('[pond-charts] `selected`/`onSelect` is set but no layer has an `id` — ' +
-                    'nothing is selectable. Give a <BarChart>/<ScatterChart>/<BoxPlot> an ' +
-                    '`id` to make it interactive (an `id` gates selection + hover).');
+                console.warn('[pond-charts] a <Selector>/<MultiSelector> is mounted (or declares ' +
+                    '`selected`) but no layer has an `id` — nothing is selectable. Give ' +
+                    'a <BarChart>/<ScatterChart>/<BoxPlot>/<HeatMap>/<LineChart>/' +
+                    '<AreaChart> an `id` to make it interactive (an `id` gates ' +
+                    'selection + hover).');
             }
         }
         else {
@@ -296,37 +558,140 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
         }
     }, [selectionWired, selectableKeys]);
     // Hover-highlight: the transient mark under the pointer (distinct from the
-    // committed selection). Controlled (`hovered` prop) or uncontrolled (internal),
-    // mirroring selection; `onHover` notifies in both modes. Deduped by key+label
-    // so it fires — and the data canvas repaints — only when the hovered mark
-    // changes, not on every pointer move (the move itself just slides the SVG
-    // cursor, which never touches the data canvas).
+    // committed selection). Controlled (a mounted selector's `hovered`) or
+    // uncontrolled (internal), mirroring selection; `onHover` notifies in both
+    // modes. Deduped by the mark's full identity so it fires — and the data
+    // canvas repaints — only when the hovered mark changes, not on every pointer
+    // move (the move itself just slides the SVG cursor, which never touches the
+    // data canvas).
+    //
+    // "Full identity" means `label` and `mark` as well as `id` and `key`, and that
+    // is load-bearing rather than belt-and-braces. `key` is the mark's position on
+    // the **bin axis**, so any layer that stacks more than one mark in a bin — a
+    // stacked bar, a `<HeatMap>` column — has several marks sharing a key, and
+    // deduping on `id + key` alone silently swallows every move *within* a bin.
+    // On a heat map that reads as the hover being stuck: dragging straight down a
+    // column never changes the reported cell.
+    // Widened past a single mark for the sweep's live preview (RFC A1.4/A3.4):
+    // a drag under a mounted <MultiSelector> lights every covered mark at once
+    // through this same field — the reason `hovered` became a set.
     const [internalHovered, setInternalHovered] = useState(null);
-    const controlledHover = hovered !== undefined;
-    const hoveredValue = controlledHover ? (hovered ?? null) : internalHovered;
-    const onHoverRef = useRef(onHover);
+    const warnedAmbiguousHoveredRef = useRef(false);
+    const controlledHovered = useMemo(() => resolveControlledHovered(selectors, warnedAmbiguousHoveredRef), [selectors]);
+    const controlledHover = controlledHovered.present;
+    // Same three-shape normalization `selected` does — a single mark, a set, or
+    // nothing — so a pointer-driven hover (always one mark) and a sweep-driven
+    // one (several) reach the draw paths in the same shape (RFC A4.2).
+    const hoveredValue = useMemo(() => {
+        const raw = controlledHover ? controlledHovered.value : internalHovered;
+        if (raw === null || raw === undefined)
+            return EMPTY_SELECTION;
+        return Array.isArray(raw) ? raw : [raw];
+    }, [controlledHover, controlledHovered.value, internalHovered]);
     const controlledHoverRef = useRef(controlledHover);
     // The last mark we reported — so the callback dedups across pointer moves even
     // in controlled mode, where there's no internal state to compare against.
     const lastHoverRef = useRef(null);
     useLayoutEffect(() => {
-        onHoverRef.current = onHover;
         controlledHoverRef.current = controlledHover;
     });
-    const setHovered = useCallback((hit) => {
+    // The last resting BLOCK we reported (identity — the row keeps the array
+    // reference-stable per block), so <MultiSelector onHover> hears one call per
+    // block transition and within-block mark transitions re-render nothing.
+    const lastHoverBlockRef = useRef(null);
+    // Unlike `select`, this is **not** gated on a mounted `<Selector>`: the
+    // hover state moves regardless, uncontrolled with none mounted; with none
+    // mounted there is simply no `onHover` to fire.
+    const setHovered = useCallback((hit, rowKey, block) => {
         const prev = lastHoverRef.current;
-        const same = prev === hit ||
+        const sameMark = prev === hit ||
             (prev !== null &&
                 hit !== null &&
                 prev.id === hit.id &&
-                prev.key === hit.key);
-        if (same)
+                prev.key === hit.key &&
+                prev.label === hit.label &&
+                prev.mark === hit.mark);
+        const blockNow = block ?? null;
+        const sameBlock = lastHoverBlockRef.current === blockNow;
+        if (sameMark && sameBlock)
             return;
         lastHoverRef.current = hit;
-        onHoverRef.current?.(hit);
+        lastHoverBlockRef.current = blockNow;
+        for (const e of effectiveSelectorEntries(selectorsRef.current, rowKey ?? null)) {
+            // <Selector onHover> keeps its per-mark currency regardless of any
+            // block — the mark under the pointer, per mark transition.
+            if (!sameMark)
+                e.onHover?.(hit);
+            // A mounted <MultiSelector> hears hover in its own plural currency:
+            // the resting BLOCK preview when there is one (per block transition —
+            // the marks a drag begun and released here would select), else 0/1
+            // hits per mark transition. A live sweep reports through
+            // `resolveSweep`'s preview instead, several at once.
+            if (blockNow !== null) {
+                if (!sameBlock)
+                    e.onHoverMany?.(blockNow);
+            }
+            else if (!sameMark) {
+                e.onHoverMany?.(hit === null ? EMPTY_SELECTION : [hit]);
+            }
+        }
+        // The block (reference-stable per block) is the hovered STATE when
+        // present, so every mark in it lights — and a within-block mark
+        // transition hands React the same value back (no re-render, no
+        // repaint), which is the block-level analog of the single-mark dedup.
         if (!controlledHoverRef.current)
-            setInternalHovered(hit);
+            setInternalHovered(blockNow ?? hit);
+    }, []);
+    // The sweep gesture's container half (interaction RFC §8 / A5.2): resolve a
+    // row's press against the mounted <MultiSelector>s in scope and hand the
+    // gesture engine its two sinks. Presence is the arm switch — `null` means no
+    // sweep can claim the drag (§7.1's mounting-is-enablement, extended). The
+    // entries are captured at the press and live for that one drag, matching the
+    // ref-not-state discipline of the range drag (#508 item 7).
+    const resolveSweep = useCallback((rowKey) => {
+        const entries = effectiveSelectorEntries(selectorsRef.current, rowKey).filter((e) => e.multi);
+        if (entries.length === 0)
+            return null;
+        return {
+            // The *declaration*, not a measurement of the block — see the field doc.
+            snapped: entries.some((e) => e.sequence !== undefined),
+            preview: (hits, light = true) => {
+                // The single-hit / resting-block dedup state is meaningless mid-sweep;
+                // reset both so the first post-sweep pointer hover always reports.
+                lastHoverRef.current = null;
+                lastHoverBlockRef.current = null;
+                // Reporting and lighting are separate on purpose — see the field doc.
+                for (const e of entries)
+                    e.onHoverMany?.(hits);
+                if (!controlledHoverRef.current)
+                    setInternalHovered(light ? hits : null);
+            },
+            commit: (hits, modifiers, spans) => {
+                for (const e of entries)
+                    e.onSelectMany?.(hits, modifiers, spans);
+                // Uncontrolled: the compact span descriptors ARE the selection (A5.2's
+                // second currency) — the swept marks stay lit via the same membership
+                // test a controlled span would use. The preview clears; the committed
+                // highlight takes over.
+                //
+                // **All of them**, not just the claimant's: a trace sweep produces one
+                // span per trace ([PND-TRACESEL]), and keeping only the topmost would
+                // leave the uncontrolled path showing less than the preview promised.
+                if (!controlledSelectionRef.current)
+                    setInternalSelected(spans.length === 0 ? null : [...spans]);
+                lastHoverRef.current = null;
+                lastHoverBlockRef.current = null;
+                if (!controlledHoverRef.current)
+                    setInternalHovered(null);
+            },
+        };
     }, []);
+    // The render-time "is a <MultiSelector> in scope for this row" fact, for the
+    // resting block preview (frame doc in context.ts). Unlike `resolveSweep` —
+    // a []-stable callback over the selectors REF, correct at pointer-down — a
+    // row reads this during render to pick its resting cursor, so it derives
+    // from the selectors STATE and re-identifies when the registry changes.
+    const hasMultiSelector = useCallback((rowKey) => effectiveSelectorEntries(selectors, rowKey).some((e) => e.multi), [selectors]);
     // Rows report their per-slot gutter widths; we reserve each slot's max.
     const [gutters, setGutters] = useState([]);
     const registerGutter = useCallback((req) => {
@@ -613,20 +978,23 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
         }
         // No sequence → snap to a bar/histogram layer's bins, if any (a value axis,
         // or a time-axis histogram with no explicit sequence). `binIntervals` is only
-        // published by a vertical bar layer on a continuous axis, so this is a no-op
-        // for line/area/scatter rows and for a category axis.
+        // published by a vertical bar layer, so this is a no-op for
+        // line/area/scatter rows. On a **category** axis the bins are the unit
+        // slots `[i, i+1)`: the region cursor never reads them (its band gates on
+        // a continuous axis), but the `<MultiSelector>` sweep's band snaps over
+        // them so it runs slot-edge to slot-edge — the band scale's `invert`
+        // returns slot *centres*, and a centre-to-centre band disagreed with the
+        // snapped-outward span the release commits (RFC A7.6's edge rule).
         //
         // **First bar layer wins** — deliberately non-fatal, unlike `xCategories`
         // (which *throws* when category rows disagree, because a mismatched slot order
         // corrupts the shared band scale). Two overlaid histograms with different bins
         // is a degenerate layout the region cursor just snaps to whichever registered
         // first; a wrong snap grid is harmless where a wrong axis is not.
-        if (resolvedKind === 'time' || resolvedKind === 'value') {
-            for (const s of sources.values()) {
-                const bins = s.binIntervals?.() ?? null;
-                if (bins && bins.length > 0)
-                    return bins;
-            }
+        for (const s of sources.values()) {
+            const bins = s.binIntervals?.() ?? null;
+            if (bins && bins.length > 0)
+                return bins;
         }
         return undefined;
     }, [cursorSequence, d0, d1, resolvedKind, sources]);
@@ -689,6 +1057,8 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
         crosshairSnap,
         cursorBuckets,
         regionAnchor,
+        previewSpans,
+        setPreviewSpans,
         setRegionAnchor,
         onRegionSelect,
         reportDrawStats,
@@ -696,6 +1066,7 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
         draggingKey,
         setDragging,
         selected: selectedValue,
+        selectedSpans,
         select,
         hovered: hoveredValue,
         setHovered,
@@ -717,6 +1088,13 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
         unregisterTrackerSource,
         registerSelectable,
         unregisterSelectable,
+        registerCursor,
+        unregisterCursor,
+        cursors,
+        registerSelector,
+        unregisterSelector,
+        resolveSweep,
+        hasMultiSelector,
         registerAnnotation,
         unregisterAnnotation,
         registerLegendItem,
@@ -734,6 +1112,13 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
         zoomEnabled,
         minDuration,
         applyRange,
+        zoomX,
+        zoomY,
+        panX,
+        panY,
+        aspectLocked,
+        yTransform,
+        applyYTransform,
         registerGutter,
         registerRow,
         firstRowKey,
@@ -751,6 +1136,8 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
         crosshairSnap,
         cursorBuckets,
         regionAnchor,
+        previewSpans,
+        setPreviewSpans,
         setRegionAnchor,
         onRegionSelect,
         reportDrawStats,
@@ -758,6 +1145,7 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
         draggingKey,
         setDragging,
         selectedValue,
+        selectedSpans,
         select,
         hoveredValue,
         setHovered,
@@ -779,6 +1167,13 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
         unregisterTrackerSource,
         registerSelectable,
         unregisterSelectable,
+        registerCursor,
+        unregisterCursor,
+        cursors,
+        registerSelector,
+        unregisterSelector,
+        resolveSweep,
+        hasMultiSelector,
         registerAnnotation,
         unregisterAnnotation,
         registerLegendItem,
@@ -796,17 +1191,28 @@ export function ChartContainer({ range, maxBandWidth, bandAlign = 'start', width
         zoomEnabled,
         minDuration,
         applyRange,
+        zoomX,
+        zoomY,
+        panX,
+        panY,
+        aspectLocked,
+        yTransform,
+        applyYTransform,
         registerGutter,
         registerRow,
         firstRowKey,
     ]);
-    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, {})] }) }) }));
+    return (_jsx(ContainerContext.Provider, { value: frame, children: _jsxs(CursorContext.Provider, { value: cursorFrame, children: [_jsx(LegacyCursor, { mode: cursor, showTime: cursorTime, snap: crosshairSnap, sequence: cursorSequenceProp, 
+                    // The 'line' default nobody asked for is IMPLICIT — the one cursor a
+                    // <MultiSelector>'s resting block preview may replace with the
+                    // brush band. An explicit `cursor` prop (any mode) still wins.
+                    implicit: cursorProp === undefined }), _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