@pond-ts/charts 0.57.0 → 0.58.0

package/dist/ohlc.js

@@ -1,6 +1,17 @@
 import { barSpanPx } from './range.js';
 import { visibleSpanRange } from './culling.js';
 import { decimateOhlc } from './decimate.js';
+import { spanMatchesAny } from './span.js';
+const NO_KEYS = [];
+const NO_SPANS = [];
+/** Linear scan — a selected/hovered set is a handful, not a collection. */
+function includesKey(keys, key) {
+    for (let i = 0; i < keys.length; i += 1) {
+        if (keys[i] === key)
+            return true;
+    }
+    return false;
+}
 /** 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. */
@@ -90,7 +101,37 @@ 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, decimate = true) {
+/**
+ * The candle whose **slot** contains `(px, py)` — the same rect-containment
+ * `boxAt` does, over the candle's full `[x0, x1] × [high, low]` extent.
+ *
+ * Deliberately the slot and not the ink. A candle's body can be a doji a
+ * pixel tall and its wick is a hairline; requiring the pointer to land on
+ * drawn pixels would make most candles unclickable. (That the box layer makes
+ * the same choice *without* saying so is [PND-BOXHIT].)
+ */
+export function ohlcAt(ohlc, px, py, xScale, yScale, gapPx, minWidthPx) {
+    for (let i = 0; i < ohlc.length; i += 1) {
+        if (!isFiniteOhlc(ohlc, i))
+            continue;
+        const [x0, x1] = barSpanPx(ohlc.x[i], ohlc.xEnd[i], xScale, gapPx, minWidthPx);
+        if (px < x0 || px > x1)
+            continue;
+        const yHigh = yScale(ohlc.high[i]);
+        const yLow = yScale(ohlc.low[i]);
+        const top = Math.min(yHigh, yLow);
+        const bottom = Math.max(yHigh, yLow);
+        if (py < top || py > bottom)
+            continue;
+        return [i, ohlc.x[i], ohlc.close[i]];
+    }
+    return null;
+}
+export function drawCandles(ctx, ohlc, xScale, yScale, style, variant = 'candle', colorBy = 'direction', gapPx = 0, minWidthPx = 1, decimate = true, 
+/** Candle keys (each candle's `x`) currently selected / hovered, and the
+ *  selection's span entries — the same three channels the bar and box draws
+ *  take. Empty ⇒ a display-only candle, byte-identical to before. */
+selectedKeys = NO_KEYS, hoveredKeys = NO_KEYS, spans = NO_SPANS) {
     const bodyFraction = style.bodyWidth ?? DEFAULT_BODY_WIDTH;
     const sourceCount = ohlc.length; // pre-cull, pre-decimation (for draw stats)
     // Viewport cull first (Phase 2): the [vStart, vEnd) candles whose span overlaps
@@ -128,11 +169,47 @@ export function drawCandles(ctx, ohlc, xScale, yScale, style, variant = 'candle'
         const yLow = yScale(ohlc.low[i]);
         const yClose = yScale(close);
         const { body, wick } = resolveCandleStyle(style, open, close, colorBy);
+        // **State without hue.** A candle's colour *is* its direction, so a
+        // selected candle keeps its own body/wick and takes an outline around the
+        // slot instead; the field recedes by opacity, and the wick — the mark's
+        // hairline — gains weight. A decimated aggregate candle carries synthetic
+        // keys no mark entry can name, so per-candle state is gated off there (as
+        // the box draw does) rather than lighting a column the selection never
+        // held.
+        const key = ohlc.x[i];
+        const isSelected = !decimated &&
+            (includesKey(selectedKeys, key) ||
+                (spans.length > 0 && spanMatchesAny(spans, key, close)));
+        const isHovered = !decimated && !isSelected && includesKey(hoveredKeys, key);
+        const dimming = style.dimmedOpacity !== undefined &&
+            !decimated &&
+            (selectedKeys.length > 0 || spans.length > 0);
+        const recede = dimming && !isSelected && !isHovered;
+        // Live = hovered or selected. Both look the same on the mark itself; what
+        // separates them is that a *selection* recedes everything else.
+        const live = isSelected || isHovered;
+        const wickW = live && style.liveWickWidth !== undefined
+            ? style.liveWickWidth
+            : style.wickWidth;
+        // A live candle **grows** rather than gaining anything new: its body is
+        // stroked in its own colour, so the mark thickens by the stroke and
+        // nothing else changes. An outline around the *slot* was the first attempt
+        // and it redraws the mark's whole footprint — far too loud for a hover,
+        // and it invents a rectangle the chart otherwise never shows.
+        const grow = live && style.liveWickWidth !== undefined;
+        // Bracket only when the field recedes, so a chart with no selection emits
+        // exactly the op stream it always did.
+        const bracketed = recede;
+        if (bracketed) {
+            ctx.save();
+            if (recede)
+                ctx.globalAlpha = style.dimmedOpacity;
+        }
         if (variant === 'bar') {
             // OHLC bar: a high–low stem, a left tick at open, a right tick at close —
             // all one colour (the `body` role), no filled body.
             ctx.strokeStyle = body;
-            ctx.lineWidth = style.wickWidth;
+            ctx.lineWidth = wickW;
             ctx.beginPath();
             ctx.moveTo(mid, yHigh); // stem
             ctx.lineTo(mid, yLow);
@@ -141,12 +218,16 @@ export function drawCandles(ctx, ohlc, xScale, yScale, style, variant = 'candle'
             ctx.moveTo(mid, yClose); // close tick (points right)
             ctx.lineTo(mid + bodyHalf, yClose);
             ctx.stroke();
+            // The `bar` variant has no body to grow; its lines already thickened
+            // above, which is the whole cue there.
+            if (bracketed)
+                ctx.restore();
             continue;
         }
         // candle / hollow: the high–low wick first (so the body overlaps it), then
         // the open→close body.
         ctx.strokeStyle = wick;
-        ctx.lineWidth = style.wickWidth;
+        ctx.lineWidth = wickW;
         ctx.beginPath();
         ctx.moveTo(mid, yHigh);
         ctx.lineTo(mid, yLow);
@@ -163,14 +244,22 @@ export function drawCandles(ctx, ohlc, xScale, yScale, style, variant = 'candle'
         // so a doji's fill and its colour agree.
         const hollow = variant === 'hollow' && close > open;
         if (hollow) {
+            // Already an outline — `wickW` is the growth.
             ctx.strokeStyle = body;
-            ctx.lineWidth = style.wickWidth;
+            ctx.lineWidth = wickW;
             ctx.strokeRect(bx0, top, bodyW, h);
         }
         else {
             ctx.fillStyle = body;
             ctx.fillRect(bx0, top, bodyW, h);
+            if (grow) {
+                ctx.strokeStyle = body;
+                ctx.lineWidth = wickW;
+                ctx.strokeRect(bx0, top, bodyW, h);
+            }
         }
+        if (bracketed)
+            ctx.restore();
     }
     // `drawnCount` = candle slots iterated (visible span, or the aggregate set when
     // decimation engaged); `sourceCount` = the raw candle count it started from.

package/dist/scatter.d.ts

@@ -2,7 +2,7 @@ import type { ChartSeries } from './data.js';
 import type { Scale } from './line.js';
 import type { ScatterStyle } from './theme.js';
 import type { ResolvedEncoding } from './encoding.js';
-import type { SelectInfo, LayerDrawStats } from './context.js';
+import type { SelectInfo, LayerDrawStats, SpanSelection } from './context.js';
 import { type DecimateOption } from './decimate.js';
 /**
  * Index of the point in `cs` **nearest** `time` by `|x − time|`, restricted to
@@ -29,11 +29,18 @@ export declare function scatterExtent(cs: ChartSeries): [number, number] | null;
  * coloured by `encoding` (data-driven radius / colour) over `style`. A gap
  * (non-finite y) draws nothing — points are discrete, there is no path to break.
  *
- * The **selected** point (when `selected` matches this layer's `label` *and* a
- * point's `begin` key) is restroked with the style's wider highlight ring after
- * the base pass, so it lifts above its neighbours regardless of draw order.
- * Matching on both key and label is what keeps two series sharing a timestamp
- * from both lighting up (the container's selection contract).
+ * **Every selected** point (each `selected` member matching this layer's
+ * `seriesId` *and* a point's `begin` key) is restroked with the style's wider
+ * highlight ring after the base pass, so it lifts above its neighbours
+ * regardless of draw order; every **hovered** point takes the same ring at
+ * {@link HOVER_RING_ALPHA}. Matching on both key and series id is what keeps two
+ * series sharing a timestamp from both lighting up (the container's selection
+ * contract). A point in both sets reads as **selected** — the precedence
+ * `drawBars` / `drawStacks` / `drawBox` share.
+ *
+ * Both are **sets**: `selected` has been one since [PND-MULTISEL] and `hovered`
+ * since RFC A4.3, so a pinned group of points, or a drag-sweep lighting several
+ * at once, rings all of them rather than only the set's first member.
  *
  * Each circle is its own `beginPath`/`arc`/`fill`/`stroke`; `save`/`restore`
  * brackets the whole pass so fill/stroke state doesn't leak into later layers.
@@ -44,16 +51,17 @@ export declare function scatterExtent(cs: ChartSeries): [number, number] | null;
  *                usually `(i) => cs.x[i]`.
  * @param labelAt optional per-point text label; `undefined` ⇒ no labels drawn.
  * @param font    `theme.font` (family + size) for label text.
- * @param selected the container's current selection (or `null`).
+ * @param selected the container's current selection set (empty ⇒ none).
+ * @param hovered  the container's current hover set (empty ⇒ none).
  * @param seriesId this layer's stable series identity (its `id` prop, or
  *                `undefined` when the layer isn't selectable) — the series half
- *                of the selection match. A point lights only when the selection's
+ *                of the selection match. A point lights only when a member's
  *                `id` matches, keyed to the sample by its `key`.
  */
 export declare function drawScatter(ctx: CanvasRenderingContext2D, cs: ChartSeries, xScale: Scale, yScale: Scale, style: ScatterStyle, encoding: ResolvedEncoding, keyAt: (i: number) => number, labelAt: ((i: number) => string | undefined) | undefined, font: {
     readonly family: string;
     readonly size: number;
-}, selected: SelectInfo | null, seriesId: string | undefined, offsetPx?: number, decimate?: DecimateOption): LayerDrawStats;
+}, selected: readonly SelectInfo[], hovered: readonly SelectInfo[], seriesId: string | undefined, offsetPx?: number, decimate?: DecimateOption, spans?: readonly SpanSelection[]): LayerDrawStats;
 /**
  * Hit-test plot-pixel `(qx, qy)` against the scatter's points — the topmost
  * point whose circle contains the click, or `null`. "Topmost" = the

package/dist/scatter.js

@@ -1,4 +1,5 @@
 import { visiblePointRange } from './culling.js';
+import { NO_SPANS, spanMatchesAny } from './span.js';
 import { shouldDecimateCount, decimateScatter, isOpaqueColor, } from './decimate.js';
 /**
  * Scatter geometry + the canvas draw — pure, like {@link drawLine} /
@@ -20,6 +21,73 @@ import { shouldDecimateCount, decimateScatter, isOpaqueColor, } from './decimate
 function isPoint(cs, i) {
     return Number.isFinite(cs.y[i]);
 }
+/**
+ * The alpha a **hovered** point's ring draws at, against the selected ring's
+ * full strength. Same two-step signal `drawBox` uses, and for the same reason:
+ * a {@link ScatterStyle} carries one highlight ring (`selectedOutline` /
+ * `selectedWidth`) and no hover token, so hover reads as a fainter version of
+ * the same ring rather than inventing a theme value the library would have to
+ * pick a colour for.
+ */
+const HOVER_RING_ALPHA = 0.5;
+/**
+ * Does **any** member of `set` name this series at all? A cheap gate so a draw
+ * with a selection belonging to some other layer — the common case on a
+ * multi-layer row — never pays the per-point key lookup.
+ */
+function namesSeries(set, seriesId) {
+    if (seriesId === undefined)
+        return false; // a no-id layer is never selectable
+    for (let i = 0; i < set.length; i += 1) {
+        if (set[i].id === seriesId)
+            return true;
+    }
+    return false;
+}
+/**
+ * Does any member of `set` identify the point of `seriesId` keyed `key`? The set
+ * form of the single `selected.key === keyAt(i)` test this draw used to make
+ * ([PND-MULTISEL] / RFC A4.3).
+ *
+ * A point's identity within its series **is** its key (a scatter reports no
+ * `SelectInfo.mark`), so `(id, key)` is the whole match. Linear over the set for
+ * the reason `barMatchesAny` records: a selection is a handful of marks a person
+ * clicked, and a `Set` per draw would cost more than it saves.
+ */
+function marksPoint(set, seriesId, key) {
+    for (let i = 0; i < set.length; i += 1) {
+        const m = set[i];
+        if (m.id === seriesId && m.key === key)
+            return true;
+    }
+    return false;
+}
+/**
+ * Past this many entries a per-draw key index beats the linear scan above.
+ * Mirrors `bars.ts`'s threshold, and exists for the same reason: `marksPoint`
+ * is written for "a handful of marks a person clicked", and a **sweep
+ * preview is not that**. A rect drag lights its whole covered region through
+ * the plural `hovered`, so the scan becomes O(V · |hovered|) — the A8.1 shape
+ * that measured **4.0 s per frame** here at 100k points with 50k covered,
+ * against the 1-D band's 6.2 s that motivated the bar index in the first
+ * place. Small enough that a sweep always indexes; big enough that a clicked
+ * handful never pays the Set build.
+ */
+const MARK_INDEX_THRESHOLD = 16;
+/**
+ * {@link marksPoint} in set form. A point's identity within its series **is**
+ * its key (a scatter reports no `SelectInfo.mark`), so unlike the bar index
+ * this is one set, not three.
+ */
+function buildKeyIndex(set, seriesId) {
+    const keys = new Set();
+    for (let i = 0; i < set.length; i += 1) {
+        const m = set[i];
+        if (m.id === seriesId)
+            keys.add(m.key);
+    }
+    return keys;
+}
 /**
  * Index of the point in `cs` **nearest** `time` by `|x − time|`, restricted to
  * finite points, or `-1` if none. `cs.x` is the sorted time axis, so a binary
@@ -97,11 +165,18 @@ export function scatterExtent(cs) {
  * coloured by `encoding` (data-driven radius / colour) over `style`. A gap
  * (non-finite y) draws nothing — points are discrete, there is no path to break.
  *
- * The **selected** point (when `selected` matches this layer's `label` *and* a
- * point's `begin` key) is restroked with the style's wider highlight ring after
- * the base pass, so it lifts above its neighbours regardless of draw order.
- * Matching on both key and label is what keeps two series sharing a timestamp
- * from both lighting up (the container's selection contract).
+ * **Every selected** point (each `selected` member matching this layer's
+ * `seriesId` *and* a point's `begin` key) is restroked with the style's wider
+ * highlight ring after the base pass, so it lifts above its neighbours
+ * regardless of draw order; every **hovered** point takes the same ring at
+ * {@link HOVER_RING_ALPHA}. Matching on both key and series id is what keeps two
+ * series sharing a timestamp from both lighting up (the container's selection
+ * contract). A point in both sets reads as **selected** — the precedence
+ * `drawBars` / `drawStacks` / `drawBox` share.
+ *
+ * Both are **sets**: `selected` has been one since [PND-MULTISEL] and `hovered`
+ * since RFC A4.3, so a pinned group of points, or a drag-sweep lighting several
+ * at once, rings all of them rather than only the set's first member.
  *
  * Each circle is its own `beginPath`/`arc`/`fill`/`stroke`; `save`/`restore`
  * brackets the whole pass so fill/stroke state doesn't leak into later layers.
@@ -112,21 +187,65 @@ export function scatterExtent(cs) {
  *                usually `(i) => cs.x[i]`.
  * @param labelAt optional per-point text label; `undefined` ⇒ no labels drawn.
  * @param font    `theme.font` (family + size) for label text.
- * @param selected the container's current selection (or `null`).
+ * @param selected the container's current selection set (empty ⇒ none).
+ * @param hovered  the container's current hover set (empty ⇒ none).
  * @param seriesId this layer's stable series identity (its `id` prop, or
  *                `undefined` when the layer isn't selectable) — the series half
- *                of the selection match. A point lights only when the selection's
+ *                of the selection match. A point lights only when a member's
  *                `id` matches, keyed to the sample by its `key`.
  */
-export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, selected, seriesId, offsetPx = 0, decimate = true) {
+export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, selected, hovered, seriesId, offsetPx = 0, decimate = true, 
+// Span descriptors covering this layer (interaction RFC A5.2), already
+// narrowed to its `id` (and constant-label `rows` resolved) by the component
+// — see `spansForLayer`. A point is selected when a mark entry names it OR a
+// span contains it: the O(1) half-open test of its key against `x` and — the
+// continuous 2-D case, RFC A3.3/A5.3 — its value against `y` when present.
+// Tested at the point's data position, per A7.6: centre-in-rect, not
+// disc-intersects-rect. Ignored on the decimated path, like the mark rings.
+spans = NO_SPANS) {
     ctx.save();
-    // The selection only lights up a point of *this* series; resolve the key once.
-    // A no-id (non-selectable) layer passes `undefined` and never matches.
-    const selectedKey = selected !== null && selected.id === seriesId ? selected.key : null;
-    let selPx = 0;
-    let selPy = 0;
-    let selR = 0;
-    let selHit = false;
+    // Either set only lights up points of *this* series; settle that once so the
+    // point loop can skip the key lookup entirely when neither names us. A no-id
+    // (non-selectable) layer passes `undefined` and never matches (`spans` is
+    // narrowed to this layer before the call, so its gate is just "any").
+    const anySelected = namesSeries(selected, seriesId);
+    const anyHovered = namesSeries(hovered, seriesId);
+    // Index the big sets once per draw, scan the small ones — see
+    // `MARK_INDEX_THRESHOLD`. Only the live-preview path ever reaches the
+    // threshold, so a clicked selection still allocates nothing.
+    const selIx = anySelected && selected.length > MARK_INDEX_THRESHOLD
+        ? buildKeyIndex(selected, seriesId)
+        : null;
+    const hovIx = anyHovered && hovered.length > MARK_INDEX_THRESHOLD
+        ? buildKeyIndex(hovered, seriesId)
+        : null;
+    const anySpan = spans.length > 0;
+    // Ring geometry, deferred to a pass after the marks so a highlight is never
+    // overpainted by a neighbour drawn later. Flat `[px, py, r, …]` triples, and
+    // **allocated only on the first hit** — the resting frame (nothing selected,
+    // nothing hovered) still allocates nothing per draw, which is the property the
+    // old pair of scalars had and the reason this isn't an array of objects.
+    let selRings = null;
+    let hovRings = null;
+    // The state ladder, or `undefined` for the pre-states behaviour — in which
+    // case every branch below it is inert and the op stream is unchanged.
+    const st = style.states;
+    // The radii arrive in px against the base radius and are applied as the
+    // RATIO between them, so a data-driven `radius` encoding still grows and
+    // shrinks proportionally instead of collapsing to one size when it goes
+    // live. `style.radius` is what an unencoded point already draws at, so on
+    // the uniform path these land exactly on the token's px value.
+    const hoverK = st === undefined ? 1 : st.hoverRadius / style.radius;
+    const dimK = st === undefined ? 1 : st.dimmedRadius / style.radius;
+    // A **committed** selection is what recedes the rest of the field; a hover
+    // is not, or the whole plot would flicker under an ordinary mousemove.
+    //
+    // Note this is all-or-nothing across the base loop: every point that is not
+    // live is dimmed, and live points leave the loop entirely, so the alpha is
+    // set ONCE around the loop rather than toggled per point. Bracketed in its
+    // own `save`/`restore` (the `drawBox` ladder's discipline) so a draw with
+    // nothing selected emits exactly the op stream it always did.
+    const dimming = st !== undefined && (anySelected || anySpan);
     // 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
@@ -164,9 +283,10 @@ export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, lab
     // overlapping cluster to one representative per mark-radius cell (2D
     // occupancy — {@link decimateScatter}). Visually lossless at that density, and
     // O(visible). Interaction is unaffected ({@link hitTestScatter} still walks
-    // every source point); the selection ring and per-point labels are dropped on
-    // this path — both are illegible under a dense blob — matching the decimated
-    // bar path. Data-driven size/colour (`!encoding.uniform`) or a translucent
+    // every source point); the selection / hover rings and per-point labels are
+    // dropped on this path — all are illegible under a dense blob — matching the
+    // decimated bar path (and `drawHeat`, which suppresses its cell outlines for
+    // the same reason). Data-driven size/colour (`!encoding.uniform`) or a translucent
     // fill (density-encoded, where overlap *should* build up) keep the full draw.
     const visibleCount = vEnd - vStart;
     const k = typeof decimate === 'object' && decimate.threshold !== undefined
@@ -213,6 +333,10 @@ export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, lab
         }
     }
     let drawn = 0;
+    if (dimming) {
+        ctx.save();
+        ctx.globalAlpha = st.dimmedOpacity;
+    }
     for (let i = vStart; i < vEnd; i += 1) {
         if (!isPoint(cs, i))
             continue;
@@ -222,8 +346,37 @@ export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, lab
         const px = xScale(cs.x[i]) + offsetPx;
         const py = yScale(cs.y[i]);
         const r = encoding.radiusAt(i);
+        // Which state this point is in. Selection (a mark entry naming it, or a
+        // span containing it) is tested first and wins outright, so a point that
+        // is both never draws twice.
+        let live = 0; // 0 = neither, 1 = hovered, 2 = selected
+        if (anySelected || anyHovered || anySpan) {
+            const key = keyAt(i);
+            if ((anySelected &&
+                (selIx !== null
+                    ? selIx.has(key)
+                    : marksPoint(selected, seriesId, key))) ||
+                (anySpan && spanMatchesAny(spans, key, cs.y[i]))) {
+                live = 2;
+            }
+            else if (anyHovered &&
+                (hovIx !== null ? hovIx.has(key) : marksPoint(hovered, seriesId, key))) {
+                live = 1;
+            }
+        }
+        // A live point is **deferred whole** under `states`, not just its ring:
+        // its fill and radius both change, so drawing the mark here and only its
+        // ring later would let a resting neighbour drawn afterwards paint over
+        // the grown body it belongs to.
+        if (live !== 0) {
+            (live === 2 ? (selRings ??= []) : (hovRings ??= [])).push(px, py, st !== undefined && live === 1 ? r * hoverK : r);
+            if (st !== undefined)
+                continue;
+        }
         ctx.beginPath();
-        ctx.arc(px, py, r, 0, Math.PI * 2);
+        // Outside a non-empty selection a point shrinks as well as fading — see
+        // `dimmedRadius`; the alpha itself is set once, around the loop.
+        ctx.arc(px, py, dimming ? r * dimK : r, 0, Math.PI * 2);
         ctx.fillStyle = encoding.colorAt(i);
         ctx.fill();
         if (style.outlineWidth > 0) {
@@ -231,22 +384,32 @@ export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, lab
             ctx.strokeStyle = style.outline;
             ctx.stroke();
         }
-        // Defer the selected point's highlight ring to a second pass so it sits on
-        // top of any neighbour drawn after it.
-        if (selectedKey !== null && keyAt(i) === selectedKey) {
-            selPx = px;
-            selPy = py;
-            selR = r;
-            selHit = true;
+    }
+    if (dimming)
+        ctx.restore();
+    // The live marks, after the base pass — always on top. Hover first, then
+    // selection over it, so the fainter state never paints over the committed
+    // one where two marks overlap.
+    if (hovRings !== null) {
+        ctx.save();
+        if (st !== undefined)
+            fillMarks(ctx, hovRings, st.hover, st.halo, st);
+        else {
+            ctx.globalAlpha = HOVER_RING_ALPHA;
+            ctx.lineWidth = style.selectedWidth;
+            ctx.strokeStyle = style.selectedOutline;
+            strokeRings(ctx, hovRings);
         }
+        ctx.restore();
     }
-    // Highlight ring for the selected point (after the base pass — always on top).
-    if (selHit) {
-        ctx.beginPath();
-        ctx.arc(selPx, selPy, selR, 0, Math.PI * 2);
-        ctx.lineWidth = style.selectedWidth;
-        ctx.strokeStyle = style.selectedOutline;
-        ctx.stroke();
+    if (selRings !== null) {
+        if (st !== undefined)
+            fillMarks(ctx, selRings, st.selected, st.halo, st);
+        else {
+            ctx.lineWidth = style.selectedWidth;
+            ctx.strokeStyle = style.selectedOutline;
+            strokeRings(ctx, selRings);
+        }
     }
     // Optional per-point labels, after all marks so text isn't overpainted.
     if (labelAt !== undefined) {
@@ -275,6 +438,31 @@ export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, lab
 }
 /** Gap (px) between a point's edge and its label text. */
 const LABEL_GAP = 4;
+/** Stroke one circle per `[px, py, r]` triple of `rings`. The caller owns the
+ *  stroke state (colour / width / alpha), so both highlight passes set it once
+ *  rather than per ring. */
+/** Draw one live mark per `[px, py, r]` triple — the `states` path's second
+ *  pass: a filled disc in the state's colour, ringed by the halo that keeps
+ *  overlapping same-coloured points countable. */
+function fillMarks(ctx, marks, fill, halo, st) {
+    ctx.fillStyle = fill;
+    ctx.lineWidth = st.haloWidth;
+    ctx.strokeStyle = halo;
+    for (let j = 0; j < marks.length; j += 3) {
+        ctx.beginPath();
+        ctx.arc(marks[j], marks[j + 1], marks[j + 2], 0, Math.PI * 2);
+        ctx.fill();
+        if (st.haloWidth > 0)
+            ctx.stroke();
+    }
+}
+function strokeRings(ctx, rings) {
+    for (let j = 0; j < rings.length; j += 3) {
+        ctx.beginPath();
+        ctx.arc(rings[j], rings[j + 1], rings[j + 2], 0, Math.PI * 2);
+        ctx.stroke();
+    }
+}
 /**
  * Hit-test plot-pixel `(qx, qy)` against the scatter's points — the topmost
  * point whose circle contains the click, or `null`. "Topmost" = the

package/dist/select.d.ts

@@ -1,13 +1,21 @@
 import type { LayerEntry, SelectInfo } from './context.js';
 /**
- * Resolve a click at plot-pixel `(px, py)` to the selected mark, or `null`.
- * Walks the row's layers **top-down** (reverse z-order — the topmost mark wins,
- * matching what the user sees) and returns the first `hitTest` hit. A layer with
- * no `hitTest` (line / band / area) or no resolvable y-scale is skipped.
+ * Resolve a pointer position at plot-pixel `(px, py)` to the mark under it, or
+ * `null`. Walks the row's layers **top-down** (reverse z-order — the topmost
+ * mark wins, matching what the user sees) and returns the first `hitTest` hit.
+ * A layer with no `hitTest` (line / band / area) or no resolvable y-scale is
+ * skipped.
+ *
+ * `mode` (default `'hover'`) is forwarded to each layer's `hitTest`: hover may
+ * attribute a generous target (a bar's whole slot — the continuous-highlight
+ * model), while `'select'` — the click path — must leave genuinely empty plot
+ * space resolving to `null`, because that `null` **is** the deselect signal
+ * (RFC §7: a click on no mark is the empty-commit path). See
+ * {@link RowLayer.hitTest}.
  *
  * Pure, given the row's `xScale` and a per-axis y-scale lookup — so the click
  * dispatch in `Layers` unit-tests without a DOM. (Layers passes its sorted
  * z-stack, the shared `xScale`, and its `axisId → yScale` resolver.)
  */
-export declare function resolveSelection(entries: readonly LayerEntry[], px: number, py: number, xScale: (value: number) => number, yScaleFor: (axisId: string | undefined) => ((value: number) => number) | undefined): SelectInfo | null;
+export declare function resolveSelection(entries: readonly LayerEntry[], px: number, py: number, xScale: (value: number) => number, yScaleFor: (axisId: string | undefined) => ((value: number) => number) | undefined, mode?: 'hover' | 'select'): SelectInfo | null;
 //# sourceMappingURL=select.d.ts.map

package/dist/select.js

@@ -1,20 +1,28 @@
 /**
- * Resolve a click at plot-pixel `(px, py)` to the selected mark, or `null`.
- * Walks the row's layers **top-down** (reverse z-order — the topmost mark wins,
- * matching what the user sees) and returns the first `hitTest` hit. A layer with
- * no `hitTest` (line / band / area) or no resolvable y-scale is skipped.
+ * Resolve a pointer position at plot-pixel `(px, py)` to the mark under it, or
+ * `null`. Walks the row's layers **top-down** (reverse z-order — the topmost
+ * mark wins, matching what the user sees) and returns the first `hitTest` hit.
+ * A layer with no `hitTest` (line / band / area) or no resolvable y-scale is
+ * skipped.
+ *
+ * `mode` (default `'hover'`) is forwarded to each layer's `hitTest`: hover may
+ * attribute a generous target (a bar's whole slot — the continuous-highlight
+ * model), while `'select'` — the click path — must leave genuinely empty plot
+ * space resolving to `null`, because that `null` **is** the deselect signal
+ * (RFC §7: a click on no mark is the empty-commit path). See
+ * {@link RowLayer.hitTest}.
  *
  * Pure, given the row's `xScale` and a per-axis y-scale lookup — so the click
  * dispatch in `Layers` unit-tests without a DOM. (Layers passes its sorted
  * z-stack, the shared `xScale`, and its `axisId → yScale` resolver.)
  */
-export function resolveSelection(entries, px, py, xScale, yScaleFor) {
+export function resolveSelection(entries, px, py, xScale, yScaleFor, mode = 'hover') {
     for (let i = entries.length - 1; i >= 0; i -= 1) {
         const entry = entries[i];
         const yScale = yScaleFor(entry.axisId);
         if (yScale === undefined)
             continue;
-        const hit = entry.layer.hitTest?.(px, py, xScale, yScale);
+        const hit = entry.layer.hitTest?.(px, py, xScale, yScale, mode);
         if (hit)
             return hit;
     }