@pond-ts/charts 0.38.0 → 0.40.0

package/CHANGELOG.md

@@ -8,7 +8,9 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`, and
 them all. Pre-1.0: minor bumps may include new features and type-level changes;
 patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.38.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.40.0...HEAD
+[0.40.0]: https://github.com/pjm17971/pond-ts/compare/v0.39.0...v0.40.0
+[0.39.0]: https://github.com/pjm17971/pond-ts/compare/v0.38.0...v0.39.0
 [0.38.0]: https://github.com/pjm17971/pond-ts/compare/v0.37.0...v0.38.0
 [0.37.0]: https://github.com/pjm17971/pond-ts/compare/v0.36.0...v0.37.0
 [0.36.0]: https://github.com/pjm17971/pond-ts/compare/v0.35.0...v0.36.0
@@ -34,6 +36,87 @@ patch bumps are strictly additive.
 [0.19.0]: https://github.com/pjm17971/pond-ts/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/pjm17971/pond-ts/compare/v0.17.1...v0.18.0
 
+## [Unreleased]
+
+## [0.40.0] — 2026-07-05
+
+A **core + charts** release from the estela `DataChart`-port friction wave.
+`@pond-ts/react` and `@pond-ts/fit` carry no code changes — republished in
+lock-step (peer ranges widen to `^0.40.0`).
+
+### Added
+
+- `pond-ts`: **`TimeSeries.fromColumns({ sort })`** — an opt-in `sort?: boolean`
+  (default `false`) that stable-sorts a columnar payload by key before
+  construction, the columnar counterpart of `fromJSON`'s `sort`. The default path
+  is unchanged: a decreasing key still throws (a backwards key on the trusted fast
+  door is a corruption signal, not silently accepted), and the `Float64Array`
+  zero-copy adoption is preserved when `sort` is unset. (#344)
+- `@pond-ts/charts`: **controlled bar hover** — `<ChartContainer hovered
+onHover>`, the transient-hover analog of the existing `selected` / `onSelect`
+  pair, keyed by the same `SelectInfo`. Pin a lit `<BarChart>` bar from a legend
+  or list row (`hovered`), or mirror a bar-originated hover out-of-band
+  (`onHover`); omit both for today's uncontrolled behavior. (#343)
+
+### Fixed
+
+- `@pond-ts/charts`: **axis and layer registration are value-equality-guarded** —
+  a fresh-but-value-equal `ticks` / `format` / `byValue()`-projected `series`
+  reference no longer re-registers the axis/layer, fixing a "Maximum update depth
+  exceeded" loop on frequently re-rendering (scrub-driven) charts. The layer and
+  axis docs gain a memoize note for `format` / `series` (an inline `format`
+  closure still must be hoisted — a closure can't be value-compared). (#342)
+
+## [0.39.0] — 2026-07-03
+
+A `@pond-ts/charts` release: the **crosshair reticle + annotation-layout** wave,
+driven by the Tidal terminal. `pond-ts`, `@pond-ts/react`, and `@pond-ts/fit`
+carry no code changes — republished in lock-step (peer ranges widen to `^0.39.0`).
+
+### Added
+
+- `@pond-ts/charts`: **`<ChartContainer crosshairSnap>`** (default `true`) — the
+  `cursor="crosshair"` reticle centres on the nearest data point; `false` gives a
+  **free** reticle whose horizontal line + value follow the pointer y
+  (`yScale.invert`), while the vertical line still snaps its x to the data grid
+  for a clean time readout.
+- `@pond-ts/charts`: **coincident marker labels merge** — labelled `<Marker>`s at
+  the same x fold into one chip (`"a, b, c"`) instead of stacking; their x-axis
+  indicator pills dedup to one.
+- `@pond-ts/charts`: **x-axis indicator pills lane-stack** when they'd overlap
+  (each connector lengthens to its lane).
+
+### Changed
+
+- `@pond-ts/charts`: **`cursor="crosshair"` is now a single reticle** — a
+  full-height dashed vertical + full-width dashed horizontal line + a centre dot +
+  one value pill, with the time pill connected to the vertical line. (Was
+  per-series dots + on-axis pills; the per-series readout stays on `flag` /
+  `inline`.)
+- `@pond-ts/charts`: top-flag **labels pack per row** — a label only contends with
+  labels in its own row's top space (a bottom-row label no longer dodges a
+  top-row one at the same x). A dragged mark is excluded from the pack, so static
+  marks hold their lanes as it crosses them (no phantom lane swaps). A marker's
+  staff now hangs from the top of its (stacked) flag.
+
+### Fixed
+
+- `@pond-ts/charts`: the crosshair x-axis pill and marker pills read the axis's
+  own formatter (a value-axis / off-boundary time no longer shows a raw number).
+- **Charts — click-to-select an annotation now works while `panZoom` is on.** A
+  _selectable but non-editable_ `<Region>` / `<Marker>` (one with no `onChange`)
+  lets its press bubble to the plot so a drag can pan _through_ it. The plot
+  captured the pointer on press to start the pan, and the browser then retargeted
+  the resulting `click` onto the plot (Pointer Events spec: a captured pointer's
+  compatibility mouse events fire on the capture target) — silently dropping the
+  mark's `onSelectAnnotation`. The plot now **defers** its pan pointer-capture
+  until the pointer actually moves past the drag slop, so a click (no drag) leaves
+  the pointer on the mark and its select fires, while a press-drag still pans
+  through and the tracker still hides once the pan commits. Resolves the
+  browser-dependent finding deferred from #308; adds
+  `e2e/annotations-panzoom.spec.ts`, the first real-pointer-event behavior e2e for
+  the annotation layer. (#309)
+
 ## [0.38.0] — 2026-07-03
 
 A `@pond-ts/charts` release: **axis-edge value indicators + the crosshair

package/dist/AreaChart.d.ts

@@ -8,6 +8,10 @@ export interface AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      * `ValueSeries` (`series.byValue('dist')`) against its value axis — the
      * container infers which from the data, no axis-type prop (mirrors
      * `<LineChart>`). Either way `column` names the numeric value to fill from.
+     *
+     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
+     * an inline `series={s.byValue('dist')}` re-registers this layer every render —
+     * on a frequently re-rendering chart, memoize the projection (`useMemo`).
      */
     series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric value column to fill from. */

package/dist/BandChart.d.ts

@@ -8,6 +8,10 @@ export interface BandChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      * container infers which from the data, no axis-type prop (mirrors
      * `<LineChart>` / `<AreaChart>`). Either way `lower`/`upper` name the numeric
      * edge columns.
+     *
+     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
+     * an inline `series={s.byValue('dist')}` re-registers this layer every render —
+     * on a frequently re-rendering chart, memoize the projection (`useMemo`).
      */
     series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric column for the band's lower edge (e.g. `p25`). */

package/dist/BarChart.d.ts

@@ -10,6 +10,10 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
      * the same neighbour-spacing span applies (see {@link barsFromValueSeries}); the
      * container infers the x-kind from the data, no axis-type prop (mirrors the
      * other layers).
+     *
+     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
+     * an inline `series={s.byValue('dist')}` re-registers this layer every render —
+     * on a frequently re-rendering chart, memoize the projection (`useMemo`).
      */
     series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric value column for the bar height. */
@@ -63,6 +67,12 @@ export interface BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends
  * readout reads the same bar you click, even across a wide bucket (they differ
  * only by the `gap` inset, where the pixel rect is narrower than the span).
  *
+ * Both channels are also **controllable from outside** the chart via the
+ * container: `selected`/`onSelect` (committed) and `hovered`/`onHover` (transient)
+ * — pass either to pin the lit/selected bar from a legend or list row, and read
+ * the callback to mirror a bar-originated hover/click out-of-band. Symmetric pair,
+ * keyed by the same {@link SelectInfo} identity.
+ *
  * **Value axis** — bars also scale on a value axis when fed a `ValueSeries`
  * (`series.byValue('dist')`): estela's distance-domain splits/laps, one bar per
  * segment over a monotonic axis. A `ValueSeries` is point-keyed, so the span is

package/dist/BarChart.js

@@ -26,6 +26,12 @@ import { useSlotKey } from './use-slot-key.js';
  * readout reads the same bar you click, even across a wide bucket (they differ
  * only by the `gap` inset, where the pixel rect is narrower than the span).
  *
+ * Both channels are also **controllable from outside** the chart via the
+ * container: `selected`/`onSelect` (committed) and `hovered`/`onHover` (transient)
+ * — pass either to pin the lit/selected bar from a legend or list row, and read
+ * the callback to mirror a bar-originated hover/click out-of-band. Symmetric pair,
+ * keyed by the same {@link SelectInfo} identity.
+ *
  * **Value axis** — bars also scale on a value axis when fed a `ValueSeries`
  * (`series.byValue('dist')`): estela's distance-domain splits/laps, one bar per
  * segment over a monotonic axis. A `ValueSeries` is point-keyed, so the span is

package/dist/ChartContainer.d.ts

@@ -57,6 +57,31 @@ export interface ChartContainerProps {
      * works in both controlled and uncontrolled mode.
      */
     onSelect?: (hit: SelectInfo | null) => void;
+    /**
+     * Controlled hover-highlight — the transiently lit mark (echo the `onHover` arg
+     * back), or `null`. **Omitted ⇒ uncontrolled** (the pointer over a selectable
+     * layer manages it internally). The hover analog of {@link selected}: pass it to
+     * **pin** a lit mark from outside the chart (e.g. hovering a legend / list row
+     * lights the matching {@link BarChart} bar). Only layers with a hover-highlight
+     * (currently `BarChart`) render it; keyed by the same {@link SelectInfo} identity
+     * as selection.
+     */
+    hovered?: SelectInfo | null;
+    /**
+     * Fires when the pointer enters a selectable layer's mark (the hit mark) or
+     * leaves every mark (`null`) — the hover analog of {@link onSelect}. Notification
+     * only (works controlled or uncontrolled), and **deduped**: it fires on a mark
+     * transition, not on every pointer move. Wire it to mirror hover out-of-band
+     * (e.g. a list row ↔ the bar), pairing with {@link hovered} to sync both ways.
+     * (The annotation counterpart is {@link onHoverAnnotation}.)
+     *
+     * **Dedup key:** by the mark's `key` + `label` only (not `value`/`color`). So on
+     * a live chart where a bar's value changes while the cursor stays on it, this
+     * won't re-fire — read the current value from your series, not the last
+     * `onHover` payload. (Matches the internal hover-highlight, which repaints on
+     * key transitions.)
+     */
+    onHover?: (hit: SelectInfo | null) => void;
     /**
      * Enable pan/zoom: drag the plot to pan the time range, wheel to zoom around
      * the cursor. **Default off** — so it doesn't capture drag/scroll unless asked.
@@ -82,6 +107,16 @@ export interface ChartContainerProps {
      * axis.
      */
     cursorTime?: boolean;
+    /**
+     * `cursor="crosshair"` reticle **y** snapping. **Default `true`** — the
+     * crosshair centres on the nearest **data point** (the horizontal line snaps to
+     * that sample's value). `false` — the horizontal line + centre follow the
+     * pointer **y** freely, the value read as `yScale.invert(pointerY)`. Either way
+     * the vertical line snaps its **x** to the data grid (so the time readout is
+     * clean), and both draw a full-height dashed vertical + full-width dashed
+     * horizontal line.
+     */
+    crosshairSnap?: boolean;
     /**
      * Enter **annotation-edit mode**: suppresses the data cursor and makes editable
      * annotations (those given an `onChange`) interactive — hovering one reveals its
@@ -145,5 +180,5 @@ export interface ChartContainerProps {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, selected, onSelect, panZoom, onTimeRangeChange, minDuration, cursor, cursorTime, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, theme, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom, onTimeRangeChange, minDuration, cursor, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, theme, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartContainer.d.ts.map

package/dist/ChartContainer.js

@@ -31,7 +31,7 @@ function normalizeRange(range) {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, selected, onSelect, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorTime = false, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, theme, children, }) {
+export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, theme, children, }) {
     // The explicit base domain from `range` (a tuple or a TimeRange). `undefined`
     // ⇒ auto-fit (resolved from the layers below). Pan/zoom seeds from it; `seed`
     // is the placeholder while auto-fitting.
@@ -77,6 +77,13 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
     // still cursor stays put while a live window slides under it; a controlled
     // `trackerPosition` resolves to a pixel below.
     const [hoverX, setHoverX] = useState(null);
+    // The free-form crosshair also needs the pointer's y + which row (row-specific,
+    // unlike the shared x). One state object so a move updates both atomically.
+    const [hoverPoint, setHoverPoint] = useState(null);
+    const setHoverY = useCallback((y, rowKey) => setHoverPoint(y === null || rowKey === null ? null : { y, rowKey }), []);
+    // The actively-dragged annotation — excluded from the lane packers so static
+    // marks hold their lanes while it crosses them (see ContainerFrame.draggingKey).
+    const [draggingKey, setDragging] = useState(null);
     // Draw layers register as tracker sources; on hover we fan in their values at
     // the cursor and hand them out via onTrackerChanged (held in a ref so an
     // inline callback doesn't churn the frame). This powers a readout rendered
@@ -168,18 +175,36 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
             setInternalSelected(hit);
     }, []);
     // Hover-highlight: the transient mark under the pointer (distinct from the
-    // committed selection). Deduped by key+label so the data canvas repaints only
-    // when the hovered mark changes — not on every pointer move (the move itself
-    // just slides the SVG cursor, which never touches the data canvas).
-    const [hovered, setHoveredState] = useState(null);
+    // committed selection). Controlled (`hovered` prop) or uncontrolled (internal),
+    // mirroring selection; `onHover` notifies in both modes. Deduped by key+label
+    // so it fires — and the data canvas repaints — only when the hovered mark
+    // changes, not on every pointer move (the move itself just slides the SVG
+    // cursor, which never touches the data canvas).
+    const [internalHovered, setInternalHovered] = useState(null);
+    const controlledHover = hovered !== undefined;
+    const hoveredValue = controlledHover ? (hovered ?? null) : internalHovered;
+    const onHoverRef = useRef(onHover);
+    const controlledHoverRef = useRef(controlledHover);
+    // The last mark we reported — so the callback dedups across pointer moves even
+    // in controlled mode, where there's no internal state to compare against.
+    const lastHoverRef = useRef(null);
+    useLayoutEffect(() => {
+        onHoverRef.current = onHover;
+        controlledHoverRef.current = controlledHover;
+    });
     const setHovered = useCallback((hit) => {
-        setHoveredState((prev) => prev === hit ||
+        const prev = lastHoverRef.current;
+        const same = prev === hit ||
             (prev !== null &&
                 hit !== null &&
                 prev.key === hit.key &&
-                prev.label === hit.label)
-            ? prev
-            : hit);
+                prev.label === hit.label);
+        if (same)
+            return;
+        lastHoverRef.current = hit;
+        onHoverRef.current?.(hit);
+        if (!controlledHoverRef.current)
+            setInternalHovered(hit);
     }, []);
     // Rows report their per-slot gutter widths; we reserve each slot's max.
     const [gutters, setGutters] = useState([]);
@@ -256,7 +281,7 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
     }, [cursorX, xScale, sources, plotWidth]);
     // Pack overlapping top-flag labels (markers + regions) into stacked lanes so
     // close-in-x labels don't collide; chips read their lane back off the frame.
-    const labelLanes = useMemo(() => computeLabelLanes(annotations, (v) => xScale(v)), [annotations, xScale]);
+    const labelLanes = useMemo(() => computeLabelLanes(annotations, (v) => xScale(v), draggingKey), [annotations, xScale, draggingKey]);
     const frame = useMemo(() => ({
         timeRange: [d0, d1],
         width,
@@ -269,9 +294,15 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         rowGap,
         cursorX,
         setHoverX,
+        cursorY: hoverPoint?.y ?? null,
+        cursorRowKey: hoverPoint?.rowKey ?? null,
+        setHoverY,
+        crosshairSnap,
+        draggingKey,
+        setDragging,
         selected: selectedValue,
         select,
-        hovered,
+        hovered: hoveredValue,
         setHovered,
         cursor,
         cursorTime,
@@ -309,9 +340,14 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         rightGutter,
         rowGap,
         cursorX,
+        hoverPoint,
+        setHoverY,
+        crosshairSnap,
+        draggingKey,
+        setDragging,
         selectedValue,
         select,
-        hovered,
+        hoveredValue,
         setHovered,
         cursor,
         cursorTime,

package/dist/ChartRow.js

@@ -9,6 +9,62 @@ import { YAxis } from './YAxis.js';
 import { ContainerContext, RowContext, } from './context.js';
 /** Sentinel id for the implicit axis a row gets when no `<YAxis>` is declared. */
 const IMPLICIT_AXIS_ID = '__default__';
+/** Element-wise compare of two optional number arrays (an axis's tick values) —
+ *  so a *fresh* `ticks={[…]}` array whose contents are unchanged doesn't count as
+ *  a new spec (see {@link axisSpecEqual}). */
+function numberArraysEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i += 1)
+        if (!Object.is(a[i], b[i]))
+            return false;
+    return true;
+}
+/**
+ * Value-equality for two {@link AxisSpec}s — the registration guard's compare
+ * (see `registerAxis`). Every field is a plain value except `format`, which may
+ * be a `(value) => string` closure: those are compared by **reference**
+ * (`Object.is`), so a stable/hoisted formatter (or a string specifier) is equal
+ * across renders but a *fresh inline function* is not — the one case a structural
+ * guard provably can't collapse, hence the `<YAxis format>` memoize note. A
+ * fresh-but-value-equal `ticks` array (the common live-chart footgun) compares
+ * equal element-wise and no-ops.
+ */
+function axisSpecEqual(a, b) {
+    return (a.id === b.id &&
+        a.side === b.side &&
+        a.width === b.width &&
+        // Object.is (not ===) so a degenerate NaN bound compares equal to itself and
+        // doesn't re-register every render.
+        Object.is(a.min, b.min) &&
+        Object.is(a.max, b.max) &&
+        a.pad === b.pad &&
+        a.labelPlacement === b.labelPlacement &&
+        a.index === b.index &&
+        Object.is(a.format, b.format) &&
+        numberArraysEqual(a.tickValues, b.tickValues));
+}
+/**
+ * Value-equality for two {@link LayerEntry}s — **defensive, not load-bearing.**
+ * The axis guard (`axisSpecEqual`) is what breaks the update-depth loop; this is
+ * belt-and-suspenders for the layer setter. Note that under the current draw-layer
+ * structure it *won't* actually fire: every layer builds `layer` inside the same
+ * `useMemo` as `entry`, so the register effect only runs when `entry` is fresh —
+ * and a fresh `entry` always carries a fresh `layer`, so `a.layer === b.layer` is
+ * never true when the guard runs (it falls through to a normal register). It would
+ * only bite if a future layer memoized `layer` separately from `entry` (or the
+ * `Layers` registry ref changed under a stable entry). A fresh `series` projection
+ * (`byValue()` mints one each call) rebuilds the memo → a new `layer` and
+ * legitimately re-registers; that's a consumer-side memoize (see the `series` note
+ * on the draw-layer components), not something the setter can value-compare.
+ */
+function layerEntryEqual(a, b) {
+    return a.layer === b.layer && a.axisId === b.axisId && a.index === b.index;
+}
 /** Axis tick count for the per-axis formatter — matches `<YAxis>`'s tick count
  *  so the readout formatter is calibrated exactly as the labels are. */
 const AXIS_TICK_COUNT = 5;
@@ -52,8 +108,19 @@ export function ChartRow({ height, cursor, children }) {
     // min/max or series change silently rebind axes / reorder the z-stack.)
     const [axes, setAxes] = useState(() => new Map());
     const [layers, setLayers] = useState(() => new Map());
+    // Registration is idempotent under value-equality: a `<YAxis>` re-fires its
+    // register effect whenever its `spec` memo yields a fresh object — which an
+    // inline `ticks={[]}` / `format` or a re-rendered parent does every render. If
+    // the spec is *value*-equal to the stored one, skip the `setState` entirely so
+    // it can't spin `register → setState → re-render → register` into React's
+    // "Maximum update depth exceeded" on a scrub-heavy chart (F-charts-axis-reregister).
     const registerAxis = useCallback((key, spec) => {
-        setAxes((m) => new Map(m).set(key, spec));
+        setAxes((m) => {
+            const prev = m.get(key);
+            if (prev !== undefined && axisSpecEqual(prev, spec))
+                return m;
+            return new Map(m).set(key, spec);
+        });
     }, []);
     const unregisterAxis = useCallback((key) => {
         setAxes((m) => {
@@ -64,8 +131,17 @@ export function ChartRow({ height, cursor, children }) {
             return next;
         });
     }, []);
+    // Same value-equality guard as `registerAxis`: a re-register carrying the same
+    // `layer` object (stable while the draw layer's inputs are) + `axisId`/`index`
+    // no-ops rather than churning state. (A fresh `series` projection rebuilds the
+    // layer and legitimately re-registers — see `layerEntryEqual`.)
     const registerLayer = useCallback((key, entry) => {
-        setLayers((m) => new Map(m).set(key, entry));
+        setLayers((m) => {
+            const prev = m.get(key);
+            if (prev !== undefined && layerEntryEqual(prev, entry))
+                return m;
+            return new Map(m).set(key, entry);
+        });
     }, []);
     const unregisterLayer = useCallback((key) => {
         setLayers((m) => {

package/dist/Layers.js

@@ -234,17 +234,23 @@ export function Layers({ children }) {
         if (!c.panZoom)
             return;
         const r = c.timeRange;
-        dragRef.current = { startX: e.clientX, startRange: [r[0], r[1]] };
-        c.setHoverX(null); // hide the tracker while panning
-        c.setHovered(null); // and drop any hover-highlight
-        // Capture so the pan continues outside the plot; an enhancement, not
-        // critical — guard the throw for synthetic / already-released pointers.
-        try {
-            e.currentTarget.setPointerCapture(e.pointerId);
-        }
-        catch {
-            /* ignore */
-        }
+        // Arm a potential pan: record the anchor, but DON'T capture the pointer or
+        // hide the tracker yet. Capturing on press retargets the eventual `click`
+        // to the plot (Pointer Events spec: a captured pointer's compatibility
+        // mouse events fire on the capture target) — which silently swallows a
+        // click-select on a *selectable but non-editable* mark, whose press bubbles
+        // up to here (its DragArea deliberately lets a non-edit press through so a
+        // pan can read past it). The pan commits — capture + hide tracker — only
+        // once the pointer moves past the slop (handlePointerMove); a press that
+        // stays put is a click, and leaving the pointer on the mark lets its
+        // onClick fire. Pan-through (drag starting on a non-editable mark) is
+        // unaffected: the first move past the slop still reaches this handler and
+        // captures then.
+        dragRef.current = {
+            startX: e.clientX,
+            startRange: [r[0], r[1]],
+            captured: false,
+        };
     }, []);
     const handlePointerMove = useCallback((e) => {
         const c = containerRef.current;
@@ -255,6 +261,16 @@ export function Layers({ children }) {
             c.setHoverX(px); // share the preview x so other rows draw a guide there
             return;
         }
+        // A pan is only live while a button is held. A move with no buttons means
+        // the press already ended without us seeing the pointerup — which the
+        // deferred-capture path allows: an uncommitted (sub-slop) potential-pan
+        // released *outside* the plot never captured, so its pointerup fires
+        // off-plot and never reaches handlePointerUp. Drop the stale dragRef here
+        // (and fall through to hover) so it can't fire a phantom pan on re-entry.
+        // A genuine pan-in-progress always has buttons !== 0, so this never cuts
+        // one short — including the press-leave-then-return-still-holding case.
+        if (dragRef.current && e.buttons === 0)
+            dragRef.current = null;
         const drag = dragRef.current;
         if (drag) {
             // Pan from the start range by the total drag — right → earlier (−dt).
@@ -263,21 +279,61 @@ export function Layers({ children }) {
             // the view nor shifts the scale the click then hit-tests against.
             if (Math.abs(dx) <= DRAG_SLOP)
                 return;
+            // First move past the slop ⇒ this is a real pan, not a click. Commit it
+            // now (deferred from press, see handlePointerDown): hide the tracker and
+            // claim the pointer so the pan keeps tracking outside the plot. Capturing
+            // here — after the click/select decision is already moot — is what keeps a
+            // tap-select on a non-editable mark working while a drag still pans.
+            if (!drag.captured) {
+                drag.captured = true;
+                c.setHoverX(null); // hide the tracker while panning
+                c.setHoverY(null, null);
+                c.setHovered(null); // and drop any hover-highlight
+                try {
+                    e.currentTarget.setPointerCapture(e.pointerId);
+                }
+                catch {
+                    /* ignore (synthetic / already-released pointer) */
+                }
+            }
             const span = drag.startRange[1] - drag.startRange[0];
             const dt = c.plotWidth > 0 ? -dx * (span / c.plotWidth) : 0;
             c.applyRange(panRange(drag.startRange, dt));
             return; // tracker suppressed during a pan
         }
         const rect = e.currentTarget.getBoundingClientRect();
-        const px = Math.max(0, Math.min(c.plotWidth, e.clientX - rect.left));
+        const r = rowRef.current;
+        const rawX = Math.max(0, Math.min(c.plotWidth, e.clientX - rect.left));
+        const py = Math.max(0, Math.min(r.height, e.clientY - rect.top));
+        // Crosshair with `crosshairSnap` (default): snap the shared vertical line to
+        // the nearest sample's x, so the reticle centres on a real data point (and
+        // stays aligned across rows on a shared grid). Free mode keeps the raw x.
+        // Crosshair always snaps the shared vertical line (and so the x-time pill)
+        // to the nearest sample's x — the reticle rides the data grid on x, giving a
+        // clean time readout (a raw pointer time formats to unreadable sub-second
+        // precision). `crosshairSnap` only governs the *y* (snap to the value vs a
+        // free horizontal line at the pointer). This is ChartIQ's model.
+        let px = rawX;
+        if ((r.cursor ?? c.cursor) === 'crosshair') {
+            const t = +c.xScale.invert(rawX);
+            for (const entry of r.layers) {
+                if (entry.layer.cursorFlag)
+                    continue;
+                const s = entry.layer.sampleAt(t)[0];
+                if (s !== undefined) {
+                    px = c.xScale(s.x);
+                    break;
+                }
+            }
+        }
         c.setHoverX(px);
+        c.setHoverY(py, r.rowKey);
         // Hover-highlight: hit-test the row's selectable layers (Bar) under the
         // pointer and set the hovered mark. Deduped in the container, so the data
         // canvas repaints only on a mark transition — not every move (the move just
         // slides the SVG cursor). A row with no selectable layer (line/area/band)
-        // resolves to null → a no-op.
-        const r = rowRef.current;
-        const hit = resolveSelection(r.layers, px, e.clientY - rect.top, c.xScale, (axisId) => r.yScales.get(axisId ?? r.defaultAxisId));
+        // resolves to null → a no-op. Uses the raw pointer, not the snapped x.
+        const hit = resolveSelection(r.layers, rawX, py, c.xScale, (axisId) => r.yScales.get(axisId ?? r.defaultAxisId));
         c.setHovered(hit);
     }, []);
     const handlePointerUp = useCallback((e) => {
@@ -323,13 +379,18 @@ export function Layers({ children }) {
             }
             return;
         }
-        if (dragRef.current) {
+        const drag = dragRef.current;
+        if (drag) {
             dragRef.current = null;
-            try {
-                e.currentTarget.releasePointerCapture(e.pointerId);
-            }
-            catch {
-                /* ignore */
+            // Only release if the pan actually committed + captured (a click never
+            // captured, so there's nothing to release).
+            if (drag.captured) {
+                try {
+                    e.currentTarget.releasePointerCapture(e.pointerId);
+                }
+                catch {
+                    /* ignore */
+                }
             }
         }
     }, []);
@@ -341,9 +402,11 @@ export function Layers({ children }) {
             drawFromRef.current = null;
             setDrawFrom(null);
             c.setHoverX(null);
+            c.setHoverY(null, null);
             return;
         }
         c.setHoverX(null);
+        c.setHoverY(null, null);
         c.setHovered(null);
     }, []);
     // Click selection: ignore the click that ends a drag/pan (moved past a few px),
@@ -427,6 +490,48 @@ export function Layers({ children }) {
     const timeX = parts.chip === 'flag' && trackerSamples.length > 0
         ? trackerSamples[0].px
         : cursorX;
+    // Crosshair reticle (`chip: 'axis'`): a single centre for THIS row — the
+    // horizontal line + centre dot + value pill anchor to `center.py` (the vertical
+    // line is the shared `cursorX`, drawn in every row). Snap: the sample nearest
+    // the pointer y in the hovered row (or the first sample when nothing's hovered,
+    // e.g. a pinned demo — so every row shows a reticle then). Free: the raw pointer
+    // y in the hovered row, its value via `yScale.invert`. `null` ⇒ vertical only.
+    const cursorInBounds = cursorX !== null && cursorX >= 0 && cursorX <= plotWidth;
+    const reticle = (() => {
+        if (parts.chip !== 'axis' || !cursorInBounds)
+            return null;
+        const hoveredRow = container.cursorRowKey === row.rowKey;
+        const cy = container.cursorY;
+        if (container.crosshairSnap) {
+            if (trackerSamples.length === 0)
+                return null;
+            const pick = hoveredRow && cy !== null
+                ? trackerSamples.reduce((a, b) => Math.abs(b.py - cy) < Math.abs(a.py - cy) ? b : a)
+                : container.cursorRowKey === null
+                    ? trackerSamples[0]
+                    : null;
+            return pick
+                ? {
+                    py: pick.py,
+                    value: pick.value,
+                    format: pick.format,
+                    side: pick.side,
+                }
+                : null;
+        }
+        // Free reticle — the raw pointer y in the hovered row.
+        if (!hoveredRow || cy === null)
+            return null;
+        const ys = yScales.get(defaultAxisId);
+        if (ys === undefined)
+            return null;
+        return {
+            py: cy,
+            value: ys.invert(cy),
+            format: formats.get(defaultAxisId) ?? String,
+            side: axisSides.get(defaultAxisId) ?? 'left',
+        };
+    })();
     // Cross-row guide lines: the x-positions of annotations on the OTHER rows
     // (markers + region edges), so a mark on one row reads against this row's data +
     // the shared x axis. A mark's own row skips itself; baselines cast no vertical
@@ -500,7 +605,9 @@ export function Layers({ children }) {
                             cursorX <= plotWidth && (_jsx("line", { x1: Math.round(cursorX), y1: 0, x2: Math.round(cursorX), y2: row.height, stroke: cursorColor, strokeWidth: 1, shapeRendering: "crispEdges" })), parts.chip === 'flag' &&
                             trackerSamples.map((s, i) => s.py > flagBase ? (_jsx("line", { x1: s.px, y1: flagBase, x2: s.px, y2: s.py, stroke: cursorColor, strokeWidth: 1, opacity: 0.5 }, `staff-${i}`)) : null), parts.chip === 'flag' &&
                             trackerFlags.map((f, i) => f.topPy > flagBase ? (_jsx("line", { x1: f.px, y1: flagBase, x2: f.px, y2: f.topPy, stroke: cursorColor, strokeWidth: 1, opacity: 0.5 }, `boxstaff-${i}`)) : null), parts.chip === 'axis' &&
-                            trackerSamples.map((s, i) => (_jsx("line", { x1: s.side === 'right' ? Math.round(s.px) : 0, y1: Math.round(s.py), x2: s.side === 'right' ? plotWidth : Math.round(s.px), y2: Math.round(s.py), stroke: s.color, strokeWidth: 1, opacity: 0.4, strokeDasharray: "3 3", shapeRendering: "crispEdges" }, `hconn-${i}`))), parts.dots &&
+                            cursorX !== null &&
+                            cursorX >= 0 &&
+                            cursorX <= plotWidth && (_jsxs(_Fragment, { children: [_jsx("line", { x1: Math.round(cursorX), y1: 0, x2: Math.round(cursorX), y2: row.height, stroke: cursorColor, strokeWidth: 1, strokeDasharray: "3 3", shapeRendering: "crispEdges" }), reticle && (_jsxs(_Fragment, { children: [_jsx("line", { x1: 0, y1: Math.round(reticle.py), x2: plotWidth, y2: Math.round(reticle.py), stroke: cursorColor, strokeWidth: 1, strokeDasharray: "3 3", shapeRendering: "crispEdges" }), _jsx("circle", { cx: cursorX, cy: reticle.py, r: 3, fill: cursorColor, stroke: background, strokeWidth: background ? 1 : 0 })] }))] })), parts.dots &&
                             trackerSamples.map((s, i) => (_jsx("circle", { cx: s.px, cy: s.py, r: 3, fill: s.color, stroke: background, strokeWidth: background ? 1 : 0 }, `dot-${i}`)))] }), showTime && timeX !== null && cursorTime !== null && (_jsx("div", { style: {
                         ...chipStyle,
                         background: 'transparent',
@@ -529,16 +636,12 @@ export function Layers({ children }) {
                                 right: flip ? `${plotWidth - s.px + 8}px` : undefined,
                                 color: s.color,
                             }, children: s.format(s.value) }, i));
-                    }), parts.chip === 'axis' &&
-                    trackerSamples.map((s, i) => {
-                        const top = Math.max(flagLineHeight / 2, Math.min(row.height - flagLineHeight / 2, s.py));
-                        return (_jsx("div", { style: {
-                                ...axisPillStyle(container.theme, s.color),
-                                top: `${top}px`,
-                                transform: 'translateY(-50%)',
-                                ...axisPillX(s.side, plotWidth),
-                            }, children: s.format(s.value) }, `ytag-${i}`));
-                    }), parts.chip === 'flag' &&
+                    }), reticle && (_jsx("div", { style: {
+                        ...axisPillStyle(container.theme, cursorColor),
+                        top: `${Math.max(flagLineHeight / 2, Math.min(row.height - flagLineHeight / 2, reticle.py))}px`,
+                        transform: 'translateY(-50%)',
+                        ...axisPillX(reticle.side, plotWidth),
+                    }, children: reticle.format(reticle.value) })), parts.chip === 'flag' &&
                     cursorX !== null &&
                     trackerSamples.map((s, i) => (
                     // The flag flies from the top of its staff — chip top at the staff top

package/dist/LineChart.d.ts

@@ -8,6 +8,11 @@ export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      * `ValueSeries` (`series.byValue('cumDist')`) against its value axis — the
      * container infers which from the data, no axis-type prop. Either way the key
      * / axis column supplies x and `column` supplies y.
+     *
+     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call, so
+     * passing `series={s.byValue('dist')}` inline re-registers this layer every
+     * render — on a frequently re-rendering (e.g. scrub-driven) chart, memoize the
+     * projection (`useMemo`) so the layer isn't rebuilt each frame.
      */
     series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric value column to plot. */

package/dist/XAxis.js

@@ -49,24 +49,61 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     // colour, reading like a tick. An indicator always shows the axis coordinate
     // (the formatted `at`), never the marker's custom label (that stays the in-plot
     // chip). Skipped when off-plot.
+    // Coincident indicator markers (same `at`) show the same time, so one pill
+    // stands for the group — dedup by `at` (the first wins), then place.
+    const seenAt = new Set();
     const markerTags = container.annotations
         .filter((a) => a.indicator && a.kind === 'marker' && a.xs[0] !== undefined)
+        .filter((a) => {
+        const at = a.xs[0];
+        if (seenAt.has(at))
+            return false;
+        seenAt.add(at);
+        return true;
+    })
         .map((a) => {
         const at = a.xs[0];
-        return { id: a.id ?? `marker-at-${at}`, x: xScale(at), text: fmt(at) };
+        return {
+            key: a.key,
+            id: a.id ?? `marker-at-${at}`,
+            x: xScale(at),
+            text: fmt(at),
+        };
     })
         .filter((t) => t.x >= 0 && t.x <= plotWidth);
+    // Stack overlapping marker pills into lanes — they all share this one strip.
+    // Greedy left→right; the dragged mark (`draggingKey`) is pinned to lane 0 so the
+    // static pills hold their lanes as it crosses them (no reshuffle mid-drag).
+    const pillWidth = (text) => text.length * theme.font.size * 0.62 + 10;
+    const pillLaneEnds = [];
+    const markerLanes = new Map();
+    for (const t of [...markerTags].sort((p, q) => p.x - q.x)) {
+        if (t.key === container.draggingKey) {
+            markerLanes.set(t.id, 0);
+            continue;
+        }
+        const left = t.x - pillWidth(t.text) / 2;
+        let lane = 0;
+        while (lane < pillLaneEnds.length && pillLaneEnds[lane] + 4 > left)
+            lane += 1;
+        pillLaneEnds[lane] = left + pillWidth(t.text);
+        markerLanes.set(t.id, lane);
+    }
+    const maxPillLane = Math.max(0, pillLaneEnds.length - 1);
     const placed = customTicks
         ? customTicks.map((t) => ({ x: xScale(t.at), label: t.label }))
         : xScale.ticks(TICK_COUNT).map((d) => ({
             x: xScale(d),
             label: fmt(+d),
         }));
-    const stripHeight = height ?? TICK_STRIP + (label ? LABEL_STRIP : 0);
     const onTop = side === 'top';
     // Axis pills (marker / crosshair) sit at the same offset as the tick labels so
     // they line up with their tick-label neighbours (matches `labelOffset` below).
     const pillOffset = align === 'right' ? 2 : 6;
+    // Per-lane vertical step for stacked pills; grow the strip to fit the stack.
+    const PILL_LANE_H = theme.font.size + 6;
+    const stripHeight = (height ?? TICK_STRIP + (label ? LABEL_STRIP : 0)) +
+        maxPillLane * PILL_LANE_H;
     return (_jsxs("div", { style: {
             position: 'relative',
             marginLeft: `${leftGutter}px`,
@@ -119,26 +156,39 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                     color: theme.axis.title?.color ?? theme.axis.label,
                     opacity: theme.axis.title?.opacity ?? 0.85,
                     whiteSpace: 'nowrap',
-                }, children: label })), markerTags.map((t) => (_jsxs(Fragment, { children: [_jsx("div", { style: {
+                }, children: label })), markerTags.map((t) => {
+                // The pill's lane: stacked below the base row when it would overlap a
+                // neighbour; the connector lengthens to reach it.
+                const laneY = pillOffset + (markerLanes.get(t.id) ?? 0) * PILL_LANE_H;
+                return (_jsxs(Fragment, { children: [_jsx("div", { style: {
+                                position: 'absolute',
+                                left: `${t.x}px`,
+                                [onTop ? 'bottom' : 'top']: 0,
+                                width: '1px',
+                                height: `${laneY}px`,
+                                background: annotationColor,
+                                zIndex: 2,
+                            } }), _jsx("div", { style: {
+                                ...axisPillStyle(theme, annotationColor),
+                                left: `${t.x}px`,
+                                transform: 'translateX(-50%)',
+                                [onTop ? 'bottom' : 'top']: `${laneY}px`,
+                                zIndex: 2,
+                            }, children: t.text })] }, t.id));
+            }), showCursorTag && (_jsxs(Fragment, { children: [_jsx("div", { style: {
                             position: 'absolute',
-                            left: `${t.x}px`,
+                            left: `${cursorX}px`,
                             [onTop ? 'bottom' : 'top']: 0,
                             width: '1px',
                             height: `${pillOffset}px`,
-                            background: annotationColor,
-                            zIndex: 2,
+                            background: cursorColor,
+                            zIndex: 3,
                         } }), _jsx("div", { style: {
-                            ...axisPillStyle(theme, annotationColor),
-                            left: `${t.x}px`,
+                            ...axisPillStyle(theme, cursorColor),
+                            left: `${cursorX}px`,
                             transform: 'translateX(-50%)',
                             [onTop ? 'bottom' : 'top']: `${pillOffset}px`,
-                            zIndex: 2,
-                        }, children: t.text })] }, t.id))), showCursorTag && (_jsx("div", { style: {
-                    ...axisPillStyle(theme, cursorColor),
-                    left: `${cursorX}px`,
-                    transform: 'translateX(-50%)',
-                    [onTop ? 'bottom' : 'top']: `${pillOffset}px`,
-                    zIndex: 3,
-                }, children: fmt(+xScale.invert(cursorX)) }))] }));
+                            zIndex: 3,
+                        }, children: fmt(+xScale.invert(cursorX)) })] }))] }));
 }
 //# sourceMappingURL=XAxis.js.map

package/dist/YAxis.d.ts

@@ -36,6 +36,12 @@ export interface YAxisProps {
      * function. Omit for the scale's d3 default — which is calibrated to the tick
      * step, so a between-ticks readout rounds to tick precision; pass a specifier
      * (e.g. `',.2f'`) when you want finer readout precision. See {@link AxisFormat}.
+     *
+     * **Live charts:** a string specifier is value-compared, so an inline
+     * `format='.0%'` is safe every render. An inline `format={(v) => …}` **function**
+     * is a fresh reference each render — the one axis prop a structural guard can't
+     * value-compare — so on a frequently re-rendering (e.g. scrub-driven) chart,
+     * hoist it or wrap it in `useCallback`, or it re-registers the axis each frame.
      */
     format?: AxisFormat;
     /**
@@ -45,9 +51,10 @@ export interface YAxisProps {
      * lever for a non-uniform axis like pace, where the caller chooses round-pace
      * positions and their own `m:ss` labels (`{ at: -300, label: '5:00' }`). `at`
      * values outside `[min, max]` extrapolate off-plot (the scale does not clamp).
-     * Pass `[]` to draw none. For a live / animating chart, **memoize the array** —
-     * an inline `ticks={[…]}` is a fresh reference each render and re-registers the
-     * axis (like `format`; harmless for a static chart).
+     * Pass `[]` to draw none. The array is **value-compared on registration**, so an
+     * inline `ticks={[…]}` (or `ticks={[]}`) with unchanged contents no longer
+     * re-registers the axis — only genuinely changed tick positions do. (An inline
+     * `format` *function* still needs hoisting; see `format`.)
      */
     ticks?: ReadonlyArray<{
         readonly at: number;

package/dist/annotations.d.ts

@@ -1,12 +1,21 @@
-import { type AnnotationSpec } from './context.js';
+import { type AnnotationSpec, type LabelPlacement } from './context.js';
 /**
- * Greedy left→right lane packing for the **top-flag** labels (markers + regions): a
- * label that would overlap the one to its left drops to the next free lane below,
- * so close-in-x labels stack instead of colliding (and a dragged label slides under
- * its neighbour). Returns slot-key → lane (0 = top). Baselines, whose labels anchor
- * at the left at their own y, don't participate.
+ * Lane placement for the **top-flag** labels (markers + regions). Returns, per
+ * slot key, its {@link LabelPlacement}. Baselines (label anchored at their own y)
+ * don't participate.
+ *
+ * Three behaviours:
+ * - **Per row** — labels only contend within their own row's top space (a
+ *   bottom-row label at the same x as a top-row one isn't "in the way").
+ * - **Coincident markers merge** — labelled markers at the *same x* (e.g. dragged
+ *   together, snapped onto one line) fold into a **single** chip (`"z1, z2, max"`)
+ *   on one lane, rather than stacking three deep. The first is the representative
+ *   (its `label` is the joined text); the rest map to `label: null`.
+ * - **Greedy stacking** — non-coincident labels that would still overlap drop to
+ *   the next free lane. The `draggingKey` is excluded (pinned to lane 0, its own
+ *   label) so the static labels hold their lanes as it crosses them.
  */
-export declare function computeLabelLanes(annotations: readonly AnnotationSpec[], toPixel: (axisX: number) => number): Map<symbol, number>;
+export declare function computeLabelLanes(annotations: readonly AnnotationSpec[], toPixel: (axisX: number) => number, draggingKey?: symbol | null): Map<symbol, LabelPlacement>;
 /**
  * Order two region bounds so `from ≤ to`. A region **edge resize** pivots around
  * the *opposite* (fixed) edge: the dragged value `v` and the pivot are ordered

package/dist/annotations.js

@@ -151,38 +151,93 @@ const LANE_H = 22;
 const LABEL_CHAR_W = 7;
 const LABEL_PAD = 16;
 const LANE_GAP = 6;
+/** Rough chip width (px) for the overlap model. */
+const labelWidth = (text) => text.length * LABEL_CHAR_W + LABEL_PAD;
 /**
- * Greedy left→right lane packing for the **top-flag** labels (markers + regions): a
- * label that would overlap the one to its left drops to the next free lane below,
- * so close-in-x labels stack instead of colliding (and a dragged label slides under
- * its neighbour). Returns slot-key → lane (0 = top). Baselines, whose labels anchor
- * at the left at their own y, don't participate.
+ * Lane placement for the **top-flag** labels (markers + regions). Returns, per
+ * slot key, its {@link LabelPlacement}. Baselines (label anchored at their own y)
+ * don't participate.
+ *
+ * Three behaviours:
+ * - **Per row** — labels only contend within their own row's top space (a
+ *   bottom-row label at the same x as a top-row one isn't "in the way").
+ * - **Coincident markers merge** — labelled markers at the *same x* (e.g. dragged
+ *   together, snapped onto one line) fold into a **single** chip (`"z1, z2, max"`)
+ *   on one lane, rather than stacking three deep. The first is the representative
+ *   (its `label` is the joined text); the rest map to `label: null`.
+ * - **Greedy stacking** — non-coincident labels that would still overlap drop to
+ *   the next free lane. The `draggingKey` is excluded (pinned to lane 0, its own
+ *   label) so the static labels hold their lanes as it crosses them.
  */
-export function computeLabelLanes(annotations, toPixel) {
-    const flags = annotations
-        .filter((a) => (a.kind === 'marker' || a.kind === 'region') &&
-        a.label.length > 0 &&
-        a.xs.length > 0)
-        .map((a) => {
-        const ax = a.kind === 'region' ? Math.min(a.xs[0], a.xs[1]) : a.xs[0];
-        return {
-            key: a.key,
-            left: toPixel(ax),
-            width: a.label.length * LABEL_CHAR_W + LABEL_PAD,
-        };
-    })
-        .sort((p, q) => p.left - q.left);
-    const laneEnds = []; // right-px of the last label placed in each lane
-    const lanes = new Map();
-    for (const f of flags) {
-        let lane = 0;
-        while (lane < laneEnds.length && laneEnds[lane] + LANE_GAP > f.left) {
-            lane += 1;
+export function computeLabelLanes(annotations, toPixel, draggingKey) {
+    const out = new Map();
+    const byRow = new Map();
+    for (const a of annotations) {
+        if ((a.kind !== 'marker' && a.kind !== 'region') ||
+            a.label.length === 0 ||
+            a.xs.length === 0)
+            continue;
+        const arr = byRow.get(a.rowKey);
+        if (arr)
+            arr.push(a);
+        else
+            byRow.set(a.rowKey, [a]);
+    }
+    for (const specs of byRow.values()) {
+        const flags = [];
+        const markerGroups = new Map();
+        for (const a of specs) {
+            if (a.kind === 'marker' && a.key !== draggingKey) {
+                const g = markerGroups.get(a.xs[0]);
+                if (g)
+                    g.push(a);
+                else
+                    markerGroups.set(a.xs[0], [a]);
+            }
+            else {
+                const ax = a.kind === 'region' ? Math.min(a.xs[0], a.xs[1]) : a.xs[0];
+                flags.push({
+                    rep: a.key,
+                    members: [a.key],
+                    left: toPixel(ax),
+                    width: labelWidth(a.label),
+                    label: a.label,
+                });
+            }
+        }
+        for (const [x, group] of markerGroups) {
+            const label = group.map((g) => g.label).join(', ');
+            flags.push({
+                rep: group[0].key,
+                members: group.map((g) => g.key),
+                left: toPixel(x),
+                width: labelWidth(label),
+                label,
+            });
         }
-        laneEnds[lane] = f.left + f.width;
-        lanes.set(f.key, lane);
+        const assign = (f, lane) => {
+            out.set(f.rep, { lane, label: f.label });
+            for (const m of f.members)
+                if (m !== f.rep)
+                    out.set(m, { lane, label: null });
+        };
+        // Greedy-pack the static flags; the dragged one is pinned to lane 0.
+        const dragged = flags.filter((f) => f.members.length === 1 && f.members[0] === draggingKey);
+        flags
+            .filter((f) => !dragged.includes(f))
+            .sort((p, q) => p.left - q.left)
+            .reduce((laneEnds, f) => {
+            let lane = 0;
+            while (lane < laneEnds.length && laneEnds[lane] + LANE_GAP > f.left)
+                lane += 1;
+            laneEnds[lane] = f.left + f.width;
+            assign(f, lane);
+            return laneEnds;
+        }, []);
+        for (const f of dragged)
+            assign(f, 0);
     }
-    return lanes;
+    return out;
 }
 /** A mark's hover state, synced both ways with the consumer. The effective hover
  *  is the local pointer hover **OR** the controlled `hovered` prop (so a legend row
@@ -259,7 +314,7 @@ function Pill({ cx, cy, w, h, color, }) {
  * **plot-pixel** position on press (`onDragStart`) / move (`onDrag`). With editing
  * off, press / move bubble so a pan reads straight through.
  */
-function DragArea({ x, y, w, h, cursor, editable, onHover, onSelect, onEdit, onDragStart, onDrag, }) {
+function DragArea({ x, y, w, h, cursor, editable, onHover, onSelect, onEdit, onDragStart, onDrag, onDragActive, }) {
     const dragging = useRef(false);
     // Tracks whether this press became a drag (moved past a few px) — a click that
     // didn't drag selects instead of edits. Tracked in *both* modes so a pan-drag
@@ -284,6 +339,7 @@ function DragArea({ x, y, w, h, cursor, editable, onHover, onSelect, onEdit, onD
                 return; // edit off: let it bubble (pan reads through)
             e.stopPropagation(); // claim the gesture — don't let the plot start a pan
             dragging.current = true;
+            onDragActive?.(true);
             onDragStart?.(p[0], p[1]);
             try {
                 e.currentTarget.setPointerCapture(e.pointerId);
@@ -312,6 +368,7 @@ function DragArea({ x, y, w, h, cursor, editable, onHover, onSelect, onEdit, onD
                 /* ignore */
             }
             dragging.current = false;
+            onDragActive?.(false);
             onHover(false);
         }, 
         // A system gesture takeover fires pointercancel, not pointerup — clear the
@@ -319,6 +376,7 @@ function DragArea({ x, y, w, h, cursor, editable, onHover, onSelect, onEdit, onD
         onPointerCancel: (e) => {
             if (!dragging.current)
                 return;
+            onDragActive?.(false);
             try {
                 e.currentTarget.releasePointerCapture(e.pointerId);
             }
@@ -364,12 +422,20 @@ export function Marker({ at, label, id, selected = false, selectable = true, hov
     const h = row.height;
     const opacity = rampAt(ann.depth, lineLevel(selectable, editable, hovering, selected));
     const showHandle = editable && (editing || hovering);
-    const lane = container.labelLanes.get(selfKey) ?? 0;
-    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: container.plotWidth, height: h, style: overlayStyle, children: [_jsx("line", { x1: x, y1: 0, x2: x, y2: h, stroke: ann.color, strokeWidth: 1, opacity: opacity, shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: x, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color })), selectable && (_jsx(DragArea, { x: x - HIT_PAD, y: 0, w: 2 * HIT_PAD, h: h, cursor: editing ? 'ew-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDrag: (px) => onChange?.(snapToGuides(container, selfKey, px) ??
-                            +container.xScale.invert(px)) }))] }), text && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
+    // Placement decides the lane + the chip text: `chipLabel` is this marker's own
+    // label, the merged `"a, b"` when coincident markers fold together, or `null`
+    // for a folded-in member (its chip is subsumed by the representative's).
+    const placement = container.labelLanes.get(selfKey);
+    const lane = placement?.lane ?? 0;
+    const chipLabel = placement?.label ?? null;
+    // The staff (vertical line) hangs from the top of its flag — so a flag stacked
+    // into a lower lane doesn't leave line poking above it. No label ⇒ full height.
+    const staffTop = text ? FLAG_TOP + lane * LANE_H : 0;
+    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: container.plotWidth, height: h, style: overlayStyle, children: [_jsx("line", { x1: x, y1: staffTop, x2: x, y2: h, stroke: ann.color, strokeWidth: 1, opacity: opacity, shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: x, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color })), selectable && (_jsx(DragArea, { x: x - HIT_PAD, y: 0, w: 2 * HIT_PAD, h: h, cursor: editing ? 'ew-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDrag: (px) => onChange?.(snapToGuides(container, selfKey, px) ??
+                            +container.xScale.invert(px)) }))] }), chipLabel && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
                     top: `${FLAG_TOP + lane * LANE_H}px`,
                     ...flagChipX(x, container.plotWidth),
-                }, children: text }))] }));
+                }, children: chipLabel }))] }));
 }
 /** A horizontal line at a y value, scaled against one row axis (RTC's `Baseline`).
  *  Its label anchors at the left, at the line's height. */
@@ -413,7 +479,7 @@ export function Baseline({ value, axis, label, labelSide = 'left', labelPosition
     const text = label === false ? '' : (label ?? (fmt ? fmt(value) : String(value)));
     // Handle pill near the right end (clears the left-anchored label).
     const handleX = w - 14;
-    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: w, height: row.height, style: overlayStyle, children: [_jsx("line", { x1: 0, y1: y, x2: w, y2: y, stroke: ann.color, strokeWidth: 1, opacity: opacity, shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: handleX, cy: y, w: HANDLE_LONG, h: HANDLE_SHORT, color: ann.color })), selectable && (_jsx(DragArea, { x: 0, y: y - HIT_PAD, w: w, h: 2 * HIT_PAD, cursor: editing ? 'ns-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDrag: (_px, py) => onChange?.(yScale.invert(py)) }))] }), text && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
+    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: w, height: row.height, style: overlayStyle, children: [_jsx("line", { x1: 0, y1: y, x2: w, y2: y, stroke: ann.color, strokeWidth: 1, opacity: opacity, shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: handleX, cy: y, w: HANDLE_LONG, h: HANDLE_SHORT, color: ann.color })), selectable && (_jsx(DragArea, { x: 0, y: y - HIT_PAD, w: w, h: 2 * HIT_PAD, cursor: editing ? 'ns-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDrag: (_px, py) => onChange?.(yScale.invert(py)) }))] }), text && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
                     top: `${y}px`,
                     [labelSide === 'right' ? 'right' : 'left']: '2px',
                     // `center` rides on the line; `above` sits its bottom edge on the line.
@@ -466,7 +532,7 @@ export function Region({ from, to, label, id, selected = false, selectable = tru
     const fillOpacity = ann.fillOpacity *
         rampAt(FILL_MULT, bodyLevel(selectable, editable, hovering, selected));
     const showHandles = editable && (editing || hovering);
-    const lane = container.labelLanes.get(selfKey) ?? 0;
+    const lane = container.labelLanes.get(selfKey)?.lane ?? 0;
     // Body move-drag: capture the start position + pointer on press, then move by
     // the TOTAL delta from there, so the *raw* position accumulates from a fixed
     // origin. Snap is applied only to the output — never fed back into this
@@ -478,7 +544,7 @@ export function Region({ from, to, label, id, selected = false, selectable = tru
     // region the other way instead of dead-ending at zero width.
     const edgeRef = useRef(null);
     const edge = (atX) => (_jsx("line", { x1: atX, y1: 0, x2: atX, y2: h, stroke: ann.color, strokeWidth: 1, opacity: edgeOpacity, shapeRendering: "crispEdges" }));
-    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: container.plotWidth, height: h, style: overlayStyle, children: [_jsx("rect", { x: left, y: 0, width: spanW, height: h, fill: ann.color, opacity: fillOpacity }), edges && edge(xa), edges && edge(xb), showHandles && (_jsxs(_Fragment, { children: [_jsx(Pill, { cx: xa, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color }), _jsx(Pill, { cx: xb, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color })] })), selectable && (_jsxs(_Fragment, { children: [_jsx(DragArea, { x: left, y: 0, w: spanW, h: h, cursor: editing ? 'grab' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragStart: (px) => {
+    return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: container.plotWidth, height: h, style: overlayStyle, children: [_jsx("rect", { x: left, y: 0, width: spanW, height: h, fill: ann.color, opacity: fillOpacity }), edges && edge(xa), edges && edge(xb), showHandles && (_jsxs(_Fragment, { children: [_jsx(Pill, { cx: xa, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color }), _jsx(Pill, { cx: xb, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color })] })), selectable && (_jsxs(_Fragment, { children: [_jsx(DragArea, { x: left, y: 0, w: spanW, h: h, cursor: editing ? 'grab' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDragStart: (px) => {
                                     dragRef.current = { from, to, startPx: px };
                                 }, onDrag: (px) => {
                                     const s = dragRef.current;
@@ -503,10 +569,10 @@ export function Region({ from, to, label, id, selected = false, selectable = tru
                                         nt = st;
                                     }
                                     onChange?.({ from: nf, to: nt });
-                                } }), editable && (_jsxs(_Fragment, { children: [_jsx(DragArea, { x: xa - EDGE_GRAB / 2, y: 0, w: EDGE_GRAB, h: h, cursor: "ew-resize", editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragStart: () => {
+                                } }), editable && (_jsxs(_Fragment, { children: [_jsx(DragArea, { x: xa - EDGE_GRAB / 2, y: 0, w: EDGE_GRAB, h: h, cursor: "ew-resize", editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDragStart: () => {
                                             edgeRef.current = to; // the fixed pivot = the far edge
                                         }, onDrag: (px) => onChange?.(orderRegion(snapToGuides(container, selfKey, px) ??
-                                            +container.xScale.invert(px), edgeRef.current ?? to)) }), _jsx(DragArea, { x: xb - EDGE_GRAB / 2, y: 0, w: EDGE_GRAB, h: h, cursor: "ew-resize", editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragStart: () => {
+                                            +container.xScale.invert(px), edgeRef.current ?? to)) }), _jsx(DragArea, { x: xb - EDGE_GRAB / 2, y: 0, w: EDGE_GRAB, h: h, cursor: "ew-resize", editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDragStart: () => {
                                             edgeRef.current = from; // the fixed pivot = the near edge
                                         }, onDrag: (px) => onChange?.(orderRegion(snapToGuides(container, selfKey, px) ??
                                             +container.xScale.invert(px), edgeRef.current ?? from)) })] }))] }))] }), text && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {

package/dist/context.d.ts

@@ -11,6 +11,14 @@ import type { AxisFormat } from './format.js';
  * time→pixel `xScale` follow. Y scales stay per-row (row-local data), on the
  * {@link RowFrame}.
  */
+/** Where a top-flag label sits: its lane (0 = top; overlapping labels stack
+ *  down) and the chip text to render — the merged label for the representative of
+ *  a coincident-marker group, `null` for the members folded into it, else the
+ *  mark's own label. Computed by `computeLabelLanes`. */
+export interface LabelPlacement {
+    readonly lane: number;
+    readonly label: string | null;
+}
 export interface ContainerFrame {
     readonly timeRange: readonly [number, number];
     readonly width: number;
@@ -39,6 +47,22 @@ export interface ContainerFrame {
     readonly cursorX: number | null;
     /** Set the hovered plot-pixel x; a row's event surface calls this on pointer move. */
     setHoverX(x: number | null): void;
+    /**
+     * The hovered plot-pixel **y** and the row it's in — for the free-form
+     * crosshair's horizontal line + value readout (which are row-specific, unlike
+     * the shared vertical `cursorX`). `null` when not hovering a plot. Hover-driven
+     * only (no controlled equivalent).
+     */
+    readonly cursorY: number | null;
+    readonly cursorRowKey: symbol | null;
+    /** Set the hovered plot-pixel y + its row; the event surface calls this on move. */
+    setHoverY(y: number | null, rowKey: symbol | null): void;
+    /**
+     * `cursor="crosshair"` **y** snapping. **Default `true`** — the reticle centres
+     * on the nearest data point's value. `false` — the y follows the pointer freely
+     * (`yScale.invert`). The x always snaps to the data grid either way.
+     */
+    readonly crosshairSnap: boolean;
     /**
      * The selected mark, or `null`. Shared across rows (single selection). A layer
      * highlights the mark matching **both** the key (epoch ms) and the series
@@ -146,10 +170,20 @@ export interface ContainerFrame {
     /** Every registered annotation — read by each row to draw the *other* rows'
      *  guides, and by a drag to find snap targets. */
     readonly annotations: readonly AnnotationSpec[];
-    /** Vertical lane (0 = top) for each top-flag label, by slot key — overlapping
-     *  marker/region labels stack into lower lanes instead of colliding. A key absent
-     *  from the map (or mapping to 0) sits in the top lane. */
-    readonly labelLanes: ReadonlyMap<symbol, number>;
+    /** Per-key top-flag {@link LabelPlacement} — the lane (0 = top; overlapping
+     *  labels stack down) + the chip text (merged for the representative of a
+     *  coincident-marker group, `null` for the folded-in members). A key absent
+     *  from the map sits at lane 0 with its own label. */
+    readonly labelLanes: ReadonlyMap<symbol, LabelPlacement>;
+    /**
+     * The annotation currently being **dragged** (its slot key), or `null`. Set on
+     * drag-start, cleared on release. The lane packers (label lanes + x-axis pill
+     * lanes) exclude it so the *static* marks don't reshuffle as the dragged one
+     * crosses them — only the mark under the pointer moves; it settles on release.
+     */
+    readonly draggingKey: symbol | null;
+    /** Mark/clear the actively-dragged annotation; a mark's drag calls this. */
+    setDragging(key: symbol | null): void;
     /**
      * The armed creation tool, or `null` (idle). Set by the consumer's toolbar;
      * when non-null the plot captures a **create gesture** (draw a new mark) instead

package/dist/tracker.js

@@ -25,9 +25,10 @@ export function cursorParts(mode) {
         case 'flag':
             return { line: false, dots: true, chip: 'flag' };
         case 'crosshair':
-            // Vertical line + per-series dots, values pinned to the axes (y pills in
-            // `Layers`, the x-time pill on `<XAxis>`).
-            return { line: true, dots: true, chip: 'axis' };
+            // A single reticle (not per-series): `Layers` draws the dashed vertical +
+            // full-width horizontal lines, the centre dot, and one value pill itself
+            // (so no generic line/dots here); the x-time pill is on `<XAxis>`.
+            return { line: false, dots: false, chip: 'axis' };
         case 'none':
             return { line: false, dots: false, chip: 'none' };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "private": false,
   "description": "Canvas-rendered, streaming-first time-series charts for pond-ts",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "perf": "PERF_BENCH=1 playwright test perf.spec.ts --workers=1"
   },
   "peerDependencies": {
-    "@pond-ts/react": "^0.38.0",
-    "pond-ts": "^0.38.0",
+    "@pond-ts/react": "^0.40.0",
+    "pond-ts": "^0.40.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {