@pond-ts/react 0.56.2 → 0.58.0

package/CHANGELOG.md

@@ -8,7 +8,9 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 under a single `v*` tag, so this file covers them all. Pre-1.0: minor bumps may
 include new features and type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pond-ts/pond/compare/v0.56.2...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.58.0...HEAD
+[0.58.0]: https://github.com/pond-ts/pond/compare/v0.57.0...v0.58.0
+[0.57.0]: https://github.com/pond-ts/pond/compare/v0.56.2...v0.57.0
 [0.56.2]: https://github.com/pond-ts/pond/compare/v0.56.1...v0.56.2
 [0.56.1]: https://github.com/pond-ts/pond/compare/v0.56.0...v0.56.1
 [0.56.0]: https://github.com/pond-ts/pond/compare/v0.55.0...v0.56.0
@@ -59,6 +61,1221 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.58.0] — 2026-08-10
+
+### Added
+
+- **charts: `<LineChart id>` / `<AreaChart id>` — selection on a continuous
+  trace** ([PND-TRACESEL]), the last two columns of the selection matrix. A
+  trace has **no marks**, so the currency differs from every other layer and
+  does so deliberately: a **sweep** commits a `SpanSelection` with **no hits**
+  (the span _is_ the selection — a trace's samples are usually undrawn and
+  several fall per pixel, so take the span and slice your own series with it),
+  and a **click** commits a **series-scoped** `SelectInfo` — `key`/`value`
+  `NaN`, plus a stable `mark` so re-clicking deselects. The brush band is the
+  whole live preview, because there are no marks to light. An area is hit
+  through its **fill** (the whole shape is the target); a line within 6px of
+  its **stroke**. New `sweepSpan` session in the kernel; `sweepsRect: false`,
+  `sweepAxis: 'x'`.
+- **charts: trace interaction states.** A selected series **thickens and keeps
+  its colour** — state is weight, never hue, because a line's colour is how a
+  reader tells one series from another (the same rule `<Candlestick>` follows).
+  Other series recede to `0.32` with their hue intact; hover echoes the
+  selected weight. A **swept window** partitions the trace: the covered portion
+  is emphasised and may take a hue (`spanColor`, defaulting to the selection
+  blue) because inside one series identity is not in question, while the rest
+  recedes. New `LineStyle` tokens `selectedWidth` / `hoverWidth` /
+  `dimmedOpacity` / `spanColor`, and `AreaStyle` gains those plus
+  `selectedFillOpacity` — an area's mark is its fill, so its state channels are
+  fill strength and edge weight rather than weight alone. The partition is
+  **live during the drag**, and a sweep covers **every trace in the row** rather
+  than the topmost one: they all share the same x window, so singling one out by
+  z-order would be arbitrary. Mark layers keep topmost-wins unchanged.
+  `spanColor` applies only when a single trace is swept — with two, both would
+  go blue and identity would be in question again inside the window. A line's
+  emphasised segment has **round ends**: it strokes an interpolated slice of the
+  path rather than the whole trace clipped, so its endpoints are real path ends
+  and take a cap. An area still clips, because a fill's boundary is a vertical
+  wall by construction.
+- **charts: keyboard parity on the list family.** Rows now navigate and select
+  from the keyboard: **↑/↓** move focus, **Home/End** jump to the ends,
+  **Enter/Space** select the focused row (carrying modifiers, so ⌘/Ctrl-Enter
+  adds), and **Shift** with any movement key extends the run. The anchor is
+  shared with the pointer, so a click can be finished with the keyboard; it
+  holds across repeats, so Shift-↓ grows one run rather than sliding a two-row
+  window. Navigation never selects on its own, movement keys are
+  `preventDefault`ed so the page cannot scroll out from under the list, and
+  arrows stay inside their own table rather than walking into a nested list in
+  an expanded row.
+- **charts: `<BarList onRowSelect>` / `<BoxList onRowSelect>`** — the range
+  gesture, and how a user actually produces a multi-row `selected`. The list's
+  answer to `<MultiSelector>`: **mounting it enables the drag** (a list with
+  only `onRowClick` is unchanged), a click reports `[row]` — so it is a strict
+  superset — and a drag across rows reports the whole inclusive run in display
+  order, plus `SelectModifiers`. **Crossing into another row is what makes it a
+  range**, not a pixel slop, so a press-and-release is always a click and a
+  horizontal wobble commits nothing; wander to another row and back and it is a
+  click again. The covered rows light as _hovered_ while the drag runs — the
+  live preview out-ranks `hovered` for the duration without touching it, and
+  `onHover` stays quiet so the two channels never contradict. The library holds
+  no state and applies no set arithmetic: you get the run and the modifiers.
+  `shiftKey` is reported but given no built-in meaning. Native text selection
+  is suppressed for the press's duration only, so a drag does not sweep up the
+  label text while the labels stay selectable at rest; **touch is excluded** —
+  a vertical drag over a list is how a touch device scrolls, so touch keeps
+  click-to-select.
+- **charts: the row-chart state ladder** — `<BarList>` / `<BoxList>` now carry
+  rest / hover / selected / dimmed states, via a new optional
+  **`ChartTheme.list`** register (`hoverBand`, `hoverRail`, `selectedBand`,
+  `selectedRail`, `markerInk`). A row's **band** (the whole stripe, gutter to
+  value) and **rail** (a 3px inset edge) carry state, because a row's mark is
+  as short as its value and cannot be its own target. **Back-compatible when
+  omitted:** a theme with no `list` keeps the pre-token look exactly — the
+  borrowed hover band, the annotation rail, and no dimmed state. An
+  **interactive** row reserves a 44px hit area (a static list is left alone). A
+  `<BoxList>` recedes its body, median and tick but never its range band, and a
+  multi-metric `<BarList>` row keeps every metric's own hue when selected — the
+  fill is the metric's identity, so state lives on the chrome.
+- **charts: a horizontal `<BarChart>` can be swept** ([PND-HSWEEP]). `<MultiSelector>`
+  now works on a transposed chart, cut with a **vertical** drag: same component,
+  same 1-D cut, the axis moved. The value axis stays inert exactly as it does on
+  a vertical chart. Layers declare which axis a sweep cuts through the new
+  `RowLayer.sweepAxis: 'x' | 'y'` (default `'x'`, so nothing else changes), and
+  the brush band is drawn transposed and snapped to bin edges. Covers a
+  **categorical** bin axis too (the funnel / ranking shape): the span reads as
+  a slot run and the band lands on whole slots. The horizontal
+  **heat map** still cannot sweep — it cannot hit-test either — and a y-cutting
+  row draws no resting block preview yet.
+
+- **charts: new `sameMark(a, b)` export** — the full mark identity (`id`,
+  `mark`-or-`key`, `label`), companion to `selectionContains`, whose doc has
+  always told a consumer to write `remove(cur, hit)` without giving them
+  anything to write it with.
+
+- **charts: a rect-sweeping row rests as a small crosshair** — the last piece
+  of the 2-D brush. Under a mounted `<MultiSelector>`, a row whose topmost
+  sweepable layer cuts a rect (a scatter, a heat map) shows a compact grey `+`
+  at the pointer; a drag pins that same `+` at the anchor, adds a second at
+  the pointer, and spans the blue rect between them.
+
+  It is deliberately _not_ a full-plot crosshair. That is a value-reading
+  instrument — it exists to project the pointer onto both axes — whereas this
+  marks a corner a rect would start from, and the rect draws its own edges out
+  to those axes the moment a drag begins. Plot-spanning rules would add two
+  more lines to a picture that is about to have them anyway.
+
+  It replaces the resting _band_, which a 2-D row should never have shown: a
+  band previews the snap block, and the block is a whole x column while the
+  drag beside it captures a rect. New `RowLayer.sweepsRect` declares which
+  shape a layer sweeps, so the resting cursor can ask without building a
+  per-drag session.
+
+- **charts: a heat map's selection is one outline around the region, not one
+  per cell** — new optional `theme.heat` slot (`HeatStates`: `veil`,
+  `hoverRing`, `ringWidth`, `perimeter`, `perimeterWidth`). Absent, the
+  pre-states treatment is unchanged. The _geometry_ still comes from
+  `theme.bar` — a cell is a bar's slot with colour instead of height — and
+  only the state styling is new, because a bar's fill is free while a cell's
+  fill **is the datum**.
+  - **The live drag shows the SNAPPED rect it is about to take** (new
+    `SweepSession.snap`), not the rectangle the pointer traced. A heat map
+    snaps to whole bins and whole rows, so a raw pointer rect promises a
+    different set than the release delivers — and the two disagree exactly
+    while the reader is deciding where to let go. A scatter's cut is free, so
+    its brush stays on the pointer, which is honest there.
+  - **A committed selection is one region however it was assembled.** On
+    release the new rect joins what is already selected and the outline
+    merges: one perimeter around the union, drawn by suppressing each cell
+    edge whose neighbour is also selected. No connectivity pass falls out of
+    that — disconnected pieces get one outline each and a hole gets its own,
+    which is what keeps a demoted region readable instead of the "mostly
+    border" grid a per-cell outline gives. No false edge where a selection
+    runs off-screen.
+  - **A snapping layer's sweep reports its covered marks without lighting
+    them** (`SweepGesture.preview`'s new `light` argument). The heat map's
+    hover treatment is a ring around _the cell under the pointer_, and during
+    a sweep there is no such cell: a ring on every covered cell turned the
+    region into a grid of borders inside a rect already saying the same
+    thing. Consumers still hear the whole set through `<MultiSelector
+onHover>`.
+  - **An unselected cell recedes under a flat overlay, not `globalAlpha`.**
+    Alpha and value are the same channel on a ramp, so fading a cell slides it
+    along the scale; an overlay is uniform and monotonic, so the ramp's order
+    survives inside the receded set. It is a colour rather than a number
+    because opacity composites with whatever is _behind_ the cell, which would
+    veil the same value to different colours in different charts.
+  - **The hover ring is a pair** — a light ring outside and a dark one inside,
+    both within the cell. A single ring cannot work against a ramp: the light
+    one vanishes at the pale end and the dark one at the dark end.
+
+- **charts: a scatter point carries its state in colour AND size** — new
+  optional `theme.scatter.*.states` (`hover` / `hoverRadius` / `selected` /
+  `halo` / `haloWidth` / `dimmedRadius` / `dimmedOpacity`). Unset ⇒ the
+  previous behaviour exactly: a live point keeps its fill and is merely
+  re-ringed in `selectedOutline`.
+
+  A point is the one mark with a spare channel. A candle's hue _is_ its
+  meaning and a heat cell's colour _is_ its value, so those carry state in
+  weight and chrome; a point's colour encodes nothing by default and it also
+  has **size**. So the two live states split the channels rather than sharing
+  one: **hover grows and brightens** (keeping its own hue — a preview that
+  borrowed the committed colour would read as committed), while **selection
+  recolours and keeps its size**, so committing a sweep does not reflow the
+  cloud under the pointer. Both take a halo, which is what keeps overlapping
+  points countable once a whole swept region shares one fill.
+
+  A point outside a non-empty selection **shrinks as well as fading** — alpha
+  alone thins a cloud to nearly nothing, and the shape of the unselected field
+  is what a scatter's background is for. A hover does not recede the field;
+  only a committed selection does.
+
+  The radii are px against the base `radius` and applied as the **ratio**
+  between them, so a data-driven `radius` encoding still grows and shrinks
+  proportionally instead of flattening to one size when a point goes live.
+
+- **charts: `<MultiSelector>` sweeps a 2-D rect on `<ScatterChart>` and
+  `<HeatMap>`** ([PND-INTERACT2D]). Every other mark owns a column of the key
+  axis, so a drag over it is a range of keys; a scatter point owns a
+  _position_ and a heat cell owns a `(bin, row)`, so the same gesture becomes
+  a **rectangle**. Nothing new is mounted and no prop is added — the layer
+  declares its own dimensionality, so the markup for a scatter is the markup
+  for a bar.
+  - **Scatter cuts a free rect** and commits `SpanSelection.y` (the drag's
+    continuous window) alongside `x`.
+  - **The heat map snaps both dimensions** — bins on x, whole rows on y — and
+    commits `SpanSelection.rows` by row **name**, so a re-ordered `columns`
+    list cannot silently repoint a selection at different data. Snapping both
+    axes is also why a capture is always a contiguous rectangle of cells.
+  - The drag paints a **rect brush** (`theme.brush`'s existing fill/edge
+    tokens) with a small `+` on each end of the drag diagonal, in place of the
+    1-D band.
+  - A 2-D drag arms on pointer **distance**, not `|dx|`, so a straight-down
+    drag is a gesture rather than a click.
+  - A 2-D layer publishes **no resting block preview**, and a click on one
+    selects the mark under the pointer: the block would be a whole column,
+    which is not what the rect gesture beside it captures.
+
+- **charts: `<Candlestick>` gains the id-gated interaction surface** — `id`,
+  `hitTest`, `beginSweep` and `binIntervals`, so a candle selects, hovers and
+  sweeps like every other column mark. A candle is an aggregation owning one
+  `[x, xEnd)` slot; hits are rect containment over that slot (a doji body is a
+  pixel tall and a wick is a hairline, so requiring drawn ink would make most
+  candles unclickable), `key` is its `x` and `value` its `close`.
+
+- **charts: a candle carries its state in weight and alpha — never in hue.**
+  New optional `theme.candle.*` tokens `liveWickWidth` and `dimmedOpacity`.
+  Where a bar swaps its fill and a box rotates its tint ladder, **a candle's
+  hue is its meaning** — rising vs falling is the first thing read off it — so
+  a candle introduces no state colour at all:
+  - **Live** (hovered _or_ selected): an outline around the slot in the
+    candle's **own body colour**, and lines thickened to `liveWickWidth`.
+  - **Selected**: the same, plus the rest of the field receding to
+    `dimmedOpacity`.
+
+  So hover and selection look identical _on the mark_ and differ in what
+  happens to the others — a deliberate consequence of hue being unavailable.
+  It also means the weight bump fires on hover here, unlike
+  `BoxStyle.selectedStrokeWidth`, which only selection triggers because a box
+  announces hover by moving its ladder.
+
+  Both tokens optional; unset ⇒ a display-only candle exactly as before.
+
+- **charts: `<BoxPlot>` joins the sweep — it publishes `binIntervals` and
+  `beginSweep`, so a `<MultiSelector>` selects boxes by column.** A box is an
+  **aggregation**: it owns one `[begin, end)` interval of the key axis, and the
+  fact that its ink floats between two quantiles rather than rising from the
+  baseline says nothing about which column the mark occupies. So it sweeps
+  exactly as a bar does — a bar that simply isn't grounded to the axis — over
+  the same `sweep1D` cut, with each materialised hit identical to what
+  `hitTest` reports for that box. A gap box (its present quantiles not all
+  finite) owns no membership, the rule `hitTest` and the flag already applied.
+
+  `binIntervals` is the other half: the region cursor and the sweep band now
+  snap to box edges instead of running centre-to-centre, which is what keeps
+  the drawn band and the committed span agreeing (RFC A7.6's edge rule).
+
+- **charts: `<BoxPlot>` gets a tint ladder — `theme.box.*.states`, one
+  four-step ladder per interaction state.** Every mark of a box reads its step
+  from the same ladder (0 body/outer · 1 the solid shape's inner bar · 2 stroke
+  - whiskers · 3 the median rule), so a state change is a **single palette
+    swap** and the quantile read survives it intact. The ladder carries its
+    meaning in _lightness_, which is what lets a box move wholesale — brighter
+    teal on hover, blue when committed — where a multi-hue stacked bar cannot.
+
+  Three rules it encodes, each the opposite of what the `bar` palette needs:
+  - **Shift the ladder, not one step.** Recolouring only the median, or only
+    the body, breaks the read; all four steps move together and keep their
+    relative spacing.
+  - **Dim without desaturating.** A single-hue ladder has nothing to muddy
+    into, so the receded state is the rest ladder at `dimmedOpacity` (`0.32`) —
+    no desaturated companion of the kind `bar.groupsDimmed` is.
+  - **Hairlines need weight, not just hue.** At 1px a colour change is nearly
+    invisible, so a selected box's body stroke and whiskers take
+    `selectedStrokeWidth` (1 → 1.5 on `defaultTheme`) alongside the swap.
+
+  It follows the bar palette's rule exactly — hover brightens within teal, blue
+  means committed — and step 2 of each ladder **is** the matching bar token
+  (`bar.hover` / `bar.highlight`), so a live box beside a live bar reads as one
+  act.
+
+  With a ladder in force the old bounding outline is superseded and no longer
+  drawn: the ladder has already moved every mark, and a rect around a whisker
+  claims the empty slot either side of it as part of the mark. `states` is
+  optional — unset ⇒ the flat `fill`/`stroke`/`median`/`whisker` tokens and the
+  outline cue, exactly as before.
+
+  **`defaultTheme.box.default.strokeWidth` moves `1.5` → `1`**, so the selected
+  weight has somewhere to go.
+
+- **charts: `defaultTheme` gains a stack group ramp — `bar.default.groups`,
+  `bar.default.groupsHover` and `bar.default.groupsDimmed`.** A multi-group stack resolved every group to
+  `bar.default.fill`, because each group looks up a theme role named after
+  itself and an unthemed stack has none — so an unthemed stacked chart painted
+  every segment one teal, its structure visible only as hairline seams. The
+  ramp is four muted hues at similar lightness (`#4c9e8f` `#5379be` `#e2a54a`
+  `#b5604e`, first group first, cycling), so it says "different group" rather
+  than "more important".
+
+  `groupsDimmed` is the receded counterpart, **per group** rather than the flat
+  `dimmed`: a stack dimmed to one colour stops being a stack, and the
+  unselected bins a selection wants you to compare against become solid blocks.
+  Each entry is its ramp colour desaturated and lightened, keeping hue and
+  relative lightness.
+
+  `groupsHover` is per-group for the reason the flat `hover` cannot be: one
+  hover colour repaints the pointed-at segment in a hue belonging to a
+  different group, so hovering _erased the ramp_ exactly where the reader was
+  looking — and under a `<MultiSelector>`, where hover is block-scoped, it
+  erased the whole bin at once. Each entry is its ramp colour brightened by
+  the same move `fill` → `hover` makes (hue held, lightness `+0.11`).
+
+  Two deliberate boundaries. **Multi-group only** — `categories` and every
+  horizontal bar run the same stacked draw path with `G === 1`, and a ramp
+  there would repaint charts that have nothing to do with stacks, so a
+  single-group stack keeps `fill`. And a **`<BarChart colors>` override yields
+  the whole ramp**, dimmed entries included, since pairing the call site's hue
+  with the ramp's receded counterpart would dim a colour to one belonging to a
+  different colour entirely.
+
+  Resolution per group is unchanged apart from the new fallback:
+  `colors` → a role named after the group → the ramp → `fill`.
+
+- **charts: `ChartTheme.brush` — the drag band is now themeable.** The live
+  region a brush drag paints (`<RangeCursor>`'s band and `<MultiSelector>`'s
+  sweep, which share one renderer) takes `{ fill, edge? }` — a wash plus 1px
+  start/end hairlines, so a band has a readable extent while the gesture is
+  still live. `defaultTheme` sets it to the bar palette's _selection_ blue at
+  7% (`rgba(63,91,224,0.07)`, edged `rgba(63,91,224,0.45)`): a live sweep is a
+  selection being made, so it reads in the hue it is about to commit to.
+  **Optional and back-compatible** — a theme that sets no `brush` draws the
+  cursor ink at `0.12` with no edges, byte-for-byte what every theme drew
+  before.
+
+- **charts: `<Selector>` — click-select is now something you mount**
+  (interaction RFC §7, step 4 of the wave). Mount it as a child of
+  `<ChartContainer>` (every row) or inside a `<ChartRow>` (that row only):
+
+  ```tsx
+  <ChartContainer selected={sel} hovered={hov}>
+    <Selector onSelect={(hit, mods) => setSel(next(sel, hit, mods))} />
+    <ChartRow>…</ChartRow>
+  </ChartContainer>
+  ```
+
+  It reports and holds nothing. `modifiers` carries `additive` (⌘ on macOS,
+  Ctrl elsewhere) plus the raw keys; pond applies **no** policy to them and
+  holds no set — the consumer computes the next selection and feeds it back.
+
+- **charts: `<MultiSelector>` — sweep-select** (interaction RFC §8 / A5.2,
+  step 5 of the wave), the superset of `<Selector>`: a click still selects one
+  mark, and a drag past the slop **sweeps** — the shared brush band extends
+  (bucket by bucket with a `sequence`, freeform without), every covered mark
+  lights live through the plural `hovered` (frame-coalesced, delta-gated), and
+  release fires once with **both currencies**:
+
+  ```tsx
+  <MultiSelector
+    sequence={daily}
+    onHover={(hits) => …}                  // live, as the sweep moves
+    onSelect={(hits, modifiers, span) => …} // marks + the span they demote to
+  />
+  ```
+
+  `hits` is the materialised live preview (release runs no fresh range query);
+  `span` is a `SpanSelection` with the covered marks' snapped-outward extent,
+  so `selectionContains([span], hit)` agrees with `hits` exactly — feed the
+  span back as `selected` and stash the hits for A5.2's demote-on-edit. Works
+  on **category axes too** (the `[PND-CATRANGE]` fold-in): ordinal and
+  continuous are the same gesture when the payload is marks. 1-D layers in
+  this release (bars — single, stacked, categorical); the 2-D rect for
+  scatter / heat map is `[PND-INTERACT2D]`. The sweep preempts pan and a
+  drag-enabled `<RangeCursor>` in the same scope (dev-warned — one drag owner
+  per scope).
+
+- **charts: large selection / hover sets no longer scan linearly in the bar
+  draws.** A sweep preview (or a demoted sweep echoed back as marks) can put
+  thousands of entries in `hovered` / `selected`, where the per-bar linear
+  match measured 6.2 s/frame at 100k undecimated bars; past 16 entries the
+  draw now builds a set index once (exact same match rule) — 18 ms on that
+  case, unchanged at click sizes.
+
+- **charts: the list family gets the canvas's hover channel.**
+  `<BarList>` / `<BoxList>` now take a controlled **`hovered`** prop —
+  one row key or a **set** of them (`string | readonly string[] | null`),
+  mirroring the plural shape `<ChartContainer hovered>` carries — plus an
+  **`onHover(row | null)`** callback. Together they make hover bidirectional
+  the way selection already was, which is what a hover-linked list ↔ chart ↔
+  map view needs: hovering a row lights the matching bar, hovering the bar
+  lights the row.
+
+  Before this, `ListTable` held hover in internal component state that a
+  consumer could neither read nor drive, so the list family was the
+  less-expressive sibling for the same two-state interaction (#608). RFC
+  `interaction.md` A3.1 rules that a conformance item, not a standalone
+  feature: the lists speak the canvas's vocabulary, not a parallel one.
+
+  **Strictly additive** — omit both and the list behaves exactly as it did
+  (a clickable list tracks its own pointer). `onHover` is notification-only,
+  fires in controlled and uncontrolled mode alike, and is deduped by row key,
+  so moving from one row straight to the next reports the new row with no
+  `null` in between. The library holds no set and applies no arithmetic: it
+  reports what the pointer is over and renders what it's handed. Hovered rows
+  also carry a `data-hovered` attribute, alongside the existing
+  `data-selected`.
+
+- **charts: cursor components.** The `cursor` string modes are now mounted
+  presets — `<LineCursor>`, `<PointCursor>`, `<InlineCursor>`, `<FlagCursor>`,
+  `<CrosshairCursor snap showTime format>`, `<RangeCursor sequence>` — mounted
+  as a child of `<ChartContainer>` (the default for all rows) or inside a
+  `<ChartRow>` (the per-row override). Each mode-conditional prop moved onto
+  the component that uses it, where it is always meaningful (interaction RFC
+  §4/A4.1). Render-only presets stack; one gesture-owning cursor
+  (crosshair/range) per scope, dev-warned otherwise. Internally each preset
+  registers a `CursorSpec` — declared snap, render slots taking resolved
+  geometry — with the container resolving and the slots drawing (RFC A2.3);
+  the spec type stays unpublished until the presets have proven it (Q3).
+
+  **Deprecated** (working for one more minor via an internal shim, with a dev
+  warning naming the replacement): `ChartContainer`'s `cursor`, `cursorTime`,
+  `crosshairSnap`, `cursorFormat`, `cursorSequence`, and `<ChartRow cursor>`.
+  `<RangeCursor>` ships the hover band only — its drag (and `onRegionSelect`'s
+  successor) is the next step.
+
+  **Bug fixed by the seam deletion:** a row-level crosshair now gets its
+  x-axis time pill. The pill was gated on the _container_ `cursor` string,
+  which a per-row override never reached (the code comment admitted it);
+  `<XAxis>` now asks whether the **hovered row's** mounted cursor registered
+  an x-axis slot, so a crosshair mounted in (or set on) one row of a multi-row
+  chart shows its pill when that row is hovered — and only then.
+
+- **charts: `<HeatMap scale="log">` and `noData="hatch"`.** Both come from the
+  same chart — US measles incidence by state and year — and both are about a
+  cell meaning what it looks like.
+
+  **`scale="log"`** bands the ramp by equal _ratio_ rather than equal width.
+  Measles incidence runs from ~2,900 per 100k before the vaccine to under 1
+  after it; linear banding over eight colours puts everything below ~360 into a
+  single band — the entire post-1965 record, which is the half of the chart that
+  carries the finding. Bands on `log1p` of the offset from the domain floor, so
+  a value **at** the floor is a real band rather than `-Infinity`; zero is the
+  case that needs it, since an eliminated disease's grid is mostly zeros and
+  those cells are the point.
+
+  **`noData="hatch"`** draws diagonal lines in the theme's grid colour where a
+  cell has no value. The default stays `'blank'`, which is right when a hole
+  just means "outside the record" — but on a pale ramp, painting nothing reads
+  as the _bottom of the scale_, so a state with no surveillance yet looks
+  exactly like a state reporting zero cases. That distinction is the whole late
+  period of the measles chart. Hatching is the convention because no ramp colour
+  can be mistaken for it. Suppressed while decimated: an aggregated cell is not
+  a hole.
+
+- **charts: `panZoom` names its axes — `panZoomX` / `panZoomY` / `panZoomXY`.**
+  The mode was x-only, so a chart wanting to zoom any other axis had nothing.
+
+  ```tsx
+  <ChartContainer panZoom="panZoomY">   // wheel zooms y, drag pans y
+  ```
+
+  **Pan follows zoom's degrees of freedom**: an axis that can be zoomed can be
+  panned, because a zoomed axis shows less than all of itself and the reader
+  needs to reach the rest. `'pan'` stays the one exception — pan with no zoom,
+  x-only, unchanged. `'panZoom'` and `true` are `'panZoomX'`, so nothing that
+  exists moves.
+
+  **`panZoomXY` zooms both axes by one factor about the cursor, holding the
+  aspect ratio** — a feature that looked square stays square. A single-axis zoom
+  changes the ratio, which is the point of asking for one.
+
+  Naming the axes is load-bearing rather than tidiness. A first cut had a single
+  `panZoom2D` that claimed both axes and then silently fell back to y-only
+  wherever x was a **category** axis: the ratio changed and nothing said so.
+  Spelling the axes out makes that the caller's choice. It also means a
+  horizontal `<HeatMap>` — categories on x, bins on y — can pan and zoom at all,
+  where both gesture handlers previously bailed on `xKind === 'category'`.
+
+  Carried as a pixel-space transform on the container, applied by narrowing each
+  y axis' **domain** to the window it makes visible. Pixels because they are
+  axis-independent, so one gesture serves a row whatever its axes' units;
+  narrowing the domain rather than stretching the range because the tick
+  generator must see the visible window (stretching it piled clamped ticks on
+  the plot edge). Panning is clamped so the content always covers the plot.
+
+- **charts: multi-selection** ([PND-MULTISEL]) — three pieces that let a
+  consumer own a multi-valued selection. The library still applies **no set
+  arithmetic**: it reports what happened and renders what it is given, and the
+  policy stays with the consumer.
+  - **`onSelect(hit, modifiers)`** — the second argument carries the keyboard
+    modifiers the click held (`{ additive, ctrlKey, metaKey, shiftKey,
+altKey }`). `additive` is the platform-idiomatic add-to-selection chord
+    (⌘ on macOS, Ctrl elsewhere) resolved once, so every consumer doesn't
+    re-derive it and get one platform wrong. Without this a consumer could not
+    implement ⌘-click-adds **at all** — the click had already been reduced to
+    a hit, forcing every click to be a replace. `undefined` for a selection
+    with no pointer event behind it (a `<Legend>` row, a programmatic select),
+    and the argument is omitted rather than passed as `undefined`, so existing
+    `onSelect` assertions keep their arity.
+  - **`<ChartContainer selected>` accepts a set** —
+    `SelectInfo | readonly SelectInfo[] | null`. A **union, not a
+    replacement**: a single `SelectInfo` still means what it always did, so no
+    existing caller changes. (`docs/rfcs/selection.md` A1.4 proposed replacing
+    the type outright and flagged it as a breaking widen needing the human gate
+    plus a one-release shim; accepting both costs one `Array.isArray`.)
+  - **`BarStyle.dimmed`** — the fill for a bar outside a non-empty selection.
+    Opt-in by construction: a theme that sets no `dimmed` dims nothing, and
+    nothing dims while the set is empty (RFC A2.3 — the library never
+    auto-dims; the theme carries selection-state styling and the library
+    references it by state). It exists because "not in the selection" was
+    otherwise re-invented per component and drifted immediately — one consumer
+    had three charts using `color-mix` at 22%, 28% and 30% for the same
+    concept, in the same week.
+
+  **Scope limit, stated rather than implied:** the selection _set_ renders on
+  **bars**. `ScatterChart` and `HeatMap` draw the first member only
+  (`selected[0]`) — their draw paths match a single mark, and widening them is
+  separate work. (Since done for `HeatMap` — see _Fixed_ above.) `dimmed` is likewise bars-only, so a mixed chart dims its bars
+  and nothing else. `selectionMode` (RFC A1.1) stays unbuilt: it would be sugar
+  over what this ships, and adding it later is additive.
+
+- **charts: `<HeatMap>` — a grid of colour-coded cells** ([PND-HEATMAP]). Bins
+  along x, the series' **columns** down y, colour carrying the value. A single
+  column is a stripe (climate stripes, a load band); many columns are a grid.
+
+  ```tsx
+  <HeatMap series={byMonth} columns={ROWS} colors={ramp} axis="yr" id="sst" />
+  ```
+
+  It adds **no reader of its own** — it builds on `stacksFromColumns`, whose
+  output is already a heat map's shape, so all four series shapes pond can
+  express today (`TimeSeries` or `ValueSeries` × one column or many) work
+  unchanged. That also means it has **no opinion about x**: cell spans are
+  ordinary bin spans, so `aggregate` over a trading calendar, `Sequence.calendar`
+  buckets and `byColumn` value bands all apply, and changing resolution is a
+  re-bin of the series rather than a chart prop.
+
+  The y dimension **must be columns** — a month-of-year grid means a column per
+  month. That keeps the second dimension in the data model, where pond's own
+  reshaping operators (`pivotByGroup`, `partitionBy`) can produce it, instead of
+  inventing a chart-level pivot.
+
+  A cell **carries its value**, so hover and click report it and the readout
+  takes the cell's own colour — the bar-based workaround this replaces cannot,
+  since its bars are a constant-height column carrying no value. Note that a
+  `TrackerSample`'s `value` is where the cursor _draws_, so the cell's number
+  rides `readout`; read it as `readout ?? value`. For a grid, prefer
+  `onHover`/`onSelect`, which resolve **both** axes — the tracker knows only x.
+
+  Colour is data and comes from `colors`, not the theme; geometry and the
+  live-cell treatment borrow `theme.bar[as] ?? theme.bar.default`. A live cell
+  keeps its own colour and gains an **outline** (hover `outlineWidth`, selection
+  twice that) rather than the bar layers' alpha pop, which on a colour scale is
+  both usually invisible and misleading.
+
+  **Viewport decimation, on by default.** Once the visible cells are denser than
+  ~2 per device pixel they overlap and overpaint each other, so the picture is
+  already one cell per column picked by draw order. `<HeatMap>` replaces that
+  with the **mean** per pixel column — what the overdrawn version resolves to at
+  that size — from `O(W·G)` rects instead of `O(V·G)`. A 20,000-bin × 45-row
+  grid over an 800px plot goes from **48ms to 5.7ms**. Below the gate nothing
+  changes at all. `decimate={false}` draws every visible cell; `{ threshold }`
+  moves the gate. While decimated, per-cell outlines are suppressed and
+  interaction still reads the source grid.
+
+  Note this is a move a per-bar-coloured `<BarChart>` deliberately does _not_
+  make: its reduction is a geometric `[min, max]` envelope, which has no honest
+  colour when it spans differently-coloured bars. A heat map's cells composite
+  rather than forming a silhouette, so reducing the **value** and letting the
+  existing ramp colour it is a resampling answer, not a statistic imposed on the
+  reader.
+
+  **`orientation="horizontal"`** transposes the grid: bins run down **y** and
+  the columns become the categories across **x**. Cheaper than the same move on
+  `<BarChart>`, because a heat map has two _position_ axes and no value axis —
+  nothing changes which scale it is measured against, only which one is
+  horizontal on the canvas.
+
+  This is the orientation gene-expression heat maps are drawn in, and it is what
+  makes the layer's y-must-be-columns constraint work rather than fight. Put the
+  long dimension on the **key** axis — one row per gene — and pond's ordinary
+  binning buckets it: `series.byColumn('rank', { width: 20 }, avg)` is "10,000
+  sorted genes into 500 buckets of 20", and `stacksFromBins` hands the result
+  straight to the layer. The few samples become the categories across the top.
+
+  Not built: a grouped two-level x axis, cell value labels, and 2-D region
+  selection / pan-zoom.
+
+### Changed
+
+- **charts (BREAKING): `<ChartContainer selected>` / `hovered` / `onSelect` /
+  `onHover` are REMOVED. Move them onto `<Selector>` / `<MultiSelector>`,
+  which now also WRAP the content they apply to.** No deprecation shim — this
+  is a straight deletion, and the fix is mechanical. Two changes at once:
+
+  **1. State moved from the container onto the selector.** `selected` /
+  `hovered` are no longer container props; they're `<Selector>` /
+  `<MultiSelector>` props, alongside `onSelect` / `onHover`. One component now
+  owns both the gesture and the state it produces — a `value`/`onChange` pair,
+  the same shape as a controlled `<input>`.
+
+  **2. The selector wraps its scope instead of sitting beside it.** Previously
+  `<Selector>` was a bare sibling mount; it now takes `children` and wraps
+  whatever it applies to — every `<ChartRow>` (mounted as a direct child of
+  `<ChartContainer>`) or just one row (mounted inside that `<ChartRow>`
+  instead).
+
+  **Migration — before:**
+
+  ```tsx
+  <ChartContainer selected={sel} onSelect={setSel}>
+    <ChartRow>…</ChartRow>
+  </ChartContainer>
+  ```
+
+  **after:**
+
+  ```tsx
+  <ChartContainer>
+    <Selector selected={sel} onSelect={setSel}>
+      <ChartRow>…</ChartRow>
+    </Selector>
+  </ChartContainer>
+  ```
+
+  Same rule for `<MultiSelector>` — `selected` / `hovered` move onto it, and
+  it wraps its `<ChartRow>`(s) the same way.
+
+  **Had `selected` with no `<Selector>` mounted at all** (controlled
+  highlighting driven from outside the chart — a legend chip, an external
+  filter list — with the plot deliberately inert on click)? Mount
+  `<Selector enabled={false} selected={sel}>` wrapping the same content.
+  `enabled` is new, defaults to `true`, and `false` disables the **gesture
+  only** — no hit-testing, no `onSelect`/`onHover` firing — while `selected` /
+  `hovered` stay in effect. This is the one case that needs a new prop rather
+  than just moving existing ones; every other case is a pure relocation.
+
+  **Why, having shipped the opposite design two days ago** (`docs/rfcs/
+interaction.md` A1.2: "the selector reports; the container holds the
+  state"): the plot gesture already requires mounting `<Selector>` (§7.1,
+  decided earlier still), so a chart that both selects on click and
+  highlights a controlled set — most of them — was wiring one concept in two
+  places with no structural link between them beyond care. Full write-up in
+  `docs/rfcs/interaction.md` Amendment 10. `<Selector>`/`<MultiSelector>` had
+  never appeared in a published release, so this is a same-cycle correction,
+  not a second breaking change to migrate through.
+
+- **charts (breaking, pre-release): `<MultiSelector onSelect>`'s span argument
+  is plural.** The signature is now
+  `(hits, modifiers, spans: readonly SpanSelection[])` — one argument, not the
+  `span` + `spans` pair #634 briefly shipped. **An empty array now carries what
+  `null` used to**: a click (clicks produce marks, only sweeps produce spans) or
+  a sweep that covered nothing. Spans arrive **topmost layer first**; compare
+  them by `id`, since each span-only layer clamps the window to its own key
+  range. Not a compatibility concern in practice — `<MultiSelector>` has never
+  appeared in a published version.
+
+- **charts: `<BarList selected>` / `<BoxList selected>` accept a set**
+  ([PND-INTERACTCONF]). Widened from `string | null` to
+  `string | readonly string[] | null` — the same union `hovered` already took.
+  **Additive:** every existing caller passes a `string` or `null`, both still
+  valid and unchanged. The lists were given the _receiving_ half of the sweep
+  vocabulary (`hovered` went plural because a sweep lights several marks at
+  once) and not the committing half, which made a list multi-select
+  inexpressible whatever gesture drives it. `onRowSelect` below is the gesture
+  that spends it.
+
+- **charts: `defaultTheme`'s resting scatter point moves off cerulean
+  (`#0284c7`) to the shared teal `#2A9D8F`, at 9px.** Blue has to mean
+  _committed_, and a cerulean point going to selection blue is barely a
+  change — the rule the bar palette reached, now for the third time. The
+  `primary` / `secondary` roles keep the **line** roles' hues (that identity
+  is why they exist) and take the same states with their own hue brightened
+  for hover.
+
+- **charts: mounting `<MultiSelector>` now changes the row's RESTING state —
+  the band and the hover become a live preview of the block a drag would
+  select.** Two halves, one requirement ("the grey cursor and the hover
+  highlighting are a preview for the block a drag will select"):
+  - **The brush band is the resting cursor.** With a `<MultiSelector>` in
+    scope over a sweep-capable row, the shared brush band (`<RangeCursor>`'s
+    renderer — one function, so the visuals cannot drift) spans the **snap
+    block under the pointer**: the `sequence` bucket where one is set, else
+    the layer's own bin/slot. It replaces the container's **implicit**
+    `'line'` default; an explicitly chosen cursor — a mounted component or a
+    legacy `cursor` string the consumer actually set — still wins the
+    surface.
+  - **Hover is block-scoped.** Pointing at any one mark of a block lights
+    (and reports through `onHover`) **every mark in the block** — e.g. all
+    four six-hour bars of a day under `sequence={Sequence.calendar('day')}`
+    — reported once per block transition, with within-block moves
+    re-rendering nothing. A co-mounted `<Selector onHover>` keeps its
+    per-mark currency.
+
+  Rest and drag share one code path (the same snap buckets, the same layer
+  sweep session), so what the rest previews and what a drag commits cannot
+  disagree — the drag just grows the same band, and release selects exactly
+  what was lit. **This is new semantics, not a bug fix**: the interaction RFC
+  had hover meaning "the mark under the pointer" (A4.2) and the sweep preview
+  meaning "what would be selected"; a mounted snapping `<MultiSelector>` now
+  unifies them at rest.
+
+- **charts: under a snapping `<MultiSelector>`, a click commits the whole
+  block it previewed** — not the single mark under the pointer. This is the
+  third state falling in behind the two above: with a `sequence` set, the
+  band spans the block, hover lights the block, and a click now selects the
+  block, so the three no longer disagree about what "the thing under the
+  pointer" means. The commit carries the same `{ kind: 'span', … }`
+  descriptor a sweep of that block would produce, so a consumer needs no
+  click-versus-drag branch.
+
+  **Without a `sequence` nothing changes**: a click still reports one mark
+  with a null span and stays distinguishable from a sweep (RFC §8). The test
+  is the **declaration** — an in-scope `<MultiSelector sequence={…}>` — and
+  deliberately not "the block covers more than one mark", which is a different
+  question on a stacked chart, where one bin holds one mark per group and an
+  ordinary unsnapped click would otherwise swallow the whole column.
+
+  On a stack a snapped click therefore commits `bins × groups` marks under one
+  span — 21 for a seven-day bucket over a three-group stack — while an
+  unsnapped one still selects the single segment under the pointer.
+
+- **charts: the brush band's edge rules now draw only while a drag is in
+  flight.** The band renders in two states — previewing the block a drag
+  _would_ select, and tracking a drag actually in progress — and since the
+  resting preview landed, the wash alone could not tell them apart. The edges
+  mark the boundary the gesture has **grabbed**, so at rest there is nothing
+  for them to mark: edging a preview asserts a range the user hasn't made yet,
+  and makes the two states read alike.
+
+  Applies to both band-drawing surfaces, `<MultiSelector>`'s sweep and a
+  snapping `<RangeCursor>`, from the one shared renderer. The wash is
+  unchanged in both states, and a _click_ never flashes the edges on its way
+  to committing a block — the sweep only anchors once it crosses `DRAG_SLOP`.
+  Themes that set no `theme.brush` drew no edges to begin with and are
+  unaffected.
+
+- **charts: `defaultTheme` bars look different. This is a visible change to
+  every chart that uses the default theme** — a new **bar interaction-state
+  palette** in which state is a _hue_ difference rather than a shade of one
+  colour. Previously `fill: '#2563eb'` and `highlight: '#1d4ed8'` were two
+  shades of one blue, so a selected bar read as "the same bar, slightly
+  darker". Now rest is teal and a committed selection is blue.
+
+  | `defaultTheme.bar.default` | old       | new                     |
+  | -------------------------- | --------- | ----------------------- |
+  | `fill` (rest)              | `#2563eb` | `#2A9D8F`               |
+  | `opacity` (rest)           | `0.85`    | `1`                     |
+  | `highlight` (selected)     | `#1d4ed8` | `#3F5BE0`               |
+  | `hover`                    | _(unset)_ | `#3FBFAE`               |
+  | `dimmed`                   | _(unset)_ | `rgba(42,157,143,0.32)` |
+  | `bands[0]` (in-range)      | `#2563eb` | `#2A9D8F`               |
+
+  `hover` is a _brighter teal_ and deliberately **not** blue: blue stays
+  reserved for committed selection, so a passing pointer and a real selection
+  never read as the same act. `bands[0]` follows `fill` because it is the
+  in-range band — a bar under its first threshold must not change colour.
+
+  Two behaviour notes beyond the colours. `defaultTheme` now ships a `dimmed`
+  value, so on the default theme **bars outside a non-empty selection now
+  recede** where before nothing did (opting in was previously the consumer's
+  job). And the resting `opacity` of `1` means gridlines no longer show
+  faintly through a bar. `emphasisOpacity` is unchanged — still unset, still
+  defaulting to `1`.
+
+  Nothing about this is forced on a custom theme: every value above lives in
+  `defaultTheme`, and `estelaTheme` plus any hand-built theme are untouched.
+  To keep the old look, override `bar.default` with the old-column values.
+
+- **charts: `defaultTheme`'s data blue and annotation register re-hued — the
+  two colour collisions the new bar palette created are fixed.** The old
+  annotation turquoise (`#0d9488`) sat ~ΔE 4 from the bar palette's resting
+  teal (`#2A9D8F`), so a placed mark over default-theme bars read as data; the
+  old royal data blue (`#2563eb`) sat ~ΔE 5 from the new _selection_ blue
+  (`#3F5BE0`), so a line drawn over bars read as nearly the selection colour.
+
+  | `defaultTheme`                                                 | old       | new       |
+  | -------------------------------------------------------------- | --------- | --------- |
+  | data blue (`line`/`band`/`area`/`scatter`/`box`/candle rising) | `#2563eb` | `#0284c7` |
+  | dark accents (box `median`, candle rising `wick`)              | `#1e3a8a` | `#075985` |
+  | box `whisker`                                                  | `#aabee9` | `#a3cde5` |
+  | `annotation.color`                                             | `#0d9488` | `#b45309` |
+
+  The whole `#2563eb` family moves together so the theme keeps one data blue
+  (a line and its variance band must stay one hue). The register's new burnt
+  amber is a deliberately warm outlier — nearest data hue ΔE2000 ≈ 18, most
+  40+ — restoring "a placed mark never reads as data" for the whole palette.
+  Both rules are now pinned by `test/default-theme-collisions.test.ts`, so a
+  future palette edit that re-introduces a collision fails CI. The teal
+  fallbacks a theme _without_ an annotation register gets (`#14b8a6` /
+  `#0d9488` built-ins) are unchanged.
+
+- **charts (dev): Storybook unified on the shipped `defaultTheme`.** All ~280
+  `theme={docsTheme}` / `theme={estelaTheme}` props are gone from the stories,
+  so every story now exercises the `theme ?? defaultTheme` fallback a
+  themeless consumer hits — previously nothing in the repo rendered the
+  default theme at all, which is how both collisions above went unseen.
+  Theming-as-a-feature lives in a curated set: the new `Theming/Showcase`
+  group (docs light/dark, estela dark), `Theming/CssVars`, and the handful of
+  stories whose subject is the theme channel itself (custom line themes, list
+  estela restyles, per-role bar/box/annotation maps — now based on
+  `defaultTheme`). Story-local `dimmed`/`highlight` overrides that predated
+  the default palette's own interaction states are dropped.
+
+- **charts: BREAKING — a plot click does nothing unless a `<Selector>` is
+  mounted.** Click-select used to be _implicit_: any layer with an `id` was
+  selectable, and the container maintained an uncontrolled `selected` whether or
+  not anything was wired. Every chart that highlighted on click goes inert on
+  upgrade until a `<Selector>` is mounted — a regression no type error catches,
+  accepted deliberately (RFC §7.1) because selection turned out to be a whole
+  subsystem (modifiers, a set, a de-emphasis slot, a sweep gesture, precedence
+  against hover) and a subsystem that large should not switch itself on because
+  a layer happened to be given an `id`.
+
+  **What is _not_ affected:** `selected` / `hovered` stay on `<ChartContainer>`
+  (RFC A1.2), so **controlled highlighting keeps working with no `<Selector>`
+  mounted** — a legend chip or an external filter list driving the chart is
+  untouched. So does the hover _highlight_, and so does a programmatic
+  `select()` from `useChartLegend`. The break is precisely the plot gesture.
+
+  Softening the landing: a dev build warns **once** when a click resolves to a
+  mark and no `<Selector>` is mounted — and **suppresses that warning when
+  `selected` is supplied** (RFC A2.6), because after A1.2 that is the signature
+  of the _endorsed_ controlled-highlight setup rather than of a lost click. The
+  warning is scoped to the deprecation window: an `id` without a `<Selector>` is
+  a legitimate configuration afterwards (identity without enablement).
+
+- **charts: `<ChartContainer onSelect>` / `onHover` are deprecated** in favour
+  of `<Selector onSelect>` / `onHover`. They keep working for one more minor —
+  the container synthesizes an equivalent registration internally, so an
+  existing chart keeps its click _and_ stays out of the warning above — and
+  dev-warn once naming the replacement. A mounted `<Selector>` in the same scope
+  overrides them.
+- **charts: `<RangeCursor>` gets its drag — `onDragRelease`, `enableDrag`,
+  `dragModifier` — on a single brush recognizer** (interaction RFC §6 / A4.2,
+  step 3 of A4.4). Wiring `onDragRelease` makes the cursor draggable: the band
+  extends bucket by bucket over the cursor's `sequence` (or a histogram's
+  bins; freeform without either), fires **once** on release, and the cursor
+  **reverts** to the single-bucket highlight — it does not keep the range.
+  The payload is a new exported **`RangeSpan`** — `{ x: [lo, hi], y? }` in
+  axis units, not the legacy bare pair: one uniform shape whose optional `y`
+  the 2-D drag (scatter / heat map, RFC A3.3) will populate additively.
+  `span.x` is exactly what `ChartContainer.range` accepts, so drag-to-zoom is
+  `onDragRelease={(s) => setRange(s.x)}`. `enableDrag` defaults to
+  `!!onDragRelease` and is the **OFF** switch — set it `false` to freeze the
+  gesture without unwiring the callback; `dragModifier="shift"` shares the
+  surface with pan (plain drag pans, shift-drag selects) and is only enforced
+  while pan is enabled.
+
+  Structurally, **one brush recognizer now arbitrates every drag claim on the
+  plot** — annotation-create capture, the range drag (component or legacy),
+  and pan — in a documented precedence order (`packages/charts/src/brush.tsx`,
+  RFC A1.5 / A2.7), replacing the ad-hoc ordering inside
+  `Layers.handlePointerDown`; the band visual is one shared renderer
+  (`renderBrushBand`) so `<RangeCursor>` and the future `<MultiSelector>`
+  cannot drift apart. Observable behaviour is unchanged — every existing
+  interaction test passes as-is. The legacy `cursor="region"` +
+  `onRegionSelect` + `regionSelectModifier` surface keeps working for one more
+  minor (now with the dev deprecation notice naming the replacements); a
+  mounted `<RangeCursor onDragRelease>` takes the gesture over it.
+
+- **charts: span selections — `SpanSelection` entries in `selected`, and
+  `selectionContains`** (interaction RFC A5.2/A5.3/A7.6). The controlled
+  `selected` prop's array form now accepts `SelectionEntry =
+SelectInfo | SpanSelection`: a span names **every** mark of one layer inside
+  a range — `{ kind: 'span', id, x: [lo, hi) }` plus `y` (a scatter's
+  continuous second dimension) or `rows` (a heat map's ordinal row names) — so
+  a swept session of ten thousand bars is one entry, not ten thousand, at an
+  O(1)-per-mark membership test in every selection-aware layer (`BarChart`
+  single + stacked, `ScatterChart`, `BoxPlot`, `HeatMap`). Containment is
+  **half-open** on `x`/`y` (the pond bucket convention, and what makes a
+  sweep's snapped-outward edges agree exactly with the marks it captured —
+  RFC A7.6's edge rule); `rows` is label-set membership, stable under a row
+  reorder. The exported `selectionContains(sel, hit)` runs the **same**
+  predicate the layers do, so consumers implementing click policy over a mixed
+  selection never re-implement the interval test; `isSpanSelection` narrows an
+  entry for A5.2's demote-on-edit flow. The union widens **non-breaking**: a
+  bare `SelectInfo` or plain `SelectInfo[]` means exactly what it did, and a
+  spanless render costs nothing new. The sweep gesture itself
+  (`<MultiSelector>`) is a later step; spans are fully exercisable through the
+  controlled prop today.
+
+- **charts: `hovered` is a set.** `<ChartContainer hovered>` accepts
+  `SelectInfo | readonly SelectInfo[] | null` (a union, so nothing existing
+  changes), and the frame carries the normalized array. Several marks can now
+  be lit at once.
+
+  RFC `selection.md` A1.4 argued hover "is inherently one mark under the
+  pointer" — true while hover _means_ pointer position, and false under a drag
+  sweep, where it means "would be selected if you released now" and several
+  marks light together. This is step 1 of A4.3's sequencing and the
+  prerequisite for `<Select>` drag-to-select; plain pointer-over is unaffected
+  and simply carries 0 or 1 members.
+
+  `BoxPlot` reads the first hovered member only, matching the limit its
+  selection reader already carries. (`HeatMap` did too; see _Fixed_ above.)
+
+### Fixed
+
+- **charts: `panZoomXY` lost its aspect ratio at the zoom edge.** The two axes
+  clamped independently — y cannot zoom out past its natural fit, x cannot zoom
+  in past `minDuration` — so whichever hit its limit first stopped while the
+  other kept going, and the picture sheared from that point on. An aspect lock
+  means a limit on **either** axis stops **both**: the factor is now agreed
+  before either axis moves (capped at what y can take, then x is asked what it
+  would do with that, and x's answer is adopted for both). Caught by two new
+  stories — `HeatMap/PanZoomXY`, deliberately diagonally banded because a
+  diagonal exposes shear the instant the ratio slips where a blocky grid hides
+  it, and `ScatterChart/PanZoomXY` — since the only prior `panZoom` story used a
+  category x axis and could not exercise `XY` at all.
+
+- **charts: a `<LineChart id>` / `<AreaChart id>` no longer draws the
+  "nothing is selectable" warning.** Traces became selectable in
+  [PND-TRACESEL] but never joined the container's selectable registry, so the
+  guard that catches a genuinely-forgotten `id` fired on every correctly-wired
+  trace chart — and its remedy told you to add an `id` to a
+  `<BarChart>`/`<ScatterChart>`/`<BoxPlot>`, none of which you had mounted.
+  Both trace layers now register on `id` like every other selectable layer, and
+  the message names all six. The guard still fires for a trace with **no** `id`,
+  which is the footgun it exists for.
+
+- **charts: `<Layers>` and `<ChartRow>` now warn when a `<Fragment>` child
+  swallows the injected declaration index.** A fragment accepts no props, so
+  the index that makes ordering follow the markup died on it and every element
+  inside fell back to the `index = 0` default. The sort is stable, so the tie
+  resolved to **mount** order — which matches declaration order on a
+  synchronous tree, and that is what made it silent: the stack looked right
+  until the two disagreed, at which point a layer toggled on between two others
+  landed on top instead of slotting into place. Direct children were already
+  documented; a dev-only warning now names the consequence, and the fragment is
+  no longer cloned, so React's less specific "invalid prop supplied to
+  React.Fragment" stops firing alongside it.
+
+  **A fragment costs more in `<ChartRow>`**, which is why both sites warn: the
+  axes inside it lose their order _and_ the `side` sort can't see a `<YAxis>`
+  through a fragment, so they render in the plot column instead of a gutter.
+
+  Four places had already tripped it, three of which **demonstrate** ordering:
+  the `LineSweep` story, the `spans[0]`-is-topmost test, and two perf stories —
+  one of them a band-behind-line stack that held only by mount luck. All now
+  use keyed arrays, and the site-traffic gallery page no longer teaches the
+  pattern in prose (its runnable example never used it).
+
+- **charts: `<MultiSelector>`'s demote-on-edit stories removed a whole bin
+  instead of the clicked mark.** They filtered on `m.key !== hit.key`, which
+  is a bar's identity but only half of a stack segment's or a heat cell's —
+  so ⌘-clicking one cell inside a swept heat-map region knocked out every row
+  of its column. Visible as a column-shaped hole in the selection's outline;
+  the outline was faithfully drawing a wrong selection. All three
+  hand-rolled identity tests in `selection-stories.tsx` now call `sameMark`.
+
+- **charts: `<MultiSelector>`'s demote story could only knock out one mark.**
+  It rewrote the span entries and passed everything else through, so once the
+  span had demoted there was nothing left for a second ⌘-click to act on and
+  it silently did nothing. It now implements the ⌘-click policy
+  `selectionContains`' doc describes in full — a mark in the selection comes
+  out, one that isn't goes in — with the demote as the extra step a span
+  needs before it can lose a member.
+
+- **charts: `<ScatterChart>` and `<HeatMap>` index a large selection set
+  instead of scanning it** — the live-preview repaint on both goes from
+  seconds to milliseconds. `bars.ts` grew a per-draw set index at 16 entries
+  because a sweep preview puts the whole covered run in `hovered` and the
+  linear scan measured 6.2 s/frame at 100k; neither 2-D layer had the fix, and
+  a rect fills that set faster than a band can. Measured by the new
+  `scripts/perf-interact2d.mjs`:
+
+  | scenario                              | before  | after   |
+  | ------------------------------------- | ------- | ------- |
+  | scatter, 100k points, 10k covered     | 1424 ms | 13.2 ms |
+  | scatter, 100k points, 50k covered     | 4042 ms | 14.7 ms |
+  | heat map, 365×45, 2,783 cells covered | 2.64 ms | 1.01 ms |
+
+  Below the threshold nothing changes: a clicked handful still scans, and
+  still allocates nothing.
+
+- **charts: a selected segment of a group-ramped stack keeps its own colour.**
+  The outline and the receded neighbours are the cue — the same exclusion
+  `binFills` already gets, and for the same reason: replacing a
+  meaning-carrying colour with the flat `highlight` erases _which group_ is
+  selected, which is the thing the selection is about.
+
+- **charts: six `<MultiSelector>` polish bugs found walking the Storybook
+  stories.**
+  - **A live sweep no longer draws the data cursor over its band.** The
+    default `line` preset (and any mounted cursor) kept painting its solid
+    vertical rule at the raw pointer for the whole drag, so the sweep read as
+    "a line" while the band (7% wash) sat underneath. A live sweep now
+    suppresses the row's cursor slots exactly as annotation editing does; the
+    shared brush band still renders, so a sweep looks like a `<RangeCursor>`
+    drag (RFC §8.1's identical pixels).
+  - **Adjacent selected bars keep their gap.** The selection outline was a
+    centred `strokeRect`, painting `outlineWidth / 2` outside each bar — with
+    the default `gap: 1` that bridged the whole gap from both sides, fusing a
+    swept run into one solid block. The outline now strokes _inside_ the ink
+    (both draw paths, `drawBars` and `drawStacks`); a mark too thin to contain
+    its outline skips it.
+  - **Clicking the empty space above the bars deselects.** Bar slots tile the
+    full plot height (the continuous hover model of #582), so a click could
+    never resolve to "no mark" — RFC §7's empty-commit deselect path was
+    unreachable on a full-range bar chart. The click hit-test now requires
+    the pointer within the bar's drawn ink vertically (the slot keeps its
+    full interval width, so the gap between columns still selects). Hover is
+    deliberately unchanged: the highlight keeps tracking the full slot like
+    the readout. No new callback needed — the existing
+    `([], modifiers, null)` empty commit is the deselect signal.
+  - **A bucket-snapped sweep lights its whole first bucket from the moment
+    the drag starts.** The move that commits the sweep now runs the covered
+    cut synchronously (later moves stay frame-coalesced per RFC A1.4), and
+    the preview is pinned to agree with the commit exactly under a
+    `sequence`.
+  - **The `SweepAdditive` story's policy handled only spans** — any click
+    (⌘ held or not) cleared the whole selection, so the A5.2 headline flow
+    ("sweep, then ⌘-click to extend") deleted it instead. The library
+    reported `(hits, modifiers, null)` correctly all along; the story-side
+    set arithmetic was wrong and is fixed (a story-driven test now pins it).
+  - **A category sweep's band snaps to the slots' outer edges.** The band
+    scale's `invert` returns slot centres, so the freeform band ran
+    centre-to-centre while capture and the committed span snapped outward
+    (RFC A7.6's edge rule) — the drawn band disagreed with the selection by
+    half a slot at each end. The vertical categorical bar layer now publishes
+    its unit slots as snap buckets and the band extends slot-edge to
+    slot-edge.
+
+- **charts: `<ScatterChart>` and `<BoxPlot>` light every selected / hovered
+  mark, not just the first.** `ContainerFrame.selected` has been a set since
+  [PND-MULTISEL] and `hovered` since RFC A4.3, but both layers narrowed it back
+  to one mark on the way into their draw — the scatter with `selected[0]`, the
+  box with a `find` on its own series id. A consumer pinning three marks got one
+  ring (or one outline), no warning, and no error.
+
+  Both now match **any** member of either set, the way the bar paths already do
+  (`barMatchesAny`), keeping the linear scan those document: a selection is a
+  handful of marks a person clicked, so a `Set` per draw would cost more than it
+  saves. Precedence is the shared one — **selected > hovered > rest** — so a
+  mark in both sets draws its selected cue only, never two.
+
+  `<ScatterChart>` gains a **hover cue** in the process: it had a hover
+  hit-test but never rendered one. A hovered point takes the style's highlight
+  ring at half strength, the same two-step signal `<BoxPlot>` uses, so no new
+  theme token is invented. Both layers still suppress every highlight while
+  **decimated**, unchanged — a sub-pixel ring isn't visible and interaction
+  still reads the source marks.
+
+  This supersedes the "`BoxPlot` and `HeatMap` read the first hovered member
+  only" note under _Changed_ below, for `BoxPlot`. `<HeatMap>` had the identical
+  bug and is fixed in the entry below — it was scoped out of this change on a
+  mistaken reading of its source (it maps both sets into plural memos, then
+  passed `selection[0]` into a single-mark `drawHeat` a hundred lines later).
+
+- **charts: `<HeatMap>` lights every selected / hovered cell, not just the
+  first.** `ContainerFrame.selected` has been a set since [PND-MULTISEL] and
+  `hovered` since RFC A4.3. `<HeatMap>` mapped **both** into plural memoized
+  arrays — which is exactly what made the layer read as already-correct — and
+  then handed `drawHeat` `selection[0] ?? null` / `hover[0] ?? null`, whose
+  parameters were `StackMark | null`. A consumer pinning three cells got one
+  outline, with no warning and no error.
+
+  `drawHeat` now takes both sets (`readonly StackMark[]`, defaulting to empty)
+  and outlines **any** cell a member names, keeping the linear scan
+  `barMatchesAny` documents: a selection is a handful of cells a person clicked,
+  so a `Set` per draw would cost more than it saves. Precedence is the shared one
+  — **selected > hovered > rest** — so a cell in both sets takes the
+  full-strength outline once rather than stacking a hover stroke under it. The
+  per-cell scan is gated on either set naming this layer, so a resting draw and a
+  draw whose selection belongs to another layer cost exactly what they did
+  before, and nothing extra is allocated per frame.
+
+  `<HeatMap>` still suppresses every per-cell outline while **decimated**,
+  unchanged — an aggregated column has no per-cell identity to match and a
+  sub-pixel ring isn't visible — now pinned by tests under a plural set.
+
+  This supersedes the "`ScatterChart` and `HeatMap` draw the first member only"
+  scope limit and the "`BoxPlot` and `HeatMap` read the first hovered member
+  only" note below, for `HeatMap`.
+
+- **charts: the `<HeatMap>` `ValueAxisStripe` story threw on mount.** It called
+  `sf.byValue('high')` on the temperature record in _date_ order, and a value
+  axis must be non-decreasing — it is the key — so the story had never rendered.
+  It now sorts by `high` before re-keying. Found by the story render smoke test
+  added alongside the fix above; `<HeatMap>` had no such net, which is how a
+  broken story went unnoticed.
+
+- **charts: hover was stuck on the y axis inside a stacked column.**
+  `<ChartContainer>` deduped the hovered mark on `id + key` so the data canvas
+  repaints only when the mark changes — but `key` is the mark's position on the
+  **bin axis**, unique only for a layer with one mark per bin. A stacked
+  `<BarChart>` column or a `<HeatMap>` column stacks several, so every pointer
+  move _within_ a bin was swallowed: dragging straight down a heat-map column
+  never changed the reported cell, and `onHover` never fired. Now compares the
+  mark's full identity (`id`, `key`, `label`, `mark`). Genuine repeats are still
+  deduped, so this costs no extra repaints.
+
+## [0.57.0] — 2026-08-07
+
+### Added
+
+- **charts: `<Zone>` — a shaded y-span annotation.** The fourth annotation
+  mark, and the value-axis counterpart of `<Region>`: a band between two y
+  values, spanning the full plot width. The mark for a **classification of the
+  value axis** — US EPA AQI categories, heart-rate / power zones, SLO bands,
+  control-chart spec limits — where a reading only means something read against
+  a scale.
+
+  ```tsx
+  {
+    AQI_CATEGORIES.map((c) => (
+      <Zone key={c.role} from={c.from} to={c.to} axis="aqi" role={c.role} />
+    ));
+  }
+  ```
+
+  Colour comes from `theme.annotation.roles[role]`, so a zone _set_ styles as
+  one palette in the theme rather than N colours at the call site. Bounds are
+  order-free, clamped to the plot (a band past the axis domain is cut, one
+  fully outside culls), and accept `±Infinity` for genuinely open-ended bands
+  (`to={Infinity}` — AQI's "Hazardous", a `ZoneTime.openEnded` zone), so a
+  whole category table can be rendered and the axis decides what shows.
+
+  Three defaults deliberately **invert** the rest of the annotation family,
+  because a zone spans the full width and a set tiles the row:
+  `selectable={false}` (else every mousemove lights a band and its hit area
+  eats the plot's clicks), `edges={false}` (contiguous sets share every
+  interior boundary — edges-on draws each twice), and no auto-label (the bounds
+  are already legible on the y axis; the useful label is a name). `<Zone>` has
+  no `onChange` — drag-to-edit zones await a consumer.
+
+  Guide: [From a CSV to a banded chart](https://pond-ts.org/docs/how-to-guides/air-quality-bands).
+
+- **charts: `annotation.dash` — an optional dash pattern for the annotation
+  register**, per-register or per-role (`{ color, fillOpacity?, dash? }`), same
+  shape as `LineStyle.dash`. Applies to marker / baseline lines and region /
+  zone boundaries; fills are never dashed. A dashed reference line reads as
+  _placed_ rather than _measured_ — the job the annotation register exists to
+  do, and one colour alone can't always carry.
+
+- **charts: threshold-banded bars** — `<BarChart thresholds={[1, 2]}>` colours
+  one bar **along its length** against a ladder (neutral → warning → alarm), so
+  a long bar shows how far through the ladder it travelled rather than only
+  which band it ended in. Band fills come from the new
+  **`BarStyle.bands`** on the resolved theme role, overridable per chart with
+  **`<BarChart bandColors>`** — breakpoints are data, colour stays in the theme,
+  the same split `colors` already applies to a stack's group fills.
+
+  The shape was previously expressible as N `<BarChart>` layers drawn
+  outermost-first, each clipped to a band, compositing the gradient by
+  overpainting. That produces the same pixels and loses what matters: N layers
+  means N hit targets, N `SelectInfo.mark` identities and N legend rows for
+  something the reader sees as one bar. Banding is **draw-only** — the hit rect
+  is untouched, so a banded bar stays one bar. It also measures **27–49%
+  cheaper** than the layered workaround at 8–400 categories
+  (`scripts/perf-bandbar.mjs`, which interleaves the arms and prints the
+  ratios), and costs nothing when unused.
+
+  Applies to any single-value bar — `series`, `bins`, `categories`, both
+  orientations. Negatives band symmetrically on the magnitude, so a ± diverging
+  scale needs no negative breakpoints. Ignored (with a dev warning) on a
+  multi-group stack, and yields to `binColors` when both are set. Suppresses
+  envelope decimation for the same reason `binColors` does.
+
+- **charts: `<YAxis hide>`** — keep the scale, draw no gutter, reserve no
+  width. A `<YAxis>` does two jobs — it _holds the scale_ (`min`/`max`/`scale`/
+  `pad`) and it _renders a gutter_ — and there was no way to ask for the first
+  without the second. A caller could express "auto domain, no gutter" (omit the
+  axis) or "explicit domain, with a gutter", but not the pairing a fixed-domain
+  chart needs. Omitting the axis is not equivalent: the row supplies an implicit
+  auto-domain axis, which is exactly what must not be given up. `width={0}`
+  isn't either — the labels still draw, over the plot.
+
+  Gridlines are unaffected: they belong to the plot, not the gutter, and
+  `<ChartContainer grid>` already governs them.
+
+- **charts: `<ChartContainer maxBandWidth>` + `bandAlign`** — cap the **slot
+  pitch** on a category x axis and place the resulting block
+  (`'start'` (default) / `'center'` / `'end'`). A band scale otherwise spreads
+  its categories across the full plot width, so three categories in a 900px
+  panel become three 300px bars and thirty become thirty 30px ones — the same
+  chart in the same panel reading as two different charts depending on how many
+  categories the data returned. Fine for a fixed domain; wrong for a **live**
+  one, where bar width becomes a variable that moves on its own and a reader
+  can't compare the chart to itself a minute ago.
+
+  `maxBandWidth` caps the **slot**; `<BarChart gap>` still insets the bar
+  within it — one knob for pitch, one for ink. Omitting `maxBandWidth` is the
+  previous fill behaviour exactly, and a cap too loose to bind degrades back to
+  it rather than clipping. There is deliberately no `bandAlign: 'fill'`: "fill"
+  is what omitting the cap means, and a `fill` alongside a pitch cap would be a
+  contradiction rather than a choice.
+
+  **Vertical / x-axis categories only** — a `orientation="horizontal"`
+  categorical chart puts its categories on the y axis as unit slots, a
+  different mechanism this does not cap.
+
+- **charts: themed emphasis on the category path** — `BarStyle.hover` /
+  `.highlight` now apply to `categories` and horizontal bars, which routed
+  through the transposed stacked draw path and read neither. New
+  `BarStyle.selectedOutline` (the selected bar's stroke, where the default is
+  its own fill) and `BarStyle.emphasisOpacity` (the alpha a live bar pops to,
+  previously hard-coded `1`) make the emphasis tunable rather than fixed.
+
+  The _behaviour_ was defensible; the problem was that the theme accepted
+  values it would not use. `bar.hover` / `.highlight` were typed, settable and
+  documented as the emphasis channel, and silently did nothing on the most
+  common categorical chart, so a theme author set them, saw no change, and
+  could not tell whether they were wrong about the colour or the mechanism.
+  The one genuine exclusion stays and is now the only one: a `binColors` bar
+  keeps its own colour under hover/selection, because swapping a
+  zone-coloured or direction-coloured bar to a single highlight hue erases
+  what the colour encodes.
+
+### Fixed
+
+- **charts: a negative segment in a multi-group stack is no longer silently
+  dropped** ([PND-SIGNSTACK]). Positives stack **up** from the baseline and
+  negatives stack **down** from it — two running totals per bin — so the
+  **signed stacked histogram** (net flow by category, inflow/outflow, buy/sell
+  pressure by venue) renders correctly. `stackValueExtent` grew the matching
+  negative half; both had to move together, since an extent stopping at `0`
+  would clip the segments the draw path now emits.
+
+  **This is a visible behaviour change** for any existing chart feeding
+  negative values into a multi-group stack — but such a chart was previously
+  rendering _wrongly_: the dropped segments did not clamp, warn or throw, every
+  remaining segment stacked up as though they had never been in the data, and a
+  mixed-sign series came out as a confident, wrong, all-positive chart. An
+  all-positive stack is bit-identical to before. Splitting into two layers was
+  not a workaround either — the negative layer was still `G > 1`, so it was
+  dropped too.
+
+### Changed
+
+- **charts (docs): `<BarChart bins>` now states that it selects a _value_
+  axis** ([PND-TICKUNIT]), so a time-bucketed histogram fed through `bins` gets
+  the decimal 1-2-5 tick ladder rather than the duration ladder a clock
+  subdivides by — labelling e.g. 11:40 and 13:20 at a ~100-minute step. The
+  natural reading ("I have pre-binned buckets, so I'll pass `bins`") is exactly
+  what forecloses the time axis, and nothing at the call site said so. The prop
+  docs now point a time-keyed caller at `<BarChart series columns>`, where the
+  clock ticks are native. No behaviour change.
+
 ## [0.56.2] — 2026-08-05
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/react",
-  "version": "0.56.2",
+  "version": "0.58.0",
   "description": "React hooks for pond-ts live time series",
   "license": "MIT",
   "repository": {
@@ -33,7 +33,7 @@
     "test:runtime": "vitest run"
   },
   "peerDependencies": {
-    "pond-ts": "^0.56.2",
+    "pond-ts": "^0.58.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {