@pond-ts/charts 0.53.0 → 0.54.0

package/dist/bars.d.ts

@@ -54,22 +54,52 @@ export declare function resolveBarBaseline(yScale: Scale): number;
  * hit rect are the same geometry.
  */
 export declare function barRect(cs: BarSeries, i: number, xScale: Scale, yScale: Scale, baseline: number, gapPx: number, minWidthPx: number): [x0: number, x1: number, yTop: number, yBottom: number] | null;
+/**
+ * The narrowed selection / hover identity a **single-series** bar matches
+ * against: the layer's series `id`, the sample's `key` (its `begin`), and — when
+ * the series carries {@link BarSeries.marks} — the stable per-bar `mark`. The
+ * single-series sibling of {@link StackMark}, which additionally carries the
+ * stack's group `label` (a single-series bar has no group to disambiguate).
+ */
+export interface BarMark {
+    readonly id: string;
+    readonly key: number;
+    readonly mark?: string;
+}
 /**
  * Fill one rectangle per bar in `cs`, each spanning its key's `[begin, end]`
  * (inset by `gapPx`) from the resolved `baseline` to the value.
  *
  * A gap (non-finite value) is skipped — no bar, no zero-height sliver. A bar
- * matching the current `selection` (same sample `key` **and** the layer's own
- * series `id` — `seriesId`; a no-id layer passes `undefined` and never matches)
- * draws in the style's `highlight` colour **and outlined**, so a click reads back
- * on the canvas; a bar matching `hovered` draws in `highlight` **without** the
- * outline (a lighter "this bar is live" on pointer-over); all others use the flat
- * `fill`. `globalAlpha` carries the fill opacity and is restored so it doesn't
- * leak into later layers.
+ * matching the current `selection` (the layer's own series `id` — `seriesId`; a
+ * no-id layer passes `undefined` and never matches — plus the bar's identity,
+ * see {@link barMatches}) draws in the style's `highlight` colour **and
+ * outlined**, so a click reads back on the canvas; a bar matching `hovered`
+ * draws in `highlight` **without** the outline (a lighter "this bar is live" on
+ * pointer-over); all others use the flat `fill`. `globalAlpha` carries the fill
+ * opacity and is restored so it doesn't leak into later layers.
+ *
+ * **Which identity.** A selection carrying a `mark` matches against the series'
+ * stable per-bar name ({@link BarSeries.marks} — the sample's own axis key,
+ * which the readers always supply); one without falls back to the sample `key`
+ * (the bar's `begin`). The mark path is what lets a caller pin a bar on a
+ * **point-keyed** series without re-deriving the neighbour-spaced span, since
+ * there `begin` is not the sample's key but an edge computed from it.
  *
  * O(N) over the events, one fill (+ optional stroke) per bar, no per-bar
  * allocation beyond the rect tuple.
  *
+ * **Per-bar fills (`binFills`):** an optional colour array aligned
+ * index-for-index to the source bars — bar `i` fills with `binFills[i]`
+ * (an `undefined` entry falls back to the flat `fill`). This is the
+ * direction-coloured financial volume row (rising / falling) and the
+ * value-band case on a time axis. Highlight follows {@link drawStacks}'s
+ * binFills convention rather than the flat path's: the bar **keeps its own
+ * colour** under hover / selection — the highlight pops `globalAlpha` to 1
+ * (and outlines the selection in the bar's own fill) — so a red / green bar
+ * stays red / green while live, instead of swapping to the single
+ * `highlight` colour and losing its meaning.
+ *
  * **M4 column decimation ([PND-MARKDEC]):** once the *visible* bars are denser
  * than ~2 per device pixel, they overplot into a solid silhouette, so
  * `decimate !== false` replaces them with one **envelope rect per pixel column**
@@ -79,15 +109,12 @@ export declare function barRect(cs: BarSeries, i: number, xScale: Scale, yScale:
  * columns aren't individually selectable, so per-bar selection/hover highlight is
  * suppressed (a <1px bar's ring wouldn't be visible anyway); interaction still
  * reads the **source** bars via {@link barAt} (§2.3). Pass `decimate={false}` to
- * always draw every bar. Returns {@link LayerDrawStats} for `onDrawStats`.
+ * always draw every bar. **`binFills` disables the envelope pass** — a single
+ * envelope rect spans many differently-coloured bars, so decimating would
+ * repaint them one flat colour; per-bar-coloured layers draw every visible bar.
+ * Returns {@link LayerDrawStats} for `onDrawStats`.
  */
-export declare function drawBars(ctx: CanvasRenderingContext2D, cs: BarSeries, xScale: Scale, yScale: Scale, style: BarStyle, baseline: number, gapPx: number, seriesId: string | undefined, selection: {
-    key: number;
-    id: string;
-} | null, hovered: {
-    key: number;
-    id: string;
-} | null, decimate?: DecimateOption): LayerDrawStats;
+export declare function drawBars(ctx: CanvasRenderingContext2D, cs: BarSeries, xScale: Scale, yScale: Scale, style: BarStyle, baseline: number, gapPx: number, seriesId: string | undefined, selection: BarMark | null, hovered: BarMark | null, decimate?: DecimateOption, binFills?: readonly (string | undefined)[]): LayerDrawStats;
 /**
  * The index of the bar whose key span `[begin, end]` contains `time` — the bar
  * **under the cursor** — or `-1` if `time` falls in no bar's span. This is the

package/dist/bars.js

@@ -79,22 +79,66 @@ export function barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx) {
     const yBase = yScale(baseline);
     return [x0, x1, Math.min(yValue, yBase), Math.max(yValue, yBase)];
 }
+/**
+ * Does `m` identify the bar with stable identity `stable` and key `begin`?
+ * The mark decides **only when both sides have one** — `m.mark` (the selection
+ * names a bar) and `stable` (this series names its bars). Either missing falls
+ * back to `m.key === begin`, so both of these keep working unchanged:
+ *
+ * - a selection with **no `mark`** — every controlled `selected={{ id, key }}`
+ *   that predates this channel, against a series that now carries marks;
+ * - a series with **no `marks`** — a hand-built {@link BarSeries} (tests, an
+ *   outside caller assembling the view themselves).
+ *
+ * This is the `mark`-first rule {@link drawStacks} applies, with one deliberate
+ * difference: it falls back on the **selection** carrying no mark, where
+ * `drawStacks` falls back on the **series** carrying none. `drawStacks` can
+ * switch on the series alone because only `categoryStack` produces marks and it
+ * never had key-pinned consumers. Every reader-built bar series now carries
+ * marks, so that unconditional switch would silently stop matching each shipped
+ * key-pinned selection — key-pinning is the only selection bars ever had.
+ */
+function barMatches(m, seriesId, stable, begin) {
+    if (m === null || m.id !== seriesId)
+        return false;
+    return m.mark !== undefined && stable !== undefined
+        ? m.mark === stable
+        : m.key === begin;
+}
 /**
  * Fill one rectangle per bar in `cs`, each spanning its key's `[begin, end]`
  * (inset by `gapPx`) from the resolved `baseline` to the value.
  *
  * A gap (non-finite value) is skipped — no bar, no zero-height sliver. A bar
- * matching the current `selection` (same sample `key` **and** the layer's own
- * series `id` — `seriesId`; a no-id layer passes `undefined` and never matches)
- * draws in the style's `highlight` colour **and outlined**, so a click reads back
- * on the canvas; a bar matching `hovered` draws in `highlight` **without** the
- * outline (a lighter "this bar is live" on pointer-over); all others use the flat
- * `fill`. `globalAlpha` carries the fill opacity and is restored so it doesn't
- * leak into later layers.
+ * matching the current `selection` (the layer's own series `id` — `seriesId`; a
+ * no-id layer passes `undefined` and never matches — plus the bar's identity,
+ * see {@link barMatches}) draws in the style's `highlight` colour **and
+ * outlined**, so a click reads back on the canvas; a bar matching `hovered`
+ * draws in `highlight` **without** the outline (a lighter "this bar is live" on
+ * pointer-over); all others use the flat `fill`. `globalAlpha` carries the fill
+ * opacity and is restored so it doesn't leak into later layers.
+ *
+ * **Which identity.** A selection carrying a `mark` matches against the series'
+ * stable per-bar name ({@link BarSeries.marks} — the sample's own axis key,
+ * which the readers always supply); one without falls back to the sample `key`
+ * (the bar's `begin`). The mark path is what lets a caller pin a bar on a
+ * **point-keyed** series without re-deriving the neighbour-spaced span, since
+ * there `begin` is not the sample's key but an edge computed from it.
  *
  * O(N) over the events, one fill (+ optional stroke) per bar, no per-bar
  * allocation beyond the rect tuple.
  *
+ * **Per-bar fills (`binFills`):** an optional colour array aligned
+ * index-for-index to the source bars — bar `i` fills with `binFills[i]`
+ * (an `undefined` entry falls back to the flat `fill`). This is the
+ * direction-coloured financial volume row (rising / falling) and the
+ * value-band case on a time axis. Highlight follows {@link drawStacks}'s
+ * binFills convention rather than the flat path's: the bar **keeps its own
+ * colour** under hover / selection — the highlight pops `globalAlpha` to 1
+ * (and outlines the selection in the bar's own fill) — so a red / green bar
+ * stays red / green while live, instead of swapping to the single
+ * `highlight` colour and losing its meaning.
+ *
  * **M4 column decimation ([PND-MARKDEC]):** once the *visible* bars are denser
  * than ~2 per device pixel, they overplot into a solid silhouette, so
  * `decimate !== false` replaces them with one **envelope rect per pixel column**
@@ -104,9 +148,12 @@ export function barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx) {
  * columns aren't individually selectable, so per-bar selection/hover highlight is
  * suppressed (a <1px bar's ring wouldn't be visible anyway); interaction still
  * reads the **source** bars via {@link barAt} (§2.3). Pass `decimate={false}` to
- * always draw every bar. Returns {@link LayerDrawStats} for `onDrawStats`.
+ * always draw every bar. **`binFills` disables the envelope pass** — a single
+ * envelope rect spans many differently-coloured bars, so decimating would
+ * repaint them one flat colour; per-bar-coloured layers draw every visible bar.
+ * Returns {@link LayerDrawStats} for `onDrawStats`.
  */
-export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, seriesId, selection, hovered, decimate = true) {
+export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, seriesId, selection, hovered, decimate = true, binFills) {
     ctx.save();
     ctx.globalAlpha = style.opacity;
     const sourceCount = cs.length; // pre-cull, pre-decimation (for draw stats)
@@ -119,9 +166,13 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
     // Decimate the visible bars to per-column envelope rects once dense (see the
     // header). `null` below the visible-density threshold ⇒ the full per-bar loop.
     // `{ threshold }` tunes the samples-per-pixel factor `k` (as line/area/band do);
-    // `undefined` ⇒ decimateBars' default (2).
+    // `undefined` ⇒ decimateBars' default (2). Per-bar fills skip the envelope —
+    // one flat rect can't carry many bars' colours (see the header) — but an
+    // *empty* colour array is "no colours" (every bar would flat-fill anyway), so
+    // it stays on the legacy path end-to-end (L2 review, PR #542).
+    const fills = binFills !== undefined && binFills.length > 0 ? binFills : undefined;
     const k = typeof decimate === 'object' ? decimate.threshold : undefined;
-    const envelope = decimate !== false
+    const envelope = decimate !== false && fills === undefined
         ? decimateBars(cs, xScale, ctx, baseline, k, vEnd - vStart)
         : null;
     if (envelope !== null) {
@@ -141,24 +192,47 @@ export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, series
         ctx.restore();
         return { sourceCount, drawnCount: drawn, decimated: true };
     }
+    // The stable per-bar identity is consulted only when the live selection /
+    // hover actually carries a `mark` — `cs.marks` builds its strings lazily, so
+    // the *draw* never materializes them on its own. (The component's `hitTest`
+    // may already have: an interactive layer echoes the hovered bar's mark on
+    // every pointer move. See BarSeries.marks — this hoist keeps the draw path
+    // clean, it doesn't make the channel free.)
+    const marks = selection?.mark !== undefined || hovered?.mark !== undefined
+        ? cs.marks
+        : undefined;
     let drawn = 0;
     for (let i = vStart; i < vEnd; i += 1) {
         const rect = barRect(cs, i, xScale, yScale, baseline, gapPx, style.minWidth);
         if (rect === null)
             continue;
         const [x0, x1, yTop, yBottom] = rect;
-        // Match by the series `id` **and** the sample `key` (begin), so two series
-        // sharing a timestamp don't both light up (a no-id, non-selectable layer
-        // passes `seriesId === undefined` and never matches). Both the committed
-        // selection and the transient hover use the `highlight` fill; only the
-        // selection adds the outline, so hover reads as a lighter "this bar is live"
-        // and select as the committed pick.
-        const selected = selection !== null &&
-            selection.id === seriesId &&
-            selection.key === cs.begin[i];
-        const isHovered = hovered !== null &&
-            hovered.id === seriesId &&
-            hovered.key === cs.begin[i];
+        // Match by the series `id` **and** the bar's identity — its stable `mark`
+        // when the selection carries one, else the sample `key` (begin) — so two
+        // series sharing a timestamp don't both light up (a no-id, non-selectable
+        // layer passes `seriesId === undefined` and never matches). Both the
+        // committed selection and the transient hover use the `highlight` fill; only
+        // the selection adds the outline, so hover reads as a lighter "this bar is
+        // live" and select as the committed pick.
+        const stable = marks?.[i];
+        const selected = barMatches(selection, seriesId, stable, cs.begin[i]);
+        const isHovered = barMatches(hovered, seriesId, stable, cs.begin[i]);
+        if (fills !== undefined) {
+            // Per-bar fills: the bar keeps its own colour under hover / selection —
+            // highlight pops the alpha to 1 and outlines the selection in the bar's
+            // own fill (the drawStacks binFills convention; see the header).
+            const fill = fills[i] ?? style.fill;
+            ctx.globalAlpha = selected || isHovered ? 1 : style.opacity;
+            ctx.fillStyle = fill;
+            ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
+            drawn += 1;
+            if (selected) {
+                ctx.lineWidth = style.outlineWidth;
+                ctx.strokeStyle = fill;
+                ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
+            }
+            continue;
+        }
         ctx.fillStyle = selected || isHovered ? style.highlight : style.fill;
         ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
         drawn += 1;

package/dist/context.d.ts

@@ -163,6 +163,17 @@ export interface ContainerFrame {
      *  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. */
     readonly xFormatCustom: boolean;
+    /**
+     * Whether an explicit container `cursorFormat` shaped {@link formatReadout} —
+     * as opposed to the axis kind supplying its own default readout (the elapsed
+     * axis's finer duration). The two are indistinguishable from the field alone,
+     * and `<XAxis>` must tell them apart to honour the documented pill precedence
+     * `cursorFormat → axis format → container`: a **`cursorFormat`** outranks an
+     * explicit `<XAxis format>`, a **default** does not. Without this the elapsed
+     * default silently occupied the `cursorFormat` slot and a wall-clock strip's
+     * pill read durations (issue #540, finding 2).
+     */
+    readonly xReadoutCustom: boolean;
     /**
      * The shared **x-side tick count** — the `count` every x-side `ticks()` /
      * `tickFormat()` call passes (`<XAxis>` labels, the canvas x gridlines and
@@ -590,6 +601,15 @@ export interface TrackerSample {
      *  quote) emits `"<as> <role>"` composites (`iv lower`, `SPY high`) when its
      *  `as` is set, else the raw column / role word. */
     readonly label: string;
+    /**
+     * Optional **source value for the off-chart readout**, when the layer plots a
+     * *derived* column but a `readout` column names the raw value (see
+     * `LineChart`/`AreaChart` `readout`). `value` stays the plotted number — so
+     * the in-chart cursor dot is unchanged — while an off-chart consumer shows
+     * `readout ?? value`. `undefined` when the layer has no `readout` column (the
+     * common case: the plotted value *is* the value to show).
+     */
+    readonly readout?: number;
 }
 /** One line of a {@link CursorFlag} — a labelled, coloured value. */
 export interface CursorFlagLine {
@@ -656,13 +676,25 @@ export interface SelectInfo {
     /** Display label (`as` ?? column ?? id) — labels the selection in a readout. */
     readonly label: string;
     /**
-     * An optional **stable per-mark identity within the layer** — a *category's
-     * column name* on the categorical axis, where every bar shares the layer's
-     * `id` but each column needs its own stable handle. When present, the
-     * highlight match + controlled `selected` echo key on `(id, mark)` instead of
-     * the sample `key`, so a pinned selection survives a column reorder / data
-     * update (the slot index is not stable; the column name is). `undefined` for
-     * marks whose sample `key` is already their identity (a time / value bar).
+     * An optional **stable per-mark identity within the layer** — every mark
+     * shares the layer's `id`, so this is the handle that picks one *within* it.
+     * When a selection carries it, the highlight match + controlled `selected`
+     * echo key on `(id, mark)` instead of the sample `key`, so a pin survives a
+     * reorder / data update that renumbers the slot.
+     *
+     * Two layers report one today:
+     *
+     * - A **categorical** bar reports its *column name* — the slot index is not
+     *   stable across a reorder, the name is.
+     * - A **single-series** bar (`<BarChart series column>`) reports its own axis
+     *   key, stringified. On a **point-keyed** series the sample `key` is *not*
+     *   its identity: the bar span is synthesized from neighbour spacing, so
+     *   `key` is a derived edge (`t - halfGap`) rather than the sample's own
+     *   time. See `BarSeries.marks`.
+     *
+     * `undefined` for every other mark (scatter, box, candle), whose sample `key`
+     * *is* its identity. A selection without a `mark` still matches on `key`
+     * everywhere — the mark is an additional channel, not a replacement.
      */
     readonly mark?: string;
 }

package/dist/data.d.ts

@@ -121,6 +121,35 @@ export interface BarSeries {
     readonly end: Float64Array;
     readonly y: Float64Array;
     readonly length: number;
+    /**
+     * Optional **stable per-bar identity** — `marks[i]` names bar `i`. The
+     * single-series sibling of {@link StackedBarSeries.marks}: when present, the
+     * draw / hit-test / selection can key on this name instead of the bar's
+     * `begin` **edge**.
+     *
+     * The readers ({@link barsFromTimeSeries} / {@link barsFromValueSeries}) fill
+     * it with the **sample's own axis key** — `String(key[i])`, the timestamp or
+     * axis value the row is keyed on. That is the identity a caller already
+     * owns, and for a **point-keyed** series it is *not* `begin[i]`: there the
+     * span is synthesized, so `begin[i]` is a derived edge (`key - prevGap/2`,
+     * see {@link neighbourSpans}) and pinning a selection by key meant
+     * re-deriving the neighbour spacing. `undefined` on a hand-built view.
+     *
+     * Built **lazily** on first read and then memoized (~9 ms per 100k bars, on
+     * top of a ~0.8 ms reader). Who pays, precisely:
+     *
+     * - A **non-interactive** layer (no `id`, so no `hitTest`) never reads them.
+     * - An **interactive** one hit-tests on every *pointer move*, and that echo
+     *   reads the hovered bar's mark — so the first move that lands on a bar
+     *   materializes the array, once per data identity, on the input path
+     *   (11.1 ms vs 1.7 ms for a warm 100k-bar hover).
+     *
+     * So this is not free for an interactive chart; it is bounded and paid once,
+     * where an eager array would cost every chart on every data update. At
+     * realistic bar counts it is under a millisecond either way. See
+     * `scripts/perf-barmarks.mjs`.
+     */
+    readonly marks?: readonly string[];
 }
 /**
  * A chart-ready view of a **stacked / histogram** bar series — the multi-segment
@@ -156,6 +185,27 @@ export interface StackedBarSeries {
      */
     readonly marks?: readonly string[];
 }
+/**
+ * Assert `column` names an existing **numeric** column of `series`, returning
+ * it. The single source of the reader's two errors, so a caller that reads a
+ * column **per event** rather than buffering it — the time-axis `readout` path
+ * in `LineChart` / `AreaChart` — rejects a bad name identically to one that
+ * materializes. Without it a mistyped `readout` throws on a `ValueSeries` (via
+ * {@link readValueColumn}) but silently produced no readout on a `TimeSeries`,
+ * where the per-event `get()` just returns `undefined`.
+ *
+ * The `undefined` guard is runtime-necessary even though it reads as dead code:
+ * `column()` returns `undefined` for an unknown name at runtime, but core's
+ * public overload currently types the result as non-`undefined` (see F-3 in the
+ * M1 friction note). Keep it — the "throws on unknown column" tests exercise it.
+ *
+ * @throws RangeError if `column` does not exist.
+ * @throws TypeError if `column` is not a numeric column.
+ */
+export declare function assertNumericColumn<S extends SeriesSchema>(series: TimeSeries<S>, column: string): {
+    kind: string;
+    read(i: number): number | undefined;
+};
 /**
  * The quantile column names a {@link boxFromTimeSeries} / {@link boxFromValueSeries}
  * reads. `lower`/`upper` (the whisker reach) are required; `q1`/`q3` (the box
@@ -306,6 +356,10 @@ export declare function ohlcFromTimeSeries<S extends SeriesSchema>(series: TimeS
  * interval-keyed series (e.g. an `aggregate`/`window` rollup) draws its true
  * bucket spans. Detected by `keyColumn().kind === 'time'`.
  *
+ * Each bar also carries its **own key** as a stable {@link BarSeries.marks}
+ * identity, so a selection can be pinned on the sample rather than on the span
+ * this derived for it.
+ *
  * @throws RangeError if `column` does not exist.
  * @throws TypeError if `column` is not a numeric column.
  */
@@ -326,6 +380,10 @@ export declare function barsFromTimeSeries<S extends SeriesSchema>(series: TimeS
  * (a slight drift from a true segment edge — fine for the bar look; key an
  * interval/timeRange `TimeSeries` instead if exact edges matter).
  *
+ * Each bar also carries its **axis value** as a stable {@link BarSeries.marks}
+ * identity — the centre it is drawn around, not the derived edge — so a
+ * selection can be pinned without re-deriving the neighbour spacing.
+ *
  * @throws RangeError if `column` does not exist.
  * @throws TypeError if `column` is not a numeric column.
  */

package/dist/data.js

@@ -1,4 +1,31 @@
 import { ValueSeries } from 'pond-ts';
+/**
+ * Assert `column` names an existing **numeric** column of `series`, returning
+ * it. The single source of the reader's two errors, so a caller that reads a
+ * column **per event** rather than buffering it — the time-axis `readout` path
+ * in `LineChart` / `AreaChart` — rejects a bad name identically to one that
+ * materializes. Without it a mistyped `readout` throws on a `ValueSeries` (via
+ * {@link readValueColumn}) but silently produced no readout on a `TimeSeries`,
+ * where the per-event `get()` just returns `undefined`.
+ *
+ * The `undefined` guard is runtime-necessary even though it reads as dead code:
+ * `column()` returns `undefined` for an unknown name at runtime, but core's
+ * public overload currently types the result as non-`undefined` (see F-3 in the
+ * M1 friction note). Keep it — the "throws on unknown column" tests exercise it.
+ *
+ * @throws RangeError if `column` does not exist.
+ * @throws TypeError if `column` is not a numeric column.
+ */
+export function assertNumericColumn(series, column) {
+    const col = series.column(column);
+    if (col === undefined) {
+        throw new RangeError(`unknown column '${column}'`);
+    }
+    if (col.kind !== 'number') {
+        throw new TypeError(`column '${column}' must be numeric (got '${col.kind}')`);
+    }
+    return col;
+}
 /**
  * Read a numeric column into a `Float64Array`, missing cells as `NaN`.
  *
@@ -15,17 +42,7 @@ import { ValueSeries } from 'pond-ts';
  * @throws TypeError if `column` is not a numeric column.
  */
 function readNumericColumn(series, column) {
-    // Runtime-necessary even though it reads as dead code: `column()` returns
-    // `undefined` for an unknown name at runtime, but core's public overload
-    // currently types the result as non-`undefined` (see F-3 in the M1 friction
-    // note). Keep the guard — the "throws on unknown column" test exercises it.
-    const col = series.column(column);
-    if (col === undefined) {
-        throw new RangeError(`unknown column '${column}'`);
-    }
-    if (col.kind !== 'number') {
-        throw new TypeError(`column '${column}' must be numeric (got '${col.kind}')`);
-    }
+    const col = assertNumericColumn(series, column);
     const length = series.length;
     const out = new Float64Array(length);
     for (let i = 0; i < length; i += 1) {
@@ -302,6 +319,43 @@ function neighbourSpans(axis, n) {
     }
     return { begin, end };
 }
+/**
+ * Attach the lazy stable per-bar identity to a bar view — see
+ * {@link BarSeries.marks}. `keys` is the **sample's own** axis buffer (the key
+ * column's `begin` for a `TimeSeries`, `axisValues()` for a `ValueSeries`), not
+ * the possibly-derived bar span, and must already be trimmed to `bars.length`.
+ *
+ * The strings are built on first read and then memoized. That is why this is a
+ * getter rather than an eager array: 100k bars is ~9 ms of string allocation on
+ * top of a ~0.8 ms reader, and eager would charge it to every chart on every
+ * data update, for a channel a non-interactive one never uses at all. An
+ * interactive chart *does* pay it, once per data identity, on its first hover
+ * over a bar — see {@link BarSeries.marks}. `scripts/perf-barmarks.mjs` pins
+ * both halves.
+ *
+ * The getter is deliberately **enumerable**, so a `{...bs}` spread carries the
+ * marks through (materializing them) rather than silently dropping them — a
+ * perf surprise beats a correctness one. Nothing in the package spreads a
+ * `BarSeries` today; this is for outside callers. If one ever appears **in the
+ * draw path**, it would force materialization on every frame — but
+ * `perf-barmarks.mjs`'s `marks untouched` row is measured on exactly that, so
+ * it would show up as a reader regression rather than pass silently.
+ */
+function withKeyMarks(bars, keys) {
+    let marks;
+    return {
+        ...bars,
+        get marks() {
+            if (marks === undefined) {
+                const out = new Array(bars.length);
+                for (let i = 0; i < bars.length; i += 1)
+                    out[i] = String(keys[i]);
+                marks = out;
+            }
+            return marks;
+        },
+    };
+}
 /**
  * Build a {@link BarSeries} from a pond `TimeSeries` — one bar per event, the
  * key's `[begin, end]` as the x-span and `column` as the height.
@@ -320,6 +374,10 @@ function neighbourSpans(axis, n) {
  * interval-keyed series (e.g. an `aggregate`/`window` rollup) draws its true
  * bucket spans. Detected by `keyColumn().kind === 'time'`.
  *
+ * Each bar also carries its **own key** as a stable {@link BarSeries.marks}
+ * identity, so a selection can be pinned on the sample rather than on the span
+ * this derived for it.
+ *
  * @throws RangeError if `column` does not exist.
  * @throws TypeError if `column` is not a numeric column.
  */
@@ -327,15 +385,15 @@ export function barsFromTimeSeries(series, column) {
     const y = readNumericColumn(series, column);
     const n = series.length;
     const kind = series.keyColumn().kind;
-    if (kind !== 'time') {
-        // Interval / timeRange: the key's own endpoints are the bar span.
-        const { begin, end } = keyBeginEnd(series);
-        return { begin, end, y, length: n };
-    }
-    // Point key (begin === end): synthesize a span from neighbour spacing so the
-    // bars have width (see neighbourSpans).
-    const { begin, end } = neighbourSpans(series.keyColumn().begin, n);
-    return { begin, end, y, length: n };
+    // Interval / timeRange: the key's own endpoints are the bar span. Point key
+    // (begin === end): synthesize a span from neighbour spacing so the bars have
+    // width (see neighbourSpans).
+    const { begin, end } = kind !== 'time'
+        ? keyBeginEnd(series)
+        : neighbourSpans(series.keyColumn().begin, n);
+    // The marks key on the event's own timestamp — which for a point key is the
+    // bar's *centre*, not the `begin` edge derived above (see BarSeries.marks).
+    return withKeyMarks({ begin, end, y, length: n }, timeAxis(series));
 }
 /**
  * Build a {@link BarSeries} from a pond `ValueSeries` — the value-axis sibling
@@ -353,6 +411,10 @@ export function barsFromTimeSeries(series, column) {
  * (a slight drift from a true segment edge — fine for the bar look; key an
  * interval/timeRange `TimeSeries` instead if exact edges matter).
  *
+ * Each bar also carries its **axis value** as a stable {@link BarSeries.marks}
+ * identity — the centre it is drawn around, not the derived edge — so a
+ * selection can be pinned without re-deriving the neighbour spacing.
+ *
  * @throws RangeError if `column` does not exist.
  * @throws TypeError if `column` is not a numeric column.
  */
@@ -361,8 +423,9 @@ export function barsFromValueSeries(series, column) {
     const n = series.length;
     // axisValues() is the monotonic key buffer (zero-copy); neighbourSpans reads it
     // and allocates fresh span buffers (never mutates the source).
-    const { begin, end } = neighbourSpans(series.axisValues(), n);
-    return { begin, end, y, length: n };
+    const axis = series.axisValues();
+    const { begin, end } = neighbourSpans(axis, n);
+    return withKeyMarks({ begin, end, y, length: n }, axis);
 }
 /**
  * The per-bin `[begin, end]` slots for a `TimeSeries`, key-shape aware — the same

package/dist/decimate.js

@@ -636,11 +636,11 @@ export function decimateBars(cs, xScale, ctx, baseline, k = 2, visibleCount = cs
 export function decimateScatter(cs, xScale, yScale, cellPx, vStart = 0, vEnd = cs.length) {
     const cell = cellPx > 0 ? cellPx : 1;
     // Affine fast path ([PND-AFFINE]) for the per-point pixel mapping the sweep
-    // needs — an inline `k·v + b` over the typed arrays instead of a d3-scale
-    // closure per point (each axis independently; a non-affine axis, e.g. a
-    // real-gap trading x, falls back to the exact scale call). Without this the
-    // sweep would re-introduce the per-point d3-scale cost the line/area paths
-    // shed, making the decimation's own cost dominate.
+    // needs — an inline rebased `(v − v0)·k + p0` over the typed arrays instead
+    // of a d3-scale closure per point (each axis independently; a non-affine
+    // axis, e.g. a real-gap trading x, falls back to the exact scale call).
+    // Without this the sweep would re-introduce the per-point d3-scale cost the
+    // line/area paths shed, making the decimation's own cost dominate.
     const ax = affineOf(xScale);
     const ay = affineOf(yScale);
     const outX = [];
@@ -652,13 +652,13 @@ export function decimateScatter(cs, xScale, yScale, cellPx, vStart = 0, vEnd = c
         if (!Number.isFinite(y))
             continue; // gap — no mark
         const xv = cs.x[i];
-        const px = ax !== null ? ax.k * xv + ax.b : xScale(xv);
+        const px = ax !== null ? (xv - ax.v0) * ax.k + ax.p0 : xScale(xv);
         const col = Math.floor(px / cell);
         if (col !== curCol) {
             rows.clear();
             curCol = col;
         }
-        const py = ay !== null ? ay.k * y + ay.b : yScale(y);
+        const py = ay !== null ? (y - ay.v0) * ay.k + ay.p0 : yScale(y);
         const row = Math.floor(py / cell);
         if (!rows.has(row)) {
             rows.add(row);