@pond-ts/charts 0.48.1 → 0.50.0

package/dist/ohlc.js

@@ -1,4 +1,6 @@
 import { barSpanPx } from './range.js';
+import { visibleSpanRange } from './culling.js';
+import { decimateOhlc } from './decimate.js';
 /** Default body width as a fraction of the candle slot when the style omits one. */
 const DEFAULT_BODY_WIDTH = 0.8;
 /** Minimum body height in px so a doji (open === close) still shows a mark. */
@@ -88,9 +90,28 @@ export function resolveCandleStyle(style, open, close, colorBy) {
  * O(N) over the keys, a fixed number of path ops each — no per-key allocation
  * beyond the `barSpanPx` tuple.
  */
-export function drawCandles(ctx, ohlc, xScale, yScale, style, variant = 'candle', colorBy = 'direction', gapPx = 0, minWidthPx = 1) {
+export function drawCandles(ctx, ohlc, xScale, yScale, style, variant = 'candle', colorBy = 'direction', gapPx = 0, minWidthPx = 1, decimate = true) {
     const bodyFraction = style.bodyWidth ?? DEFAULT_BODY_WIDTH;
-    for (let i = 0; i < ohlc.length; i += 1) {
+    // Viewport cull first (Phase 2): the [vStart, vEnd) candles whose span overlaps
+    // the window (+1 each side). Full range when `xScale` has no domain (a stub).
+    let [vStart, vEnd] = visibleSpanRange(ohlc.x, ohlc.xEnd, ohlc.length, xScale);
+    // M4 candle decimation (Phase 5): once the *visible* candles are denser than ~2
+    // per device pixel, replace them with per-column **aggregate candles**
+    // (open=first, high=max, low=min, close=last — a coarser-timeframe candle;
+    // {@link decimateOhlc}). Gate on the visible count, NOT `ohlc.length`: a candle's
+    // width is its slot, so decimating when only a handful are on screen (deep zoom
+    // into a large series) would re-slot each to a 1px sliver. `decimateOhlc` no-ops
+    // (returns the same object) below the visible-density threshold or on a
+    // domainless scale, leaving the loop-bound cull above.
+    const decimated = decimate !== false
+        ? decimateOhlc(ohlc, xScale, ctx, 2, vEnd - vStart)
+        : ohlc;
+    if (decimated !== ohlc) {
+        ohlc = decimated; // aggregate candles are already the visible set
+        vStart = 0;
+        vEnd = ohlc.length;
+    }
+    for (let i = vStart; i < vEnd; i += 1) {
         if (!isFiniteOhlc(ohlc, i))
             continue;
         const open = ohlc.open[i];

package/dist/scatter.js

@@ -1,3 +1,4 @@
+import { visiblePointRange } from './culling.js';
 /**
  * Scatter geometry + the canvas draw — pure, like {@link drawLine} /
  * {@link drawBand}, so the recording-mock tests assert the op sequence and the
@@ -5,11 +6,13 @@
  *
  * A scatter plots one mark per finite point at `(xScale(x), yScale(y))`, sized
  * + coloured by the resolved {@link ResolvedEncoding} (data-driven radius /
- * colour) over the style's base. All three of `drawScatter`, `scatterExtent`,
- * and {@link hitTestScatter} are **O(N)** in the point count (a single pass; no
- * spatial index — a chart row holds far fewer points than a dense line, and a
- * click happens at human cadence). If a scatter ever needs 100k+ points this is
- * the place to add a coarse x-bucket index; today the linear walk is the right
+ * colour) over the style's base. `drawScatter` culls to the visible x-window
+ * first (Phase 2 — see the draw loop), so a pan/zoom repaint is O(visible), not
+ * O(N); `scatterExtent` and {@link hitTestScatter} still walk the full series
+ * (**O(N)** — the y-extent must see every point and a click happens at human
+ * cadence). No spatial index — a chart row holds far fewer points than a dense
+ * line. If a scatter ever needs 100k+ points *and* a hot hit-test this is the
+ * place to add a coarse x-bucket index; today the linear walk is the right
  * tradeoff.
  */
 /** A non-finite y (the gap signal) means "no point here" — skip it everywhere. */
@@ -123,7 +126,39 @@ export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, lab
     let selPy = 0;
     let selR = 0;
     let selHit = false;
-    for (let i = 0; i < cs.length; i += 1) {
+    // Viewport culling (Phase 2): draw only the marks in the visible x-window
+    // (+1 each side). The loop keeps the **original** index `i`, so the index-keyed
+    // accessors (`colorAt`/`radiusAt`/`keyAt`/`labelAt`) and the selection match
+    // stay correct — a subarray would renumber them. Full range when `xScale` has
+    // no domain (a test stub). A selected point outside the window isn't drawn (its
+    // ring would be off-screen anyway).
+    //
+    // Radius-aware pad (the follow-up #499 flagged): the ±1 margin is in *index*
+    // space, but a mark's **radius** can reach the plot from further out — a dense
+    // scatter of visible-size bubbles would otherwise drop an edge bubble whose
+    // centre is >1 sample off-screen while its disc overlaps the edge (a flicker
+    // under pan). So we make two window calls: pass 1 is the plain window; scan it
+    // for the max drawn radius; pass 2 re-expands by that radius plus `|offsetPx|`
+    // (the pixel nudge shifts marks in px space, so it widens the reach too). The
+    // common small-radius frame re-expands by a few pixels — usually the same
+    // window. Interval marks (bars/candles/boxes) don't need this — their width
+    // *is* their x-span (`visibleSpanRange` captures it exactly); only sub-pixel
+    // `minWidth`/`gapPx` rounding can poke past the edge, which the ±1 margin
+    // absorbs and which only bites when zoomed out (where culling barely narrows).
+    const [w0Start, w0End] = visiblePointRange(cs.x, cs.length, xScale);
+    let maxR = 0;
+    for (let i = w0Start; i < w0End; i += 1) {
+        if (isPoint(cs, i)) {
+            const r = encoding.radiusAt(i);
+            if (r > maxR)
+                maxR = r;
+        }
+    }
+    const pad = maxR + Math.abs(offsetPx);
+    const [vStart, vEnd] = pad > 0
+        ? visiblePointRange(cs.x, cs.length, xScale, pad)
+        : [w0Start, w0End];
+    for (let i = vStart; i < vEnd; i += 1) {
         if (!isPoint(cs, i))
             continue;
         // `offsetPx` nudges the whole scatter in pixel space (zoom-stable) — for
@@ -162,7 +197,7 @@ export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, lab
         ctx.fillStyle = style.label;
         ctx.font = `${font.size}px ${font.family}`;
         ctx.textBaseline = 'middle';
-        for (let i = 0; i < cs.length; i += 1) {
+        for (let i = vStart; i < vEnd; i += 1) {
             if (!isPoint(cs, i))
                 continue;
             const text = labelAt(i);

package/dist/swatch.d.ts

@@ -0,0 +1,104 @@
+/**
+ * `<Legend>` support — the swatch vocabulary, the per-layer registration hook,
+ * and the pure ordering/dedup pipeline the component renders from.
+ *
+ * The mechanism ([PND-LEGEND], #508 item 2): each draw layer registers its
+ * **resolved** style as a {@link SwatchSpec} alongside its readout identity, so
+ * a legend can never drift from the plot — the property an app-side legend
+ * only gets by manually sharing a palette. The legend renders the registry;
+ * layers self-describe.
+ */
+import { type ContainerFrame } from './context.js';
+/**
+ * A legend item's **swatch** — the layer's resolved style, in the mark's own
+ * vocabulary (a line shows stroke + dash, a band shows its translucent fill, a
+ * candle shows its up/down pair). Resolved means post-theme: the exact values
+ * the canvas draws with, so the swatch and the mark can never disagree.
+ */
+export type SwatchSpec = {
+    readonly kind: 'line';
+    readonly color: string;
+    readonly width: number;
+    readonly dash?: readonly number[] | undefined;
+} | {
+    readonly kind: 'area';
+    readonly line: string;
+    readonly fill: string;
+    readonly fillOpacity: number;
+} | {
+    readonly kind: 'band';
+    readonly fill: string;
+    readonly opacity: number;
+} | {
+    readonly kind: 'scatter';
+    readonly color: string;
+    readonly radius: number;
+    readonly outline?: string | undefined;
+} | {
+    readonly kind: 'box';
+    readonly whisker: string;
+    readonly whiskerWidth: number;
+} | {
+    readonly kind: 'bar';
+    readonly fill: string;
+} | {
+    readonly kind: 'candle';
+    readonly up: string;
+    readonly down: string;
+};
+/**
+ * One row as a layer registers it (and as `<Legend items>` accepts it):
+ * the display `label` (the layer's readout identity `as ?? column`, or its
+ * `legend="name"` override), the resolved {@link SwatchSpec}, and — when the
+ * layer is interactive — its selection `id`.
+ */
+export interface LegendItemInput {
+    readonly label: string;
+    readonly swatch: SwatchSpec;
+    /** The layer's selection identity (its `id` prop) — gates the legend's
+     *  default hover/select interactions, and keys dedup ahead of `label`. */
+    readonly id?: string | undefined;
+}
+/** A registered legend row: the input plus its place in the chart (chart row,
+ *  declaration index, position within the layer), which drives display order. */
+export interface LegendItemSpec extends LegendItemInput {
+    readonly rowKey: symbol;
+    readonly index: number;
+    /** Position within a multi-row layer (a stacked bar registers one row per
+     *  column, in stack order) — `0` for the single-row marks. */
+    readonly subIndex: number;
+}
+/**
+ * Order + dedup the registered rows for display: chart-row order first (the
+ * container's top-to-bottom `rowOrder`), declaration `index` within a row —
+ * the existing z-order convention — then `subIndex` (stack order within a
+ * multi-row layer), then label as a final stable tiebreak. Dedup keys on
+ * `(id ?? label, subIndex)` — the A2.2 selection model makes `id` the series
+ * identity (a theme-role label can repeat), and the `subIndex` component
+ * keeps a **multi-group layer's** rows distinct (its groups all share the
+ * layer's `id`; without it a stacked bar with an `id` would collapse to one
+ * row). Two single-row layers still collapse on a shared identity (both are
+ * `subIndex 0`) — the first row in display order stands, exactly as the
+ * tracker readout merges keys.
+ */
+export declare function orderLegendItems(items: Iterable<LegendItemSpec>, rowOrder: readonly symbol[]): LegendItemSpec[];
+/**
+ * Resolve a layer's `legend` prop + identity into what it registers:
+ * `false` ⇒ `null` (opt out — no row); a string ⇒ that display name; omitted /
+ * `true` ⇒ the layer's own readout identity. Kept as a helper so every mark
+ * resolves the prop identically.
+ */
+export declare function legendLabelFor(legend: boolean | string | undefined, identity: string): string | null;
+/**
+ * Register this layer instance's legend row(s) — one for the single-row marks,
+ * one per column for a stacked bar — keyed off the layer's per-instance
+ * `slot` (row *i* registers under a derived per-index key, so the layer's rows
+ * live and die together); unregister all on unmount. Pass `rows: null` (or
+ * `[]`) to register nothing (the layer opted out via `legend={false}`).
+ * `rows` must be **memoised by the caller** (like `useRegisterAnnotation`'s
+ * `xs`) so the effect re-runs only when a swatch / label genuinely changes,
+ * not every render. Reads the enclosing chart row's key itself — a layer
+ * outside a `<ChartRow>` (impossible today) simply doesn't register.
+ */
+export declare function useLegendItems(container: ContainerFrame, slot: symbol, index: number, rows: readonly LegendItemInput[] | null): void;
+//# sourceMappingURL=swatch.d.ts.map

package/dist/swatch.js

@@ -0,0 +1,96 @@
+/**
+ * `<Legend>` support — the swatch vocabulary, the per-layer registration hook,
+ * and the pure ordering/dedup pipeline the component renders from.
+ *
+ * The mechanism ([PND-LEGEND], #508 item 2): each draw layer registers its
+ * **resolved** style as a {@link SwatchSpec} alongside its readout identity, so
+ * a legend can never drift from the plot — the property an app-side legend
+ * only gets by manually sharing a palette. The legend renders the registry;
+ * layers self-describe.
+ */
+import { useContext, useEffect, useRef } from 'react';
+import { RowContext } from './context.js';
+/**
+ * Order + dedup the registered rows for display: chart-row order first (the
+ * container's top-to-bottom `rowOrder`), declaration `index` within a row —
+ * the existing z-order convention — then `subIndex` (stack order within a
+ * multi-row layer), then label as a final stable tiebreak. Dedup keys on
+ * `(id ?? label, subIndex)` — the A2.2 selection model makes `id` the series
+ * identity (a theme-role label can repeat), and the `subIndex` component
+ * keeps a **multi-group layer's** rows distinct (its groups all share the
+ * layer's `id`; without it a stacked bar with an `id` would collapse to one
+ * row). Two single-row layers still collapse on a shared identity (both are
+ * `subIndex 0`) — the first row in display order stands, exactly as the
+ * tracker readout merges keys.
+ */
+export function orderLegendItems(items, rowOrder) {
+    const rowPos = new Map();
+    rowOrder.forEach((k, i) => rowPos.set(k, i));
+    const sorted = [...items].sort((a, b) => (rowPos.get(a.rowKey) ?? rowOrder.length) -
+        (rowPos.get(b.rowKey) ?? rowOrder.length) ||
+        a.index - b.index ||
+        a.subIndex - b.subIndex ||
+        a.label.localeCompare(b.label));
+    const seen = new Set();
+    const out = [];
+    for (const it of sorted) {
+        const key = `${it.id ?? it.label} ${it.subIndex}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(it);
+    }
+    return out;
+}
+/**
+ * Resolve a layer's `legend` prop + identity into what it registers:
+ * `false` ⇒ `null` (opt out — no row); a string ⇒ that display name; omitted /
+ * `true` ⇒ the layer's own readout identity. Kept as a helper so every mark
+ * resolves the prop identically.
+ */
+export function legendLabelFor(legend, identity) {
+    if (legend === false)
+        return null;
+    return typeof legend === 'string' && legend.length > 0 ? legend : identity;
+}
+/**
+ * Register this layer instance's legend row(s) — one for the single-row marks,
+ * one per column for a stacked bar — keyed off the layer's per-instance
+ * `slot` (row *i* registers under a derived per-index key, so the layer's rows
+ * live and die together); unregister all on unmount. Pass `rows: null` (or
+ * `[]`) to register nothing (the layer opted out via `legend={false}`).
+ * `rows` must be **memoised by the caller** (like `useRegisterAnnotation`'s
+ * `xs`) so the effect re-runs only when a swatch / label genuinely changes,
+ * not every render. Reads the enclosing chart row's key itself — a layer
+ * outside a `<ChartRow>` (impossible today) simply doesn't register.
+ */
+export function useLegendItems(container, slot, index, rows) {
+    const rowFrame = useContext(RowContext);
+    const rowKey = rowFrame?.rowKey;
+    const { registerLegendItem, unregisterLegendItem } = container;
+    // Stable per-subIndex child keys, grown lazily; `slot` itself keys row 0 so
+    // the common single-row mark registers exactly one symbol.
+    const childKeys = useRef([slot]);
+    useEffect(() => {
+        const keys = childKeys.current;
+        return () => keys.forEach((k) => unregisterLegendItem(k));
+    }, [unregisterLegendItem]);
+    useEffect(() => {
+        const keys = childKeys.current;
+        const want = rowKey === undefined ? [] : (rows ?? []);
+        while (keys.length < want.length) {
+            keys.push(Symbol(`legend-${keys.length}`));
+        }
+        want.forEach((row, i) => registerLegendItem(keys[i], {
+            ...row,
+            rowKey: rowKey,
+            index,
+            subIndex: i,
+        }));
+        // Drop rows beyond the current count (a stack that lost a column).
+        for (let i = want.length; i < keys.length; i += 1) {
+            unregisterLegendItem(keys[i]);
+        }
+    }, [registerLegendItem, unregisterLegendItem, slot, rows, rowKey, index]);
+}
+//# sourceMappingURL=swatch.js.map

package/dist/theme.d.ts

@@ -179,6 +179,33 @@ export interface ChartTheme {
         readonly color: string;
         readonly fillOpacity: number;
         readonly depth: readonly [number, number, number];
+        /**
+         * **Optional per-role overrides** — a small map from a role name to its
+         * `color` (and optionally `fillOpacity`), so distinct marks can be styled
+         * at once without splitting the whole register: a `<Baseline role="atm">`
+         * green, a `<Marker role="ref">` in another hue, each still drawn through
+         * the shared {@link depth} ramp. A mark's `role` resolves
+         * `roles[role] ?? { color, fillOpacity }` (an unknown/unset role is the
+         * base register). Colour stays a **theme** concern — there is no per-mark
+         * colour prop (the one-styling-channel discipline).
+         */
+        readonly roles?: {
+            readonly [role: string]: {
+                readonly color: string;
+                readonly fillOpacity?: number;
+            };
+        };
+    };
+    /**
+     * The **`<Legend>` card** — background, border, and label text of the
+     * in-chart series key. **Optional**: when absent the legend derives from
+     * existing tokens (`chip.background`, `axis.grid`, `axis.label`), so a
+     * hand-built theme keeps compiling and reads coherently without opting in.
+     */
+    readonly legend?: {
+        readonly background: string;
+        readonly border: string;
+        readonly text: string;
     };
 }
 /** A resolved line style: stroke colour + width (px). */

package/dist/theme.js

@@ -131,6 +131,12 @@ export const defaultTheme = {
         fillOpacity: 0.1,
         depth: [1, 0.7, 0.4],
     },
+    // The in-chart series key: chip-white card, gridline border, axis-label text.
+    legend: {
+        background: '#ffffff',
+        border: '#e2e8f0',
+        text: '#64748b',
+    },
 };
 /**
  * The estela theme — estela's real `@estela/ui` palette as *one theme*, on its
@@ -271,5 +277,11 @@ export const estelaTheme = {
         fillOpacity: 0.1,
         depth: [1, 0.7, 0.4],
     },
+    // The in-chart series key on the dark ground: deep panel, abyss-line border.
+    legend: {
+        background: '#0B4E58', // --es-deep (the chip panel)
+        border: '#1B6B75',
+        text: '#B7D9DD',
+    },
 };
 //# sourceMappingURL=theme.js.map

package/dist/useChartLegend.d.ts

@@ -0,0 +1,106 @@
+import { type ContainerFrame } from './context.js';
+import type { SelectInfo } from './context.js';
+import { type LegendItemInput, type SwatchSpec } from './swatch.js';
+/** One legend **item** as {@link useChartLegend} serves it — a series entry:
+ *  the registered identity + resolved swatch, plus its live interaction
+ *  state. (Items are grouped into {@link LegendRow}s by chart row.) */
+export interface LegendItem extends LegendItemInput {
+    /** This item's series is the container's current selection (id-keyed). */
+    readonly selected: boolean;
+    /** This item's series is the container's current hover (id-keyed). */
+    readonly hovered: boolean;
+}
+/** One **chart row's** group of legend {@link LegendItem}s — the grouping
+ *  matches the chart's `<ChartRow>` layout, so a legend can mirror the rows
+ *  (a flat legend is `rows.flatMap((r) => r.items)`). */
+export interface LegendRow {
+    /** The chart row these items belong to (its stable per-row key). */
+    readonly rowKey: symbol;
+    /** The row's items, in display order (declaration → stack position). */
+    readonly items: readonly LegendItem[];
+}
+/** What {@link useChartLegend} returns — the data shape + the sync verbs a
+ *  custom-rendered legend needs. */
+export interface ChartLegend {
+    /** The registered items **grouped by chart row** (top-to-bottom), each
+     *  group's items in declaration → stack order, deduped by
+     *  `(id ?? label, stack position)`. A flat list is
+     *  `rows.flatMap((r) => r.items)`; a row-scoped legend has one entry. */
+    readonly rows: readonly LegendRow[];
+    /**
+     * The container's reserved axis gutters in px — how far the **plot** is
+     * inset from the chart box on each side. A custom legend laid out above /
+     * below the chart pads by `gutters.left` (and `gutters.right`) to align
+     * with the plot instead of the y-axis column.
+     */
+    readonly gutters: {
+        readonly left: number;
+        readonly right: number;
+    };
+    /**
+     * The **cursor's x position** in axis units — epoch ms on a time axis, the
+     * axis value on a value axis (the `TrackerInfo.time` convention) — or
+     * `null` when no cursor is live. The values-in-the-legend seam: with a
+     * row's identity and this instant, look up each series' value at the
+     * cursor (`series.nearest(cursorTime)`), falling back to the latest sample
+     * when `null` — a "current or cursor value" readout per row. Live: the
+     * frame rebuilds as the cursor moves, so a hook consumer re-renders with
+     * it.
+     */
+    readonly cursorTime: number | null;
+    /**
+     * Echo a row hover into the container's `hovered` channel (the same one an
+     * in-plot hover drives — marks light up where they support it, and
+     * `onHover` fires); `null` clears. Id-gated: a row without an `id` is a
+     * no-op (there is no series identity to point at).
+     */
+    hover(row: LegendItemInput | null): void;
+    /**
+     * Toggle the container selection to this row's series (fires `onSelect`;
+     * clears when the row is already selected — the `<Legend>` click
+     * semantics). Id-gated no-op for rows without an `id`.
+     */
+    select(row: LegendItemInput): void;
+}
+/** The series-scoped {@link SelectInfo} a legend interaction reports: no
+ *  sample under it, so `key`/`value` are deliberately `NaN` (see the
+ *  provenance note on {@link SelectInfo.key}); `color` is the swatch's
+ *  primary colour. */
+export declare function seriesSelectInfo(row: LegendItemInput): SelectInfo;
+/** The swatch's primary colour — what a series-scoped `SelectInfo` reports. */
+export declare function swatchColor(s: SwatchSpec): string;
+/** Build the {@link ChartLegend} from a frame — the pure core `<Legend>` and
+ *  {@link useChartLegend} share, so a custom-rendered legend and the built-in
+ *  card can never disagree about rows or sync semantics. Pass a `rowKey` to
+ *  **scope** the rows to a single chart row (the layers registered under it);
+ *  omit it for the whole container. */
+export declare function buildChartLegend(container: ContainerFrame, rowKey?: symbol): ChartLegend;
+/**
+ * **Headless legend** — the registry `<Legend>` renders, as data, plus the
+ * hover/select verbs already wired to the chart. For consumers whose legend
+ * is a design of its own (a horizontal strip, a ticker-compare pair with the
+ * secondary dimmed, values-in-the-legend): render from `rows` (items grouped
+ * by chart row; a flat legend is `rows.flatMap((r) => r.items)`), call
+ * `hover`/`select` from your item handlers, and read each item's
+ * `selected`/`hovered` state back — the same contract the built-in card uses,
+ * because both are built by {@link buildChartLegend}.
+ *
+ * **Readout integration:** an item's `label` is the layer's readout identity —
+ * the same string the tracker's `onTrackerChanged` samples carry — so merging
+ * live cursor values into your legend is a label-keyed join, no extra
+ * plumbing.
+ *
+ * **Scope follows placement:** called at the container level it enumerates
+ * **all** rows; called inside a `<Layers>` (i.e. under a `<ChartRow>`) it
+ * **scopes to that row's** layers — a per-row legend needs no prop, just
+ * placement, the same way annotations scope to the row they sit in.
+ *
+ * **Placement:** it reads the frame, so it works anywhere under the
+ * `<ChartContainer>`. To render the markup *outside* the chart's box, portal
+ * it out (`createPortal`) — context flows through portals.
+ *
+ * Must be under a `<ChartContainer>`; throws otherwise (for a fully detached
+ * key, `<Legend items>` renders explicit rows without a chart).
+ */
+export declare function useChartLegend(): ChartLegend;
+//# sourceMappingURL=useChartLegend.d.ts.map

package/dist/useChartLegend.js

@@ -0,0 +1,122 @@
+import { useContext, useMemo } from 'react';
+import { ContainerContext, RowContext, } from './context.js';
+import { orderLegendItems, } from './swatch.js';
+/** The series-scoped {@link SelectInfo} a legend interaction reports: no
+ *  sample under it, so `key`/`value` are deliberately `NaN` (see the
+ *  provenance note on {@link SelectInfo.key}); `color` is the swatch's
+ *  primary colour. */
+export function seriesSelectInfo(row) {
+    return {
+        id: row.id,
+        key: NaN,
+        value: NaN,
+        color: swatchColor(row.swatch),
+        label: row.label,
+    };
+}
+/** The swatch's primary colour — what a series-scoped `SelectInfo` reports. */
+export function swatchColor(s) {
+    switch (s.kind) {
+        case 'line':
+            return s.color;
+        case 'area':
+            return s.line;
+        case 'band':
+            return s.fill;
+        case 'scatter':
+            return s.color;
+        case 'box':
+            return s.whisker;
+        case 'bar':
+            return s.fill;
+        case 'candle':
+            return s.up;
+    }
+}
+/** Build the {@link ChartLegend} from a frame — the pure core `<Legend>` and
+ *  {@link useChartLegend} share, so a custom-rendered legend and the built-in
+ *  card can never disagree about rows or sync semantics. Pass a `rowKey` to
+ *  **scope** the rows to a single chart row (the layers registered under it);
+ *  omit it for the whole container. */
+export function buildChartLegend(container, rowKey) {
+    const scoped = Array.from(container.legendItems.values()).filter((it) => rowKey === undefined || it.rowKey === rowKey);
+    // Ordered + deduped specs (chart-row first), each carrying its `rowKey`;
+    // group consecutive same-row specs into a LegendRow, mapping spec → item.
+    const rows = [];
+    for (const spec of orderLegendItems(scoped, container.rowOrder)) {
+        const item = {
+            label: spec.label,
+            swatch: spec.swatch,
+            ...(spec.id !== undefined ? { id: spec.id } : {}),
+            selected: spec.id !== undefined && container.selected?.id === spec.id,
+            hovered: spec.id !== undefined && container.hovered?.id === spec.id,
+        };
+        const last = rows[rows.length - 1];
+        if (last !== undefined && last.rowKey === spec.rowKey) {
+            last.items.push(item);
+        }
+        else {
+            rows.push({ rowKey: spec.rowKey, items: [item] });
+        }
+    }
+    // The cursor pixel → axis units, exactly as the tracker fan-in resolves it
+    // (in-bounds guard included, so an off-plot cursor reads as "no cursor").
+    const cursorTime = container.cursorX !== null &&
+        container.cursorX >= 0 &&
+        container.cursorX <= container.plotWidth
+        ? +container.xScale.invert(container.cursorX)
+        : null;
+    return {
+        rows,
+        gutters: { left: container.leftGutter, right: container.rightGutter },
+        cursorTime,
+        hover: (row) => {
+            if (row === null)
+                return container.setHovered(null);
+            if (row.id !== undefined)
+                container.setHovered(seriesSelectInfo(row));
+        },
+        select: (row) => {
+            if (row.id === undefined)
+                return;
+            container.select(container.selected?.id === row.id ? null : seriesSelectInfo(row));
+        },
+    };
+}
+/**
+ * **Headless legend** — the registry `<Legend>` renders, as data, plus the
+ * hover/select verbs already wired to the chart. For consumers whose legend
+ * is a design of its own (a horizontal strip, a ticker-compare pair with the
+ * secondary dimmed, values-in-the-legend): render from `rows` (items grouped
+ * by chart row; a flat legend is `rows.flatMap((r) => r.items)`), call
+ * `hover`/`select` from your item handlers, and read each item's
+ * `selected`/`hovered` state back — the same contract the built-in card uses,
+ * because both are built by {@link buildChartLegend}.
+ *
+ * **Readout integration:** an item's `label` is the layer's readout identity —
+ * the same string the tracker's `onTrackerChanged` samples carry — so merging
+ * live cursor values into your legend is a label-keyed join, no extra
+ * plumbing.
+ *
+ * **Scope follows placement:** called at the container level it enumerates
+ * **all** rows; called inside a `<Layers>` (i.e. under a `<ChartRow>`) it
+ * **scopes to that row's** layers — a per-row legend needs no prop, just
+ * placement, the same way annotations scope to the row they sit in.
+ *
+ * **Placement:** it reads the frame, so it works anywhere under the
+ * `<ChartContainer>`. To render the markup *outside* the chart's box, portal
+ * it out (`createPortal`) — context flows through portals.
+ *
+ * Must be under a `<ChartContainer>`; throws otherwise (for a fully detached
+ * key, `<Legend items>` renders explicit rows without a chart).
+ */
+export function useChartLegend() {
+    const container = useContext(ContainerContext);
+    if (container === null) {
+        throw new Error('useChartLegend() must be used inside a <ChartContainer>');
+    }
+    // A RowContext in scope (rendered inside a <Layers>) narrows to that row.
+    const rowKey = useContext(RowContext)?.rowKey;
+    return useMemo(() => buildChartLegend(container, rowKey), [container, rowKey]);
+}
+//# sourceMappingURL=useChartLegend.js.map

package/dist/yticks.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The **y-axis auto-tick count** — the `count` a `<YAxis>`'s labels and the
+ * row's gridlines both pass to `scale.ticks(count)` / `tickFormat(count)`, so
+ * a label and its gridline stay on the same instants (the alignment the two
+ * hardcoded `5`s in `YAxis` + `Layers` used to hold by agreeing).
+ *
+ * Height-derived by default — a short strip gets fewer ticks than a tall row,
+ * so a 72px histogram lane no longer crushes 5 labels into the space a 380px
+ * row uses (the #508 vol-surface friction). This mirrors the trading-time x
+ * axis, whose count is width-derived (0.44.1). An explicit `<YAxis tickCount>`
+ * overrides the derivation; explicit `<YAxis ticks>` bypasses this entirely.
+ */
+/**
+ * Resolve a y-axis's auto-tick count: the explicit `tickCount` when given,
+ * else `floor(height / Y_TICK_PX)` floored at 2 (a drawable minimum even on a
+ * pre-layout zero height). `ticks(count)` treats it as a target and returns
+ * nice 1-2-5 values near it, so a larger count on a tall row is exactly right.
+ */
+export declare function resolveYTickCount(height: number, explicit?: number | undefined): number;
+//# sourceMappingURL=yticks.d.ts.map

package/dist/yticks.js

@@ -0,0 +1,28 @@
+/**
+ * The **y-axis auto-tick count** — the `count` a `<YAxis>`'s labels and the
+ * row's gridlines both pass to `scale.ticks(count)` / `tickFormat(count)`, so
+ * a label and its gridline stay on the same instants (the alignment the two
+ * hardcoded `5`s in `YAxis` + `Layers` used to hold by agreeing).
+ *
+ * Height-derived by default — a short strip gets fewer ticks than a tall row,
+ * so a 72px histogram lane no longer crushes 5 labels into the space a 380px
+ * row uses (the #508 vol-surface friction). This mirrors the trading-time x
+ * axis, whose count is width-derived (0.44.1). An explicit `<YAxis tickCount>`
+ * overrides the derivation; explicit `<YAxis ticks>` bypasses this entirely.
+ */
+/** Target px of row height per y tick. A y label is one line, so this is the
+ *  vertical breathing room between gridlines — a touch tighter than the x
+ *  axis's per-tick budget, since stacked numbers need less room than dates. */
+const Y_TICK_PX = 48;
+/**
+ * Resolve a y-axis's auto-tick count: the explicit `tickCount` when given,
+ * else `floor(height / Y_TICK_PX)` floored at 2 (a drawable minimum even on a
+ * pre-layout zero height). `ticks(count)` treats it as a target and returns
+ * nice 1-2-5 values near it, so a larger count on a tall row is exactly right.
+ */
+export function resolveYTickCount(height, explicit) {
+    if (explicit !== undefined)
+        return Math.max(1, Math.floor(explicit));
+    return Math.max(2, Math.floor(height / Y_TICK_PX));
+}
+//# sourceMappingURL=yticks.js.map