@pond-ts/charts 0.60.0 → 0.62.0

package/API.md

@@ -421,6 +421,7 @@ Series shapes (same file): `ChartSeries`, `BandSeries`, `BoxSeries`,
 | `CandleVariant` / `ColorBy`                | OHLC mark shape / colouring strategy                                                                  | `packages/charts/src/ohlc.ts`             |
 | `AxisFormat` / `CursorFormat`              | Tick and cursor-readout formatting (d3 specifier or fn)                                               | `packages/charts/src/format.ts`           |
 | `AxisTransform`                            | Monotonic `to`/`from` pair for derived-unit x-axis relabeling                                         | `packages/charts/src/derivedTicks.ts`     |
+| `AxisMouseEvent` / `AxisMouseHandler`      | Axis `onMouseEvent` payload — the mouse event, the axis's `id`, and the value/label under the pointer | `packages/charts/src/axis-events.ts`      |
 | `Orientation`                              | Bar growth direction                                                                                  | `packages/charts/src/bars.ts`             |
 
 ---
@@ -520,31 +521,31 @@ Typed dataflow graphs for pipelines whose **shape is data** (runtime-assembled,
 user-edited, one computation fanned out to several consumers). Chaining stays
 the default for pipelines known at authoring time — see the package README.
 
-| Group                   | Exports                                                                                                                                                                                                                                                                                                                                                                                                          | Source                                               |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
-| Worker pool (Node)      | `HostPool` (`start`, `run`, `close`, `size`, `inFlight`); types `HostPoolOptions`, `PoolSetup`, `PoolSetupConfig`; `toWire` / `fromWire`, types `WireResult`, `WireColumn` — subpath `@pond-ts/process/pool`                                                                                                                                                                                                     | `packages/process/src/pool/index.ts`                 |
-| Ports                   | `Inlet`, `Outlet` (typed fields on `node.in` / `node.out`; `get()`, `peek()`, `version`, `connect`, `disconnect`)                                                                                                                                                                                                                                                                                                | `packages/process/src/port.ts`                       |
-| Nodes                   | `Node` (`in`, `out`, `dirty`, `error`, `invalidate()`), `defineNode` (reusable multi-output node type), `derive` (single-output, wired inline)                                                                                                                                                                                                                                                                   | `packages/process/src/node.ts`                       |
-| Port declaration        | `port<T>({ equals, defaultValue })`; types `PortSpec`, `PortSpecMap`, `PortValue`, `PortValues`                                                                                                                                                                                                                                                                                                                  | `packages/process/src/types.ts`                      |
-| Sources                 | `source<T>()` → `SourceNode` (`set()`), `fromLive(liveSource)` → `LiveSourceNode` (`dispose()`); `GraphSource` (bind contract — looser than core's `LiveSource`, accepts `LiveAggregation`), `SnapshotSource`, `NoInputs`                                                                                                                                                                                        | `packages/process/src/source.ts`                     |
-| Graph view              | `Graph` (`Graph.from(...roots)`, `nodes`, `order()`, `edges()`, `toJSON()`); types `GraphEdge`, `GraphJson`, `GraphNodeJson`, `GraphEdgeJson`                                                                                                                                                                                                                                                                    | `packages/process/src/graph.ts`                      |
-| Range output buffers    | `prepareRange(length, keep, prior)` → `RangeOutput` (`values`, `bits`, `set`, `clear`) carrying `[0, keep)` forward as blocks — values **and** validity; `sealRange(out, length)` → `Float64Column`; `validityByteCount`. Reached from an op as `ctx.out[n]`                                                                                                                                                     | `packages/process/src/column.ts`                     |
-| Ranged recompute        | `graph.setSourceFrom(series, changedFrom)` — declares which row first changed; `graph.recomputes` → `{ ranged, full }`. An op opts in with `OpDef.runRange(ctx)`, receiving `{ from, to, previous, previousView, out }` (type `RangeContext`) — write into `out` and return nothing for the block path alongside the usual context. Requires `lookback`. Falls back to a full `run` whenever anything is missing | `packages/process/src/plan/graph.ts`                 |
-| Node budget             | `bind(series, { registry, budgetBytes })` — engine-wide cap on retained node values, LRU, enforced after each `run`; `graph.retainedBytes` / `graph.evictions` / `graph.enforceBudget()`. Unbounded when omitted. Skips a node whose consumer still holds its outlet                                                                                                                                             | `packages/process/src/plan/graph.ts`                 |
-| Plan history            | `requiredHistory(registry, plan)` → `{ known, rows?, undeclared, byOp }` — the minimum safe tail in rows, folded from per-op `OpDef.lookback`. Sums along nesting, maxes across siblings. `known: false` names ops with no declared lookback rather than defaulting to zero (type `HistoryResult`)                                                                                                               | `packages/process/src/plan/history.ts`               |
-| Column values           | `packColumn` (values → packed `Float64Column`, NaN = missing), `columnBytes` (retained size, for a byte budget), `appendColumn` (column → series; boxing-free when gapless), `columnBuffers` / `columnFromBuffers` (the buffer pair a column is, for an isolate boundary; type `ColumnBuffers`), `columnView` (zero-copy borrowed read view for in-process folds; type `ColumnView`)                             | `packages/process/src/column.ts`                     |
-| Plan — registry         | `createRegistry({ folds })` / `Registry` (`define`, `get`, `foldFor`, `outputsOf`, `resolveParams`, `byFamily`, `describe`, `toJsonSchema`), param builders `int` / `num` / `choice` / `flag`, `UnknownOpError`, `ParamError`                                                                                                                                                                                    | `packages/process/src/plan/registry.ts`, `params.ts` |
-| Plan — identity         | `specId` (content-addressed, param-order invariant, defaults materialized), `refToId`, `explain`, `unitOf`, `columnsOf`, `dependsOn`, `outputKey`                                                                                                                                                                                                                                                                | `packages/process/src/plan/identity.ts`              |
-| Plan — types            | `Spec`, `Plan`, `Input` (column name \| `Spec` \| `PickedOutput`), `SpecRef`, `Def` (`OpDef` \| `FoldDef`), `OpContext`, `OpResult`, `FoldContext`, `FactBody`, `isFold`, `ParamDef`, `Params`, `Units`, `InputDef`, `OutputDef`                                                                                                                                                                                 | `packages/process/src/plan/types.ts`                 |
-| Plan — bind / run       | `bind(series, { registry, units })` → `BoundGraph` (`compile`, `setSource`, `ids`, `series`, `columnOf`), `run(graph, { plan, select, onError })` → `RunResult`, `UnitError`                                                                                                                                                                                                                                     | `packages/process/src/plan/graph.ts`, `run.ts`       |
-| Plan — request/response | `RunRequest` (`PlanRequest` \| `SlotRequest`), `RunOptions`, `RunResult`, `Select` (`{ on, output?, name? }` — points at a node; what comes back is what that node produces), `ErrorPolicy`, `Fact` (carries `op`), `OutputInfo`, `Skipped`, `NodeTiming` (`slot`, `pulled`, `cached`, `ms`, `inputs`)                                                                                                           | `packages/process/src/plan/run.ts`                   |
-| Plan — host             | `createHost({ registry, units, sources })` → `Host` (`add`, `has`, `datasets`, `graphFor`, `run`, `runAsync`), `toWire`, `UnknownDatasetError`; local-string `Envelope` (`PlanEnvelope` \| `SlotEnvelope`), remote-capable `AsyncEnvelope` (`AsyncPlanEnvelope` \| `AsyncSlotEnvelope` \| `Envelope`), `DatasetInfo`, `WireResult`                                                                               | `packages/process/src/plan/host.ts`                  |
-| Plan — slots            | `expandSlots(slots, columns)` → `Map<slot, Spec>` (expands to the nested form, so ids match by construction; `slot#Output` picks one output), `SlotError`; types `SlotDef` (`{ op, params, in }`), `Slots`                                                                                                                                                                                                       | `packages/process/src/plan/slots.ts`                 |
-| Plan — builder          | `plan(from)` → low-level `PlanBuilder`; `process(registry, from)` → typed fluent `ProcessBuilder` (`column`, op methods, `outputs`), `BuilderError`; types `NodeHandle`, `OutputHandle`, `FluentColumnRef`, `SingleColumnNode`, `MultiColumnNode`, `ColumnSelection`, `FactRef`, `BuiltRequest`                                                                                                                  | `packages/process/src/plan/builder.ts`, `fluent.ts`  |
-| Plan — async sources    | `defineSource({ name, load })`, `createSourceRegistry()` / `SourceRegistry`, `sourceId`, `UnknownSourceError`; types `SourceRef`, `SourceParams`, `LoadedSource` (value + revision), `SourceLoadContext`, `SourceDef`                                                                                                                                                                                            | `packages/process/src/plan/source.ts`                |
-| Plan — folds            | `STANDARD_FOLDS` and the four it holds — `last`, `extremes`, `percentileRank`, `shape` — pre-registered by `createRegistry()`; each a plain `FoldDef`, so a consumer can `define` over one                                                                                                                                                                                                                       | `packages/process/src/plan/folds.ts`                 |
-| Errors                  | `ProcessError` (base), `CycleError`, `UnconnectedInputError`, `MissingOutputError`, `UnsetSourceError`                                                                                                                                                                                                                                                                                                           | `packages/process/src/errors.ts`                     |
-| Node type helpers       | `NodeSpec`, `NodeFactory`, `InletsFor`, `OutletsFor`, `OutletValue`, `SpecsForOutlets`, `DerivedOutput`                                                                                                                                                                                                                                                                                                          | `packages/process/src/node.ts`                       |
+| Group                   | Exports                                                                                                                                                                                                                                                                                                                                                                                                               | Source                                               |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| Worker pool (Node)      | `HostPool` (`start`, `run`, `close`, `size`, `inFlight`); types `HostPoolOptions`, `PoolSetup`, `PoolSetupConfig`; `toWire` / `fromWire`, types `WireResult`, `WireColumn` — subpath `@pond-ts/process/pool`                                                                                                                                                                                                          | `packages/process/src/pool/index.ts`                 |
+| Ports                   | `Inlet`, `Outlet` (typed fields on `node.in` / `node.out`; `get()`, `peek()`, `version`, `connect`, `disconnect`)                                                                                                                                                                                                                                                                                                     | `packages/process/src/port.ts`                       |
+| Nodes                   | `Node` (`in`, `out`, `dirty`, `error`, `invalidate()`), `defineNode` (reusable multi-output node type), `derive` (single-output, wired inline)                                                                                                                                                                                                                                                                        | `packages/process/src/node.ts`                       |
+| Port declaration        | `port<T>({ equals, defaultValue })`; types `PortSpec`, `PortSpecMap`, `PortValue`, `PortValues`                                                                                                                                                                                                                                                                                                                       | `packages/process/src/types.ts`                      |
+| Sources                 | `source<T>()` → `SourceNode` (`set()`), `fromLive(liveSource)` → `LiveSourceNode` (`dispose()`); `GraphSource` (bind contract — looser than core's `LiveSource`, accepts `LiveAggregation`), `SnapshotSource`, `NoInputs`                                                                                                                                                                                             | `packages/process/src/source.ts`                     |
+| Graph view              | `Graph` (`Graph.from(...roots)`, `nodes`, `order()`, `edges()`, `toJSON()`); types `GraphEdge`, `GraphJson`, `GraphNodeJson`, `GraphEdgeJson`                                                                                                                                                                                                                                                                         | `packages/process/src/graph.ts`                      |
+| Range output buffers    | `prepareRange(length, keep, prior)` → `RangeOutput` (`values`, `bits`, `set`, `clear`) carrying `[0, keep)` forward as blocks — values **and** validity; `sealRange(out, length)` → `Float64Column`; `validityByteCount`. Reached from an op as `ctx.out[n]`                                                                                                                                                          | `packages/process/src/column.ts`                     |
+| Ranged recompute        | `graph.setSourceFrom(series, changedFrom)` — declares which row first changed; `graph.recomputes` → `{ ranged, full }`. An op opts in with `OpDef.runRange(ctx)`, receiving `{ from, to, previous, previousView, out }` (type `RangeContext`) — write into `out` and return nothing for the block path alongside the usual context. Requires `lookback`. Falls back to a full `run` whenever anything is missing      | `packages/process/src/plan/graph.ts`                 |
+| Node budget             | `bind(series, { registry, budgetBytes })` — engine-wide cap on retained node values, LRU, enforced after each `run`; `graph.retainedBytes` / `graph.evictions` / `graph.enforceBudget()`. Unbounded when omitted. Skips a node whose consumer still holds its outlet                                                                                                                                                  | `packages/process/src/plan/graph.ts`                 |
+| Plan history            | `requiredHistory(registry, plan)` → `{ known, rows?, undeclared, byOp }` — the minimum safe tail in rows, folded from per-op `OpDef.lookback`. Sums along nesting, maxes across siblings. `known: false` names ops with no declared lookback rather than defaulting to zero (type `HistoryResult`)                                                                                                                    | `packages/process/src/plan/history.ts`               |
+| Column values           | `packColumn` (values → packed `Float64Column`, NaN = missing), `columnBytes` (retained size, for a byte budget), `appendColumn` (column → series; boxing-free when gapless), `columnBuffers` / `columnFromBuffers` (the buffer pair a column is, for an isolate boundary; type `ColumnBuffers`), `columnView` (zero-copy borrowed read view for in-process folds; type `ColumnView`)                                  | `packages/process/src/column.ts`                     |
+| Plan — registry         | `createRegistry({ folds })` / `Registry` (`define`, `get`, `foldFor`, `outputsOf`, `resolveParams` (`{ validate: false }` applies defaults and skips every check), `byFamily`, `describe`, `toJsonSchema`), param builders `int` / `num` / `choice` / `flag`, `UnknownOpError`, `ParamError`                                                                                                                          | `packages/process/src/plan/registry.ts`, `params.ts` |
+| Plan — identity         | `specId(registry, spec, { validate })` (content-addressed, param-order invariant, defaults materialized; `validate: false` is **total** — names a spec that would not compile in a separate `p1?:` namespace that cannot collide with a valid id; a valid spec's id is identical either way), `SpecIdOptions`, `refToId`, `explain`, `unitOf`, `columnsOf`, `dependsOn`, `outputKey`                                  | `packages/process/src/plan/identity.ts`              |
+| Plan — types            | `Spec`, `Plan`, `Input` (column name \| `Spec` \| `PickedOutput`), `SpecRef`, `Def` (`OpDef` \| `FoldDef`), `OpContext`, `OpResult`, `FoldContext`, `FactBody`, `isFold`, `ParamDef`, `Params`, `Units`, `InputDef`, `OutputDef`                                                                                                                                                                                      | `packages/process/src/plan/types.ts`                 |
+| Plan — bind / run       | `bind(series, { registry, units })` → `BoundGraph` (`compile`, `setSource`, `ids`, `series`, `columnOf`), `run(graph, { plan, select, onError })` → `RunResult`, `UnitError`, `UnknownColumnError` (a raw string input naming no column of the bound series, checked over the whole closure and re-checked on the warm path)                                                                                          | `packages/process/src/plan/graph.ts`, `run.ts`       |
+| Plan — request/response | `RunRequest` (`PlanRequest` \| `SlotRequest`), `RunOptions`, `RunResult`, `Select` (`{ on, output?, name? }` — points at a node; what comes back is what that node produces), `ErrorPolicy`, `Fact` (carries `op`), `OutputInfo`, `Skipped` (`spec`, `select`, `reason`, `code` — the failure's kind, matching the error class a throw would have carried), `NodeTiming` (`slot`, `pulled`, `cached`, `ms`, `inputs`) | `packages/process/src/plan/run.ts`                   |
+| Plan — host             | `createHost({ registry, units, sources })` → `Host` (`add`, `has`, `datasets`, `graphFor`, `run`, `runAsync`), `toWire`, `UnknownDatasetError`; local-string `Envelope` (`PlanEnvelope` \| `SlotEnvelope`), remote-capable `AsyncEnvelope` (`AsyncPlanEnvelope` \| `AsyncSlotEnvelope` \| `Envelope`), `DatasetInfo`, `WireResult`                                                                                    | `packages/process/src/plan/host.ts`                  |
+| Plan — slots            | `expandSlots(slots, columns)` → `Map<slot, Spec>` (expands to the nested form, so ids match by construction; `slot#Output` picks one output), `SlotError`; types `SlotDef` (`{ op, params, in }`), `Slots`                                                                                                                                                                                                            | `packages/process/src/plan/slots.ts`                 |
+| Plan — builder          | `plan(from)` → low-level `PlanBuilder`; `process(registry, from)` → typed fluent `ProcessBuilder` (`column`, op methods, `outputs`), `BuilderError`; types `NodeHandle`, `OutputHandle`, `FluentColumnRef`, `SingleColumnNode`, `MultiColumnNode`, `ColumnSelection`, `FactRef`, `BuiltRequest`                                                                                                                       | `packages/process/src/plan/builder.ts`, `fluent.ts`  |
+| Plan — async sources    | `defineSource({ name, load })`, `createSourceRegistry()` / `SourceRegistry`, `sourceId`, `UnknownSourceError`; types `SourceRef`, `SourceParams`, `LoadedSource` (value + revision), `SourceLoadContext`, `SourceDef`                                                                                                                                                                                                 | `packages/process/src/plan/source.ts`                |
+| Plan — folds            | `STANDARD_FOLDS` and the four it holds — `last`, `extremes`, `percentileRank`, `shape` — pre-registered by `createRegistry()`; each a plain `FoldDef`, so a consumer can `define` over one                                                                                                                                                                                                                            | `packages/process/src/plan/folds.ts`                 |
+| Errors                  | `ProcessError` (base; `code` — a stable per-class literal, minification-proof, also surfaced on `Skipped`), `CycleError`, `UnconnectedInputError`, `MissingOutputError`, `UnsetSourceError`                                                                                                                                                                                                                           | `packages/process/src/errors.ts`                     |
+| Node type helpers       | `NodeSpec`, `NodeFactory`, `InletsFor`, `OutletsFor`, `OutletValue`, `SpecsForOutlets`, `DerivedOutput`                                                                                                                                                                                                                                                                                                               | `packages/process/src/node.ts`                       |
 
 Note: this package's `npm test` includes a `test:dts` step that typechecks the
 **emitted** `dist/*.d.ts` from a consumer's perspective (`test-dts/`,

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.60.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.62.0...HEAD
+[0.62.0]: https://github.com/pond-ts/pond/compare/v0.61.0...v0.62.0
+[0.61.0]: https://github.com/pond-ts/pond/compare/v0.60.0...v0.61.0
 [0.60.0]: https://github.com/pond-ts/pond/compare/v0.59.0...v0.60.0
 [0.59.0]: https://github.com/pond-ts/pond/compare/v0.58.0...v0.59.0
 [0.58.0]: https://github.com/pond-ts/pond/compare/v0.57.0...v0.58.0
@@ -63,6 +65,110 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.62.0] — 2026-08-16
+
+### Added
+
+- `@pond-ts/process`: **`specId` is total under `{ validate: false }`** — a
+  third options argument that names a spec which would not compile
+  (`specId(registry, spec, { validate: false })`). Identity used to be coupled
+  to validity, so the moments a consumer most needs an id — labelling the chip
+  it is skipping, keying "this persisted entry is broken", logging what was
+  rejected — were exactly the moments it threw, leaving the consumer to
+  re-implement canonicalization or carry a second key. Lenient mode still
+  applies defaults and sorts keys, carries an undeclared param through rather
+  than dropping it, and recurses into nested inputs; **a valid spec has the
+  same id under either mode**, so nothing needs a second cache line. Validity
+  stays `compile`'s job. `Registry.resolveParams` takes the same
+  `{ validate: false }`.
+
+  An id that did **not** validate is minted in a separate namespace — marked
+  `p1?:` instead of `p1:`, with type-preserving param encoding — so it can
+  never collide with a legal id. Both measures are confined to that branch:
+  a valid id is byte-identical to what shipped in 0.61.0. The mark rides up a
+  chain, so a spec over an unvalidated input is unvalidated too.
+
+- `@pond-ts/process`: **`Skipped.code`** — every entry in `RunResult.skipped`
+  now carries the failure's kind (`'UnknownColumnError'`, `'ParamError'`,
+  `'UnitError'`, `'SlotError'`, …) beside its human `reason`. Under
+  `onError: 'skip' | 'collect'` nothing is thrown, so `instanceof` — the right
+  discriminator when a consumer catches — never reached a consumer reading
+  `skipped`, leaving it to match on prose whose wording is not a contract. The
+  value is `ProcessError.code`, a **literal declared per class** rather than
+  `constructor.name`, so a consumer's minifier cannot silently rename it. It is
+  absent when the throw did not come from this package, which is itself the
+  signal: op code failed, not the plan layer.
+
+### Fixed
+
+- `@pond-ts/process`: **`run` under `onError: 'throw'` — the default — now
+  raises the original error rather than a base `ProcessError` rebuilt from its
+  message.** A caught `UnknownColumnError`, `ParamError`, `UnitError` or
+  `SlotError` reached the caller as a bare `ProcessError`, so `instanceof`
+  could not discriminate on the throw path at all.
+
+- `@pond-ts/process`: **a raw string input naming a column the bound series
+  does not carry is now rejected**, at `compile`, with a new
+  `UnknownColumnError`. Nothing checked it at compile or at pull: the op ran
+  against an un-widened series, and one that doesn't defend its own inputs
+  appended a plausible-looking column of garbage under the spec's id — with
+  `skipped` empty and `onError` never engaged. A persisted plan citing a column
+  the feed has since dropped now skips (or throws) instead of returning a
+  value. The check is the one `expandSlots` already made against the same
+  column list, so the two request forms no longer disagree; it runs before the
+  unit check, whose "is 'unitless'" answer for an absent column named the wrong
+  problem. The key/time column is not a value column and is rejected too.
+
+  The check covers the **whole spec closure** (a missing column under a typed
+  parent otherwise surfaced as `UnitError`) and runs on the **warm** path as
+  well as the cold one — `setSource` replaces the data under compiled nodes by
+  design, so a memoized node could outlive the column it reads and go on
+  emitting the garbage column this fix exists to prevent. A node that fails the
+  re-check is dropped from the graph.
+  (Both items reported by Tidal —
+  `docs/notes/tidal-process-adoption-friction-2026-08.md`.)
+
+## [0.61.0] — 2026-08-16
+
+### Added
+
+- `@pond-ts/charts`: **`onMouseEvent` on `<XAxis>` and `<YAxis>`** — mouse
+  events on an axis strip, carrying the **axis value under the pointer** (the
+  part a consumer can't compute, since the scale lives inside the container).
+  One handler takes every mouse event on the strip (`click`, `dblclick`,
+  `contextmenu`, `mousedown`/`mouseup`, `mousemove`, `mouseenter`/`mouseleave`)
+  — switch on `event.type`. The payload (`AxisMouseEvent`, exported) carries
+  the raw React event, `axis: 'x' | 'y'`, the axis's `id` (a `<YAxis>` has one;
+  an `<XAxis>` does not), the inverted `value`, and the `label` that axis would
+  print there — the **category name** on a category axis, whose scale inverts
+  to the nearest band centre. Nothing is attached when the prop is omitted, so
+  an axis that doesn't opt in pays nothing for the move events. Axis strips now
+  also carry `data-axis="x"` / `data-axis="y"` + `data-axis-id` hooks, so a
+  consumer can style one (`[data-axis='x'] { cursor: pointer }`) despite the
+  axes taking no `className`.
+
+### Fixed
+
+- `@pond-ts/charts`: the category x-axis label fit now **measures** rendered
+  label widths (offscreen-canvas `measureText` in the axis font, with a
+  per-glyph estimate fallback for SSR/test DOMs) instead of estimating by
+  character count — labels wider than their band (e.g. `SYMBOL-VENUE-TYPE`
+  keys) no longer overprint into a smear. The fit measures against the scale's
+  real band pitch (so a `maxBandWidth`-packed axis thins correctly), keeps a
+  minimum clear gap between drawn labels, truncates from the **middle**
+  (`EDGE01…EQT`) so a shared prefix or a shared tail stays distinguishable,
+  and draws **no** labels at a degenerate (collapsed / pre-layout) width
+  rather than overprinting every label at x ≈ 0. Filed from the SPARC
+  migration ([PND-CATFIT]).
+
+  **Heads-up on a deliberate visual change:** an axis whose labels previously
+  packed edge-to-edge at a borderline pitch (label within a couple of px of
+  its band) now **thins to every 2nd label** instead — clear separation
+  outranks per-band labelling at the margin. On a dense dashboard axis this
+  can read as "half the labels disappeared"; it is the fit working as
+  intended, not data loss — every band still draws its mark, and the cursor
+  readout still names every category.
+
 ## [0.60.0] — 2026-08-13
 
 ### Added

package/dist/CategoryAxis.d.ts

@@ -7,10 +7,14 @@ import { type XAxisProps } from './XAxis.js';
  * formatter). Kept as the familiar name for categorical charts, mirroring
  * {@link TimeAxis}. Forwards every {@link XAxisProps} (`label`, `side`, …).
  *
- * A high-cardinality axis (many categories) thins + truncates its labels to stay
- * legible (categorical-axis RFC, Phase 1). The labels **come from the data** (the
- * `categories` list), so a d3 `format` prop does not apply here (it can't name a
- * category); customize a label by changing the `categories` datum's `label`.
+ * A crowded axis thins + truncates its labels to stay legible — triggered by
+ * **measured geometry** (rendered label width vs. band pitch), not category
+ * count, so few-but-wide labels fit as reliably as many short ones
+ * ([PND-CATFIT]; categorical-axis RFC, Phase 1). Truncation is from the
+ * middle (`EDGE01…EQT`), keeping both the prefix and the distinguishing tail.
+ * The labels **come from the data** (the `categories` list), so a d3 `format`
+ * prop does not apply here (it can't name a category); customize a label by
+ * changing the `categories` datum's `label`.
  */
 export declare function CategoryAxis(props?: XAxisProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=CategoryAxis.d.ts.map

package/dist/CategoryAxis.js

@@ -8,10 +8,14 @@ import { XAxis } from './XAxis.js';
  * formatter). Kept as the familiar name for categorical charts, mirroring
  * {@link TimeAxis}. Forwards every {@link XAxisProps} (`label`, `side`, …).
  *
- * A high-cardinality axis (many categories) thins + truncates its labels to stay
- * legible (categorical-axis RFC, Phase 1). The labels **come from the data** (the
- * `categories` list), so a d3 `format` prop does not apply here (it can't name a
- * category); customize a label by changing the `categories` datum's `label`.
+ * A crowded axis thins + truncates its labels to stay legible — triggered by
+ * **measured geometry** (rendered label width vs. band pitch), not category
+ * count, so few-but-wide labels fit as reliably as many short ones
+ * ([PND-CATFIT]; categorical-axis RFC, Phase 1). Truncation is from the
+ * middle (`EDGE01…EQT`), keeping both the prefix and the distinguishing tail.
+ * The labels **come from the data** (the `categories` list), so a d3 `format`
+ * prop does not apply here (it can't name a category); customize a label by
+ * changing the `categories` datum's `label`.
  */
 export function CategoryAxis(props = {}) {
     return _jsx(XAxis, { ...props });

package/dist/XAxis.d.ts

@@ -1,5 +1,30 @@
 import { type AxisTransform } from './derivedTicks.js';
 import { type AxisFormat } from './format.js';
+import { type AxisMouseHandler } from './axis-events.js';
+/** One placed tick — its plot-pixel x, the text to draw, and (stacked band
+ *  style) whether it sits on a band turn and renders emphasized. */
+interface PlacedTick {
+    readonly x: number;
+    readonly label: string;
+    /** This tick opens a coarser calendar period (a day/month/year turn), so it
+     *  renders emphasized (bold): a band turn in stacked, an inline promotion in
+     *  flat — the same boundaries in both styles. */
+    readonly bold?: boolean;
+}
+/**
+ * Thin + truncate a **category** axis's labels so a dense axis stays legible
+ * — triggered by **measured geometry**, not category count ([PND-CATFIT]):
+ * keep every `stride`-th label, and middle-ellipsize a kept one that still
+ * overruns its room. `stride` is the fewest slots the widest label needs once
+ * it may ellipsize to {@link TRUNC_KEEP} of itself, so short label sets keep
+ * every full label and long ones trade thinning against truncation instead of
+ * overprinting. `slot` is the **real band pitch** (`bandwidth()`), which a
+ * `maxBandWidth`-packed axis makes narrower than `plotWidth / n`. Rotation is
+ * a later option.
+ *
+ * Exported for tests only — not re-exported from the package index.
+ */
+export declare function thinCategoryLabels(ticks: readonly PlacedTick[], slot: number, plotWidth: number, fontSize: number, fontFamily: string): PlacedTick[];
 export interface XAxisProps {
     /**
      * Tick / cursor value formatting — a d3 format/time specifier string or a
@@ -59,8 +84,10 @@ export interface XAxisProps {
      * - `'auto'` — centred, but the first label left-anchors and the last
      *   right-anchors so the edge labels stay inside the plot (the old default).
      * - `'right'` — the label sits to the **right** of an extended tick that
-     *   drops from the axis line (label beside the tick, not under it) — useful
-     *   for dense or wide labels that would collide when centred.
+     *   drops from the axis line (label beside the tick, not under it) — a
+     *   *style* choice (the TradingView look). It re-anchors without measuring,
+     *   so it is **not** a remedy for colliding labels; on a category axis the
+     *   measured fit (thin + middle-ellipsize) is what prevents collisions.
      */
     align?: 'auto' | 'center' | 'right';
     /**
@@ -80,6 +107,22 @@ export interface XAxisProps {
      *   on each turn is emphasized and joins its divider as one boundary line.
      */
     dateStyle?: 'flat' | 'stacked';
+    /**
+     * Mouse events on the axis strip, with the **axis value under the pointer**
+     * ({@link AxisMouseHandler}, whose `AxisMouseEvent` payload carries it) — a click on a time axis reports the instant it
+     * landed on, a click on a category axis reports the category. The lever for
+     * axis-driven UI: pick a date by clicking its tick, open a menu on the strip
+     * (`event.type === 'contextmenu'`), drill into a category.
+     *
+     * **One handler takes every mouse event** — click, double-click, context
+     * menu, down/up, move, enter, leave — so switch on `event.type`. Nothing is
+     * attached when the prop is omitted, so the move events cost nothing unless
+     * you ask for them.
+     *
+     * The x strip has no `id` (only a `<YAxis>` does); to distinguish stacked
+     * axes, close over it: `onMouseEvent={(e) => onAxis('delta', e)}`.
+     */
+    onMouseEvent?: AxisMouseHandler;
 }
 /**
  * The shared **x axis**, a sibling of {@link YAxis} for the horizontal axis. A
@@ -91,5 +134,6 @@ export interface XAxisProps {
  *
  * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
  */
-export declare function XAxis({ format, label, side, height, ticks: customTicks, transform, color, align, dateStyle, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function XAxis({ format, label, side, height, ticks: customTicks, transform, color, align, dateStyle, onMouseEvent, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
+export {};
 //# sourceMappingURL=XAxis.d.ts.map

package/dist/XAxis.js

@@ -7,6 +7,7 @@ import { tickValues } from './yticks.js';
 import { xAxisCursorEntries } from './cursors.js';
 import { axisPillStyle } from './chip.js';
 import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
+import { axisMouseProps, axisPointerPx, } from './axis-events.js';
 /** Tick strip height (mark + value label) in CSS px. */
 const TICK_STRIP = 22;
 /** Extra height reserved for an axis `label` line. */
@@ -18,32 +19,132 @@ const BAND_STRIP = 20;
  *  ladder's per-tick budget (a hair tighter: derived labels are short). */
 const TRANSFORM_TICK_PX = 48;
 /**
- * Thin + truncate a **category** axis's labels so a dense axis stays legible: keep
- * every `stride`-th label (so a kept label has room), and ellipsize one that still
- * overruns its space. `stride` grows with the longest label vs the per-category
- * slot width, so a few short categories keep every full label and many long ones
- * decimate. A rough `fontSize`-based width estimate (no DOM measure) — good enough
- * for placement; the exact metric is the browser's. Rotation is a later option.
+ * Measure a category label's rendered width in the axis font. A shared
+ * offscreen canvas gives the browser's own metric — the thing the old
+ * per-character estimate could only approximate, and approximated low on
+ * exactly the labels category axes carry (all-caps keys with digits and
+ * hyphens), which let "fits by the estimate" labels overprint on screen
+ * ([PND-CATFIT]). Falls back to the estimate where no canvas backend exists
+ * (SSR, test DOMs). Results are cached per font+text; a webfont that loads
+ * after first measure keeps its fallback-font metric until the cache turns
+ * over, which the fit's inter-label gap absorbs.
  */
-function thinCategoryLabels(ticks, plotWidth, fontSize) {
+const measureCache = new Map();
+// Module state: the first render's canvas context is kept for the process
+// lifetime. In tests this captures whatever canvas stub is installed at first
+// measure — harmless while stubs measure 0 (the estimate fallback takes over
+// per call), but a future *nonzero* canvas mock would need a reset hook here.
+let measureCtx;
+function labelWidth(text, font, fontSize) {
+    const key = `${font}|${text}`;
+    const hit = measureCache.get(key);
+    if (hit !== undefined)
+        return hit;
+    if (measureCtx === undefined) {
+        try {
+            measureCtx =
+                typeof document === 'undefined'
+                    ? null
+                    : (document.createElement('canvas').getContext('2d') ?? null);
+        }
+        catch {
+            measureCtx = null; // a DOM shim whose getContext throws → estimate path
+        }
+    }
+    let w = 0;
+    if (measureCtx !== null) {
+        measureCtx.font = font;
+        w = measureCtx.measureText(text).width;
+    }
+    // No backend, or a mock that measures everything at 0 → per-glyph estimate.
+    if (!(w > 0))
+        w = text.length * fontSize * 0.62;
+    if (measureCache.size > 4096)
+        measureCache.clear();
+    measureCache.set(key, w);
+    return w;
+}
+/** Minimum clear space between two neighbouring drawn labels, px. */
+const LABEL_GAP = 4;
+/**
+ * A kept label may ellipsize down to this fraction of its full width before
+ * the fit prefers dropping labels (growing `stride`) instead — below it, the
+ * text no longer identifies its category.
+ */
+const TRUNC_KEEP = 0.6;
+/**
+ * Ellipsize `text` from the **middle** to fit `room` px: category keys often
+ * share a prefix and differ in the tail (or the reverse), so keeping both ends
+ * preserves whichever part distinguishes — end-truncation makes shared-prefix
+ * keys visually identical. Head-heavy split (60/40). Binary search on the kept
+ * **code-point** count (a UTF-16 `slice` could split a surrogate pair and
+ * emit mojibake); the result is only accepted when it *measures* within
+ * `room`, so the returned label can never overrun its space.
+ */
+function ellipsizeMiddle(text, room, font, fontSize) {
+    const cp = Array.from(text); // code points, not UTF-16 units
+    let lo = 1;
+    let hi = cp.length - 1;
+    let best = '…';
+    while (lo <= hi) {
+        const k = (lo + hi) >> 1;
+        const head = Math.ceil(k * 0.6);
+        const tail = k - head;
+        const s = cp.slice(0, head).join('') +
+            '…' +
+            (tail > 0 ? cp.slice(cp.length - tail).join('') : '');
+        if (labelWidth(s, font, fontSize) <= room) {
+            best = s;
+            lo = k + 1;
+        }
+        else {
+            hi = k - 1;
+        }
+    }
+    return best;
+}
+/**
+ * Thin + truncate a **category** axis's labels so a dense axis stays legible
+ * — triggered by **measured geometry**, not category count ([PND-CATFIT]):
+ * keep every `stride`-th label, and middle-ellipsize a kept one that still
+ * overruns its room. `stride` is the fewest slots the widest label needs once
+ * it may ellipsize to {@link TRUNC_KEEP} of itself, so short label sets keep
+ * every full label and long ones trade thinning against truncation instead of
+ * overprinting. `slot` is the **real band pitch** (`bandwidth()`), which a
+ * `maxBandWidth`-packed axis makes narrower than `plotWidth / n`. Rotation is
+ * a later option.
+ *
+ * Exported for tests only — not re-exported from the package index.
+ */
+export function thinCategoryLabels(ticks, slot, plotWidth, fontSize, fontFamily) {
     const n = ticks.length;
-    const slot = plotWidth / n; // per-category width in px
-    // Before first layout `plotWidth` is 0 → `slot` is 0 and the stride/room math
-    // below goes to Infinity/NaN. Nothing is visible at zero width anyway, so pass
-    // the ticks through untouched until a real width arrives.
-    if (!(slot > 0))
-        return [...ticks];
-    const charW = fontSize * 0.62; // ~average glyph advance
-    const longest = Math.min(12, ticks.reduce((m, t) => Math.max(m, t.label.length), 1));
-    const stride = Math.max(1, Math.ceil((longest * charW) / slot));
-    const room = Math.max(1, Math.floor((slot * stride) / charW));
+    // Degenerate / pre-layout width: nothing can be legible, so draw NO labels.
+    // The old passthrough here was the collapsed-panel smear: these are
+    // absolutely-positioned `nowrap` divs, so at width ≈ 0 every label rendered
+    // full-length at x ≈ 0, overflowing the strip and overprinting.
+    if (!(slot > 0) || !(plotWidth > 0))
+        return [];
+    const font = `${fontSize}px ${fontFamily}`;
+    const widths = ticks.map((t) => labelWidth(t.label, font, fontSize));
+    const maxW = widths.reduce((m, w) => Math.max(m, w), 0);
+    // The width a kept label must be allowed: its full measure when that's
+    // modest, else the legibility floor — TRUNC_KEEP of it, but never less than
+    // ~two glyphs of text.
+    const required = Math.min(maxW, Math.max(maxW * TRUNC_KEEP, fontSize * 2));
+    const stride = Math.max(1, Math.ceil((required + LABEL_GAP) / slot));
+    const room = Math.min(slot * stride - LABEL_GAP, plotWidth - LABEL_GAP);
+    // Not even ~two glyphs fit (a collapsed strip) — an empty axis over a smear.
+    if (!(room >= fontSize * 2))
+        return [];
     const out = [];
     for (let i = 0; i < n; i += stride) {
-        const s = ticks[i].label;
-        out.push({
-            x: ticks[i].x,
-            label: s.length <= room ? s : `${s.slice(0, Math.max(1, room - 1))}…`,
-        });
+        const t = ticks[i];
+        const label = widths[i] <= room
+            ? t.label
+            : ellipsizeMiddle(t.label, room, font, fontSize);
+        // A bare ellipsis identifies nothing — leave that tick unlabeled.
+        if (label !== '…')
+            out.push({ x: t.x, label });
     }
     return out;
 }
@@ -57,7 +158,7 @@ function thinCategoryLabels(ticks, plotWidth, fontSize) {
  *
  * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
  */
-export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, transform, color, align = 'center', dateStyle = 'flat', } = {}) {
+export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, transform, color, align = 'center', dateStyle = 'flat', onMouseEvent, } = {}) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<XAxis> must be rendered inside a <ChartContainer>');
@@ -281,9 +382,14 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                             flatFmt(+d) !== baseFmt(+d),
                 }));
     // A category axis ticks once per category; thin + truncate its labels when they
-    // crowd (an explicit `customTicks` axis keeps its labels verbatim).
-    const placed = xKind === 'category' && customTicks === undefined && rawTicks.length > 1
-        ? thinCategoryLabels(rawTicks, plotWidth, theme.font.size)
+    // crowd (an explicit `customTicks` axis keeps its labels verbatim). The slot is
+    // the scale's own band pitch — under `maxBandWidth` packing it is narrower than
+    // `plotWidth / n`, and the fit must measure against the pitch labels actually
+    // sit on.
+    const placed = xKind === 'category' && customTicks === undefined && rawTicks.length > 0
+        ? thinCategoryLabels(rawTicks, 'bandwidth' in xScale
+            ? xScale.bandwidth()
+            : plotWidth / rawTicks.length, plotWidth, theme.font.size, theme.font.family)
         : rawTicks;
     const onTop = side === 'top';
     // Axis pills (marker / crosshair) sit at the same offset as the tick labels so
@@ -305,7 +411,20 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     const stripHeight = (height ?? TICK_STRIP + (label ? LABEL_STRIP : 0)) +
         (hasBands ? BAND_STRIP : 0) +
         maxPillLane * PILL_LANE_H;
-    return (_jsxs("div", { style: {
+    // The axis coordinate under the pointer, for `onMouseEvent`. The strip is
+    // laid out flush with the plot (the left gutter is its margin, its width is
+    // `plotWidth`), so a strip-local pixel inverts straight through the shared x
+    // scale — no gutter arithmetic. The label reads the same channel a cursor
+    // pill does: the band scale's category name on a category axis (a d3 number
+    // format can't name one), this axis's readout format everywhere else.
+    const mouse = axisMouseProps(onMouseEvent, 'x', undefined, (event) => {
+        const value = +xScale.invert(axisPointerPx(event, 'x', [0, plotWidth]));
+        return {
+            value,
+            label: xKind === 'category' ? fmt(value) : readoutFmt(value),
+        };
+    });
+    return (_jsxs("div", { "data-axis": "x", ...mouse, style: {
             position: 'relative',
             marginLeft: `${leftGutter}px`,
             width: `${plotWidth}px`,

package/dist/YAxis.d.ts

@@ -1,4 +1,5 @@
 import { type AxisFormat } from './format.js';
+import { type AxisMouseHandler } from './axis-events.js';
 export interface YAxisProps {
     /** Identifier a chart links to via its `axis` prop (and the first declared is
      *  the row's default). */
@@ -197,6 +198,19 @@ export interface YAxisProps {
      * colours. Presentation-only: it never re-registers the axis.
      */
     color?: string;
+    /**
+     * Mouse events on this axis's gutter, with the **axis value under the
+     * pointer** ({@link AxisMouseHandler}, whose `AxisMouseEvent` payload carries it) — a click reports the value it landed
+     * on, and this axis's `id`, so one handler can serve several axes. The lever
+     * for axis-driven UI: set a threshold by clicking the gutter, open a scale
+     * menu (`event.type === 'contextmenu'`), drill into a categorical row.
+     *
+     * **One handler takes every mouse event** — click, double-click, context
+     * menu, down/up, move, enter, leave — so switch on `event.type`. Nothing is
+     * attached when the prop is omitted, so the move events cost nothing unless
+     * you ask for them. A `hide`den axis draws no gutter and so fires nothing.
+     */
+    onMouseEvent?: AxisMouseHandler;
     /**
      * @internal Declaration position among the row's children, injected by
      * `ChartRow` so the first-declared axis stays the default. Do not set.
@@ -211,5 +225,5 @@ export interface YAxisProps {
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export declare function YAxis({ id, side, label, scale, linearWindow, min, max, format, ticks, tickCount, pad, boundaryLabels, width, hide, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function YAxis({ id, side, label, scale, linearWindow, min, max, format, ticks, tickCount, pad, boundaryLabels, width, hide, labelPlacement, color, onMouseEvent, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element | null;
 //# sourceMappingURL=YAxis.d.ts.map

package/dist/YAxis.js

@@ -4,6 +4,7 @@ import { ContainerContext, RowContext } from './context.js';
 import { resolveAxisFormat } from './format.js';
 import { useSlotKey } from './use-slot-key.js';
 import { tickValues } from './yticks.js';
+import { axisMouseProps, axisPointerPx, } from './axis-events.js';
 const DEFAULT_WIDTH = 50;
 /** Fallback tick count before the row has published its resolved count (the
  *  first render, pre-registration). The row's height-derived value takes over
@@ -17,7 +18,7 @@ const DEFAULT_TICK_COUNT = 5;
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow, min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, hide = false, labelPlacement = 'rotated', color, index = 0, }) {
+export function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow, min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, hide = false, labelPlacement = 'rotated', color, onMouseEvent, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
@@ -124,7 +125,33 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow
     // axes line up column-by-column. Keyed by this instance's slot key (not `id`,
     // which may repeat across a mirror). Falls back to own width until reserved.
     const slotWidth = row.axisSlots.get(slot) ?? width;
-    return (_jsx("div", { style: {
+    // The axis value under the pointer, for `onMouseEvent` — read on the **slot**
+    // box (below), so the whole reserved gutter answers, not just this axis's own
+    // narrower content. The box is exactly the row's height and shares its top
+    // edge with the plot, so a box-local pixel inverts straight through this
+    // axis's scale. Before the row has published one there is no value to report
+    // and the event is dropped. A categorical row labels by slot, matching its
+    // ticks; every other row reads this axis's own tick format.
+    const mouse = axisMouseProps(onMouseEvent, 'y', id, (event) => {
+        if (!yScale)
+            return null;
+        // Clamp on the **scale's** range, not the box: a row with a
+        // `labelPlacement="top"` axis reserves a header, so the range is
+        // `[height, topHeader]` while the box still starts at 0 (`ChartRow`).
+        const [r0, r1] = yScale.range();
+        const value = yScale.invert(axisPointerPx(event, 'y', [r0, r1]));
+        return {
+            value,
+            label: layerCategories !== null
+                ? // A slot index, clamped to a real category: the domain's top edge
+                    // inverts to exactly `n` (and rounding can nudge the bottom below
+                    // 0), which no category occupies — the nearest one is the honest
+                    // answer, matching the band scale's own `invert`.
+                    (layerCategories[Math.min(layerCategories.length - 1, Math.max(0, Math.floor(value)))] ?? '')
+                : fmt(value),
+        };
+    });
+    return (_jsx("div", { "data-axis": "y", "data-axis-id": id, ...mouse, style: {
             flex: `0 0 ${slotWidth}px`,
             display: 'flex',
             justifyContent: side === 'left' ? 'flex-end' : 'flex-start',

package/dist/axis-events.d.ts

@@ -0,0 +1,106 @@
+import type { MouseEvent as ReactMouseEvent } from 'react';
+/**
+ * What an axis hands its {@link AxisMouseHandler} — the raw mouse event, plus
+ * the **axis coordinate under the pointer**, which is the part a consumer
+ * cannot compute for itself (the scale lives inside the container).
+ */
+export interface AxisMouseEvent {
+    /**
+     * The React mouse event, verbatim — `type` says which one fired
+     * (`'click'`, `'mousemove'`, `'contextmenu'`, …), and the modifier keys,
+     * `button`, `preventDefault()` and `stopPropagation()` are all the ordinary
+     * ones. **A single handler receives every mouse event on the strip**, so
+     * switch on `event.type` (or ignore the ones you don't want).
+     */
+    event: ReactMouseEvent<HTMLDivElement>;
+    /** Which axis fired — so one handler can serve both. */
+    axis: 'x' | 'y';
+    /**
+     * The axis's `id`, when it has one. A `<YAxis>` always does (it's required —
+     * charts link to it); an `<XAxis>` has none, so this is `undefined` there.
+     * To tell two stacked x-axes apart, close over the distinction at the call
+     * site (`onMouseEvent={(e) => onAxis('delta', e)}`).
+     */
+    id?: string | undefined;
+    /**
+     * The axis value under the pointer, **in the axis's own data units** — epoch
+     * ms on a time axis, the number on a value axis, the slot value on a
+     * categorical one. Read {@link label} for what the axis would *print* there.
+     *
+     * Not clamped to a tick — it is the continuous inverse of the pixel, so it
+     * lands between ticks. The one exception is a **categorical x-axis**, whose
+     * scale inverts to the nearest band **centre** (`i + 0.5`); a categorical
+     * *row* (horizontal bars on the y-axis) is a plain linear slot scale and does
+     * not snap, so `Math.floor(value)` is its slot index.
+     *
+     * On a `transform`ed x-axis this is the **underlying** value, not the derived
+     * unit — apply the same `transform.to` you passed the axis to get the unit
+     * its ticks read in.
+     */
+    value: number;
+    /**
+     * {@link value} formatted the way this axis reads it — the category name on a
+     * categorical axis, the axis's `format` (or the container's shared formatter)
+     * elsewhere.
+     *
+     * Precisely: it is the axis's **readout** channel, the one the cursor pill
+     * uses — so it always agrees with the pill at that pixel, and a container
+     * `cursorFormat` shapes it exactly as it shapes the pill. That is the
+     * documented precedence (`cursorFormat` → axis `format` → container), and it
+     * is the one case where `label` can read differently from the tick text: a
+     * chart with a precise `cursorFormat` over terse ticks gets the precise form
+     * here, which is the readout it asked for.
+     */
+    label: string;
+}
+/**
+ * A single handler for every mouse event on an axis strip — see
+ * {@link AxisMouseEvent}. Passed as `onMouseEvent` to `<XAxis>` / `<YAxis>`.
+ */
+export type AxisMouseHandler = (info: AxisMouseEvent) => void;
+/** The mouse props an axis strip spreads onto its root element. */
+type AxisMouseProps = {
+    onClick?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+    onDoubleClick?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+    onContextMenu?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+    onMouseDown?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+    onMouseUp?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+    onMouseMove?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+    onMouseEnter?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+    onMouseLeave?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+};
+/**
+ * Build the mouse props for an axis strip: every mouse event routed to the one
+ * `onMouseEvent` handler, each carrying the axis coordinate `at` resolves from
+ * the pointer.
+ *
+ * With no handler this returns `{}` — **nothing is attached**, so an axis that
+ * doesn't opt in keeps costing nothing (no per-move callback, no listeners).
+ *
+ * `at` returns `null` when the pointer maps to no value — the transient render
+ * before a `<YAxis>` has a resolved scale — and the event is then dropped
+ * rather than reported at a made-up coordinate.
+ */
+export declare function axisMouseProps(onMouseEvent: AxisMouseHandler | undefined, axis: 'x' | 'y', id: string | undefined, at: (event: ReactMouseEvent<HTMLDivElement>) => {
+    value: number;
+    label: string;
+} | null): AxisMouseProps;
+/**
+ * The pointer's position along an axis strip, in **strip-local pixels** — the
+ * coordinate the scale inverts. Read from the strip's own client rect
+ * (`currentTarget`, so it is the strip whichever tick label was hit), which is
+ * laid out flush with the plot on that dimension: the x strip carries the left
+ * gutter as a margin and is exactly `plotWidth` wide, and the y gutter is
+ * exactly the row's height.
+ *
+ * Clamped to **the scale's range, not the strip's box** — the two are not
+ * always the same. A row carrying a `labelPlacement="top"` axis reserves a
+ * header, so its y scales run `[height, topHeader]` while the gutter box still
+ * starts at 0; clamping to the box would invert the header band to values
+ * *above* the domain and report a coordinate the axis never draws. Passing the
+ * range means a `mouseleave` off the edge — or a press in that header — still
+ * reports a value the scale actually holds.
+ */
+export declare function axisPointerPx(event: ReactMouseEvent<HTMLDivElement>, axis: 'x' | 'y', range: readonly [number, number]): number;
+export {};
+//# sourceMappingURL=axis-events.d.ts.map

package/dist/axis-events.js

@@ -0,0 +1,56 @@
+/**
+ * Build the mouse props for an axis strip: every mouse event routed to the one
+ * `onMouseEvent` handler, each carrying the axis coordinate `at` resolves from
+ * the pointer.
+ *
+ * With no handler this returns `{}` — **nothing is attached**, so an axis that
+ * doesn't opt in keeps costing nothing (no per-move callback, no listeners).
+ *
+ * `at` returns `null` when the pointer maps to no value — the transient render
+ * before a `<YAxis>` has a resolved scale — and the event is then dropped
+ * rather than reported at a made-up coordinate.
+ */
+export function axisMouseProps(onMouseEvent, axis, id, at) {
+    if (onMouseEvent === undefined)
+        return {};
+    const fire = (event) => {
+        const hit = at(event);
+        if (hit === null)
+            return;
+        onMouseEvent({ event, axis, id, value: hit.value, label: hit.label });
+    };
+    return {
+        onClick: fire,
+        onDoubleClick: fire,
+        onContextMenu: fire,
+        onMouseDown: fire,
+        onMouseUp: fire,
+        onMouseMove: fire,
+        onMouseEnter: fire,
+        onMouseLeave: fire,
+    };
+}
+/**
+ * The pointer's position along an axis strip, in **strip-local pixels** — the
+ * coordinate the scale inverts. Read from the strip's own client rect
+ * (`currentTarget`, so it is the strip whichever tick label was hit), which is
+ * laid out flush with the plot on that dimension: the x strip carries the left
+ * gutter as a margin and is exactly `plotWidth` wide, and the y gutter is
+ * exactly the row's height.
+ *
+ * Clamped to **the scale's range, not the strip's box** — the two are not
+ * always the same. A row carrying a `labelPlacement="top"` axis reserves a
+ * header, so its y scales run `[height, topHeader]` while the gutter box still
+ * starts at 0; clamping to the box would invert the header band to values
+ * *above* the domain and report a coordinate the axis never draws. Passing the
+ * range means a `mouseleave` off the edge — or a press in that header — still
+ * reports a value the scale actually holds.
+ */
+export function axisPointerPx(event, axis, range) {
+    const rect = event.currentTarget.getBoundingClientRect();
+    const px = axis === 'x' ? event.clientX - rect.left : event.clientY - rect.top;
+    const lo = Math.min(range[0], range[1]);
+    const hi = Math.max(range[0], range[1]);
+    return Math.max(lo, Math.min(hi, px));
+}
+//# sourceMappingURL=axis-events.js.map

package/dist/index.d.ts

@@ -31,6 +31,7 @@ export type { YAxisProps } from './YAxis.js';
 export { XAxis } from './XAxis.js';
 export type { XAxisProps } from './XAxis.js';
 export type { AxisTransform } from './derivedTicks.js';
+export type { AxisMouseEvent, AxisMouseHandler } from './axis-events.js';
 export { TimeAxis } from './TimeAxis.js';
 export { CategoryAxis } from './CategoryAxis.js';
 export { HeatMap } from './HeatMap.js';

package/package.json

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