@pond-ts/charts 0.53.1 → 0.54.0

package/dist/AreaChart.d.ts

@@ -17,6 +17,14 @@ export interface AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extend
     series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric value column to fill from. */
     column: string;
+    /**
+     * Optional column to **read out** at the cursor instead of the plotted
+     * `column` — the area still fills `column`, but each tracker sample also
+     * carries this column's value as {@link TrackerSample.readout}, so an
+     * off-chart readout can show a **source** value while the area draws a derived
+     * one. Mirrors `<LineChart readout>`. **Omitted ⇒ no readout channel.**
+     */
+    readout?: string;
     /**
      * The series' semantic identifier — what the data _is_ / how it should read
      * (e.g. `elevation`, or a signed-traffic role like `in` / `out`). The theme
@@ -108,5 +116,5 @@ export interface AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extend
  * </Layers>
  * ```
  */
-export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, axis, baseline, curve, gaps, decimate, legend, index, }: AreaChartProps<S, VS>): null;
+export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, readout, as: semantic, axis, baseline, curve, gaps, decimate, legend, index, }: AreaChartProps<S, VS>): null;
 //# sourceMappingURL=AreaChart.d.ts.map

package/dist/AreaChart.js

@@ -1,6 +1,6 @@
 import { useContext, useEffect, useMemo } from 'react';
 import { ValueSeries } from 'pond-ts';
-import { fromTimeSeries, fromValueSeries } from './data.js';
+import { assertNumericColumn, fromTimeSeries, fromValueSeries, } from './data.js';
 import { areaExtent, drawArea } from './area.js';
 import { resolveCurve } from './curve.js';
 import { DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
@@ -36,7 +36,7 @@ function domainFloor(yScale) {
  * </Layers>
  * ```
  */
-export function AreaChart({ series, column, as: semantic, axis, baseline, curve, gaps = DEFAULT_GAP_MODE, decimate = true, legend, index = 0, }) {
+export function AreaChart({ series, column, readout, as: semantic, axis, baseline, curve, gaps = DEFAULT_GAP_MODE, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<AreaChart> must be rendered inside a <ChartContainer>');
@@ -48,6 +48,22 @@ export function AreaChart({ series, column, as: semantic, axis, baseline, curve,
     const cs = useMemo(() => series instanceof ValueSeries
         ? fromValueSeries(series, column)
         : fromTimeSeries(series, column), [series, column]);
+    // Readout column values for a value-axis series (time path reads it off the
+    // event) — the tracker reports it alongside the plotted fill so an off-chart
+    // readout can show a source value. See AreaChartProps.readout.
+    //
+    // The time path buffers nothing (it has an event, not an index), so it
+    // validates the name here instead, so a mistyped `readout` fails the same way
+    // on both axis kinds rather than throwing on one and silently doing nothing
+    // on the other. Mirrors `<LineChart>`.
+    const readoutY = useMemo(() => {
+        if (readout === undefined)
+            return undefined;
+        if (series instanceof ValueSeries)
+            return fromValueSeries(series, readout).y;
+        assertNumericColumn(series, readout);
+        return undefined;
+    }, [series, readout]);
     // Styling: semantic identifier → theme area style. The single styling channel.
     const { area } = container.theme;
     const style = (semantic !== undefined ? area[semantic] : undefined) ?? area.default;
@@ -77,8 +93,19 @@ export function AreaChart({ series, column, as: semantic, axis, baseline, curve,
                     if (i < 0)
                         return [];
                     const v = cs.y[i];
+                    const rv = readoutY?.[i];
                     return Number.isFinite(v)
-                        ? [{ x: cs.x[i], value: v, color: style.color, label }]
+                        ? [
+                            {
+                                x: cs.x[i],
+                                value: v,
+                                color: style.color,
+                                label,
+                                ...(rv !== undefined && Number.isFinite(rv)
+                                    ? { readout: rv }
+                                    : {}),
+                            },
+                        ]
                         : [];
                 }
                 const e = series.nearest(x);
@@ -87,11 +114,23 @@ export function AreaChart({ series, column, as: semantic, axis, baseline, curve,
                 // get() wants a literal key; column is a runtime string. Cast the
                 // *event* (not the method — that would detach `this`) to a
                 // string-keyed get; runtime-safe read + guard.
-                const v = e.get(column);
+                const ev = e;
+                const v = ev.get(column);
+                const rv = readout !== undefined ? ev.get(readout) : undefined;
                 // The readout dot rides the value line (not the baseline), coloured by
                 // the outline stroke. A gap yields no readout (like the fill).
                 return typeof v === 'number' && Number.isFinite(v)
-                    ? [{ x: e.begin(), value: v, color: style.color, label }]
+                    ? [
+                        {
+                            x: e.begin(),
+                            value: v,
+                            color: style.color,
+                            label,
+                            ...(typeof rv === 'number' && Number.isFinite(rv)
+                                ? { readout: rv }
+                                : {}),
+                        },
+                    ]
                     : [];
             },
             draw: (ctx, xScale, yScale) => drawArea(ctx, cs, xScale, yScale, style, 
@@ -106,6 +145,8 @@ export function AreaChart({ series, column, as: semantic, axis, baseline, curve,
         cs,
         series,
         column,
+        readout,
+        readoutY,
         style,
         label,
         baseline,

package/dist/BarChart.d.ts

@@ -68,14 +68,21 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
      */
     colors?: Readonly<Record<string, string>>;
     /**
-     * **Per-bin** colours for a single-series band chart — `binColors[i]` fills
-     * bar `i` (aligned to the bins / bands in order), overriding the `as`/theme
-     * fill. This is the way to colour heart-rate / power **zones** or value bands
-     * each their own colour (the `colors` map above is per-**group**, for stacks).
-     * An `undefined`/short entry falls back to the theme fill. Meant for a
-     * single-series chart (`column` + `bins`, or a horizontal single series); on a
+     * **Per-bar** colours for a single-series chart — `binColors[i]` fills bar
+     * `i` (aligned to the bars / bins in order), overriding the `as`/theme fill.
+     * This is the way to colour heart-rate / power **zones** or value bands each
+     * their own colour, and the **direction-coloured financial volume row** — a
+     * time-axis `series` derives `binColors` from its own data (rising / falling
+     * off open vs close) so volume bars read green / red under the candles (the
+     * `colors` map above is per-**group**, for stacks). An `undefined`/short
+     * entry falls back to the theme fill. Works on any **single-series** shape —
+     * a time / value `series` (vertical or horizontal) or `bins`; on a
      * multi-group stack it would tint every segment of a bin alike, so it's not
-     * the tool there.
+     * the tool there. A per-bar-coloured bar keeps its own colour under hover /
+     * selection (the highlight pops opacity instead of swapping the fill), and
+     * the hover / click readout reports the bar's own colour. **Disables the
+     * dense-bar envelope decimation** (see `decimate`) — an envelope rect can't
+     * carry many bars' colours, so every visible bar draws.
      */
     binColors?: readonly (string | undefined)[];
     /**
@@ -130,7 +137,9 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
      * at that density (a perf knob, not a style); interaction still reads the source
      * bars. Pass `false` to always draw every bar, or `{ threshold }` to tune the
      * samples-per-pixel factor. **No-op for a stacked / multi-group histogram** (the
-     * categorical case is low-count; only the single-series path decimates).
+     * categorical case is low-count; only the single-series path decimates) — and
+     * **no-op when `binColors` is set** (an envelope rect would repaint its bars
+     * one flat colour; a per-bar-coloured layer draws every visible bar).
      */
     decimate?: DecimateOption;
     /**

package/dist/BarChart.js

@@ -244,7 +244,9 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                             {
                                 x: (bs.begin[i] + bs.end[i]) / 2,
                                 value: v,
-                                color: singleStyle.fill,
+                                // A per-bar colour wins over the flat fill, so the readout
+                                // pill reads the bar's own colour (as the stacked path does).
+                                color: binColors?.[i] ?? singleStyle.fill,
                                 label,
                             },
                         ];
@@ -257,17 +259,27 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                                 const hit = barAt(bs, px, py, xScale, yScale, baseline, gapPx, singleStyle.minWidth);
                                 if (hit === null)
                                     return null;
-                                const [, begin, value] = hit;
+                                const [bi, begin, value] = hit;
+                                // The bar's stable `mark` (its own axis key) rides the
+                                // selection, so the highlight match and a controlled echo key
+                                // on the *sample* rather than on the `begin` edge — which on a
+                                // point-keyed series is derived geometry, not the sample's key
+                                // (see BarSeries.marks). `bi` is the exact bar index from the
+                                // hit, as the stacked path uses it.
+                                const stableMark = bs.marks?.[bi];
                                 return {
                                     id,
                                     key: begin,
                                     value,
-                                    color: singleStyle.fill,
+                                    // The bar's own colour when per-bar coloured (stacked-path
+                                    // parity: the readout pill matches the pixels).
+                                    color: binColors?.[bi] ?? singleStyle.fill,
                                     label,
+                                    ...(stableMark !== undefined ? { mark: stableMark } : {}),
                                 };
                             },
                         }),
-                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover, decimate),
+                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover, decimate, binColors),
                 },
                 axisId: axis,
                 index,
@@ -335,6 +347,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         orientation,
         singleStyle,
         stackStyle,
+        binColors,
         label,
         id,
         gapPx,

package/dist/LineChart.d.ts

@@ -18,6 +18,17 @@ export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extend
     series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric value column to plot. */
     column: string;
+    /**
+     * Optional column to **read out** at the cursor instead of the plotted
+     * `column`. The layer still plots `column`; each tracker sample additionally
+     * carries this column's value as {@link TrackerSample.readout}, so an
+     * off-chart readout can show the **source** value while the line draws a
+     * derived one — a smoothed / transformed / normalized plot with a raw-value
+     * readout (estela plots pace-space + Gaussian-smoothed, reads the native m/s).
+     * The plotted `value` (hence the in-chart cursor dot) is unchanged.
+     * **Omitted ⇒ no readout channel** (`readout` is `undefined` on the sample).
+     */
+    readout?: string;
     /**
      * The series' semantic identifier — what the data _is_ / how it should read
      * (e.g. `heartrate`, `power`, or a role name like `foam`). The theme maps it
@@ -94,5 +105,5 @@ export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extend
  * (scaling against its `axis`), and renders nothing to the DOM — the row draws
  * it. The line breaks at gaps rather than spanning them.
  */
-export declare function LineChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, axis, curve, gaps, sessionBreaks, decimate, legend, index, }: LineChartProps<S, VS>): null;
+export declare function LineChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, readout, as: semantic, axis, curve, gaps, sessionBreaks, decimate, legend, index, }: LineChartProps<S, VS>): null;
 //# sourceMappingURL=LineChart.d.ts.map

package/dist/LineChart.js

@@ -1,6 +1,6 @@
 import { useContext, useEffect, useMemo } from 'react';
 import { ValueSeries } from 'pond-ts';
-import { fromTimeSeries, fromValueSeries } from './data.js';
+import { assertNumericColumn, fromTimeSeries, fromValueSeries, } from './data.js';
 import { drawLine, yExtent } from './line.js';
 import { resolveCurve } from './curve.js';
 import { DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
@@ -16,7 +16,7 @@ const NO_BREAKS = [];
  * (scaling against its `axis`), and renders nothing to the DOM — the row draws
  * it. The line breaks at gaps rather than spanning them.
  */
-export function LineChart({ series, column, as: semantic, axis, curve, gaps = DEFAULT_GAP_MODE, sessionBreaks = false, decimate = true, legend, index = 0, }) {
+export function LineChart({ series, column, readout, as: semantic, axis, curve, gaps = DEFAULT_GAP_MODE, sessionBreaks = false, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<LineChart> must be rendered inside a <ChartContainer>');
@@ -28,6 +28,22 @@ export function LineChart({ series, column, as: semantic, axis, curve, gaps = DE
     const cs = useMemo(() => series instanceof ValueSeries
         ? fromValueSeries(series, column)
         : fromTimeSeries(series, column), [series, column]);
+    // Readout column values for a value-axis series (the time path reads it off
+    // the event in `sampleAt`). Built once per (series, readout) so the tracker
+    // can report a source value the line doesn't plot — see LineChartProps.readout.
+    //
+    // The time path buffers nothing (it has an event, not an index), so it
+    // validates the name here instead: otherwise a mistyped `readout` throws on a
+    // value axis but silently yields no readout on a time axis, and the same typo
+    // fails two different ways. Both now throw the reader's errors.
+    const readoutY = useMemo(() => {
+        if (readout === undefined)
+            return undefined;
+        if (series instanceof ValueSeries)
+            return fromValueSeries(series, readout).y;
+        assertNumericColumn(series, readout);
+        return undefined;
+    }, [series, readout]);
     // Styling: semantic identifier → theme style. The single styling channel.
     const { line } = container.theme;
     const style = (semantic !== undefined ? line[semantic] : undefined) ?? line.default;
@@ -68,8 +84,19 @@ export function LineChart({ series, column, as: semantic, axis, curve, gaps = DE
                     if (i < 0)
                         return [];
                     const v = cs.y[i];
+                    const rv = readoutY?.[i];
                     return Number.isFinite(v)
-                        ? [{ x: cs.x[i], value: v, color: style.color, label }]
+                        ? [
+                            {
+                                x: cs.x[i],
+                                value: v,
+                                color: style.color,
+                                label,
+                                ...(rv !== undefined && Number.isFinite(rv)
+                                    ? { readout: rv }
+                                    : {}),
+                            },
+                        ]
                         : [];
                 }
                 const e = series.nearest(x);
@@ -78,9 +105,21 @@ export function LineChart({ series, column, as: semantic, axis, curve, gaps = DE
                 // get() wants a literal key; column is a runtime string. Cast the
                 // *event* (not the method — that would detach `this`) to a
                 // string-keyed get; runtime-safe read + guard.
-                const v = e.get(column);
+                const ev = e;
+                const v = ev.get(column);
+                const rv = readout !== undefined ? ev.get(readout) : undefined;
                 return typeof v === 'number' && Number.isFinite(v)
-                    ? [{ x: e.begin(), value: v, color: style.color, label }]
+                    ? [
+                        {
+                            x: e.begin(),
+                            value: v,
+                            color: style.color,
+                            label,
+                            ...(typeof rv === 'number' && Number.isFinite(rv)
+                                ? { readout: rv }
+                                : {}),
+                        },
+                    ]
                     : [];
             },
             draw: (ctx, xScale, yScale) => drawLine(ctx, cs, xScale, yScale, style, curveFactory, gaps, gapConnectorOpacity, sessionBreakInstants, decimate),
@@ -91,6 +130,8 @@ export function LineChart({ series, column, as: semantic, axis, curve, gaps = DE
         cs,
         series,
         column,
+        readout,
+        readoutY,
         style,
         label,
         curveFactory,

package/dist/affine.d.ts

@@ -2,13 +2,25 @@
  * Affine-scale fast path (charts perf, [PND-AFFINE]). A chart's continuous
  * scales — `scaleLinear` (value axis, every y axis), `scaleTime`, and the
  * **gap-free** `scaleTradingTime(identityProvider())` (the default continuous
- * time axis) — map data→pixels by a single `px = k·v + b`. The per-point draw
- * loops in `drawLine` / `drawArea` can then multiply-add inline over the typed
+ * time axis) — map data→pixels affinely. The per-point draw loops in
+ * `drawLine` / `drawArea` can then evaluate the map inline over the typed
  * arrays instead of paying a d3-scale closure call (deinterpolate → interpolate)
  * per point — the ~37% of stroke-bound frame self-time the 2026-07 external
  * bench profile attributed to `scale()` (see
  * `docs/notes/charts-bench-vs-scichart-suite-2026-07.md`, finding 1).
  *
+ * The map is stored and evaluated in the **rebased** form
+ * `px = (v − v0)·k + p0` (v0 = the domain's low endpoint, p0 = scale(v0)) —
+ * the same association d3's own deinterpolate → interpolate uses — never
+ * expanded to `k·v + b`. The expanded form is catastrophically ill-conditioned
+ * on epoch-millisecond domains: with t ≈ 1.8e12 and a deeply zoomed window,
+ * `k·t` and `b` are huge near-cancelling terms whose rounding (½ ULP of `k·t`)
+ * survives the cancellation — ~0.16 px reconstruction error at a 1 ms window,
+ * ~24 px at 1 µs (measured). Under the expanded form the interior probe below
+ * caught that drift and *rejected* the scale, so deep-zoomed frames silently
+ * lost the fast path; the rebased form evaluates to ≲1e-9 px of the exact
+ * d3 path at every zoom depth, so the fast path stays engaged.
+ *
  * The affine coefficients are recovered from the scale's own domain/range
  * endpoints, then **verified affine** by probing interior points: a scale that
  * deviates (a `scaleTradingTime` with *collapsed* gaps, or a future
@@ -19,23 +31,32 @@
  * a straight line.
  */
 import type { Scale } from './line.js';
-/** Coefficients of an affine pixel map `px = k·value + b`. */
+/**
+ * Coefficients of an affine pixel map in rebased form:
+ * `px = (value − v0)·k + p0`. `v0` is the domain's low endpoint and `p0` its
+ * pixel image, so the multiply sees the O(span) offset `value − v0` (exact for
+ * in-domain values, by Sterbenz cancellation) rather than an O(1e12) absolute
+ * epoch value — see the module comment for why the expanded `k·value + b`
+ * form must not be reintroduced.
+ */
 export interface Affine {
     readonly k: number;
-    readonly b: number;
+    readonly v0: number;
+    readonly p0: number;
 }
 /**
- * The affine coefficients `{ k, b }` with `scale(v) === k·v + b` for all `v`, or
- * `null` when the scale is not affine over its domain (a real-gap
- * `scaleTradingTime`, a non-linear axis) or exposes no numeric domain/range (a
- * bare `(v) => v` test stub, a `scaleBand` category axis). `null` ⇒ the caller
- * keeps the d3-scale path.
+ * The affine coefficients `{ k, v0, p0 }` with `scale(v) === (v − v0)·k + p0`
+ * for all `v`, or `null` when the scale is not affine over its domain (a
+ * real-gap `scaleTradingTime`, a non-linear axis) or exposes no numeric
+ * domain/range (a bare `(v) => v` test stub, a `scaleBand` category axis).
+ * `null` ⇒ the caller keeps the d3-scale path.
  *
- * Recovered from the domain/range endpoints (`k` from the two extremes, `b`
- * pinning the low end), then verified at {@link PROBE_FRACTIONS}. Every probe
- * must map finite and within {@link PROBE_EPSILON} of the reconstruction — so a
- * scale that returns non-numbers for an interior value (a `scaleBand`) or bends
- * away from the endpoint line (trading gaps, log) is rejected.
+ * Recovered from the domain/range endpoints (`k` from the two extremes, the
+ * `(v0, p0)` base pinning the low end), then verified at
+ * {@link PROBE_FRACTIONS}. Every probe must map finite and within
+ * {@link PROBE_EPSILON} of the reconstruction — so a scale that returns
+ * non-numbers for an interior value (a `scaleBand`) or bends away from the
+ * endpoint line (trading gaps, log) is rejected.
  */
 export declare function affineOf(scale: Scale): Affine | null;
 //# sourceMappingURL=affine.d.ts.map

package/dist/affine.js

@@ -2,13 +2,25 @@
  * Affine-scale fast path (charts perf, [PND-AFFINE]). A chart's continuous
  * scales — `scaleLinear` (value axis, every y axis), `scaleTime`, and the
  * **gap-free** `scaleTradingTime(identityProvider())` (the default continuous
- * time axis) — map data→pixels by a single `px = k·v + b`. The per-point draw
- * loops in `drawLine` / `drawArea` can then multiply-add inline over the typed
+ * time axis) — map data→pixels affinely. The per-point draw loops in
+ * `drawLine` / `drawArea` can then evaluate the map inline over the typed
  * arrays instead of paying a d3-scale closure call (deinterpolate → interpolate)
  * per point — the ~37% of stroke-bound frame self-time the 2026-07 external
  * bench profile attributed to `scale()` (see
  * `docs/notes/charts-bench-vs-scichart-suite-2026-07.md`, finding 1).
  *
+ * The map is stored and evaluated in the **rebased** form
+ * `px = (v − v0)·k + p0` (v0 = the domain's low endpoint, p0 = scale(v0)) —
+ * the same association d3's own deinterpolate → interpolate uses — never
+ * expanded to `k·v + b`. The expanded form is catastrophically ill-conditioned
+ * on epoch-millisecond domains: with t ≈ 1.8e12 and a deeply zoomed window,
+ * `k·t` and `b` are huge near-cancelling terms whose rounding (½ ULP of `k·t`)
+ * survives the cancellation — ~0.16 px reconstruction error at a 1 ms window,
+ * ~24 px at 1 µs (measured). Under the expanded form the interior probe below
+ * caught that drift and *rejected* the scale, so deep-zoomed frames silently
+ * lost the fast path; the rebased form evaluates to ≲1e-9 px of the exact
+ * d3 path at every zoom depth, so the fast path stays engaged.
+ *
  * The affine coefficients are recovered from the scale's own domain/range
  * endpoints, then **verified affine** by probing interior points: a scale that
  * deviates (a `scaleTradingTime` with *collapsed* gaps, or a future
@@ -30,22 +42,25 @@ const PROBE_FRACTIONS = [0.1213, 0.2857, 0.4391, 0.6137, 0.7649, 0.8831];
 /**
  * Pixel tolerance for the affinity probe. Far below a sub-pixel (so a real
  * non-affine deviation — a collapsed trading gap or a log curve is many pixels)
- * yet far above the float-reconstruction noise of `k·v + b` on wide domains
- * (~1e-9 px), so an exactly-affine scale is never rejected.
+ * yet far above the float-reconstruction noise of the rebased
+ * `(v − v0)·k + p0` against d3's own evaluation (≲1e-9 px at any domain
+ * magnitude or zoom depth — both sides subtract the domain origin before
+ * multiplying), so an exactly-affine scale is never rejected.
  */
 const PROBE_EPSILON = 1e-3;
 /**
- * The affine coefficients `{ k, b }` with `scale(v) === k·v + b` for all `v`, or
- * `null` when the scale is not affine over its domain (a real-gap
- * `scaleTradingTime`, a non-linear axis) or exposes no numeric domain/range (a
- * bare `(v) => v` test stub, a `scaleBand` category axis). `null` ⇒ the caller
- * keeps the d3-scale path.
+ * The affine coefficients `{ k, v0, p0 }` with `scale(v) === (v − v0)·k + p0`
+ * for all `v`, or `null` when the scale is not affine over its domain (a
+ * real-gap `scaleTradingTime`, a non-linear axis) or exposes no numeric
+ * domain/range (a bare `(v) => v` test stub, a `scaleBand` category axis).
+ * `null` ⇒ the caller keeps the d3-scale path.
  *
- * Recovered from the domain/range endpoints (`k` from the two extremes, `b`
- * pinning the low end), then verified at {@link PROBE_FRACTIONS}. Every probe
- * must map finite and within {@link PROBE_EPSILON} of the reconstruction — so a
- * scale that returns non-numbers for an interior value (a `scaleBand`) or bends
- * away from the endpoint line (trading gaps, log) is rejected.
+ * Recovered from the domain/range endpoints (`k` from the two extremes, the
+ * `(v0, p0)` base pinning the low end), then verified at
+ * {@link PROBE_FRACTIONS}. Every probe must map finite and within
+ * {@link PROBE_EPSILON} of the reconstruction — so a scale that returns
+ * non-numbers for an interior value (a `scaleBand`) or bends away from the
+ * endpoint line (trading gaps, log) is rejected.
  */
 export function affineOf(scale) {
     const s = scale;
@@ -63,15 +78,17 @@ export function affineOf(scale) {
     if (!Number.isFinite(pLo) || !Number.isFinite(pHi))
         return null;
     const k = (pHi - pLo) / (hi - lo);
-    const b = pLo - k * lo;
     const span = hi - lo;
     for (const t of PROBE_FRACTIONS) {
         const v = lo + t * span;
         const p = scale(v);
-        if (!Number.isFinite(p) || Math.abs(p - (k * v + b)) > PROBE_EPSILON) {
+        // Probe the exact rebased expression the draw loops evaluate, so what is
+        // verified is what runs.
+        if (!Number.isFinite(p) ||
+            Math.abs(p - ((v - lo) * k + pLo)) > PROBE_EPSILON) {
             return null;
         }
     }
-    return { k, b };
+    return { k, v0: lo, p0: pLo };
 }
 //# sourceMappingURL=affine.js.map

package/dist/area.js

@@ -65,8 +65,8 @@ export function fillAffineArea(ctx, xs, ys, baselinePx, ax, ay) {
     for (let j = 0; j <= n; j += 1) {
         const finite = j < n && Number.isFinite(ys[j]);
         if (finite) {
-            const px = ax.k * xs[j] + ax.b;
-            const py = ay.k * ys[j] + ay.b;
+            const px = (xs[j] - ax.v0) * ax.k + ax.p0;
+            const py = (ys[j] - ay.v0) * ay.k + ay.p0;
             if (runStart < 0) {
                 runStart = j;
                 ctx.moveTo(px, py);
@@ -78,8 +78,8 @@ export function fillAffineArea(ctx, xs, ys, baselinePx, ax, ay) {
         else if (runStart >= 0) {
             // Close the run: drop to the baseline under the last point, run flat back
             // to the first point's x, close. (j-1 is the run's last finite index.)
-            ctx.lineTo(ax.k * xs[j - 1] + ax.b, baselinePx);
-            ctx.lineTo(ax.k * xs[runStart] + ax.b, baselinePx);
+            ctx.lineTo((xs[j - 1] - ax.v0) * ax.k + ax.p0, baselinePx);
+            ctx.lineTo((xs[runStart] - ax.v0) * ax.k + ax.p0, baselinePx);
             ctx.closePath();
             runStart = -1;
         }

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