pond-ts 0.48.1 → 0.49.0

package/CHANGELOG.md

@@ -8,7 +8,8 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 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.48.1...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.49.0...HEAD
+[0.49.0]: https://github.com/pond-ts/pond/compare/v0.48.1...v0.49.0
 [0.48.1]: https://github.com/pond-ts/pond/compare/v0.48.0...v0.48.1
 [0.48.0]: https://github.com/pond-ts/pond/compare/v0.47.0...v0.48.0
 [0.47.0]: https://github.com/pond-ts/pond/compare/v0.46.0...v0.47.0
@@ -48,6 +49,204 @@ and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.49.0] — 2026-07-21
+
+### Added
+
+- **charts:** **Annotation theme roles** (#508 item 3, Tidal vol-surface
+  friction). `theme.annotation` gains an optional **`roles`** map (role name →
+  `{ color, fillOpacity? }`), and `<Baseline>` / `<Marker>` / `<Region>` gain a
+  **`role`** prop that recolours that mark from `roles[role]` while keeping the
+  shared depth ramp — so a smile can place a green ATM baseline, a distinct
+  reference marker, and an amber zone at once without the whole register
+  shifting together. Resolves `roles[role] ?? annotation` (an unknown/unset
+  role is the base register). **Colour stays a theme concern** — there is no
+  per-mark colour prop (the one-styling-channel discipline; consistent with the
+  per-box red/green reject). `cssVarTheme` carries the `roles` map through
+  unchanged (deep-merged). `theme.annotation.roles` is optional, so existing
+  themes are unaffected.
+- **charts:** **`<BoxPlot id>` — box selection** (#508 item 5, Tidal
+  vol-surface friction). A `BoxPlot` with an `id` is now clickable on the same
+  id-gated contract `<BarChart>` / `<ScatterChart>` carry
+  (`selected`/`onSelect`, `hovered`/`onHover`): a click anywhere on a box —
+  body or whisker, a range-only bid→ask segment included — selects it via
+  rect-containment (`boxAt`, the interval-mark analog of `barAt`, **not** the
+  continuous nearest-point threshold), and the selected box outlines (hovered
+  fainter, reusing `theme.box.stroke`, no new token). `key` is the box's `x`
+  (its span begin). Without an `id` the box stays display-only. Independent of
+  the box's `cursorFlag` cursor opt-out — selection rides the separate
+  `hitTest` path.
+- **charts:** **`<YAxis tickCount>` + height-derived tick density** (#508
+  item 4, Tidal vol-surface friction). The y axis's auto-tick count now
+  follows the **row height** by default — a short strip (e.g. a 72px
+  histogram lane) gets fewer ticks than a tall row instead of crushing the
+  same ~5 labels into the space (mirrors the width-derived trading-time x
+  axis). A new **`tickCount`** prop pins an explicit target; explicit
+  `ticks` still overrides both. The count is resolved once per axis on the
+  row (`resolveYTickCount`) and shared by the axis labels, the cursor-readout
+  formatter, and the row gridlines, so a label / its gridline / its readout
+  stay on the same `ticks(count)` (replaces three hardcoded `5`s that agreed
+  by convention).
+
+- **charts:** **`<Legend>` — the series key** (#508 item 2, Tidal vol-surface
+  friction; design per the sender's sketch on the issue). Every draw layer now
+  registers its readout identity (`as ?? column`) plus its **resolved** style
+  as a `SwatchSpec` (line stroke+dash, area fill+line, band envelope, scatter
+  dot, box whisker, bar fill, candle up/down pair), and `<Legend />` renders
+  the registry as a small card anchored to a corner of the rows block
+  (`placement`, default `top-right`) — so the key can never drift from the
+  plot. Rows follow chart-row → declaration order; identities collapse
+  (`id ?? label`, as the tracker readout merges keys); a **stacked bar
+  registers one row per group** with its resolved fill. Per-layer control via
+  a new `legend` prop on all seven marks: `false` opts out, a string renames.
+  Interactions are **id-gated** (the shipped selection contract): rows whose
+  layer has an `id` echo hover into the container and toggle selection on
+  click; `onRowHover` / `onRowClick` take over when provided; series
+  show/hide deliberately stays consumer-side. **Scope follows placement:** at
+  the container level the card lists every row; placed inside a `<Layers>` it
+  scopes to that `<ChartRow>` and anchors to that row's plot (a per-row legend
+  needs no prop). `<Legend items={…}>` renders explicit rows — inside a
+  container or standalone (a dashboard-side key).
+  New optional `theme.legend` slot (background/border/text; derives from
+  `chip`/`axis` tokens when absent, so hand-built themes keep compiling).
+  **Headless variant:** `useChartLegend()` serves the entries as data —
+  `rows` (**items grouped by chart row**; each item is
+  `label` + resolved swatch + `id` + live `selected`/`hovered`; a flat list
+  is `rows.flatMap((r) => r.items)`) plus chart-synced `hover`/`select`
+  verbs, the container's axis `gutters` (for aligning a custom layout to the
+  plot), and **`cursorTime`** (the cursor's axis instant, `null` when idle) —
+  the seams for a legend that is a design of its own: horizontal chip rows,
+  ticker-compare with the secondary dimmed, and **current-or-cursor values**
+  per item (`series.nearest(cursorTime)`, else the latest sample; item
+  labels also match the tracker's sample labels, so an `onTrackerChanged`
+  merge is a label-keyed join); `<Legend>` itself renders through the same
+  core, so the two can't disagree. **Scope follows placement** for both the
+  card and the hook: inside a `<Layers>` they scope to that `<ChartRow>` and
+  the card anchors to that row's plot; container-level stays all-rows. Card
+  polish per the first design pass: plot-area-inset placement, selection
+  reads by contrast (the selected item bold, others dulled — the
+  ticker-compare treatment), a dashed line's swatch hand-renders as a
+  canonical three-dash glyph, and a bar's swatch is a centred rounded square.
+  New exports: `Legend`, `LegendProps`, `LegendPlacement`, `SwatchSpec`,
+  `LegendItemInput`, `useChartLegend`, `ChartLegend`, `LegendRow`,
+  `LegendItem`.
+- **charts:** **`cursorFormat` reaches value axes** (#508 item 1, Tidal
+  vol-surface friction) — the container's readout channel now applies on a
+  value x axis exactly as on a time axis: a **string** is a d3 _number_
+  specifier there, a **function** receives
+  `(value, { grain: undefined, defaultText })` (no time grain to hand over;
+  `defaultText` is the axis-default text). The readout also gains its
+  documented precedence on the axis strip on **every** axis kind:
+  `cursorFormat → axis format → container`, so an explicit `<XAxis format>`
+  keeps ticks terse while `cursorFormat` makes the cursor pill / marker
+  indicators / annotation auto-labels precise (`+2.0σ` ticks, `+1.83σ` pill).
+  A `transform`ed axis is exempt (its pill speaks the derived unit); a
+  category axis reads names and ignores `cursorFormat`. Type change:
+  `CursorFormat`'s function form widens `ctx.grain` from `TimeGrain` to
+  `TimeGrain | undefined`; the frame gains an optional `formatReadout`
+  channel (see Fixed below for the `formatTime` clarification).
+- **charts:** **M4 line decimation** (charts decimator wave, Phase 3) — the
+  `<LineChart>` now draws from the per-device-pixel-column min/max/first/last
+  (pond's `binBy(…, 'minMaxFirstLast')`) once the visible data exceeds ~2 samples
+  per pixel, so a **fully-visible** dense series (which viewport culling can't
+  help) draws from O(plot width) points instead of every sample: a 1M-point line
+  drops from ~34 ms/frame to ~3.4 ms, under the 60 fps budget. It is **visually
+  lossless** (an e2e pixel-diff bounds the decimated-vs-full difference to a thin
+  sub-pixel AA seam) and **preserves single-sample anomalies** (the min/max
+  channel keeps the spike M4 is chosen over LTTB to keep). Bucket edges are the
+  scale's pixel range inverted back to key space, so each bucket is one pixel
+  column on **any** scale, including a non-affine `TradingTimeScale`. Auto-on with
+  an opt-out / tuning prop
+  `decimate={false | { threshold }}` (new `DecimateOption` export). **All gap
+  modes** decimate: a §2.2 **gap-edge union** folds each ≥1-pixel interior gap's
+  boundaries into the bucket edges, so the gap reduces to its own empty (`NaN`)
+  bucket with exact pre/post-gap values — `'empty'` breaks precisely, `'none'`
+  bridges, and the `dashed`/`step`/`fade` connectors still draw across the gap.
+  **`sessionBreaks` decimate too** — the same union folds each trading-axis
+  session-break instant into the bucket edges so no bucket merges two sessions'
+  extremes across the discontinuity, and `sessionRuns` then splits the decimated
+  series into clean per-session subpaths (a dense intraday line on a trading-time
+  axis decimates _and_ breaks at each session open). Still gated off only a
+  non-linear `curve` (documented backlog). Interaction reads the source series
+  (§2.3), so readouts/selection are unaffected.
+- **charts:** M4 decimation extended to **`<AreaChart>` and `<BandChart>`** (same
+  auto-on `decimate={false | { threshold }}` prop). An **area** reuses the line M4
+  on its outline (gap-edge union included) with the fill following under the
+  full-series gradient — so a dense filled area shrinks its fill + outline work to
+  O(plot width). A **band** decimates to the per-pixel-column **min(`lower`) /
+  max(`upper`)** — the widest envelope the samples span, so it can never invert
+  (§2.5) and covers the same pixels; the win is the canvas fill (≈W vertices vs
+  every sample). Both gated off a non-linear `curve`; interaction unaffected.
+- **charts:** **Viewport culling** (charts decimator wave, Phase 2). Line, area,
+  and band layers now clip to the **visible slice** of their key column — plus
+  one entry/exit point each side so the segment crossing each plot edge still
+  draws — before any path work, so a pan/zoom repaint costs O(visible) instead
+  of O(N). On a large series zoomed in, the per-frame `drawLine` path-generation
+  cost drops from ~29 ms at 1M points (over the 16.67 ms/60 fps budget — the
+  cause of the #256 pan-FPS collapse) to ~0.06 ms; a fully-visible series is
+  unchanged (culling no-ops, keeping that draw byte-identical — the baseline the
+  Phase 3 M4 decimator addresses). Interaction is unaffected: `sampleAt` /
+  `hitTest` read the full source series, so a hover readout or selection never
+  shifts when the window resizes (the decimator RFC §2.3 invariant). Culling is
+  automatic and internal — no API change.
+- **charts:** Viewport culling extended to the **per-mark** layers — scatter,
+  bars, candles, and boxes. These loop over independent marks with index-keyed
+  accessors (a scatter's `colorAt(i)`, a bar's `begin[i]` selection match), so
+  rather than a subarray view they cull by **restricting the draw loop to the
+  visible index range** (the original `i` is preserved, so every accessor and
+  selection/hover match stays correct). Point marks (scatter) use the same
+  entry/exit window as lines; interval marks (bars / candles / boxes) use a
+  span-overlap window that keeps a wide mark crossing a plot edge. Same
+  automatic, internal, interaction-safe behaviour — a 500k-bar chart zoomed in
+  drops from ~23 ms/frame to ~0.16 ms.
+- **charts:** Scatter culling is now **radius-aware**. The per-mark index margin
+  above measures neighbours in sample count, but a scatter mark's disc has a
+  pixel radius independent of sample spacing — so a dense scatter of fat marks
+  could drop an edge bubble whose _centre_ sits several samples off-screen while
+  its _disc_ still overlaps the plot edge (a subtle flicker under pan). The
+  scatter draw now widens the visible window by its max drawn radius (converted
+  px→data through the scale, plus any `offsetPx` nudge) before culling, so every
+  mark that can paint into the plot is kept. Small-radius scatters are unaffected
+  (they re-expand by a few pixels — usually the same window). Interval marks
+  (bars / candles / boxes) don't need this — their width _is_ their x-span.
+
+### Changed
+
+- **charts:** **Tracker labels key on `as` across the multi-value marks**
+  (F-charts-8 §3, the `<Legend>` label-source prerequisite). With a semantic
+  `as`, a `<BandChart>`'s edge samples now read `"<as> lower"` / `"<as>
+upper"` and a `<Candlestick showOHLC>`'s quote pills read `"<as> high"` /
+  `"<as> open"` / … — the series-name + role convention `<BoxPlot>` already
+  shipped (`iv upper`) — so readout/legend merge keys are the series
+  identity, not raw column names or bare role words. Without an `as`,
+  labels are unchanged (column names / role words). Consumers keying
+  `onTrackerChanged` readouts on the old labels while setting `as` should
+  key on the new `"<as> <role>"` form.
+
+### Fixed
+
+- **charts:** **`cursorFormat` no longer leaks into tick labels** — setting
+  `timeFormat` _and_ `cursorFormat` together on a time axis rendered the
+  **tick labels** with `cursorFormat` (the ladder was disqualified by
+  `timeFormat`, and the tick fallback read the merged readout formatter).
+  The frame now carries two channels: `formatTime` is the label channel
+  (`timeFormat`-shaped, never `cursorFormat` — restoring its documented
+  meaning), and the new optional `formatReadout` carries `cursorFormat` to
+  the readout consumers (crosshair pill + in-plot cursor time, marker
+  indicators, annotation auto-labels). Frame consumers that read
+  `ContainerFrame.formatTime` for a readout should use
+  `formatReadout ?? formatTime`.
+- **charts:** **Region drag-select no longer races the pointer stream**
+  (#508 item 7) — the drag anchor was container **state** read back through
+  the rendered frame at `pointerup`, so a batched/untrusted pointer stream
+  (automation, jsdom — plausibly a very fast flick under load) could deliver
+  `down→up` before the anchor committed: the select was **silently dropped**
+  and the late-committing anchor **leaked**, leaving the band stuck.
+  Human-paced trusted input hid this (React flushes trusted discrete events
+  synchronously). Gesture logic now reads a ref (the same ref+state
+  discipline the annotation-create drag already used); the state stays
+  paint-only. Deterministic regression tests cover both pacings.
+
 ## [0.48.1] — 2026-07-19
 
 ### Fixed

package/dist/batch/time-series.d.ts

@@ -53,6 +53,14 @@ type PrefixesForSeriesTuple<T extends SeriesTuple> = {
     [I in keyof T]: string;
 } extends infer Result ? Result extends readonly [string, ...string[]] ? Result : never : never;
 export declare function toKey(value: KeyLike): EventKey;
+/**
+ * An immutable, schema-typed, ordered collection of events — the batch
+ * layer's core primitive. A series is constructed whole from complete data
+ * and never mutated: every transform (`filter`, `align`, `rollup`, …)
+ * returns a new `TimeSeries`, so the full analytical surface can sort,
+ * scan, or index freely. Example:
+ * `new TimeSeries({ name, schema, rows })`.
+ */
 export declare class TimeSeries<S extends SeriesSchema> {
     #private;
     readonly name: string;

package/dist/batch/time-series.js

@@ -452,6 +452,14 @@ function prepareSeriesForJoin(series, options) {
  * actually runs).
  */
 const TRUSTED_STORE_SENTINEL = Symbol('TimeSeries.trustedStoreSentinel');
+/**
+ * An immutable, schema-typed, ordered collection of events — the batch
+ * layer's core primitive. A series is constructed whole from complete data
+ * and never mutated: every transform (`filter`, `align`, `rollup`, …)
+ * returns a new `TimeSeries`, so the full analytical surface can sort,
+ * scan, or index freely. Example:
+ * `new TimeSeries({ name, schema, rows })`.
+ */
 export class TimeSeries {
     name;
     schema;

package/dist/live/live-series.d.ts

@@ -41,6 +41,14 @@ export type LiveSeriesOptions<S extends SeriesSchema> = {
 type EventListener<S extends SeriesSchema> = (event: EventForSchema<S>) => void;
 type BatchListener<S extends SeriesSchema> = (events: ReadonlyArray<EventForSchema<S>>) => void;
 type EvictListener<S extends SeriesSchema> = (events: ReadonlyArray<EventForSchema<S>>) => void;
+/**
+ * A mutable, append-optimized event buffer for live ingestion — the entry
+ * point to the live layer. `push` validates rows against the same schema
+ * as `TimeSeries`, retention (`maxEvents` / `maxAge`) bounds the buffer,
+ * and subscribers react on the `'event'`, `'batch'`, and `'evict'`
+ * channels; snapshot to the batch layer at any time with `toTimeSeries()`.
+ * Example: `new LiveSeries({ name, schema, retention: { maxEvents: 10_000 } })`.
+ */
 export declare class LiveSeries<S extends SeriesSchema> {
     #private;
     readonly name: string;

package/dist/live/live-series.js

@@ -86,6 +86,14 @@ function assertCellKind(kind, value, name) {
     }
 }
 // ── LiveSeries ──────────────────────────────────────────────────
+/**
+ * A mutable, append-optimized event buffer for live ingestion — the entry
+ * point to the live layer. `push` validates rows against the same schema
+ * as `TimeSeries`, retention (`maxEvents` / `maxAge`) bounds the buffer,
+ * and subscribers react on the `'event'`, `'batch'`, and `'evict'`
+ * channels; snapshot to the batch layer at any time with `toTimeSeries()`.
+ * Example: `new LiveSeries({ name, schema, retention: { maxEvents: 10_000 } })`.
+ */
 export class LiveSeries {
     /** @internal */
     [EMITS_EVICT] = true;

package/dist/live/live-view.d.ts

@@ -37,6 +37,15 @@ type ViewOptions<S extends SeriesSchema> = {
  * Reuses `KeyColumnForSchema`, gated on the time variant.
  */
 type TimeKeyOnly<S extends SeriesSchema> = KeyColumnForSchema<S> extends TimeKeyColumn ? KeyColumnForSchema<S> : 'LiveView.keyColumn() supports time-keyed views only — use toTimeSeries() for other key kinds';
+/**
+ * A derived, subscribable live projection — the result of chainable live
+ * operators such as `filter`, `map`, `select`, `fill`, `diff`, and `rate`.
+ * A view subscribes to its source `LiveSource`, runs each event through
+ * its process function as it arrives (emitting a transformed event or
+ * skipping it), and mirrors source eviction — you obtain one from an
+ * operator rather than constructing it directly. Example:
+ * `live.filter((e) => (e.get('value') as number) > 5)`.
+ */
 export declare class LiveView<S extends SeriesSchema> implements LiveSource<S> {
     #private;
     readonly name: string;

package/dist/live/live-view.js

@@ -10,6 +10,15 @@ import { float64ColumnFromArray } from '../columnar/column.js';
 import { TimeKeyColumn } from '../columnar/key-column.js';
 import { EMITS_EVICT, } from '../schema/index.js';
 import { parseDuration } from '../core/duration.js';
+/**
+ * A derived, subscribable live projection — the result of chainable live
+ * operators such as `filter`, `map`, `select`, `fill`, `diff`, and `rate`.
+ * A view subscribes to its source `LiveSource`, runs each event through
+ * its process function as it arrives (emitting a transformed event or
+ * skipping it), and mirrors source eviction — you obtain one from an
+ * operator rather than constructing it directly. Example:
+ * `live.filter((e) => (e.get('value') as number) > 5)`.
+ */
 export class LiveView {
     /** @internal */
     [EMITS_EVICT] = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pond-ts",
-  "version": "0.48.1",
+  "version": "0.49.0",
   "description": "TypeScript-first time series primitives",
   "license": "MIT",
   "repository": {