@pond-ts/charts 0.48.1 → 0.50.0

package/dist/annotations.d.ts

@@ -84,6 +84,12 @@ export interface MarkerProps {
      *  `false` it's inert background context — drawn at the back (level 3) always,
      *  no hover, no select, no edit. */
     selectable?: boolean;
+    /** Theme **role** — recolours this mark from `theme.annotation.roles[role]`
+     *  (its `color`, optionally `fillOpacity`), keeping the shared depth ramp, so
+     *  several marks can differ (a green ATM baseline, a distinct marker) without
+     *  splitting the register. Omitted / unknown ⇒ the base annotation colour.
+     *  Colour is a theme concern — there is no per-mark colour prop. */
+    role?: string;
     /** Controlled hover (OR'd with pointer hover) — lets a legend row light the mark
      *  remotely. Pair with the container's `onHoverAnnotation` to sync both ways. */
     hovered?: boolean;
@@ -105,7 +111,7 @@ export interface MarkerProps {
     indicator?: boolean;
 }
 /** A vertical line at an x position (a time, a distance, a lap boundary). */
-export declare function Marker({ at, label, id, selected, selectable, hovered, editing, onChange, indicator, }: MarkerProps): import("react/jsx-runtime").JSX.Element;
+export declare function Marker({ at, label, id, selected, selectable, hovered, editing, onChange, indicator, role, }: MarkerProps): import("react/jsx-runtime").JSX.Element;
 export interface BaselineProps {
     /** y value in the linked axis's units. */
     value: number;
@@ -127,6 +133,12 @@ export interface BaselineProps {
     /** Whether the baseline responds to hover + selection (default `true`). When
      *  `false` it's inert background context — drawn at the back (level 3) always. */
     selectable?: boolean;
+    /** Theme **role** — recolours this mark from `theme.annotation.roles[role]`
+     *  (its `color`, optionally `fillOpacity`), keeping the shared depth ramp, so
+     *  several marks can differ (a green ATM baseline, a distinct marker) without
+     *  splitting the register. Omitted / unknown ⇒ the base annotation colour.
+     *  Colour is a theme concern — there is no per-mark colour prop. */
+    role?: string;
     /** Controlled hover (OR'd with pointer hover) — lets a legend row light the mark
      *  remotely. Pair with the container's `onHoverAnnotation` to sync both ways. */
     hovered?: boolean;
@@ -148,7 +160,7 @@ export interface BaselineProps {
 }
 /** A horizontal line at a y value, scaled against one row axis (RTC's `Baseline`).
  *  Its label anchors at the left, at the line's height. */
-export declare function Baseline({ value, axis, label, labelSide, labelPosition, id, selected, selectable, hovered, editing, onChange, indicator, }: BaselineProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function Baseline({ value, axis, label, labelSide, labelPosition, id, selected, selectable, hovered, editing, onChange, indicator, role, }: BaselineProps): import("react/jsx-runtime").JSX.Element | null;
 export interface RegionProps {
     /** Start x in axis units (time or value). */
     from: number;
@@ -170,6 +182,12 @@ export interface RegionProps {
      *  `false` it's inert background context — drawn at the back (level 3) always,
      *  and the double-click hit-test skips it. */
     selectable?: boolean;
+    /** Theme **role** — recolours this mark from `theme.annotation.roles[role]`
+     *  (its `color`, optionally `fillOpacity`), keeping the shared depth ramp, so
+     *  several marks can differ (a green ATM band, a distinct marker) without
+     *  splitting the register. Omitted / unknown ⇒ the base annotation colour.
+     *  Colour is a theme concern — there is no per-mark colour prop. */
+    role?: string;
     /** Controlled hover (OR'd with pointer hover) — lets a legend row light the mark
      *  remotely. Pair with the container's `onHoverAnnotation` to sync both ways. */
     hovered?: boolean;
@@ -192,6 +210,6 @@ export interface RegionProps {
 }
 /** A shaded span over an x range — a lap, a zone, a selected interval. Its label
  *  flies as a flag off the left edge. */
-export declare function Region({ from, to, label, id, selected, selectable, hovered, editing, onChange, edges, }: RegionProps): import("react/jsx-runtime").JSX.Element;
+export declare function Region({ from, to, label, id, selected, selectable, hovered, editing, onChange, edges, role, }: RegionProps): import("react/jsx-runtime").JSX.Element;
 export {};
 //# sourceMappingURL=annotations.d.ts.map

package/dist/annotations.js

@@ -97,8 +97,16 @@ const overlayStyle = {
     left: 0,
     pointerEvents: 'none',
 };
-/** Read the container + row frames an annotation needs, or throw if misplaced. */
-function useAnnotationFrame(name) {
+/**
+ * Read the container + row frames an annotation needs (throw if misplaced), and
+ * resolve the mark's annotation style for its optional `role`. A `role` recolors
+ * *this* mark from the theme's `annotation.roles[role]` map (`color`, and
+ * optionally `fillOpacity`) while keeping the shared depth ramp — so a smile can
+ * place a green ATM baseline, a neutral vertical, and a distinct marker at once
+ * without splitting the whole register. An unknown / unset role falls back to
+ * the base `annotation` register (`roles[role] ?? annotation`).
+ */
+function useAnnotationFrame(name, role) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error(`<${name}> must be rendered inside a <ChartContainer>`);
@@ -107,7 +115,17 @@ function useAnnotationFrame(name) {
     if (row === null) {
         throw new Error(`<${name}> must be rendered inside a <ChartRow>`);
     }
-    const ann = container.theme.annotation ?? DEFAULT_ANNOTATION;
+    const base = container.theme.annotation ?? DEFAULT_ANNOTATION;
+    const roleStyle = role !== undefined ? base.roles?.[role] : undefined;
+    // The role overrides only colour (+ optional fill); depth stays the shared
+    // ramp, so selection / hover / edit levels read identically per role.
+    const ann = roleStyle
+        ? {
+            ...base,
+            color: roleStyle.color,
+            fillOpacity: roleStyle.fillOpacity ?? base.fillOpacity,
+        }
+        : base;
     return { container, row, ann };
 }
 /** Register this annotation with the container (so it can draw the mark's guide on
@@ -450,8 +468,8 @@ function DragArea({ x, y, w, h, cursor, editable, onHover, onSelect, onEdit, onD
         } }));
 }
 /** A vertical line at an x position (a time, a distance, a lap boundary). */
-export function Marker({ at, label, id, selected = false, selectable = true, hovered, editing = false, onChange, indicator = false, }) {
-    const { container, row, ann } = useAnnotationFrame('Marker');
+export function Marker({ at, label, id, selected = false, selectable = true, hovered, editing = false, onChange, indicator = false, role, }) {
+    const { container, row, ann } = useAnnotationFrame('Marker', role);
     const selfKey = useSlotKey();
     const { hovering, reportHover } = useAnnotationHover(container, id, hovered);
     // Draggable right now: global edit mode OR this mark's single-edit flag, and no
@@ -460,8 +478,11 @@ export function Marker({ at, label, id, selected = false, selectable = true, hov
         container.creating === null &&
         onChange !== undefined;
     const xs = useMemo(() => [at], [at]);
-    // `label === false` (or '') ⇒ no chip; omitted ⇒ auto-label off the x formatter.
-    const text = label === false ? '' : (label ?? container.formatTime(at));
+    // `label === false` (or '') ⇒ no chip; omitted ⇒ auto-label off the readout
+    // channel (else the x label formatter).
+    const text = label === false
+        ? ''
+        : (label ?? (container.formatReadout ?? container.formatTime)(at));
     useRegisterAnnotation(container, selfKey, id, row.rowKey, 'marker', xs, selected, selectable, editing, text, indicator);
     // No select/edit while a create tool is armed — the chart is in draw mode then.
     const select = id !== undefined && container.creating === null
@@ -491,8 +512,8 @@ export function Marker({ at, label, id, selected = false, selectable = true, hov
 }
 /** A horizontal line at a y value, scaled against one row axis (RTC's `Baseline`).
  *  Its label anchors at the left, at the line's height. */
-export function Baseline({ value, axis, label, labelSide = 'left', labelPosition = 'center', id, selected = false, selectable = true, hovered, editing = false, onChange, indicator = false, }) {
-    const { container, row, ann } = useAnnotationFrame('Baseline');
+export function Baseline({ value, axis, label, labelSide = 'left', labelPosition = 'center', id, selected = false, selectable = true, hovered, editing = false, onChange, indicator = false, role, }) {
+    const { container, row, ann } = useAnnotationFrame('Baseline', role);
     const selfKey = useSlotKey();
     const { hovering, reportHover } = useAnnotationHover(container, id, hovered);
     // Draggable right now: global edit mode OR this mark's single-edit flag, and no
@@ -551,8 +572,8 @@ export function Baseline({ value, axis, label, labelSide = 'left', labelPosition
 }
 /** A shaded span over an x range — a lap, a zone, a selected interval. Its label
  *  flies as a flag off the left edge. */
-export function Region({ from, to, label, id, selected = false, selectable = true, hovered, editing = false, onChange, edges = true, }) {
-    const { container, row, ann } = useAnnotationFrame('Region');
+export function Region({ from, to, label, id, selected = false, selectable = true, hovered, editing = false, onChange, edges = true, role, }) {
+    const { container, row, ann } = useAnnotationFrame('Region', role);
     const selfKey = useSlotKey();
     const { hovering, reportHover } = useAnnotationHover(container, id, hovered);
     // Draggable right now: global edit mode OR this mark's single-edit flag, and no
@@ -561,10 +582,10 @@ export function Region({ from, to, label, id, selected = false, selectable = tru
         container.creating === null &&
         onChange !== undefined;
     const xs = useMemo(() => [from, to], [from, to]);
-    // `label === false` (or '') ⇒ no chip; omitted ⇒ auto-label the `from–to` span.
-    const text = label === false
-        ? ''
-        : (label ?? `${container.formatTime(from)}–${container.formatTime(to)}`);
+    // `label === false` (or '') ⇒ no chip; omitted ⇒ auto-label the `from–to`
+    // span off the readout channel (else the x label formatter).
+    const fmtX = container.formatReadout ?? container.formatTime;
+    const text = label === false ? '' : (label ?? `${fmtX(from)}–${fmtX(to)}`);
     useRegisterAnnotation(container, selfKey, id, row.rowKey, 'region', xs, selected, selectable, editing, text, false);
     // No select/edit while a create tool is armed — the chart is in draw mode then.
     const select = id !== undefined && container.creating === null

package/dist/area.d.ts

@@ -3,6 +3,7 @@ import type { ChartSeries } from './data.js';
 import type { Scale } from './line.js';
 import type { AreaStyle } from './theme.js';
 import { type GapMode } from './gaps.js';
+import { type DecimateOption } from './decimate.js';
 /**
  * The `[min, max]` vertical extent an area occupies — the finite values of
  * `cs.y` widened to include `baseline`, since the fill spans from each value to
@@ -50,5 +51,5 @@ export declare function areaExtent(cs: ChartSeries, baseline: number | undefined
  * bracketed by `save`/`restore` so they don't leak into later layers. Gap edges
  * are collected by one O(N) walk ({@link collectGapEdges}).
  */
-export declare function drawArea(ctx: CanvasRenderingContext2D, cs: ChartSeries, xScale: Scale, yScale: Scale, style: AreaStyle, baselineValue: number, curve?: CurveFactory, gaps?: GapMode, gapConnectorOpacity?: number): void;
+export declare function drawArea(ctx: CanvasRenderingContext2D, cs: ChartSeries, xScale: Scale, yScale: Scale, style: AreaStyle, baselineValue: number, curve?: CurveFactory, gaps?: GapMode, gapConnectorOpacity?: number, decimate?: DecimateOption): void;
 //# sourceMappingURL=area.d.ts.map

package/dist/area.js

@@ -1,5 +1,7 @@
 import { area as d3area, curveLinear } from 'd3-shape';
 import { bridgeGaps, collectGapEdges, drawGapBridges, drawGapFades, drawGapSteps, withAlpha, DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
+import { cullChartSeries } from './culling.js';
+import { decimateM4 } from './decimate.js';
 /**
  * The `[min, max]` vertical extent an area occupies — the finite values of
  * `cs.y` widened to include `baseline`, since the fill spans from each value to
@@ -70,8 +72,31 @@ export function areaExtent(cs, baseline) {
  * bracketed by `save`/`restore` so they don't leak into later layers. Gap edges
  * are collected by one O(N) walk ({@link collectGapEdges}).
  */
-export function drawArea(ctx, cs, xScale, yScale, style, baselineValue, curve = curveLinear, gaps = DEFAULT_GAP_MODE, gapConnectorOpacity = DEFAULT_GAP_CONNECTOR_OPACITY) {
+export function drawArea(ctx, cs, xScale, yScale, style, baselineValue, curve = curveLinear, gaps = DEFAULT_GAP_MODE, gapConnectorOpacity = DEFAULT_GAP_CONNECTOR_OPACITY, decimate = true) {
     const baselinePx = yScale(baselineValue);
+    // The fill gradient's vertical extent is computed from the **full** series (a
+    // vertical, position-anchored gradient spanning the data's whole pixel extent)
+    // so viewport culling stays behavior-neutral: the culled path below paints the
+    // exact same visible pixels under the same gradient. This is a cheap O(N)
+    // min/max scan; the expensive per-point path work (fill + outline) culls. (Cull
+    // the region too and the shade would drift under pan as off-screen extrema
+    // enter/leave — a visible change culling must not make.)
+    const fullYs = gaps === 'none' ? bridgeGaps(cs.y, cs.length) : cs.y;
+    const fill = buildGradient(ctx, fullYs, cs.length, yScale, baselinePx, style);
+    // Viewport culling (Phase 2): the path, outline, and gap bridges walk the
+    // visible slice (+1 entry/exit point) only. A no-op — the same `cs` back — when
+    // fully in view or `xScale` has no domain (a test stub), keeping that hot path
+    // byte-identical.
+    cs = cullChartSeries(cs, xScale);
+    // M4 decimation (Phase 3): the outline is a line, so the same {@link decimateM4}
+    // pre-pass shrinks the fill + outline + gap-bridge work to O(plot width) once
+    // dense — with the §2.2 gap-edge union so every gap mode composes. The gradient
+    // above is over the FULL series, so the decimated fill paints identical pixels
+    // under it. Gated off a smoothing `curve`; a no-op on a sparse slice / test scale.
+    if (decimate !== false && curve === curveLinear) {
+        const k = typeof decimate === 'object' ? decimate.threshold : undefined;
+        cs = decimateM4(cs, xScale, ctx, k);
+    }
     // `none` interpolates interior gaps so the fill + outline bridge them; every
     // other mode keeps NaN so d3 breaks both (the inferred line bridge, if any, is
     // a separate overlay pass below).
@@ -86,9 +111,9 @@ export function drawArea(ctx, cs, xScale, yScale, style, baselineValue, curve =
     ctx.save();
     // The fill: a vertical gradient anchored at the baseline pixel, opaque at the
     // line and transparent at the baseline (see buildGradient — handles both the
-    // one-sided elevation form and the two-sided above/below form). The gradient
-    // spans the drawn region; `ys` (gap-bridged for `none`) is what's drawn.
-    ctx.fillStyle = buildGradient(ctx, ys, cs.length, yScale, baselinePx, style);
+    // one-sided elevation form and the two-sided above/below form). Spans the full
+    // data region (above), so the culled `ys` paints identical pixels under it.
+    ctx.fillStyle = fill;
     ctx.globalAlpha = style.fillOpacity;
     ctx.beginPath();
     gen(ys);

package/dist/band.d.ts

@@ -2,6 +2,7 @@ import { type CurveFactory } from 'd3-shape';
 import type { BandSeries } from './data.js';
 import type { Scale } from './line.js';
 import type { BandStyle } from './theme.js';
+import { type DecimateOption } from './decimate.js';
 /**
  * The `[min, max]` vertical extent of the **drawn** band — the lowest `lower`
  * and highest `upper` over samples where both edges are finite — or `null` if
@@ -27,5 +28,5 @@ export declare function bandExtent(band: BandSeries): [number, number] | null;
  * index, so there's no per-point object allocation. `globalAlpha` carries the
  * opacity and is restored so it doesn't leak into later layers.
  */
-export declare function drawBand(ctx: CanvasRenderingContext2D, band: BandSeries, xScale: Scale, yScale: Scale, style: BandStyle, curve?: CurveFactory): void;
+export declare function drawBand(ctx: CanvasRenderingContext2D, band: BandSeries, xScale: Scale, yScale: Scale, style: BandStyle, curve?: CurveFactory, decimate?: DecimateOption): void;
 //# sourceMappingURL=band.d.ts.map

package/dist/band.js

@@ -1,4 +1,6 @@
 import { area as d3area, curveLinear } from 'd3-shape';
+import { cullBandSeries } from './culling.js';
+import { decimateBand } from './decimate.js';
 /**
  * The `[min, max]` vertical extent of the **drawn** band — the lowest `lower`
  * and highest `upper` over samples where both edges are finite — or `null` if
@@ -38,7 +40,22 @@ export function bandExtent(band) {
  * index, so there's no per-point object allocation. `globalAlpha` carries the
  * opacity and is restored so it doesn't leak into later layers.
  */
-export function drawBand(ctx, band, xScale, yScale, style, curve = curveLinear) {
+export function drawBand(ctx, band, xScale, yScale, style, curve = curveLinear, decimate = true) {
+    // Viewport culling (Phase 2): clip the envelope to the visible slice (+1 each
+    // side) before filling, so a pan strokes O(visible). The solid fill has no
+    // cross-point state, so a zero-copy subarray view is exact; a no-op (same
+    // object) when fully in view or the scale has no domain (a test stub).
+    band = cullBandSeries(band, xScale);
+    // M4 band decimation (Phase 3): once the culled envelope is denser than ~2
+    // samples per device pixel, replace it with the per-column min-lower / max-upper
+    // envelope ({@link decimateBand}) — O(plot width) points that cover the same
+    // pixels. Gated off a smoothing `curve` (which would distort the per-column
+    // envelope) and `decimate === false`; `decimateBand` itself no-ops on a sparse
+    // envelope or a domainless test scale, so this stays byte-identical there.
+    if (decimate !== false && curve === curveLinear) {
+        const k = typeof decimate === 'object' ? decimate.threshold : undefined;
+        band = decimateBand(band, xScale, ctx, k);
+    }
     const gen = d3area()
         .defined((_, i) => Number.isFinite(band.lower[i]) && Number.isFinite(band.upper[i]))
         .x((_, i) => xScale(band.x[i]))

package/dist/bars.js

@@ -1,4 +1,5 @@
 import { barSpanPx } from './range.js';
+import { visibleSpanRange } from './culling.js';
 /**
  * The `[min, max]` vertical extent the bars occupy — the finite values of `cs.y`
  * **widened to include `0`**, since a bar spans from its value to the baseline
@@ -96,7 +97,13 @@ export function barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx) {
 export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, seriesId, selection, hovered) {
     ctx.save();
     ctx.globalAlpha = style.opacity;
-    for (let i = 0; i < cs.length; i += 1) {
+    // Viewport culling (Phase 2): draw only the bars whose span overlaps the
+    // visible x-window (+1 each side). The loop keeps the original index `i`, so
+    // the `begin[i]` selection/hover match stays correct; full range when `xScale`
+    // has no domain (a test stub). A selected/hovered bar off-screen isn't drawn
+    // (its highlight would be off-screen anyway).
+    const [vStart, vEnd] = visibleSpanRange(cs.begin, cs.end, cs.length, xScale);
+    for (let i = vStart; i < vEnd; i += 1) {
         const rect = barRect(cs, i, xScale, yScale, baseline, gapPx, style.minWidth);
         if (rect === null)
             continue;

package/dist/box.d.ts

@@ -1,6 +1,7 @@
 import type { BoxSeries } from './data.js';
 import type { Scale } from './line.js';
 import type { BoxStyle } from './theme.js';
+import { type DecimateOption } from './decimate.js';
 /**
  * The `[min, max]` vertical extent of the **drawn** boxes — the lowest `lower`
  * whisker and highest `upper` whisker over the keys {@link isFiniteBox} draws
@@ -24,6 +25,19 @@ export declare function boxExtent(box: BoxSeries): [number, number] | null;
  * the caller drops it on the finiteness check. O(N) over the boxes (view-scale).
  */
 export declare function boxIndexAtTime(box: BoxSeries, time: number): number;
+/**
+ * Hit-test plot-pixel `(px, py)` against `box`'s marks — the **first** box whose
+ * bounding rect (its x-slot × its `[upper, lower]` whisker extent) contains the
+ * point, or `null`. The x-span is {@link barSpanPx} (same `gapPx`/`minWidthPx`/
+ * `offsetPx` as {@link drawBox}), so the hit rect matches the drawn mark; the y
+ * extent is the full whisker reach, so a click anywhere on the box (body or
+ * whisker) selects it — a range-only bid→ask segment included. The returned
+ * tuple is `[index, begin, value]` (`begin` = the box's `x`, `value` = its
+ * `upper` — provenance) for the chart to assemble a `SelectInfo`; keeping this
+ * theme-free mirrors {@link barAt} and stays unit-testable without a
+ * `ChartTheme`. A gap box (some drawn quantile non-finite) is skipped. O(N).
+ */
+export declare function boxAt(box: BoxSeries, px: number, py: number, xScale: Scale, yScale: Scale, gapPx: number, minWidthPx: number, offsetPx?: number): [index: number, begin: number, value: number] | null;
 /**
  * How a box renders its spread (pjm17971): **`whisker`** (today's thin stems +
  * end-caps), **`solid`** (the candlestick look — a light outer bar over the full
@@ -64,7 +78,7 @@ export type BoxShape = 'whisker' | 'solid' | 'none';
  * O(N) over the keys, a fixed number of path ops each — no per-key allocation
  * beyond the `barSpanPx` tuple.
  */
-export declare function drawBox(ctx: CanvasRenderingContext2D, box: BoxSeries, xScale: Scale, yScale: Scale, style: BoxStyle, gapPx?: number, minWidthPx?: number, shape?: BoxShape, showMedian?: boolean, offsetPx?: number, capWidthPx?: number): void;
+export declare function drawBox(ctx: CanvasRenderingContext2D, box: BoxSeries, xScale: Scale, yScale: Scale, style: BoxStyle, gapPx?: number, minWidthPx?: number, shape?: BoxShape, showMedian?: boolean, offsetPx?: number, capWidthPx?: number, selectedKey?: number | null, hoveredKey?: number | null, decimate?: DecimateOption): void;
 /**
  * This key is drawable — the quantiles it actually carries are all finite at `i`.
  * `lower`/`upper` (the whisker reach) are always required; `q1`/`q3` only when the

package/dist/box.js

@@ -1,4 +1,6 @@
 import { barSpanPx } from './range.js';
+import { visibleSpanRange } from './culling.js';
+import { decimateBox } from './decimate.js';
 /** Fraction of the box width the whisker end-caps span (centred on the stem). */
 const WHISKER_CAP_FRACTION = 0.5;
 /**
@@ -44,6 +46,36 @@ export function boxIndexAtTime(box, time) {
     }
     return -1;
 }
+/**
+ * Hit-test plot-pixel `(px, py)` against `box`'s marks — the **first** box whose
+ * bounding rect (its x-slot × its `[upper, lower]` whisker extent) contains the
+ * point, or `null`. The x-span is {@link barSpanPx} (same `gapPx`/`minWidthPx`/
+ * `offsetPx` as {@link drawBox}), so the hit rect matches the drawn mark; the y
+ * extent is the full whisker reach, so a click anywhere on the box (body or
+ * whisker) selects it — a range-only bid→ask segment included. The returned
+ * tuple is `[index, begin, value]` (`begin` = the box's `x`, `value` = its
+ * `upper` — provenance) for the chart to assemble a `SelectInfo`; keeping this
+ * theme-free mirrors {@link barAt} and stays unit-testable without a
+ * `ChartTheme`. A gap box (some drawn quantile non-finite) is skipped. O(N).
+ */
+export function boxAt(box, px, py, xScale, yScale, gapPx, minWidthPx, offsetPx = 0) {
+    for (let i = 0; i < box.length; i += 1) {
+        if (!isFiniteBox(box, i))
+            continue;
+        const [span0, span1] = barSpanPx(box.x[i], box.xEnd[i], xScale, gapPx, minWidthPx);
+        const x0 = span0 + offsetPx;
+        const x1 = span1 + offsetPx;
+        const yUpper = yScale(box.upper[i]);
+        const yLower = yScale(box.lower[i]);
+        // upper is the higher value ⇒ the smaller pixel y; order defensively.
+        const yTop = Math.min(yUpper, yLower);
+        const yBottom = Math.max(yUpper, yLower);
+        if (px >= x0 && px <= x1 && py >= yTop && py <= yBottom) {
+            return [i, box.x[i], box.upper[i]];
+        }
+    }
+    return null;
+}
 /**
  * Draw a discrete box per key of `box`, mapping data→pixels through
  * `xScale`/`yScale`. The bar-chart analog of {@link drawBand}: each key gets its
@@ -76,12 +108,36 @@ export function boxIndexAtTime(box, time) {
  * O(N) over the keys, a fixed number of path ops each — no per-key allocation
  * beyond the `barSpanPx` tuple.
  */
-export function drawBox(ctx, box, xScale, yScale, style, gapPx = 0, minWidthPx = 1, shape = 'whisker', showMedian = true, offsetPx = 0, capWidthPx) {
+export function drawBox(ctx, box, xScale, yScale, style, gapPx = 0, minWidthPx = 1, shape = 'whisker', showMedian = true, offsetPx = 0, capWidthPx, 
+// Selection / hover highlight, keyed by the box's `x` (its `begin`, matched to
+// the container selection's `key` by the caller). `null` ⇒ none. A selected
+// box gets a full-strength bounding outline; a hovered one a fainter one —
+// the box analog of the bar highlight, drawn without a new theme token.
+selectedKey = null, hoveredKey = null, decimate = true) {
+    // Viewport cull first (Phase 2): the [vStart, vEnd) boxes whose span overlaps
+    // the window (+1 each side). Full range when `xScale` has no domain (a stub);
+    // `offsetPx` is a small pixel nudge the ±1 margin absorbs.
+    let [vStart, vEnd] = visibleSpanRange(box.x, box.xEnd, box.length, xScale);
+    // M4 box decimation (Phase 5): once the *visible* boxes are denser than ~2 per
+    // device pixel, replace them with per-column **aggregate boxes** ({@link
+    // decimateBox}). Gate on the visible count, NOT `box.length`: a box's width is
+    // its slot, so decimating when only a handful are on screen (deep zoom) would
+    // re-slot each to a 1px sliver. `decimateBox` no-ops (returns the same object)
+    // below the visible-density threshold or on a domainless scale, leaving the
+    // loop-bound cull above. A selection/hover highlight keyed by the source box's
+    // `x` won't match an aggregate column edge — but per-box highlight is
+    // meaningless at decimation density, and hit-testing still reads the source.
+    const decimated = decimate !== false ? decimateBox(box, xScale, ctx, 2, vEnd - vStart) : box;
+    if (decimated !== box) {
+        box = decimated; // aggregate boxes are already the visible set
+        vStart = 0;
+        vEnd = box.length;
+    }
     // A range-only box (bid→ask segment) has no body / median; the whisker (or the
     // solid bar) runs the full lower→upper. Flags default true (a full box).
     const hasBox = box.hasBox !== false;
     const drawMedian = showMedian && box.hasMedian !== false;
-    for (let i = 0; i < box.length; i += 1) {
+    for (let i = vStart; i < vEnd; i += 1) {
         if (!isFiniteBox(box, i))
             continue;
         const [span0, span1] = barSpanPx(box.x[i], box.xEnd[i], xScale, gapPx, minWidthPx);
@@ -159,6 +215,19 @@ export function drawBox(ctx, box, xScale, yScale, style, gapPx = 0, minWidthPx =
             ctx.lineTo(x1, yMedian);
             ctx.stroke();
         }
+        // Selection / hover: outline the whole mark (x-slot × whisker extent) so a
+        // click / pointer-over reads back on the canvas. Selected = full strength;
+        // hovered = fainter. Bracketed so alpha/width don't leak to the next box.
+        const key = box.x[i];
+        if (key === selectedKey || key === hoveredKey) {
+            ctx.save();
+            ctx.strokeStyle = style.stroke;
+            ctx.lineWidth =
+                key === selectedKey ? style.strokeWidth + 1 : style.strokeWidth;
+            ctx.globalAlpha = key === selectedKey ? 1 : 0.5;
+            ctx.strokeRect(x0, yUpper, x1 - x0, yLower - yUpper);
+            ctx.restore();
+        }
     }
 }
 /**

package/dist/context.d.ts

@@ -1,6 +1,7 @@
 import type { ScaleLinear, ScaleTime } from 'd3-scale';
 import type { ChartTheme } from './theme.js';
 import type { AxisFormat } from './format.js';
+import type { LegendItemSpec } from './swatch.js';
 import type { Interval } from 'pond-ts';
 import type { TradingTimeScale, DiscontinuityProvider } from './tradingTimeScale.js';
 import type { ScaleBand } from './bandScale.js';
@@ -139,7 +140,8 @@ export interface ContainerFrame {
      *  a row may override it via its own `cursor`. */
     readonly cursor: CursorMode;
     /** Show the cursor's time atop the in-chart readout (when a row's cursor draws
-     *  one), formatted by {@link formatTime} to match the time axis. */
+     *  one), formatted by {@link formatReadout} (else {@link formatTime}, matching
+     *  the time axis). */
     readonly cursorTime: boolean;
     /**
      * Whether the chart is in **annotation-edit mode** — suppresses the data cursor
@@ -149,8 +151,18 @@ export interface ContainerFrame {
      */
     readonly editAnnotations: boolean;
     /** Format an epoch-ms instant the same way the time axis labels its ticks —
-     *  shared by `<TimeAxis>` and the cursor-time readout. */
+     *  shared by `<TimeAxis>` and (absent {@link formatReadout}) the cursor-time
+     *  readout. Shaped by the container `timeFormat` only, never `cursorFormat`. */
     readonly formatTime: (epochMs: number) => string;
+    /**
+     * The **readout** channel — defined only when the container's `cursorFormat`
+     * is set (time or value axis; a category axis reads names). Readout
+     * consumers — the crosshair x pill and in-plot cursor time, marker axis
+     * indicators, annotation auto-labels — read `formatReadout ?? <their label
+     * formatter>`, so the readout can be shaped (or made more precise than the
+     * tick labels) without moving them.
+     */
+    readonly formatReadout?: ((value: number) => string) | undefined;
     /** Whether an explicit container `timeFormat` shaped {@link formatTime}. The
      *  x axis suppresses its boundary (second) label row when it's set — a
      *  custom format owns the whole label, so the ladder mustn't second-line it. */
@@ -181,6 +193,25 @@ export interface ContainerFrame {
      */
     registerSelectable(key: symbol): void;
     unregisterSelectable(key: symbol): void;
+    /**
+     * Register this layer's **legend row** — its display label + resolved
+     * {@link SwatchSpec} (and selection `id` when it has one) — keyed by the
+     * layer's per-instance slot; unregister on unmount (see
+     * {@link useLegendItems}). `<Legend>` renders this registry in
+     * {@link rowOrder}-then-declaration order, deduped by `id ?? label`; a layer
+     * that opted out (`legend={false}`) simply never registers.
+     */
+    registerLegendItem(key: symbol, item: LegendItemSpec): void;
+    unregisterLegendItem(key: symbol): void;
+    /** The registered legend rows, keyed by layer slot (see
+     *  {@link registerLegendItem}). */
+    readonly legendItems: ReadonlyMap<symbol, LegendItemSpec>;
+    /**
+     * The chart rows' keys in **display (top-to-bottom) order** — mount order,
+     * exactly the ordering {@link firstRowKey} is head of. `<Legend>` sorts its
+     * rows by this so a two-row chart lists the top row's series first.
+     */
+    readonly rowOrder: readonly symbol[];
     /**
      * Shared x→pixel scale, range `[0, plotWidth]`. A d3 `scaleTime` (default) so
      * ticks land on wall-clock boundaries, or a `scaleLinear` when the data is
@@ -448,7 +479,10 @@ export interface TrackerSample {
     readonly value: number;
     /** Dot / label colour — the layer's resolved style colour. */
     readonly color: string;
-    /** Series identity (`as` ?? column) — labels the value in a readout. */
+    /** Labels the value in a readout: the series identity (`as` ?? column) for a
+     *  single-value mark; a multi-value mark (band edges, box quantiles, an OHLC
+     *  quote) emits `"<as> <role>"` composites (`iv lower`, `SPY high`) when its
+     *  `as` is set, else the raw column / role word. */
     readonly label: string;
 }
 /** One line of a {@link CursorFlag} — a labelled, coloured value. */
@@ -503,9 +537,13 @@ export interface SelectInfo {
     /**
      * The clicked sample's key as epoch ms (its event's `begin`) — click
      * **provenance**, informational. NOT the selection identity (that is {@link id}).
+     * A **series-scoped** selection with no sample under it (a `<Legend>` row's
+     * default hover/select) carries `NaN` here and in {@link value} — check
+     * `Number.isFinite` before treating them as a sample.
      */
     readonly key: number;
-    /** The clicked sample's value (the plotted column) — provenance. */
+    /** The clicked sample's value (the plotted column) — provenance. `NaN` for a
+     *  series-scoped selection (see {@link key}). */
     readonly value: number;
     /** The mark's resolved style colour. */
     readonly color: string;
@@ -581,6 +619,10 @@ export interface AxisSpec {
     /** Explicit tick values (from `<YAxis ticks>`), driving BOTH the axis labels
      *  and the row's gridlines so they align; `undefined` auto-picks from the scale. */
     readonly tickValues: readonly number[] | undefined;
+    /** Explicit auto-tick **count** (from `<YAxis tickCount>`) — a `ticks(count)`
+     *  target; `undefined` derives the count from the row height (see
+     *  {@link resolveYTickCount}). Ignored when {@link tickValues} is set. */
+    readonly tickCount: number | undefined;
     /**
      * Declaration position among the row's children, injected by `ChartRow`. The
      * row sorts axes by this, so the **first declared** axis is the default
@@ -606,6 +648,11 @@ export interface RowFrame {
      *  that set `<YAxis ticks>` — so `Layers` draws gridlines at the same positions
      *  the axis labels. Absent id ⇒ that axis auto-picks. */
     readonly tickValues: ReadonlyMap<string, readonly number[]>;
+    /** Resolved auto-tick **count** per axis id — the explicit `<YAxis tickCount>`
+     *  or the row-height-derived default ({@link resolveYTickCount}). The single
+     *  source both the `<YAxis>` labels and the `Layers` gridlines read, so a
+     *  label and its gridline stay on the same `ticks(count)`. */
+    readonly tickCounts: ReadonlyMap<string, number>;
     /** The side each axis sits on, keyed by id — so an axis-edge overlay (the
      *  crosshair value pills) hugs the correct gutter. */
     readonly axisSides: ReadonlyMap<string, 'left' | 'right'>;