@pond-ts/charts 0.56.2 → 0.58.0

package/dist/context.d.ts

@@ -1,8 +1,9 @@
+import { type ReactNode } from 'react';
 import type { ScaleContinuousNumeric, ScaleLinear, ScaleTime } from 'd3-scale';
 import type { ChartTheme } from './theme.js';
-import type { AxisFormat } from './format.js';
+import type { AxisFormat, CursorFormat } from './format.js';
 import type { LegendItemSpec } from './swatch.js';
-import type { Interval } from 'pond-ts';
+import type { Interval, Sequence, BoundedSequence } from 'pond-ts';
 import type { TradingTimeScale, DiscontinuityProvider } from './tradingTimeScale.js';
 import type { ScaleBand } from './bandScale.js';
 import type { ElapsedScale } from './elapsed.js';
@@ -74,6 +75,26 @@ export interface ContainerFrame {
     readonly regionAnchor: number | null;
     /** Set / clear the region-drag anchor (see {@link regionAnchor}). */
     setRegionAnchor(value: number | null): void;
+    /**
+     * The **live** spans of a sweep in flight — the preview a span-only layer
+     * paints ([PND-TRACESEL]), and empty at rest.
+     *
+     * A mark layer previews through plural `hovered`: the covered marks light.
+     * A **trace has no marks**, so there is nothing for that channel to carry —
+     * what wants lighting is the *portion of the trace inside the window*, which
+     * is a span, not a set of marks. Hence a second preview channel rather than
+     * an abuse of the first.
+     *
+     * A paint mirror in the same sense as {@link regionAnchor}: `Layers` writes
+     * it from the live session and clears it on release, and it never enters the
+     * committed selection — {@link selectedSpans} is the consumer's, this is the
+     * gesture's. A layer that finds itself named here should draw as though the
+     * span were committed, so releasing changes nothing visually and the preview
+     * cannot promise a different picture than the commit delivers.
+     */
+    readonly previewSpans: readonly SpanSelection[];
+    /** Set / clear the live sweep preview (see {@link previewSpans}). */
+    setPreviewSpans(spans: readonly SpanSelection[]): void;
     /**
      * One-shot callback fired when a `region`-cursor **drag** is released, with the
      * selected `[lo, hi]` span in **axis units** — epoch ms on a time axis, the axis
@@ -102,36 +123,93 @@ export interface ContainerFrame {
      */
     readonly regionSelectModifier: 'shift' | undefined;
     /**
-     * The selected mark, or `null`. Shared across rows (single selection). A layer
-     * highlights the mark matching the selection's series **`id`** and the clicked
-     * sample `key` (epoch ms) — the `id` picks the series (so two series sharing a
-     * timestamp don't both light up), the `key` picks the mark within it. A
-     * controlled `selected` prop pins it; otherwise a click on a selectable layer
-     * (one with an `id`) sets it.
+     * The selected marks — **empty when nothing is selected**, never `null`.
+     * Shared across rows, insertion-ordered. A layer highlights every mark
+     * matching a member's series **`id`** and clicked sample `key` (epoch ms) —
+     * the `id` picks the series (so two series sharing a timestamp don't both
+     * light up), the `key` picks the mark within it. A controlled `selected` prop
+     * pins the set; otherwise a click on a selectable layer (one with an `id`)
+     * sets it.
+     *
+     * **A set, not a single mark, since [PND-MULTISEL].** The container prop
+     * accepts either shape and normalizes here, so a single-selection consumer is
+     * unaffected; this frame field is internal (not exported from `index.ts`), so
+     * widening it breaks nobody. A layer that only ever wants one mark can read
+     * `selected[0]`, but membership is the honest test — see `isSelected`.
      */
-    readonly selected: SelectInfo | null;
+    readonly selected: readonly SelectInfo[];
     /**
-     * Select a mark, or `null` to clear — a row's click surface calls this after
-     * hit-testing its layers. Always fires `onSelect`; manages the internal
-     * selection only when uncontrolled (no `selectedKey` prop). The split mirrors
-     * the tracker's `trackerPosition` (controlled by a *value* prop) + its
-     * `onTrackerChanged` notification — not `applyRange`, which is controlled by
-     * the presence of a *callback*.
+     * The **span** entries of the controlled `selected` prop — **empty when it
+     * carries none**, never `null`. The container splits the prop's mixed
+     * `SelectionEntry` array into per-mark entries ({@link selected}) and range
+     * descriptors (this field) once at the boundary, so every existing reader of
+     * {@link selected} keeps its exact shape (and cost) while span-aware layers
+     * read this **additionally** — the union of the two fields is the selection
+     * (interaction RFC A5.2). Like `selected`, this frame field is internal (not
+     * exported from `index.ts`).
+     *
+     * Only the controlled prop can populate it: clicks produce marks, so the
+     * uncontrolled path never holds a span.
      */
-    select(hit: SelectInfo | null): void;
+    readonly selectedSpans: readonly SpanSelection[];
     /**
-     * The **hovered** mark, or `null` — the transient hover-highlight, distinct
-     * from the committed `selected`. A row's pointer-move surface hit-tests its
-     * selectable layers and sets it; a layer that supports hover-highlight (Bar)
-     * draws the matching mark lit (a lighter treatment than `selected`'s outline).
+     * Select a mark, or `null` to clear. Reports the hit to the `<Selector>`s in
+     * scope and manages the internal selection only when uncontrolled (no
+     * `selected` prop). The split mirrors the tracker's `trackerPosition`
+     * (controlled by a *value* prop) + its `onTrackerChanged` notification — not
+     * `applyRange`, which is controlled by the presence of a *callback*.
+     *
+     * **`rowKey` distinguishes the two callers, and it is load-bearing**
+     * (interaction RFC §7.1). Pass a row's key for a **plot gesture** — the row's
+     * click surface, after hit-testing — and the call is *gated on a mounted
+     * `<Selector>`*: with none in scope it does nothing at all (the deliberate
+     * break), and dev-warns on the hit that went nowhere. Omit it for a
+     * **programmatic** select (a `<Legend>` chip, a consumer's own control),
+     * which reports to the container-scoped selectors and commits as it always
+     * has — mounting gates the *plot*, not an explicit call.
+     */
+    select(hit: SelectInfo | null, modifiers?: SelectModifiers, rowKey?: symbol): void;
+    /**
+     * The **hovered** marks — **empty when nothing is hovered, never `null`** —
+     * the transient hover-highlight, distinct from the committed `selected`. A
+     * row's pointer-move surface hit-tests its selectable layers and sets it; a
+     * layer that supports hover-highlight (Bar) draws every matching mark lit (a
+     * lighter treatment than `selected`'s outline).
+     *
+     * **A set, not one mark, since RFC `selection.md` A4.2.** A1.4 argued hover
+     * "is inherently one mark under the pointer" — true while hover *means*
+     * pointer position, and false under a drag sweep, where it means "would be
+     * selected if you released now" and several marks are lit at once. Plain
+     * pointer-over therefore carries 0 or 1 members; that slightly odd type for
+     * the common case is the accepted cost of not minting a third `preview`
+     * state a theme would style identically anyway.
      * Set-on-change (deduped by the series `id` + sample `key`) so the data canvas
      * repaints only on a mark transition, not every pointer move.
      */
-    readonly hovered: SelectInfo | null;
-    /** Set the hovered mark (or `null` to clear) from a pointer-move hit-test;
-     *  deduped by series `id` + sample `key`, so an unchanged mark is a no-op
-     *  (no repaint). */
-    setHovered(hit: SelectInfo | null): void;
+    readonly hovered: readonly SelectInfo[];
+    /**
+     * Set the hovered mark (or `null` to clear) from a pointer-move hit-test;
+     * deduped by series `id` + sample `key`, so an unchanged mark is a no-op (no
+     * repaint). `rowKey` scopes which `<Selector>`s hear about it (a row's own
+     * mounts, else the container's) exactly as {@link select} does; omit it for a
+     * programmatic hover (a `<Legend>` chip).
+     *
+     * **Not gated on a mounted `<Selector>`, unlike {@link select}.** With no
+     * selector mounted there is simply nobody registered to hear about it (RFC
+     * A10.3) — the hover state still moves, it just has nothing to report to,
+     * which needs no gate to arrange.
+     *
+     * `block` — the **resting block preview** under a mounted `<MultiSelector>`
+     * (the marks of the snap block the pointer is in — exactly the set a drag
+     * begun and released there would select). When present it becomes the
+     * hovered *state* (every mark in the block lights) and what
+     * `<MultiSelector onHover>` hears, deduped by the block array's identity
+     * (the caller keeps it reference-stable per block, so within-block mark
+     * transitions re-render nothing). `<Selector onHover>` keeps its per-mark
+     * currency — `hit` still reports per mark transition. Omitted ⇒ the
+     * plain single-mark hover, exactly as before.
+     */
+    setHovered(hit: SelectInfo | null, rowKey?: symbol, block?: readonly SelectInfo[]): void;
     /** The default in-chart cursor presentation for all rows ({@link CursorMode});
      *  a row may override it via its own `cursor`. */
     readonly cursor: CursorMode;
@@ -200,6 +278,45 @@ export interface ContainerFrame {
      */
     registerSelectable(key: symbol): void;
     unregisterSelectable(key: symbol): void;
+    /**
+     * Register a mounted **selector** ({@link SelectorEntry}) — `<Selector>` /
+     * `<MultiSelector>` call this, keyed by the component's per-instance slot
+     * key. The same idiom as `registerCursor` / `registerAxis` / `registerLayer`:
+     * update in place, unregister on unmount.
+     *
+     * **The registration is the enablement** (interaction RFC §7.1): a plot click
+     * resolves the selectors in scope (`effectiveSelectorEntries`) and does
+     * nothing when there are none.
+     *
+     * The registry itself is deliberately **not** exposed on the frame (unlike
+     * `cursors`, which the rows and `<XAxis>` render): nothing outside the
+     * container reads it — `select` / `setHovered` resolve the scope internally —
+     * and publishing it would re-identify the whole frame on every selector
+     * mount. Same shape as `registerSelectable`, which also keeps its set private.
+     */
+    registerSelector(key: symbol, entry: SelectorEntry): void;
+    unregisterSelector(key: symbol): void;
+    /**
+     * Resolve a row's press against the mounted `<MultiSelector>`s in scope
+     * (interaction RFC §8): the {@link SweepGesture} sinks when at least one is
+     * in scope, else `null` — which is how the brush recognizer learns whether a
+     * sweep can claim the drag at all (mounting arms the gesture, §7.1's rule
+     * extended to the sweep). Scope resolution mirrors {@link select}'s: the
+     * row's own mounts when it has any, else the container's. The selector
+     * registry itself stays private, for the reason documented on
+     * {@link registerSelector}.
+     */
+    resolveSweep(rowKey: symbol): SweepGesture | null;
+    /**
+     * Whether a `<MultiSelector>` is in scope for this row — the *render-time*
+     * fact behind {@link resolveSweep} (which builds the per-drag gesture and is
+     * for the pointer-down path). Rows read this to decide the **resting block
+     * preview**: with one in scope over a sweep-capable row, the shared brush
+     * band becomes the resting cursor (replacing the implicit line shim) and
+     * hover lights the whole snap block a drag would select. Identity changes
+     * when the selector registry does, so it is safe in render memos.
+     */
+    hasMultiSelector(rowKey: symbol): boolean;
     /**
      * Register this layer's **legend row** — its display label + resolved
      * {@link SwatchSpec} (and selection `id` when it has one) — keyed by the
@@ -275,6 +392,34 @@ export interface ContainerFrame {
      * called while `panZoom` is on.
      */
     applyRange(range: readonly [number, number]): void;
+    /**
+     * The **y view transform** for 2-D pan/zoom (`panZoom="panZoom2D"`), in
+     * *pixel* space: a y scale's range becomes `ty + k · basePixel`. Identity is
+     * `{ k: 1, ty: 0 }`.
+     *
+     * Pixel space rather than domain space is what makes this axis-independent.
+     * A row may carry several y axes with unrelated domains (left price, right
+     * volume), and the question "which one does a vertical gesture own?" has no
+     * good answer — but a uniform pixel transform sidesteps it: every axis zooms
+     * by the same factor about its own pivot, which is also exactly what keeps
+     * the **aspect ratio** fixed. The x half stays in domain space, where
+     * `bounds`, `minDuration` and the trading-calendar zoom maths live.
+     */
+    /** Which axes the gestures own; pan follows zoom's degrees of freedom. */
+    readonly zoomX: boolean;
+    readonly zoomY: boolean;
+    readonly panX: boolean;
+    readonly panY: boolean;
+    /** True only when both axes zoom — one factor, so the ratio is fixed. */
+    readonly aspectLocked: boolean;
+    readonly yTransform: {
+        readonly k: number;
+        readonly ty: number;
+    };
+    applyYTransform(next: {
+        k: number;
+        ty: number;
+    }): void;
     /**
      * A row reports its per-slot gutter widths each side; the container reserves
      * each slot's max so every row's plot left-aligns. Returns an unregister fn.
@@ -289,6 +434,19 @@ export interface ContainerFrame {
     registerRow(key: symbol): () => void;
     /** The first (topmost) row's key, or `null` before any row has registered. */
     readonly firstRowKey: symbol | null;
+    /**
+     * Register a mounted **cursor** ({@link CursorEntry}) — the `<LineCursor>` /
+     * `<CrosshairCursor>` / … presets (and the deprecation shim synthesizing them
+     * from the legacy string props) call this, keyed by the component's
+     * per-instance slot key. The container resolves the per-row effective set
+     * (row mounts override container mounts — see `effectiveCursorEntries`) and
+     * the rows/`<XAxis>` render the registered slots. Update is in place;
+     * unregister on unmount.
+     */
+    registerCursor(key: symbol, entry: CursorEntry): void;
+    unregisterCursor(key: symbol): void;
+    /** Every registered cursor, in mount order (see {@link registerCursor}). */
+    readonly cursors: readonly CursorEntry[];
     /**
      * Register an annotation (`<Region>`/`<Marker>`/`<Baseline>`) so the container
      * can coordinate what a mark can't do in isolation: draw each mark's **guide
@@ -349,6 +507,15 @@ export interface ContainerFrame {
 }
 /** The kind of an annotation, and of a creation tool. */
 export type AnnotationKind = 'region' | 'marker' | 'baseline';
+/**
+ * The kind of a **registered** mark — wider than {@link AnnotationKind}.
+ *
+ * A `<Zone>` is a mark you place in JSX but **not** a create *tool*: there is no
+ * draw gesture for it and no {@link CreateSpec} variant, so it registers under
+ * its own kind without widening the toolbar vocabulary (which would let
+ * `creating="zone"` type-check and then silently never fire `onCreate`).
+ */
+export type AnnotationSpecKind = AnnotationKind | 'zone';
 /** What a completed create gesture reports to {@link ContainerFrame.onCreate} —
  *  the new mark's kind + position in axis units (+ the y-axis id for a baseline).
  *  (Which row a mark lands on is the consumer's call for now; multi-row routing is
@@ -376,14 +543,14 @@ export interface AnnotationSpec {
      *  double-click reports via {@link ContainerFrame.onSelectAnnotation}, so the
      *  consumer knows which mark to select. */
     readonly id: string | undefined;
-    readonly kind: AnnotationKind;
+    readonly kind: AnnotationSpecKind;
     /** The row it lives on (its `<ChartRow>`'s key), so a row skips its own marks
      *  when drawing guides. */
     readonly rowKey: symbol;
     /**
      * Its vertical-guide x-position(s) in **axis units** (the shared x): a marker's
-     * `[at]`, a region's `[from, to]`. Empty for a baseline — a horizontal line
-     * casts no vertical guide.
+     * `[at]`, a region's `[from, to]`. Empty for a baseline or a zone — a
+     * horizontal line (or band) casts no vertical guide.
      */
     readonly xs: readonly number[];
     /** Whether it's currently selected (controlled by the consumer). */
@@ -554,13 +721,15 @@ export interface RowLayer {
     binCategories?(): readonly string[] | null;
     /**
      * A bar/histogram layer's bar `[begin, end)` spans, as pond `Interval`s — the
-     * **region cursor's snap buckets**. When present (and no `cursorSequence` is
-     * set), a region drag snaps bar by bar and a hover highlights the bar under the
-     * pointer, so a histogram gets bin-aligned selection for free. Only a
-     * **vertical** bar layer on a **continuous** (time / value) x axis publishes
-     * them — a horizontal chart puts the value on x (snapping counts is meaningless)
-     * and a **category** (ordinal-slot) axis is excluded from the region cursor.
-     * `null` / absent otherwise.
+     * **shared snap buckets**. When present (and no `cursorSequence` is set), a
+     * region drag snaps bar by bar and a `<MultiSelector>` sweep's band extends
+     * bar by bar, so a histogram gets bin-aligned selection for free. Only a
+     * **vertical** bar layer publishes them — a horizontal chart puts the value
+     * on x (snapping counts is meaningless). On a **category** axis they are
+     * the unit slots `[i, i+1)`: the region cursor still ignores them (its band
+     * gates on a continuous axis), but the sweep band snaps over them to the
+     * slots' outer edges (RFC A7.6's edge rule — the band must agree with the
+     * span the release commits). `null` / absent otherwise.
      */
     binIntervals?(): readonly Interval[] | null;
     /**
@@ -589,8 +758,87 @@ export interface RowLayer {
      * so they render + read out but never select/hover (a click on them resolves
      * to empty space ⇒ deselect). `xScale`/`yScale` map data→pixels (the row
      * resolves the layer's axis scale, as for `draw`).
+     *
+     * `mode` says which gesture is asking, and a layer whose hover target is
+     * generous may narrow the *select* one. The single-series bar path does:
+     * **hover** attributes the bar's whole slot (full interval width, full plot
+     * height — the continuous model #582 asked for, so the highlight tracks
+     * like the readout), while **select** additionally requires the pointer to
+     * be within the bar's drawn ink vertically. Without that narrowing, slots
+     * tile the entire plot and a click can never resolve to `null` — RFC §7's
+     * empty-click deselect path becomes unreachable on any full-range bar
+     * chart. Layers whose hit target is already the drawn mark (stacks,
+     * scatter, boxes, heat cells) ignore `mode`.
      */
-    hitTest?(px: number, py: number, xScale: (value: number) => number, yScale: (value: number) => number): SelectInfo | null;
+    hitTest?(px: number, py: number, xScale: (value: number) => number, yScale: (value: number) => number, mode?: 'hover' | 'select'): SelectInfo | null;
+    /**
+     * Begin a **sweep session** over this layer's marks — `<MultiSelector>`'s
+     * range query (interaction RFC A7.6/A7.7), the range analog of
+     * {@link hitTest} and gated exactly like it: only a layer with an `id` (and
+     * discrete selectable marks) wires it, so an untagged layer is never swept.
+     * Called on the pointer-down that survives `DRAG_SLOP` under a mounted
+     * `<MultiSelector>`; the session lives for that one drag and nothing
+     * persists outside it. Returns `null` when there is nothing sweepable.
+     *
+     * `xScale`/`yScale` are the resolved scales (as for `draw`/`hitTest`) —
+     * unused by the 1-D layers, but part of the seam so the 2-D sessions
+     * (scatter's y-window, the heat map's row cut — [PND-INTERACT2D]) can be
+     * added without redesigning the shape (RFC A7.6).
+     */
+    beginSweep?(xScale: (value: number) => number, yScale: (value: number) => number): SweepSession | null;
+    /**
+     * Whether a sweep over this layer cuts a **rect** rather than a band — the
+     * same fact {@link SweepSession.twoD} reports, declared on the layer because
+     * the RESTING state has to know it and there is no session at rest.
+     *
+     * It decides what the row's resting cursor is: a band over the snap block
+     * for a 1-D layer, a small crosshair at the pointer for a 2-D one (a rect
+     * gesture has no resting block to preview — see `Layers`). Building a
+     * per-drag session just to ask would be the wrong shape and would snapshot
+     * the layer's arrays for nothing.
+     *
+     * Must agree with the session the layer's own `beginSweep` returns;
+     * `sweep-capabilities.test.ts` pins that across every layer.
+     */
+    readonly sweepsRect?: boolean;
+    /**
+     * **Which screen axis a sweep over this layer cuts** — `'x'` (the default,
+     * and every layer that shipped before [PND-HSWEEP]) or `'y'` for a
+     * transposed layer whose bins run down the screen: a horizontal
+     * `<BarChart>` puts the value on the shared x, so a window there says
+     * nothing about which bins are covered and the cut has to come from the
+     * pointer's y.
+     *
+     * **Orthogonal to {@link sweepsRect}, and all four pairs are real** — (x,
+     * band) a vertical bar, (y, band) a horizontal bar, (x, rect) a scatter or a
+     * vertical heat map, (y, rect) a horizontal heat map. That is why this is a
+     * second field rather than a third value on `sweepsRect`.
+     *
+     * The session itself is unaffected: {@link SweepSession.update} takes
+     * **key-axis units** and does not care which screen axis produced them, so a
+     * transposed layer builds the same `sweep1D` a vertical one does. What the
+     * axis changes is the *gesture* — which pointer coordinate is inverted (and
+     * through which scale), where the drag slop lives (`|dy|` rather than
+     * `|dx|`), and which way the brush band is drawn.
+     *
+     * A `'y'` cut is measured against **one row's** axis, so its band is
+     * row-local exactly as a rect is, and it takes its geometry from
+     * {@link SweepSession.extent} rather than from the shared bin channel —
+     * `binIntervals` carries the *value* axis on a transposed layer.
+     */
+    readonly sweepAxis?: 'x' | 'y';
+    /**
+     * **Whether a sweep over this layer has a range but no marks** — the same
+     * fact {@link SweepSession.spanOnly} reports, declared on the layer for
+     * exactly the reason {@link sweepsRect} is: the RESTING state has to know it
+     * and there is no session at rest.
+     *
+     * It suppresses the resting **block** band. That band previews "a drag begun
+     * here selects this block", and a trace has no blocks — a drag takes a
+     * freeform window — so the band would advertise a set the gesture never
+     * selects. Precisely the reason a `twoD` layer gets no resting band either.
+     */
+    readonly sweepSpanOnly?: boolean;
     /**
      * Draw into the plot canvas. `xScale`/`yScale` map data→pixels. May return
      * {@link LayerDrawStats} (source/drawn counts + whether decimation engaged) so
@@ -599,6 +847,142 @@ export interface RowLayer {
      */
     draw(ctx: CanvasRenderingContext2D, xScale: (value: number) => number, yScale: (value: number) => number): LayerDrawStats | void;
 }
+/**
+ * A layer's per-drag **sweep session** ({@link RowLayer.beginSweep} — RFC
+ * A7.7's `beginSweep(scales) → session` shape, 1-D form). The gesture engine
+ * drives it: `update` per coalesced frame with the swept key-window,
+ * {@link hits} for the frame-gated live preview, and — at release — the same
+ * `hits()` again as the commit payload plus {@link extent} for the span, so
+ * the committed hits ARE the materialised preview rather than a fresh range
+ * query (RFC A5.2's "the hits are free"). Internal, like `RowLayer` itself.
+ */
+export interface SweepSession {
+    /** The layer's `id` — what the committed {@link SpanSelection} carries. */
+    readonly id: string;
+    /**
+     * Re-cut the covered set to the marks intersecting the half-open window
+     * `[x0, x1)` (key-axis units, `x0 <= x1`). Returns whether the covered set
+     * changed — the delta gate: an unchanged frame re-materialises nothing.
+     *
+     * `y0`/`y1` are the rect's second dimension in the layer's **y-axis data
+     * units** (not pixels — the gesture inverts through the same `yScale` the
+     * session was built with), and only a {@link twoD} session reads them; the
+     * gesture omits them entirely for a 1-D layer. They are unordered, because
+     * a drag upward hands them over inverted and the session is the one place
+     * that knows whether its axis descends.
+     *
+     * **A `twoD` session must include y in its own delta gate.** A purely
+     * vertical drag leaves the x run untouched, so a gate that watched x alone
+     * would answer `false` and freeze the preview under a moving pointer.
+     */
+    update(x0: number, x1: number, y0?: number, y1?: number): boolean;
+    /**
+     * The covered marks, materialised (and cached until the next change) — the
+     * live preview `hovered` lights, and verbatim the release payload.
+     */
+    hits(): readonly SelectInfo[];
+    /**
+     * The covered marks' snapped-outward key extent `[begin(first), end(last))`
+     * — {@link SpanSelection.x} per RFC A7.6's edge rule, so the span's
+     * half-open containment test reproduces exactly the captured set. `null`
+     * when nothing is covered.
+     */
+    extent(): readonly [number, number] | null;
+    /**
+     * **Set by a layer whose marks live in two dimensions** — a scatter (a point
+     * is a position, not a column) or a heat map (a grid of cells). The gesture
+     * reads this to decide whether to track a y window alongside x and to draw a
+     * rect rather than a band: dimensionality is a property of the *layer*, so a
+     * consumer mounts the same `<MultiSelector>` either way (RFC Q14).
+     */
+    readonly twoD?: boolean;
+    /**
+     * **Set by a layer that has a range but no marks** — a continuous trace
+     * ([PND-TRACESEL]). `hits()` is always empty and the span is the whole
+     * selection.
+     *
+     * The gesture reads this to answer "who else did I sweep?". Topmost-wins
+     * exists because a release carried **one** span, and on mark layers it is
+     * defensible — you were pointing at marks, so the topmost is the one you
+     * meant. A trace sweep points at *nothing*: every trace in the row shares
+     * the same x window, so singling one out by z-order is arbitrary to the
+     * reader. Every span-only layer in the row is therefore swept together,
+     * while mark layers keep topmost-wins unchanged.
+     */
+    readonly spanOnly?: boolean;
+    /**
+     * The captured set's **second-dimension** channels, for a `twoD` session —
+     * whichever of {@link SpanSelection.y} (a scatter's continuous window) and
+     * {@link SpanSelection.rows} (a heat map's ordinal row set) the layer uses.
+     * `null` when nothing is covered. Absent on a 1-D session.
+     */
+    extent2D?(): {
+        readonly y?: readonly [number, number];
+        readonly rows?: readonly string[];
+    } | null;
+    /**
+     * The cut's **snapped rect in axis units** (x in key units, y in the
+     * sweeping layer's y-axis units), for the brush to draw — `null` when the
+     * layer's cut is free, or when nothing is covered.
+     *
+     * A snapping layer must draw the rect it is going to *take*, not the one
+     * the pointer traced: a heat map snaps to whole cells, so a raw pointer
+     * rect promises a different set than the release delivers, and the two
+     * disagree most visibly at exactly the moment the user is deciding where
+     * to let go.
+     */
+    snappedRect?(): {
+        readonly x: readonly [number, number];
+        readonly y: readonly [number, number];
+    } | null;
+}
+/**
+ * What the container resolves for a row's press under a mounted
+ * `<MultiSelector>` ({@link ContainerFrame.resolveSweep}): the two sinks of
+ * the sweep gesture, with the selector registry kept private (the same reason
+ * `select` resolves scope internally). Both operate on the entries that were
+ * in scope at the press, for the lifetime of that one drag.
+ */
+export interface SweepGesture {
+    /**
+     * Whether an in-scope `<MultiSelector>` **declared a `sequence`** — i.e. the
+     * consumer said selection happens in bucket units rather than in marks.
+     *
+     * This is what widens a *click* from the mark under the pointer to the whole
+     * snap block (RFC §8). It has to be the declaration and not a property of
+     * what the block happened to contain: a stack's bin holds one mark per
+     * group, so "the block covers more than one mark" is true of an ordinary
+     * single-bin click on a stacked chart, and using that as the test made a
+     * click there select the whole bin instead of the clicked segment.
+     */
+    readonly snapped: boolean;
+    /**
+     * The frame-coalesced **live preview**: light `hits` through the plural
+     * `hovered` (RFC A3.4 — the library owns the state, each layer renders its
+     * own hover treatment) and report them to the `<MultiSelector>`s in scope.
+     * Nothing else crosses the public boundary until release (RFC A1.4).
+     *
+     * `light: false` **reports without lighting** — for a layer whose brush
+     * already outlines exactly the covered region (a heat map's snapped rect).
+     * Its hover treatment is a ring around *the cell under the pointer*, and
+     * during a sweep there is no such cell: a ring on every covered cell turns
+     * the region into the mostly-border grid the selection outline exists to
+     * avoid, inside a rect that is already saying the same thing. The consumer
+     * still hears the full set through `onHoverMany`, so a controlled `hovered`
+     * can render it however it likes.
+     */
+    preview(hits: readonly SelectInfo[], light?: boolean): void;
+    /**
+     * The release: report `(hits, modifiers, span)` to the `<MultiSelector>`s in
+     * scope (RFC A5.2), clear the preview, and — when `selected` is
+     * uncontrolled — commit the compact span descriptor as the selection.
+     */
+    commit(hits: readonly SelectInfo[], modifiers: SelectModifiers, 
+    /** Every span the gesture produced, **topmost first** — see
+     *  `<MultiSelector onSelect>`. Empty for a click, or for a sweep that
+     *  covered nothing. */
+    spans: readonly SpanSelection[]): void;
+}
 /** One tracker readout point — a dot + value the overlay draws at the cursor. */
 export interface TrackerSample {
     /** The sample's time (epoch ms); the dot sits at `xScale(x)`. */
@@ -676,6 +1060,125 @@ export interface TrackerSource {
  * a selection survives a streaming data update where a sample `key` would go
  * stale. Only layers that carry an `id` are selectable (see {@link RowLayer.hitTest}).
  */
+/**
+ * The keyboard modifiers held during the click that produced a selection —
+ * handed to `<Selector onSelect>` alongside the hit ([PND-MULTISEL]).
+ *
+ * **Why the library reports these instead of acting on them.** A consumer with
+ * a multi-valued filter needs ⌘/Ctrl-click to mean "add to the selection", and
+ * without the modifier state on the callback it simply cannot: the click has
+ * already been reduced to a hit by the time it arrives, so every consumer is
+ * forced to treat every click as a replace. Reporting the modifiers keeps the
+ * *policy* with the consumer while removing the thing that made the policy
+ * unexpressible.
+ *
+ * The library itself still applies no modifier semantics — a chart click sets
+ * the single hit as it always has. A consumer that wants add/toggle reads
+ * {@link additive} and drives the controlled `selected` set itself.
+ */
+export interface SelectModifiers {
+    /**
+     * The platform-idiomatic **"add to selection"** chord — `metaKey` on macOS,
+     * `ctrlKey` elsewhere, surfaced as one boolean so every consumer doesn't
+     * re-derive the same platform rule (and get it wrong on one of the two).
+     * Prefer this over the raw keys unless you specifically want one of them.
+     */
+    readonly additive: boolean;
+    readonly ctrlKey: boolean;
+    readonly metaKey: boolean;
+    /**
+     * **Note the conflict:** `shift` is already the drag chord for
+     * `<ChartContainer regionSelectModifier="shift">` on a continuous axis, so a
+     * shift-click there may also be the start of a region drag. Reported for
+     * completeness; think before you give it a second meaning. (There is
+     * deliberately no derived `range` flag for this reason — an ordinal range
+     * gesture is [PND-CATRANGE], not a modifier.)
+     */
+    readonly shiftKey: boolean;
+    readonly altKey: boolean;
+}
+/**
+ * A mounted `<Selector>` as the container holds it — the reporting callbacks
+ * plus the mount scope (interaction RFC §7 / A4.2). **A selector both reports
+ * and, optionally, owns controlled state** (`selected` / `hovered` — A10.3):
+ * the gesture and the state it drives are declared on the same mount.
+ *
+ * Registered via {@link ContainerFrame.registerSelector}, the same idiom as
+ * `registerCursor`. Internal (not exported from `index.ts`) — `<Selector>`'s
+ * props are the public surface.
+ */
+export interface SelectorEntry {
+    /** Report the mark under the pointer (`null` on leaving every mark). */
+    readonly onHover: ((hit: SelectInfo | null) => void) | undefined;
+    /** Report the clicked mark plus the modifiers held. The library applies no
+     *  policy to them and holds no set — see {@link SelectModifiers}. */
+    readonly onSelect: ((hit: SelectInfo | null, modifiers?: SelectModifiers) => void) | undefined;
+    /**
+     * Whether this entry is a mounted `<MultiSelector>` (RFC §8) — the flag the
+     * sweep gesture resolves on: **mounting one is what arms the sweep drag** on
+     * the plot, exactly as mounting any selector is what arms the click (§7.1).
+     * `<Selector>` registers `false`.
+     */
+    readonly multi: boolean;
+    /** `<MultiSelector onHover>` — the marks a live sweep covers (0/1 outside a
+     *  drag, mirroring the single-hit channel). Plural entries only. */
+    readonly onHoverMany?: ((hits: readonly SelectInfo[]) => void) | undefined;
+    /** `<MultiSelector onSelect>` — RFC A5.2's `(hits, modifiers, span)`. A
+     *  plain click reports `([hit] | [], modifiers, null)`; a sweep release
+     *  reports the covered marks plus the span they demote to. Plural entries
+     *  only. */
+    readonly onSelectMany?: ((hits: readonly SelectInfo[], modifiers: SelectModifiers | undefined, spans: readonly SpanSelection[]) => void) | undefined;
+    /** `<MultiSelector sequence>` — the sweep's bucket snap, folded into the
+     *  container's shared snap-bucket channel (as `<RangeCursor sequence>` is). */
+    readonly sequence?: Sequence | BoundedSequence | undefined;
+    /** Mount scope: a row's key when mounted inside a `<ChartRow>` (that row's
+     *  clicks only), `null` when mounted at the container (every row). */
+    readonly rowKey: symbol | null;
+    /**
+     * Whether the **gesture** is active (`<Selector enabled>`, A10.2). `false`
+     * means the plot behaves as if this entry were unmounted — no hit-testing,
+     * no callbacks fire, no sweep arms — while the entry may still be the
+     * chart's controlled-state owner below. This is what makes
+     * `<Selector enabled={false} selected={sel} />` the "highlight only, no
+     * plot gesture" configuration: one component, gesture off, state on.
+     */
+    readonly gestureEnabled: boolean;
+    /** Whether `selected` was explicitly passed to this mount — distinguishes
+     *  "controlled with nothing selected" (`null`) from "not the state owner"
+     *  (`undefined`), the same three-state shape `selected` itself needs. */
+    readonly declaresSelected: boolean;
+    /** `<Selector selected>` / `<MultiSelector selected>` (A10.3) — meaningful
+     *  only when {@link declaresSelected} is true. */
+    readonly selected?: SelectInfo | readonly SelectionEntry[] | null | undefined;
+    /** As {@link declaresSelected}, for `hovered`. */
+    readonly declaresHovered: boolean;
+    /** `<Selector hovered>` / `<MultiSelector hovered>` (A10.3) — meaningful
+     *  only when {@link declaresHovered} is true. */
+    readonly hovered?: SelectInfo | readonly SelectInfo[] | null | undefined;
+}
+/**
+ * The span a completed `<RangeCursor>` drag reports to `onDragRelease` —
+ * **one uniform shape with an optional y** (interaction RFC A3.3), not the
+ * bare pair the legacy `onRegionSelect` used, and not a polymorphic union a
+ * consumer must narrow.
+ *
+ * `x` is `[lo, hi]` in **axis units** — epoch ms on a time axis, the axis
+ * value (strike, distance, …) on a value axis — snapped to the cursor's
+ * buckets when it has a `sequence` (or a histogram's bins), else the raw drag
+ * span. `y` is **absent on today's 1-D layers**; the 2-D drag (scatter / heat
+ * map — [PND-INTERACT2D]) will populate it *without a breaking change*, which
+ * is the whole reason the 1-D payload is already an object.
+ *
+ * The x pair feeds `ChartContainer.range` directly (it accepts a
+ * `readonly [number, number]`), so drag-to-zoom is
+ * `onDragRelease={(s) => setRange(s.x)}`; a time-axis consumer who wants a
+ * `TimeRange` constructs one from the pair.
+ */
+export interface RangeSpan {
+    readonly x: readonly [number, number];
+    /** Present only on a 2-D drag (scatter / heat map) — not yet emitted. */
+    readonly y?: readonly [number, number];
+}
 export interface SelectInfo {
     /**
      * The **series identity** — the layer's `id` prop. The selection / dedup /
@@ -720,6 +1223,77 @@ export interface SelectInfo {
      */
     readonly mark?: string;
 }
+/**
+ * A **span selection** — a compact range descriptor over one layer's marks, the
+ * second currency `selected` accepts beside per-mark {@link SelectInfo} entries
+ * (interaction RFC A5.2). Where a mark entry names one mark, a span names
+ * *every* mark of layer {@link id} inside its extent — the shape a sweep
+ * gesture commits, and the shape a consumer with a range-valued filter already
+ * has. Membership is evaluated per draw against the mark's own channels, so a
+ * span costs O(1) per mark however many marks it covers.
+ *
+ * **The containment rule, stated once** (evaluated by `selectionContains` and,
+ * identically, by every layer's draw): a mark is inside a span when the span's
+ * `id` is the mark's layer, the mark's **key** (its `SelectInfo.key` — the bin
+ * axis position in axis units) lies in the **half-open** interval
+ * `x[0] <= key < x[1]`, the mark's **value** (its `SelectInfo.value`) lies in
+ * `y[0] <= value < y[1]` when {@link y} is present, and the mark's **label**
+ * (its `SelectInfo.label` — the row/group name on a 2-D-ordinal layer) is a
+ * member of {@link rows} when present.
+ *
+ * **Half-open, deliberately** — the pond bucket convention (`[begin, end)`),
+ * and the half the edge rule needs: contiguous interval marks share edges
+ * (`end[i] === begin[i+1]`), so a sweep that captures marks `i..j` by
+ * *intersection* stores the snapped-outward edges `[begin(i), end(j)]`, and the
+ * half-open key test then reproduces exactly the captured set — `begin(j+1) ===
+ * end(j)` falls out on the open side (RFC A7.6). A closed test would light the
+ * first mark *past* the sweep on every shared edge.
+ *
+ * **Two optional second dimensions, not one** (RFC A5.3): {@link y} is a
+ * numeric interval for a continuous × continuous layer (scatter), where the
+ * second coordinate is the mark's plotted value. {@link rows} is a label set
+ * for a continuous × ordinal layer (heat map), whose second coordinate is an
+ * ordinal row **name** — a numeric y-interval there would be untestable from a
+ * hit (the hit carries no slot number) and unstable under a row reorder. Do not
+ * conflate them.
+ */
+export interface SpanSelection {
+    /** Discriminant against {@link SelectInfo} (which has no `kind`). */
+    readonly kind: 'span';
+    /** The **layer** whose marks the span covers — a layer `id`, exactly as
+     *  {@link SelectInfo.id}. A span never matches marks of another layer. */
+    readonly id: string;
+    /**
+     * The key-axis extent in **axis units** (epoch ms on a time axis, the axis
+     * value on a value axis), half-open `[lo, hi)` against each mark's
+     * {@link SelectInfo.key}. This is the layer's **bin/key axis** whatever the
+     * orientation — a horizontal heat map's bins run down the screen, but their
+     * keys (and so this interval) stay in bin-axis units. Must be ordered
+     * `lo <= hi`; a reversed or empty pair matches nothing.
+     */
+    readonly x: readonly [number, number];
+    /**
+     * Optional **value-axis** interval, half-open against each mark's
+     * {@link SelectInfo.value} — the continuous second dimension of a 2-D sweep
+     * on a scatter (RFC A3.3/A5.3). Omit for 1-D layers.
+     */
+    readonly y?: readonly [number, number];
+    /**
+     * Optional **row label set**, matched against each mark's
+     * {@link SelectInfo.label} — the ordinal second dimension of a 2-D sweep on
+     * a heat map (RFC A5.3), stable under a row reorder because it names rows
+     * rather than numbering slots. Omit for 1-D layers.
+     */
+    readonly rows?: readonly string[];
+}
+/**
+ * One entry of a plural `selected` — a single mark ({@link SelectInfo}) or a
+ * whole range of one layer's marks ({@link SpanSelection}). The two currencies
+ * of interaction RFC A5.2: clicks produce marks, sweeps produce a span (plus
+ * the marks it covered, for demote-on-edit). Discriminate with
+ * `isSpanSelection` / the `kind` field.
+ */
+export type SelectionEntry = SelectInfo | SpanSelection;
 /** The hover snapshot handed to `onTrackerChanged` — the cursor time + every
  *  series' value there, so a consumer can render the readout outside the chart. */
 export interface TrackerInfo {
@@ -743,6 +1317,267 @@ export interface TrackerInfo {
  *   snap to the series (the axis pills read like ticks), not the raw mouse Y.
  */
 export type CursorMode = 'none' | 'line' | 'point' | 'inline' | 'flag' | 'crosshair' | 'region';
+/**
+ * How a cursor wants the shared `cursorX` snapped, **declared, resolved by the
+ * container** (interaction RFC A2.3). The x-snap consults each layer's
+ * `sampleAt` in the hovered row and writes the result into the shared
+ * {@link CursorFrame.cursorX} every other row reads — a cursor component has
+ * neither the layers nor the right to write that value, so it declares the
+ * policy and the container resolves it. Container resolves; slots draw.
+ *
+ * - `'none'` — the raw pointer x.
+ * - `'sample'` — snap to the nearest data sample's x (the crosshair).
+ * - `'sequence'` — bucket-shaped: the *rendering* snaps to the realized
+ *   sequence buckets (the range cursor's band); `cursorX` itself stays raw.
+ */
+export type CursorSnapX = 'none' | 'sample' | 'sequence';
+/**
+ * One resolved per-series measurement at the cursor — **finished numbers, not
+ * raw materials** (interaction RFC A2.3): the sample's plot pixels, the axis it
+ * scales against (id + side, so a pill can hug the right gutter), and its value
+ * already formatted by that axis's formatter. A cursor slot draws these; it
+ * never sees a scale, a format map, or an axis-side map.
+ */
+export interface ResolvedCursorSample {
+    readonly px: number;
+    readonly py: number;
+    readonly axisId: string;
+    readonly side: 'left' | 'right';
+    readonly formatted: string;
+    readonly color: string;
+    readonly label: string;
+}
+/** A resolved consolidated multi-value flag (a {@link RowLayer.cursorFlag}
+ *  layer — the BoxPlot): its anchor pixels + the formatted, coloured lines. */
+export interface ResolvedCursorFlag {
+    readonly px: number;
+    readonly topPy: number;
+    readonly lines: readonly {
+        readonly text: string;
+        readonly color: string;
+    }[];
+}
+/**
+ * The frame handed to a {@link CursorSpec}'s render slots — resolved geometry
+ * and finished measurements (RFC A2.3), never scales or format maps.
+ *
+ * **Internal for now** (deliberately not exported from `index.ts`): RFC Q3
+ * publishes the cursor contract only after every built-in preset — and the SR
+ * gapped crosshair — is written against it. The presets in `cursors.tsx` are
+ * that litmus; until it passes, this shape may still move.
+ */
+export interface ResolvedCursorFrame {
+    /** The shared plot-pixel x ({@link CursorFrame.cursorX}) — may be out of
+     *  `[0, plotWidth]` (a controlled tracker extrapolated); slots gate. */
+    readonly cursorX: number | null;
+    /** The hovered plot-pixel y (row-local; see {@link CursorFrame.cursorY}). */
+    readonly cursorY: number | null;
+    /** The **renderer's own** row, `null` in the x-axis slot… */
+    readonly rowKey: symbol | null;
+    /** …alongside the **hovered** row (A1.3: a slot needs both to know whether
+     *  it is drawing in the row the pointer is in). */
+    readonly hoveredRowKey: symbol | null;
+    /** Per-series resolved measurements at the cursor time (empty when the
+     *  effective cursors declared no need for them, or nothing is hovered). */
+    readonly samples: readonly ResolvedCursorSample[];
+    /** Resolved consolidated flags (BoxPlot) — the flag cursor's one-chip form. */
+    readonly flags: readonly ResolvedCursorFlag[];
+    /**
+     * The **raw pointer**'s y resolved against the row's default axis — position,
+     * formatted value, and axis side — or `null` when this row isn't hovered.
+     * The free (non-snapping) crosshair reads this; it is resolved here because a
+     * slot has no `yScale.invert` to do it itself.
+     */
+    readonly pointer: {
+        readonly py: number;
+        readonly formatted: string;
+        readonly side: 'left' | 'right';
+    } | null;
+    /** The range cursor's **band** under the pointer (bucket-snapped via the
+     *  declared sequence, else the drag span), as clamped plot pixels; `null`
+     *  when nothing to shade. Resolved by the container from `regionSpan`. */
+    readonly band: {
+        readonly x0: number;
+        readonly x1: number;
+    } | null;
+    /**
+     * The **transposed band** — the same brush over a layer that declares
+     * `sweepAxis: 'y'` (a horizontal `<BarChart>`, whose bins run down the
+     * screen), as plot pixels on the row's own y axis. `null` in every other
+     * state, including an x sweep, which paints {@link band}.
+     *
+     * Row-local for {@link rect}'s reason: a y interval only means anything
+     * against the axis that measured it, so the row owning the drag resolves it
+     * and the others stay `null`. It is drawn by the same `renderBrushBand` with
+     * the geometry transposed — one renderer, so the two orientations of one
+     * gesture cannot drift (§8.1).
+     */
+    readonly bandY: {
+        readonly y0: number;
+        readonly y1: number;
+    } | null;
+    /** Degenerate range cursor (no buckets, not mid-drag): draw a plain line. */
+    readonly bandLine: boolean;
+    /**
+     * Whether the band's extent is being **dragged** right now — a range drag
+     * anchored, or a `<MultiSelector>` sweep past its slop — rather than merely
+     * previewing the block under the pointer.
+     *
+     * The band renders in both states; this is what separates them. The edges
+     * are the gesture's grabbed boundary, so they draw only while there is a
+     * gesture: at rest the band is a *preview*, and edging a preview reads as a
+     * committed range the user hasn't made yet.
+     */
+    readonly bandDragging: boolean;
+    /**
+     * The **2-D brush rect** — a live `<MultiSelector>` sweep over a `twoD`
+     * layer ({@link SweepSession.twoD}: a scatter, a heat map), as clamped plot
+     * pixels. `null` in every other state, including a 1-D sweep, which paints
+     * {@link band} instead.
+     *
+     * It is deliberately **not** a band with a y range bolted on. The band is
+     * container state, so every row paints it from one anchor — right for an
+     * x-range, which means the same thing in every row. A rect's y is only
+     * meaningful in the row whose layer's axis it was measured against, so this
+     * is resolved per row by the row that owns the drag, and stays `null` in
+     * the others.
+     *
+     * **Unsorted, on purpose:** `(x0, y0)` is the corner the drag was anchored
+     * at and `(x1, y1)` the corner under the pointer, so either may be the
+     * larger. The renderer sorts for the box, but it needs the diagonal intact
+     * to put the two crosshairs on the corners the user is actually holding.
+     * (`x` is still the *snapped* band edge where the layer snaps — assigned to
+     * whichever end the anchor is on.)
+     */
+    readonly rect: {
+        readonly x0: number;
+        readonly x1: number;
+        readonly y0: number;
+        readonly y1: number;
+    } | null;
+    /**
+     * Draw the **resting** 2-D brush — a small grey `+` at the pointer, the
+     * rect gesture's answer to {@link band}'s resting block preview.
+     *
+     * Small on purpose, and not a crosshair in the usual sense. A full-plot
+     * crosshair is a value-reading instrument: it exists to project the pointer
+     * onto both axes. This one marks *a corner a rect would start from*, and
+     * the rect draws its own edges out to those axes the moment a drag begins —
+     * so plot-spanning rules would add two more lines to a picture that is
+     * about to have them anyway. The compact `+` says "here", which is all a
+     * corner needs to say.
+     */
+    readonly restingCross: boolean;
+    /** The cursor time, formatted by the container's readout channel
+     *  (`formatReadout ?? formatTime` in a row; the axis's own resolved readout
+     *  formatter in the x-axis slot). `null` when out of bounds / not wanted. */
+    readonly formattedTime: string | null;
+    readonly plotWidth: number;
+    /** The renderer's row height (`0` in the x-axis slot). */
+    readonly rowHeight: number;
+    /** Whether this row is the topmost — the shared time chip shows once, here. */
+    readonly isFirstRow: boolean;
+    readonly theme: ChartTheme;
+    /** X-axis slot placement (set only when invoking {@link CursorSpec.renderXAxis}):
+     *  which side the axis strip is on and the pill's tick-label offset. */
+    readonly xAxis: {
+        readonly onTop: boolean;
+        readonly pillOffset: number;
+    } | null;
+}
+/**
+ * A mounted cursor's contract with the container (interaction RFC A2.3):
+ * **declared** snap plus up to three render slots taking resolved geometry.
+ * The container resolves (`cursorX` snapping, per-sample measurements, the
+ * band); the slots draw. Registered via {@link ContainerFrame.registerCursor}
+ * — the same idiom as `registerAxis` / `registerLayer`.
+ *
+ * Internal for now, like {@link ResolvedCursorFrame} (RFC Q3).
+ */
+export interface CursorSpec {
+    /** How the shared `cursorX` snaps while this cursor owns the hovered row. */
+    readonly snapX?: CursorSnapX;
+    /** SVG into the row's cursor overlay (above the data canvas — hovering never
+     *  repaints the canvas). */
+    renderPlot?(f: ResolvedCursorFrame): ReactNode;
+    /**
+     * DOM into the row's overlay, above the SVG — the value chips (inline /
+     * flag) and the in-plot time readout. NOT in RFC A2.3's three-slot shape:
+     * the production flag/inline cursors are DOM chips positioned in plot space,
+     * which "SVG into the overlay" cannot express — the same gap A1.3 called on
+     * §5. Kept internal; the published contract must resolve this (see the
+     * step-2 notes in the charts plan).
+     */
+    renderPlotHtml?(f: ResolvedCursorFrame): ReactNode;
+    /** DOM, per row: the axis-edge **value pill** (positioned via `axisPillX`,
+     *  overflowing the plot into its axis gutter). */
+    renderYGutter?(f: ResolvedCursorFrame): ReactNode;
+    /** DOM, on the shared x axis: the **time pill** (+ its connector). `<XAxis>`
+     *  shows it whenever the hovered row's effective cursor registers this slot
+     *  — the mount is the gate, not a mode string. */
+    renderXAxis?(f: ResolvedCursorFrame): ReactNode;
+}
+/** What a cursor needs the container to resolve per pointer move — declared at
+ *  registration so a line-only cursor never pays for per-sample measurement. */
+export interface CursorWants {
+    /** Per-series {@link ResolvedCursorSample}s (dots, chips, the reticle pick). */
+    readonly samples: boolean;
+    /** Consolidated {@link ResolvedCursorFlag}s (the flag cursor only). */
+    readonly flags: boolean;
+    /** The range band (+ the degenerate band line). */
+    readonly band: boolean;
+    /** The raw-pointer readout (the free crosshair). */
+    readonly pointer: boolean;
+    /** The formatted in-plot cursor time (`showTime` presets). */
+    readonly time: boolean;
+}
+/**
+ * A registered cursor as the container holds it: the {@link CursorSpec} plus
+ * the resolution inputs that must live on the registration rather than the
+ * spec — scope, gesture ownership, and the declared needs.
+ */
+export interface CursorEntry {
+    readonly spec: CursorSpec;
+    /** Mount scope: a row's key when mounted inside a `<ChartRow>` (the per-row
+     *  override), `null` when mounted at the container (the default for all rows). */
+    readonly rowKey: symbol | null;
+    /** Synthesized by the deprecation shim from the legacy string props. A scope
+     *  with any non-legacy (component-mounted) cursor drops its legacy entries —
+     *  mounting a component overrides the string prop during the window. */
+    readonly legacy: boolean;
+    /**
+     * The shim entry nobody asked for: the container's `'line'` **default**,
+     * synthesized with no `cursor` prop set. A mounted `<MultiSelector>`'s
+     * resting block preview (the brush band as the resting cursor) replaces
+     * only these — an explicitly chosen cursor, component-mounted or via the
+     * legacy string prop, still wins.
+     */
+    readonly implicit?: boolean;
+    /**
+     * Whether this cursor owns **snap and gesture** (RFC A2.5): at most one per
+     * scope (dev-warned otherwise), resolved to the hovered row's innermost
+     * mount. Render-only presets (line/point/inline/flag) stack freely.
+     */
+    readonly ownsGesture: boolean;
+    readonly wants: CursorWants;
+    /** The range cursor's bucket sequence (realized by the container into the
+     *  shared snap buckets — the `cursorSequence` successor). */
+    readonly sequence?: Sequence | BoundedSequence | undefined;
+    /** The range cursor's drag-release callback (the `onRegionSelect`
+     *  successor) — read by the brush recognizer (`resolveRangeDrag`), which
+     *  wraps it into the range-drag session. Only a `<RangeCursor>` sets it. */
+    readonly onDragRelease?: ((span: RangeSpan) => void) | undefined;
+    /** Whether the range drag is live — **resolved** at build time
+     *  (`enableDrag ?? !!onDragRelease`), so `false` here means frozen: the
+     *  gesture is off even though the callback is wired (§6's OFF switch). */
+    readonly enableDrag?: boolean | undefined;
+    /** The modifier the range drag needs (the `regionSelectModifier`
+     *  successor) — only enforced while pan is enabled. */
+    readonly dragModifier?: 'shift' | undefined;
+    /** The cursor's readout format (the `cursorFormat` successor) — resolved by
+     *  the container into the shared readout channel. */
+    readonly format?: CursorFormat | undefined;
+}
 /** A registered layer plus the axis id it draws against. */
 export interface LayerEntry {
     readonly layer: RowLayer;