@pond-ts/process 0.58.0 → 0.59.0

package/API.md

@@ -0,0 +1,576 @@
+# API.md — public API map for agents
+
+A fast-navigation map of every public export across pond's six packages,
+written **for coding agents**. Use it to find the right primitive and the file
+it lives in without crawling `src/`. It is a map, not a reference: one line per
+export, grouped by purpose, with the source path. Verify exact signatures in
+the listed source file (or the generated typedoc) before writing code against
+them.
+
+**This file ships inside every `pond-ts` / `@pond-ts/*` npm package**, so an
+agent working in a consuming repo has the whole export surface locally — no
+network, no crawling `node_modules/*/dist/*.d.ts`. Every package carries the
+same monorepo-wide copy on purpose: the packages compose, so knowing what is
+next door is the point.
+
+- **Authority**: each package's `src/index.ts` is the export surface. If this
+  file and `index.ts` disagree, `index.ts` wins.
+- **Source paths** (`packages/core/src/…`) are repo-relative. From a consuming
+  repo, read them on GitHub:
+  <https://github.com/pond-ts/pond/blob/main/>`<path>`.
+- **Human-facing docs**: <https://pond-ts.org> — narrative guides, per-feature
+  reference, and generated typedoc per package. This file is the agent-facing
+  complement, not a replacement.
+- **Contributing to pond itself**: when a PR adds, removes, or renames a public
+  export, update the matching row here in that PR — CI enforces it (the
+  `API map` workflow).
+
+| Package              | npm name             | Entry points                                           | Docs hub                  |
+| -------------------- | -------------------- | ------------------------------------------------------ | ------------------------- |
+| `packages/core`      | `pond-ts`            | `.` and `./types` (zero-runtime schema contract)       | `website/docs/pond-ts/`   |
+| `packages/react`     | `@pond-ts/react`     | `.`                                                    | `website/docs/react/`     |
+| `packages/charts`    | `@pond-ts/charts`    | `.`                                                    | `website/docs/charts/`    |
+| `packages/financial` | `@pond-ts/financial` | `.` and `./fluent` (prototype augmentation)            | `website/docs/financial/` |
+| `packages/fit`       | `@pond-ts/fit`       | `.`                                                    | `website/docs/fit/`       |
+| `packages/process`   | `@pond-ts/process`   | `.` and `./pool` (Node worker pool) — **experimental** | `website/docs/process/`   |
+
+---
+
+## pond-ts (core) — batch
+
+### Series classes & construction
+
+| Export                  | Purpose                                                | Source                                               |
+| ----------------------- | ------------------------------------------------------ | ---------------------------------------------------- |
+| `TimeSeries`            | Immutable time-indexed collection, columnar storage    | `packages/core/src/batch/time-series.ts`             |
+| `ValueSeries`           | Series keyed by a monotonic non-time value axis        | `packages/core/src/batch/value-series.ts`            |
+| `PartitionedTimeSeries` | Scoped view for per-partition stateful transforms      | `packages/core/src/batch/partitioned-time-series.ts` |
+| `Sequence`              | Infinite grid of time buckets (daily, hourly, every N) | `packages/core/src/sequence/sequence.ts`             |
+| `BoundedSequence`       | Finite ordered list of explicit interval buckets       | `packages/core/src/sequence/bounded-sequence.ts`     |
+
+Static constructors on `TimeSeries`: `fromJSON()` (row tuples/objects),
+`fromColumns()` (struct-of-arrays; `number` + `string` value columns),
+`fromArrow()` (bring-your-own Apache Arrow `Table`; zero-copy Float64 adopt +
+BigInt-free int64 time. Readable Arrow types are an **allowlist checked
+against each field's declared type** — `Int`, `Float32`/`Float64`, `Date`,
+`Time`, `Timestamp`, `Utf8`/`Utf8View`, `Null`, and a `Dictionary` of any of
+those — and anything else, notably `Decimal` and `Float16`, is refused by name
+rather than misread; see
+`packages/core/src/batch/operators/arrow-types.ts`), `fromEvents()`,
+`fromPoints()` (wide rows with `ts`), `concat()`, `joinMany()`. On
+`ValueSeries`, the same three shapes keyed on the axis instead of time:
+`fromJSON()`, `fromColumns()`, `fromArrow()` (`{ axis }` is required — no
+`'time'` field convention to fall back on, and no unit scaling). Arrow-ingest
+types (`ArrowTableLike`, `ArrowVectorLike`, `ArrowDataLike`, `ArrowFieldLike`,
+`ArrowSchemaLike`, `ArrowTimeUnit`, `FromArrowOptions`,
+`FromArrowValueOptions`) live in
+`packages/core/src/batch/operators/from-arrow.ts`.
+
+Both classes also export **columnar JSON** — `toColumns()`, one plain array
+per column with gaps as `null`, the exact `{ name, schema, columns }` envelope
+`fromColumns()` takes back (`packages/core/src/batch/operators/to-columns.ts`).
+A **two-edged key** (`timeRange` / `interval`) flattens into extra columns
+named off it — `timeRange` + `timeRangeEnd`, `interval` + `intervalEnd` +
+`intervalLabel` — the convention `toArrow` already emitted, now read by
+`fromColumns` and by `fromArrow({ keyKind })` as well
+(`packages/core/src/batch/operators/flat-keys.ts` owns the naming + collision
+rules). Columnar wire types live beside their row siblings:
+`TimeSeriesJsonColumns` / `FlatKeyColumns` / `TimeSeriesColumnarInput` /
+`TimeSeriesColumnarOutput` in `packages/core/src/schema/json.ts`.
+
+Going the other way, `TimeSeries.toArrow()` / `ValueSeries.toArrow()` export
+the columns **in Arrow's memory layout with no copy** — pond's validity bitmap
+is already LSB-first one-bit-per-value, numerics are a contiguous
+`Float64Array`, booleans a packed bitmap, dict-encoded strings `Int32Array`
+indices plus a dictionary. It returns `{ length, fields }` rather than an Arrow
+`Table` (pond doesn't depend on `apache-arrow`; the caller assembles with
+`makeData`/`makeVector`), so another columnar engine is a buffer handoff
+instead of a re-ingest. Arrow-export types (`ArrowExport`, `ArrowExportField`,
+`ArrowExportType`, `ToArrowOptions`) live in
+`packages/core/src/batch/operators/to-arrow.ts`.
+
+`ValueSeries` also exports rows (`toRows()`, `toObjects()`, `toJSON()`).
+Value-axis wire types
+(`ValueSeriesJsonInput`, `ValueSeriesJsonRow`, `ValueSeriesJsonObjectRow`,
+`ValueSeriesJsonOutputArray`, `ValueSeriesJsonOutputObject`,
+`ValueSeriesJsonCell`, `ValueSeriesRow`, `ValueSeriesObjectRow`,
+`ValueSeriesJsonColumns`, `ValueSeriesColumnarInput`,
+`ValueSeriesColumnarOutput`) live in `packages/core/src/schema/value-io.ts`.
+
+### Temporal keys & events
+
+| Export        | Purpose                                       | Source                                 |
+| ------------- | --------------------------------------------- | -------------------------------------- |
+| `Time`        | Point-in-time event key                       | `packages/core/src/core/time.ts`       |
+| `TimeRange`   | Interval event key (start/end)                | `packages/core/src/core/time-range.ts` |
+| `Interval`    | Labeled time-interval event key               | `packages/core/src/core/interval.ts`   |
+| `Event`       | Immutable event: temporal key + typed payload | `packages/core/src/core/event.ts`      |
+| `toTimeRange` | Coerce temporal values to `TimeRange`         | `packages/core/src/core/time-range.ts` |
+
+### TimeSeries methods (all in `packages/core/src/batch/time-series.ts`)
+
+- **Query**: `at()`, `first()`, `last()`, `bisect(key)`, `includesKey(key)`,
+  `atOrBefore(key)`, `atOrAfter(key)`, `nearest(key)`, `find()`, `some()`,
+  `every()`
+- **Export/access**: `column(name)`, `keyColumn()`, `toRows()`, `toObjects()`,
+  `toArray()`, `toJSON()`, `toColumns()`, `toArrow()`, `toPoints()`
+- **Temporal range**: `timeRange()`, `overlaps()`, `contains()`,
+  `intersection()`, `overlapping(range)`, `containedBy(range)`, `trim(range)`,
+  `after()`, `before()`, `within()`, `tail(duration)`
+- **Key-type conversion**: `asTime({ at })`, `asTimeRange()`, `asInterval()`
+- **Filter/slice**: `filter()`, `sample(strategy)`, `slice(begin, end)`
+- **Column reshape**: `select()`, `rename()`, `map()`, `mapColumns()`,
+  `withColumn()`, `collapse()`
+- **Array columns**: `arrayContains()`, `arrayContainsAll()`,
+  `arrayContainsAny()`, `arrayAggregate()`, `arrayExplode()`
+- **Gap fill / dedupe**: `fill()`, `materialize()`, `dedupe()`
+- **Aggregate/group**: `aggregate(sequence, spec)`, `reduce()`, `groupBy()`,
+  `partitionBy()`, `byColumn()` (order-free, by column value),
+  `rollingByColumn()`, `byValue(axis)` (project onto a `ValueSeries`)
+- **Windowing/smoothing**: `rolling(window, spec, opts)`, `smooth(column,
+method)` (EMA / Butterworth / Savitzky-Golay), `align(method, opts)`
+- **Differential/statistical**: `diff()`, `rate()`, `pctChange()`,
+  `cumulative()`, `scan()` (custom stateful reducer), `shift()`, `baseline()`
+  (rolling avg/sd/bands), `outliers()` (deviation from baseline)
+- **Join/pivot**: `join(other, opts)`, `pivotByGroup(group, opts)`
+
+### ValueSeries methods (all in `packages/core/src/batch/value-series.ts`)
+
+Deliberately small — the ordering-based slice of the algebra, no calendar ops
+(see `docs/rfcs/value-axis.md`) — except for ingest/export, which is at full
+`TimeSeries` parity.
+
+- **Query/read**: `length`, `axisName`, `axisValues()`, `axisAt(i)`,
+  `column(name)`, `nearestIndex(value)`, `sliceByValue(lo, hi)`
+- **Export**: `toRows()`, `toObjects()`, `toJSON({ rowFormat })`,
+  `toColumns()`, `toArrow(opts)`
+
+### Columnar layer & support
+
+| Export                                                                                         | Purpose                                    | Source                                         |
+| ---------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------- |
+| `Float64Column` / `StringColumn` / `BooleanColumn` / `ArrayColumn`                             | Packed value-column storage per kind       | `packages/core/src/columnar/`                  |
+| `ChunkedFloat64Column` / `ChunkedStringColumn` / `ChunkedBooleanColumn` / `ChunkedArrayColumn` | Chunked variants (variable-length buffers) | `packages/core/src/columnar/chunked-column.ts` |
+| `TimeKeyColumn` / `TimeRangeKeyColumn` / `IntervalKeyColumn` / `ValueKeyColumn`                | Key-column storage per key kind            | `packages/core/src/columnar/key-column.ts`     |
+| `top`                                                                                          | Reducer factory: top-N values              | `packages/core/src/reducers/top.ts`            |
+| `ValidationError`                                                                              | Error class thrown on invalid input        | `packages/core/src/core/errors.ts`             |
+
+### Key exported types (batch)
+
+| Type group        | Names                                                                                                                                              | Source                                                             |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| Schema contract   | `SeriesSchema`, `RowForSchema`, `EventForSchema`, `EventDataForSchema`, `EventKeyForSchema`, `TimeSeriesInput`, `TimeSeriesJsonInput`              | `packages/core/src/schema/index.ts`                                |
+| Aggregation specs | `AggregateReducer`, `AggregateMap`, `AggregateOutputMap`, `AggregateSchema`, `BinReducerName`, `BinOutput`                                         | `packages/core/src/schema/index.ts`, `packages/core/src/column.ts` |
+| Operation schemas | `RollingSchema`, `RollingAlignment`, `AlignSchema`, `DiffSchema`, `SmoothSchema`, `SmoothMethod`, `FillStrategy`, `FillMapping`                    | `packages/core/src/schema/index.ts`                                |
+| Column/data kinds | `Column`, `KeyColumn`, `ColumnKind`, `ScalarKind`, `ScalarValue`, `ColumnValue`, `ArrayValue`, `ValidityBitmap`                                    | `packages/core/src/columnar/`                                      |
+| JSON wire format  | `JsonRowFormat`, `JsonRowForSchema`, `JsonObjectRowForSchema`, `JsonValueForKind`, `JsonTimestampInput`, `JsonTimeRangeInput`, `JsonIntervalInput` | `packages/core/src/schema/index.ts`                                |
+| Temporal utility  | `TemporalLike`, `DurationInput`, `CalendarUnit`, `TimeZoneOptions`, `KeyLike`, `BatchSampleStrategy`                                               | `packages/core/src/core/`, `packages/core/src/sequence/`           |
+
+The `pond-ts/types` subpath re-exports the schema-as-contract types with zero
+runtime (`packages/core/src/schema/public.ts`).
+
+---
+
+## pond-ts (core) — live / streaming
+
+### Classes
+
+| Export                        | Purpose                                                      | Source                                                     |
+| ----------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- |
+| `LiveSeries`                  | Bounded in-memory buffer of time-keyed events with retention | `packages/core/src/live/live-series.ts`                    |
+| `LiveView`                    | Stateful transformation view over a live source              | `packages/core/src/live/live-view.ts`                      |
+| `LivePartitionedSeries`       | Routes events into per-partition sub-buffers by column value | `packages/core/src/live/live-partitioned-series.ts`        |
+| `LivePartitionedView`         | Derived per-partition view over a partitioned series         | `packages/core/src/live/live-partitioned-series.ts`        |
+| `LiveAggregation`             | Emits aggregated buckets when `Sequence` boundaries cross    | `packages/core/src/live/live-aggregation.ts`               |
+| `LiveRollingAggregation`      | Single-window rolling aggregation, configurable trigger      | `packages/core/src/live/live-rolling-aggregation.ts`       |
+| `LiveFusedRolling`            | Multi-window rolling, shared deque, single ingest pass       | `packages/core/src/live/live-fused-rolling.ts`             |
+| `LivePartitionedFusedRolling` | Fused rolling per partition, synchronized emission           | `packages/core/src/live/live-partitioned-fused-rolling.ts` |
+| `LiveReduce`                  | Reduce over current buffer; emits per trigger                | `packages/core/src/live/live-reduce.ts`                    |
+| `LiveColumnGroup`             | Zero-copy column gather over a view slice                    | `packages/core/src/live/live-view.ts`                      |
+
+### Triggers
+
+`Trigger` factory (`packages/core/src/live/triggers.ts`): `Trigger.event()`
+(per-event, default), `Trigger.clock(sequence)` (boundary crossing),
+`Trigger.every(duration)` (fixed cadence sugar), `Trigger.count(n)`. Types:
+`EventTrigger`, `ClockTrigger`, `CountTrigger`.
+
+### Methods
+
+- **`LiveSeries`** — static: `LiveSeries.fromJSON()`; ingest: `push()`,
+  `pushMany()`, `pushJson()`; query: same
+  key-query set as `TimeSeries` (`at`/`first`/`last`/`find`/`bisect`/
+  `atOrBefore`/`atOrAfter`/…); operators: `window()`, `aggregate()`,
+  `rolling()`, `reduce()`, `diff()`, `rate()`, `pctChange()`, `fill()`,
+  `cumulative()`, `partitionBy()`; snapshots: `toTimeSeries()`, `toRows()`;
+  subscription: `on()` (event/batch/evict) → unsubscribe fn; utilities:
+  `stats()`, `clear()`, `timeRange()`, `eventRate()`, `length`.
+- **`LiveView`** — transform: `filter()`, `map()`, `select()`, `sample()`;
+  plus the same operator/query/snapshot/subscription surface as `LiveSeries`
+  (minus ingest).
+- **`LivePartitionedSeries`** — `toMap()` (spawn all partitions), `apply()`
+  (per-partition factory), `collect()` (fan-in unified series), `sample()`,
+  `stats()`, `on()` (spawn callback).
+
+### Key exported types (live)
+
+`LiveSeriesOptions` (`name`, `schema`, `ordering: 'strict' | 'drop' |
+'reorder'`, `graceWindow`, `retention: { maxEvents?, maxAge? }`),
+`LivePartitionedOptions`, `LiveAggregationOptions`, `LiveRollingOptions`,
+`RollingWindow`, `LiveFillStrategy`, `LiveFillMapping` — all under
+`packages/core/src/live/`.
+
+---
+
+## @pond-ts/react
+
+All hooks in `packages/react/src/<hookName>.ts`.
+
+| Export           | Signature gist                          | Purpose                                                                            |
+| ---------------- | --------------------------------------- | ---------------------------------------------------------------------------------- |
+| `useLiveSeries`  | `useLiveSeries(opts, hookOpts?)`        | Create + own a `LiveSeries` for the component lifetime; returns it with a snapshot |
+| `useTimeSeries`  | `useTimeSeries(input, key?)`            | Memoized `TimeSeries.fromJSON` for static/fetched data                             |
+| `useSnapshot`    | `useSnapshot(source, opts?)`            | Subscribe to a live source, return a throttled `TimeSeries` snapshot               |
+| `useWindow`      | `useWindow(source, size, opts?)`        | Windowed view of a live source + throttled snapshot                                |
+| `useDerived`     | `useDerived(series, transform)`         | Batch transform of a snapshot, recomputed on change                                |
+| `useLiveQuery`   | `useLiveQuery(build, deps, opts?)`      | Build a derived live view, subscribe, return view + snapshot                       |
+| `useLatest`      | `useLatest(source, opts?)`              | Only the latest event                                                              |
+| `useCurrent`     | `useCurrent(source, mapping, opts?)`    | Current value of a reducer over the source                                         |
+| `useEventRate`   | `useEventRate(source, duration, opts?)` | Events-per-second over a trailing window                                           |
+| `useLiveVersion` | `useLiveVersion(source, opts?)`         | Change signal for reading columns without a snapshot                               |
+| `takeSnapshot`   | `takeSnapshot(source)`                  | Non-hook: snapshot any live source to a `TimeSeries`                               |
+
+Types: `UseSnapshotOptions`, `SnapshotSource` (structural — covers
+`LiveSeries`, `LiveView`, …), `UseCurrentOptions`, `UseLiveVersionOptions`.
+
+---
+
+## @pond-ts/charts
+
+### Components — layout & axes
+
+| Component                   | Key props                                                                                                                                                             | Purpose                                                                                                                                     | Source                                                 |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `ChartContainer`            | `width`, `range?`, `theme?`, `cursor?`, `panZoom?`, `bounds?`, `showAxis?`, `calendar?`, `origin?`, `maxBandWidth?`/`bandAlign?`, `onTrackerChanged?`, `onDrawStats?` | Root: shared x-scale, interactions, annotations                                                                                             | `packages/charts/src/ChartContainer.tsx`               |
+| `ChartRow`                  | `height`, `cursor?` (deprecated — mount a cursor in the row)                                                                                                          | One stacked plot band; owns its y-axes                                                                                                      | `packages/charts/src/ChartRow.tsx`                     |
+| `Layers`                    | children                                                                                                                                                              | Mandatory z-stack inside a row (back-to-front)                                                                                              | `packages/charts/src/Layers.tsx`                       |
+| `YAxis`                     | `id` (req), `side?`, `scale?` (`'linear'` \| `'log'` \| `'symlog'`), `linearWindow?`, `min?`/`max?`, `format?`, `width?`, `hide?`                                     | Y-axis gutter; layers bind via their `axis` prop                                                                                            | `packages/charts/src/YAxis.tsx`                        |
+| `XAxis`                     | `side?`, `label?`, `format?`, `ticks?`, `transform?`, `dateStyle?`                                                                                                    | Placeable x-axis strip; kind inferred from data                                                                                             | `packages/charts/src/XAxis.tsx`                        |
+| `TimeAxis` / `CategoryAxis` | (XAxis props)                                                                                                                                                         | Thin `XAxis` presets                                                                                                                        | `packages/charts/src/TimeAxis.tsx`, `CategoryAxis.tsx` |
+| `Canvas`                    | `width`, `height`, `draw`                                                                                                                                             | Low-level DPR-aware canvas primitive                                                                                                        | `packages/charts/src/Canvas.tsx`                       |
+| `Selector`                  | `enabled?` (default `true`), `selected?` (mark \| set), `hovered?`, `onSelect?`, `onHover?`, `children?`                                                              | Wraps its scope; mounting enables click-select and owns the state it drives (RFC A10)                                                       | `packages/charts/src/selectors.tsx`                    |
+| `MultiSelector`             | `enabled?`, `selected?`, `hovered?`, `sequence?`, `onSelect?`, `onHover?`, `children?`                                                                                | Sweep-select superset of `Selector`: drag sweeps marks, release reports `(hits, modifiers, spans)` — plural, one per swept layer (RFC A5.2) | `packages/charts/src/selectors.tsx`                    |
+
+### Components — draw layers
+
+All take `series` plus an `as?` style identifier (theme lookup) and `axis?`
+scale id — style and scale are separate channels; there are no per-component
+color props (see Theming).
+
+**Column props are schema-derived** ([PND-CHARTAPI]): a name that isn't a
+numeric column of the series fails to compile, and `<BarChart>`'s props are a
+union of its legal source modes, so mixing `series`/`bins`/`categories` or
+`column`/`columns` is a compile error too. Two carve-outs:
+a **loosely-typed** series (`TimeSeries<SeriesSchema>`) still accepts any name
+(`packages/charts/src/column-names.ts` explains the `never` fallback that makes
+this work), and `bins` names stay `string` (they name aggregate fields, not
+schema columns). Because the union splits per series _kind_, a value typed as
+**either** kind must be narrowed or cast at the call site.
+
+| Component      | Data props                                                                                                | Purpose                                             | Source                                 |
+| -------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------- |
+| `LineChart`    | `column`, `gaps?`, `sessionBreaks?`                                                                       | Gap-aware line                                      | `packages/charts/src/LineChart.tsx`    |
+| `AreaChart`    | `column`, `baseline?`, `gaps?`                                                                            | Filled area                                         | `packages/charts/src/AreaChart.tsx`    |
+| `BandChart`    | `lower`, `upper`                                                                                          | Variance-band envelope                              | `packages/charts/src/BandChart.tsx`    |
+| `ScatterChart` | `column`, `id?` (selection), radius/color encodings                                                       | Points; data-driven size/colour                     | `packages/charts/src/ScatterChart.tsx` |
+| `BarChart`     | `column` \| `columns` \| `bins` \| `categories`, `orientation?`, `thresholds?`/`bandColors?`              | Bars, stacked bars, histograms, categorical         | `packages/charts/src/BarChart.tsx`     |
+| `HeatMap`      | `series`, `columns` (rows), `colors`, `domain?`, `scale?`, `noData?`, `gap?`, `decimate?`, `orientation?` | Grid of colour-coded cells; bins on x, columns on y | `packages/charts/src/HeatMap.tsx`      |
+| `BoxPlot`      | `lower`/`q1?`/`median?`/`q3?`/`upper`, `shape?`                                                           | Box-and-whisker from quantile columns               | `packages/charts/src/BoxPlot.tsx`      |
+| `Candlestick`  | OHLC columns, `variant?`, `colorBy?`, `showOHLC?`                                                         | First-class OHLC candles (TimeSeries only)          | `packages/charts/src/Candlestick.tsx`  |
+| `Legend`       | `placement?`, `items?`, `onRowClick?`, `onRowHover?`                                                      | Series key from registered layers' resolved styles  | `packages/charts/src/Legend.tsx`       |
+
+### Components — annotations & indicators
+
+| Component        | Key props                                             | Purpose                                                                                                                | Source                                |
+| ---------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| `Region`         | `from`, `to`, `label?`, `id?`, `onChange?`            | Shaded x-span; draggable when `onChange` given                                                                         | `packages/charts/src/annotations.tsx` |
+| `Baseline`       | `value`, `axis?`, `label?`, `indicator?`, `onChange?` | Horizontal value line                                                                                                  | `packages/charts/src/annotations.tsx` |
+| `Marker`         | `at`, `label?`, `indicator?`, `onChange?`             | Vertical x line                                                                                                        | `packages/charts/src/annotations.tsx` |
+| `Zone`           | `from`, `to`, `axis?`, `role?`, `label?`, `edges?`    | Shaded y-span — a value-axis scale (AQI categories, HR zones); inert + edge-less by default, `±Infinity` for open ends | `packages/charts/src/annotations.tsx` |
+| `YAxisIndicator` | `value?` \| `source?`, `axis?`, `format?`             | Live value pill pinned to a y-axis edge                                                                                | `packages/charts/src/indicators.tsx`  |
+
+### Components — cursors (mounted presets)
+
+The `cursor` string modes as components (interaction RFC §4/A4.1) — mount one
+as a child of `<ChartContainer>` (the default for every row) or inside a
+`<ChartRow>` (the per-row override). Render-only presets stack; one
+gesture-owning cursor (`Crosshair`/`Range`) per scope. The `cursor` /
+`cursorTime` / `crosshairSnap` / `cursorFormat` / `cursorSequence` /
+`onRegionSelect` / `regionSelectModifier` props (and `<ChartRow cursor>`) are
+**deprecated** — they keep working for one minor via an internal shim. The
+underlying `CursorSpec` contract stays unpublished (Q3); every drag claim on
+the plot (annotation-create, the range drag, pan) is arbitrated by one brush
+recognizer with a documented precedence (`src/brush.tsx`, RFC A1.5/A2.7).
+
+| Component         | Key props                                                     | Purpose                                                                                                                       | Source                            |
+| ----------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| `LineCursor`      | `showTime?`                                                   | The synced vertical line (`cursor="line"`, the legacy default)                                                                | `packages/charts/src/cursors.tsx` |
+| `PointCursor`     | `showTime?`                                                   | A dot on each series at the cursor (`"point"`)                                                                                | `packages/charts/src/cursors.tsx` |
+| `InlineCursor`    | `showTime?`                                                   | Dots + a value chip beside each (`"inline"`)                                                                                  | `packages/charts/src/cursors.tsx` |
+| `FlagCursor`      | `showTime?`                                                   | Dots + staffed value flags stacked at the top (`"flag"`)                                                                      | `packages/charts/src/cursors.tsx` |
+| `CrosshairCursor` | `snap?`, `showTime?`, `format?`                               | The inspection reticle: dashed cross, y value pill, x time pill (`"crosshair"`)                                               | `packages/charts/src/cursors.tsx` |
+| `RangeCursor`     | `sequence?`, `onDragRelease?`, `enableDrag?`, `dragModifier?` | The hover-time band + the drag: release fires once with a `RangeSpan`, then reverts (`"region"` + `onRegionSelect` successor) | `packages/charts/src/cursors.tsx` |
+
+### Components — standalone row lists (DOM tables, no `<ChartContainer>`)
+
+One row per _entity_ (interface, split, symbol) on one shared value scale;
+label + data cells, `sortBy`/`sort`, optional per-row expander. The in-plot
+histogram stays `<BarChart orientation="horizontal">` — these are the table
+shape (react-timeseries-charts' `HorizontalBarChart`).
+
+| Component | Data props                                                                           | Purpose                                                             | Source                            |
+| --------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | --------------------------------- |
+| `BarList` | `rows`, `columns` (`values` names), `sortBy?`, `before?`/`after?`, `renderExpanded?` | Ranked bar list — one proportional bar line per column per row      | `packages/charts/src/BarList.tsx` |
+| `BoxList` | `rows`, `columns` (five-number names + `value?` tick), same table props              | Distribution list — range band / q1→q3 body / median / current tick | `packages/charts/src/BoxList.tsx` |
+
+Row/option types + readers (`packages/charts/src/list.ts`): `ListRow`,
+`ListValue`, `ListCellSpec`, `ListMarker` (reference rule through every row,
+label above; joins the auto domain fit), `ListSortDirection`, `BarListColumn`,
+`BoxListColumn`, `ListRowsOptions`; `listRowsFromTimeSeries` /
+`listRowsFromValueSeries` build one `ListRow` per event / axis key (numeric +
+string columns land in `values`).
+
+### View builders (all in `packages/charts/src/data.ts`)
+
+With a pond series, the components are the whole data contract (pass the
+series directly) — these exports expose the chart-ready view shapes for
+consumers writing custom draw code; no shipped layer needs their output.
+The ValueSeries siblings (`fromValueSeries` etc.) are deliberately
+**unexported** (adapters are internal; see [PND-VSADAPT]).
+
+| Export               | Signature gist                                         | Feeds                                                     |
+| -------------------- | ------------------------------------------------------ | --------------------------------------------------------- |
+| `fromTimeSeries`     | `(series, column) → ChartSeries`                       | Line/Area/Scatter                                         |
+| `bandFromTimeSeries` | `(series, lower, upper) → BandSeries`                  | BandChart                                                 |
+| `boxFromTimeSeries`  | `(series, BoxColumns) → BoxSeries`                     | BoxPlot                                                   |
+| `barsFromTimeSeries` | `(series, column) → BarSeries`                         | BarChart                                                  |
+| `ohlcFromTimeSeries` | `(series, OhlcColumns) → OhlcSeries`                   | Candlestick                                               |
+| `stacksFromGroups`   | `(Map<string, TimeSeries>, column) → StackedBarSeries` | Stacked bars from grouped series                          |
+| `stacksFromColumns`  | `(series, columns[]) → StackedBarSeries`               | Stacked bars from wide columns                            |
+| `barsFromBins`       | `(bins, column, opts?) → BarSeries`                    | One-column histogram (single-series path, [PND-BARSEM])   |
+| `stacksFromBins`     | `(bins, columns[], opts?) → StackedBarSeries`          | Multi-column histograms from `byColumn` output            |
+| `categoryStack`      | `(CategoryDatum[]) → StackedBarSeries`                 | Categorical bars                                          |
+| `categoryStacks`     | `(CategoryStackDatum[], columns) → StackedBarSeries`   | Stacked categorical bars ([PND-CATSTACK])                 |
+| `bandedColor`        | `(value, colors[], lo, hi) → string \| undefined`      | The heat map's own banding — for a matching legend        |
+| `heatValueExtent`    | `(StackedBarSeries) → [lo, hi] \| null`                | Finite extent across a grid; `<HeatMap>`'s domain default |
+| `transposeRow`       | `(series, opts?) → CategoryDatum[]`                    | One row read across as categories                         |
+
+Series shapes (same file): `ChartSeries`, `BandSeries`, `BoxSeries`,
+`BarSeries`, `OhlcSeries`, `StackedBarSeries`; option types `BoxColumns`,
+`OhlcColumns`, `BinRecord`, `StacksFromBinsOptions`, `CategoryDatum`,
+`CategoryStackDatum`, `RowAt`,
+`TransposeRowOptions`.
+
+### Theming
+
+| Export                         | Purpose                                                                                      | Source                                                 |
+| ------------------------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `ChartTheme`                   | The one styling channel: role-keyed slots per draw layer + fixed chrome slots                | `packages/charts/src/theme.ts`                         |
+| `defaultTheme` / `estelaTheme` | Built-in themes (neutral light / dark estela palette)                                        | `packages/charts/src/theme.ts`                         |
+| `cssVarTheme`                  | `(base, resolve, opts?) → ChartTheme` — static CSS-custom-property overlay                   | `packages/charts/src/css-theme.ts`                     |
+| `useChartTheme`                | Hook: re-resolves on `data-theme`/`class` flips (MutationObserver)                           | `packages/charts/src/useChartTheme.ts`                 |
+| Style types                    | `LineStyle`, `AreaStyle`, `BandStyle`, `ScatterStyle`, `BarStyle`, `BoxStyle`, `CandleStyle` | `packages/charts/src/theme.ts`                         |
+| State types                    | `ScatterStates`, `BoxStates`, `BoxLadder`, `HeatStates` — the per-state sub-objects          | `packages/charts/src/theme.ts`                         |
+| Helper types                   | `ChartThemeOverrides`, `VarReader`, `UseChartThemeOptions`                                   | `packages/charts/src/css-theme.ts`, `useChartTheme.ts` |
+
+### Live values, scales & key types
+
+| Export                                     | Purpose                                                                                               | Source                                    |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| `createLiveValue` / `LiveValue`            | Imperative push channel for high-frequency indicator updates (isolated repaint)                       | `packages/charts/src/indicators.tsx`      |
+| `scaleTradingTime` / `TradingTimeScale`    | Discontinuous time scale collapsing closed-market gaps                                                | `packages/charts/src/tradingTimeScale.ts` |
+| `DiscontinuityProvider`                    | Gap topology consumed by the trading-time scale                                                       | `packages/charts/src/tradingTimeScale.ts` |
+| `scaleBand` / `ScaleBand`                  | Ordinal slot scale for the category axis                                                              | `packages/charts/src/bandScale.ts`        |
+| `GapMode`                                  | `'none' \| 'empty' \| 'dashed' \| 'step' \| 'fade'` (Line/Area `gaps` prop)                           | `packages/charts/src/gaps.ts`             |
+| `DecimateOption`                           | `<LineChart decimate>` — M4 viewport decimation (`bool \| { threshold }`)                             | `packages/charts/src/decimate.ts`         |
+| `CursorMode`                               | `'none' \| 'line' \| 'point' \| 'inline' \| 'flag' \| 'crosshair' \| 'region'`                        | `packages/charts/src/context.ts`          |
+| `TrackerInfo` / `TrackerSample`            | Hover readout payload (`onTrackerChanged`)                                                            | `packages/charts/src/context.ts`          |
+| `AnnotationKind` / `CreateSpec`            | Annotation identity + draw-gesture payload (`onCreate`)                                               | `packages/charts/src/context.ts`          |
+| `SelectInfo`                               | Selection/hover payload (`Selector`/`MultiSelector` `onSelect`/`onHover`)                             | `packages/charts/src/context.ts`          |
+| `SelectModifiers`                          | Keyboard modifiers on a click, 2nd arg to `onSelect`                                                  | `packages/charts/src/context.ts`          |
+| `SelectorProps`                            | `<Selector>`'s props — `enabled?` / `selected?` / `hovered?` / `onSelect?` / `onHover?` / `children?` | `packages/charts/src/selectors.tsx`       |
+| `MultiSelectorProps`                       | `<MultiSelector>`'s props — the above plus `sequence?`, with plural callbacks                         | `packages/charts/src/selectors.tsx`       |
+| `RangeSpan`                                | `<RangeCursor onDragRelease>` payload — `{ x: [lo, hi], y? }` in axis units                           | `packages/charts/src/context.ts`          |
+| `SpanSelection`                            | Range entry for `selected` — one layer's marks over `x`/`y`/`rows` (RFC A5.2)                         | `packages/charts/src/context.ts`          |
+| `SelectionEntry`                           | One `selected` array entry: `SelectInfo \| SpanSelection`                                             | `packages/charts/src/context.ts`          |
+| `selectionContains`                        | Is a hit in a mixed selection? The same membership predicate the layers run                           | `packages/charts/src/span.ts`             |
+| `sameMark`                                 | Are two hits the same mark? Full identity (`id`, `mark`-or-`key`, `label`)                            | `packages/charts/src/span.ts`             |
+| `isSpanSelection`                          | Entry discriminant — narrows a `SelectionEntry` to `SpanSelection`                                    | `packages/charts/src/span.ts`             |
+| `DrawStatsFrame` / `LayerDrawInfo`         | Per-repaint draw-cost + decimation stats (`ChartContainer` `onDrawStats`)                             | `packages/charts/src/context.ts`          |
+| `TimeGrain`                                | Coarse time unit for grain-aware formatting                                                           | `packages/charts/src/tickLadder.ts`       |
+| `SwatchSpec` / `LegendItemInput`           | Legend swatch vocabulary + explicit-rows input (`<Legend items>`)                                     | `packages/charts/src/swatch.ts`           |
+| `useChartLegend`                           | Headless legend hook: rows (items grouped by chart row) + `hover`/`select` verbs                      | `packages/charts/src/useChartLegend.ts`   |
+| `ChartLegend` / `LegendRow` / `LegendItem` | The hook's return shape (`rows` group `items`; items carry `selected`/`hovered`)                      | `packages/charts/src/useChartLegend.ts`   |
+| `LegendPlacement`                          | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'`                                        | `packages/charts/src/Legend.tsx`          |
+| `Curve`                                    | Path interpolation: `'linear' \| 'monotone' \| 'natural' \| 'basis' \| 'step'`                        | `packages/charts/src/curve.ts`            |
+| `RadiusEncoding` / `ColorEncoding`         | Data-driven scatter size/colour                                                                       | `packages/charts/src/encoding.ts`         |
+| `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`     |
+| `Orientation`                              | Bar growth direction                                                                                  | `packages/charts/src/bars.ts`             |
+
+---
+
+## @pond-ts/financial
+
+### Studies (each also a fluent method after `import '@pond-ts/financial/fluent'`)
+
+All are pure `(series, options) → TimeSeries` appending output columns;
+`column` defaults to `'close'`; periods are bar counts; warm-up is
+length-preserving (`undefined` head rows).
+
+| Study                       | Output column(s)                    | Options gist                                        | Source                                             |
+| --------------------------- | ----------------------------------- | --------------------------------------------------- | -------------------------------------------------- |
+| `sma`                       | `sma`                               | `{ period, column?, output? }`                      | `packages/financial/src/studies/moving-average.ts` |
+| `ema`                       | `ema`                               | `{ period, column?, output? }` (α = 2/(period+1))   | `packages/financial/src/studies/moving-average.ts` |
+| `bollinger`                 | `bbMiddle`, `bbUpper`, `bbLower`    | `{ period, stdDev?, column?, prefix? }`             | `packages/financial/src/studies/bollinger.ts`      |
+| `envelope`                  | `envMiddle`, `envUpper`, `envLower` | `{ period, percent?, maType?, column?, prefix? }`   | `packages/financial/src/studies/envelope.ts`       |
+| `rollingStdev`              | `stdev`                             | `{ period, column?, output? }` (population, ddof=0) | `packages/financial/src/studies/rolling-stat.ts`   |
+| `rollingMin` / `rollingMax` | `min` / `max`                       | `{ period, column?, output? }` (Donchian edges)     | `packages/financial/src/studies/rolling-stat.ts`   |
+| `rollingPercentile`         | `p{q}` (e.g. `p90`)                 | `{ period, q, column?, output? }`                   | `packages/financial/src/studies/rolling-stat.ts`   |
+| `zScore`                    | `zscore`                            | `{ period, column?, output? }`                      | `packages/financial/src/studies/z-score.ts`        |
+| `percentChange`             | `pctChange`                         | `{ periods?, column?, output? }`                    | `packages/financial/src/studies/percent-change.ts` |
+
+Adding a study? Follow `packages/financial/src/studies/README.md` (uniform
+shape + pandas oracle case + fluent method are all REQUIRED).
+
+### Trading calendars & sessions
+
+| Export                                                           | Purpose                                                                                                                                                                              | Source                             |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- |
+| `TradingCalendar`                                                | Query API: `.sessions()`, `.sessionOn()`, `.isTradingDay()`, `.isOpen()`, `.sessionsInRange()`, `.sessionSequence()`, `.barSequence(period)`, `.tagSessions()`, `.discontinuities()` | `packages/financial/src/calendar/` |
+| `generateSessions`                                               | `Session[]` from `SessionRules` over a date range (DST-correct)                                                                                                                      | `packages/financial/src/calendar/` |
+| `normalizeSessions`                                              | Validate + sort an explicit session list                                                                                                                                             | `packages/financial/src/calendar/` |
+| `identityDiscontinuity` / `segmentDiscontinuity` / `weekendSkip` | `DiscontinuityProvider`s for the trading-time axis                                                                                                                                   | `packages/financial/src/calendar/` |
+| Types                                                            | `Session`, `SessionBreak`, `SessionRules`, `DateRange`, `InstantRange`, `TaggedSchema`, `LiveSegment`, `DiscontinuityProvider`                                                       | `packages/financial/src/calendar/` |
+
+### Contract & constants
+
+`OhlcvColumns` (column-name contract), `DEFAULT_OHLCV`
+(`{ open, high, low, close, volume }`), `DEFAULT_SOURCE` (`'close'`) —
+`packages/financial/src/contract/`. `RollingReducer` (reducer-name union used
+by studies) — `packages/financial/src/kernels/rolling.ts`.
+
+---
+
+## @pond-ts/fit
+
+| Group                | Exports                                                                                                                                                                                                                                                                                                                      | Source                                             |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| Activity model types | `ImportedActivity`, `ActivityMeta`, `ActivityStreams`, `Lap`, `GeoPoint`, `ActivitySource`                                                                                                                                                                                                                                   | `packages/fit/src/types.ts`                        |
+| Activity façade      | `Activity` (`Activity.fromStreams(imported)`), `Section`, `ProfiledActivity`, `ProfiledSection`, `Sample`, `SectionMetrics`                                                                                                                                                                                                  | `packages/fit/src/activity/`                       |
+| Summary pipeline     | `computeActivitySummary`, `prepareActivity` → `summaryFromPrepared` (reuse decode), `windowChannels` (zoom re-bucketing), `buildTrackFromStreams` (pond series from streams); types `ActivitySummary`, `PreparedActivity`, `ChannelProfile`, `ChannelSample`, `ChannelKey`                                                   | `packages/fit/src/summary/`                        |
+| Track & geo          | `Track` (`Track.of(points)`), `polylineCumulative`, `interpolateAtDistance`, `polylineSlice`, `boundsOf`, `bestEffortsByDistance`, `segmentsInRange`                                                                                                                                                                         | `packages/fit/src/track/`, `packages/fit/src/geo/` |
+| Power analytics      | `computePower` (NP/IF/TSS/zones; `{ binWatts }` sets the histogram bucket width), `powerBestEfforts`; types `PowerSummary`, `PowerZone`, `PowerBin`, `PowerCurvePoint`, `PowerEffort`, `ComputePowerOptions`. `PowerBin`/`PowerZone` carry pond's canonical `start`/`end` bin edges, so they feed `@pond-ts/charts` unmapped | `packages/fit/src/power/`                          |
+| Profile & zones      | `Profile`, `hydrateProfile`, `profileAsOf`, `hrZonesFrom`, `paceZonesFrom`, `powerZonesFrom` (Coggan from FTP)                                                                                                                                                                                                               | `packages/fit/src/profile/`                        |
+| Zone distribution    | `zoneDistributionByValue`, `hrZoneDistribution`, `paceZoneDistribution`, `ZoneTime` (canonical `start`/`end` edges + `openEnded`; chart-ready)                                                                                                                                                                               | `packages/fit/src/zones/`                          |
+| Quantities           | Value objects with canonical units: `Distance`, `Elevation`, `Duration`, `Speed`, `Pace`, `Power`, `HeartRate`, `Cadence`                                                                                                                                                                                                    | `packages/fit/src/quantities.ts`                   |
+| Units                | `convertDistance` / `convertElevation` / `convertTemperature` / `convertSpeed`, `metersToMiles`, `metersToFeet`, `formatDuration`, `formatPace`, `*UnitLabel` helpers, `DEFAULT_UNITS`                                                                                                                                       | `packages/fit/src/units.ts`                        |
+
+---
+
+### `@pond-ts/financial/parallel` (Node-only, opt-in)
+
+`withWorkers(series, { workers })` — opts a series into partitioned rolling
+studies and returns it unchanged; `shutdownWorkers()`; `parallelDispatches()`;
+`MIN_ROWS`; type `WithWorkersOptions`. Chosen **once at ingest**: the studies keep their
+signatures and stay synchronous, and derived series inherit it (registration is
+keyed on the key-column buffer). **Single-threaded remains the default** — the
+main package never imports this. Node-only by construction: `Atomics.wait` on
+the main thread is what keeps the studies synchronous, and browsers forbid it.
+
+Accelerates any rolling study asking for `avg`/`stdev` off one column — `sma`,
+`envelope`, `bollinger` — at 1.85×/1.35×/1.92×. **Partitioning does not change
+the answer**: since [PND-PROCKERN] the kernel's accumulator rebuilds are pinned
+to absolute row index, so a chunk reconstructs exactly the state a whole-column
+pass held and the partitioned result is bit-identical. **`zScore` is not
+accelerated**: [PND-SHIFTFRAME] moved it onto a shifted-frame kernel this pool
+does not hook, so opting in neither speeds it up nor changes its answer. It used
+to be the fastest entry here at 2.44×, and the only one whose error had no bound.
+Below `MIN_ROWS` a registered series still runs sequentially and is
+bit-identical. `parallelDispatches()` returns how many passes have actually run
+on workers — acceleration is otherwise invisible, since a declined pass returns
+the same answer, only slower than you expected. Source:
+`packages/financial/src/parallel/`.
+
+## @pond-ts/process
+
+**Experimental — published pre-1.0, API expected to move with friction
+reports; pin an exact version.** The declarative plan layer is the consumer
+surface (RFC [process.md](docs/rfcs/process.md)); the engine ships exported
+beneath it — the [PND-PROCSUB] packaging decision, resolved at first publish.
+Docs: [website/docs/process/](website/docs/process/). Tickets:
+[PND_PROCESS_PLAN.md](docs/plans/PND_PROCESS_PLAN.md).
+
+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`                       |
+
+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/`,
+`skipLibCheck: false`). The package's own build sets `skipLibCheck: true` and
+never checks its own output, so a declaration referencing a type `stripInternal`
+deleted builds green and breaks only downstream. If you mark something
+`@internal`, confirm no public signature names it.
+
+---
+
+## Cross-package seams (where agents most often need the joint)
+
+- **Batch → charts**: a draw layer takes a pond `series` + `column` directly;
+  the `data.ts` adapters are the explicit versions of what layers do
+  internally. Histogram path: `series.byColumn(...)` → `stacksFromBins(...)` →
+  `<BarChart bins>`.
+- **Live → react → charts**: `LiveSeries` → `useSnapshot`/`useWindow` →
+  the same layer props a batch chart uses (no separate live-mode API).
+- **Financial → charts**: `TradingCalendar.discontinuities()` →
+  `ChartContainer calendar` (trading-time axis); studies append columns that
+  `LineChart`/`BandChart` draw (`bbUpper`/`bbLower` → `BandChart`).
+- **Core → financial**: studies compose on core kernels; fluent methods mutate
+  `TimeSeries.prototype` (runtime import of `@pond-ts/financial/fluent`
+  required).
+- **Live → process**: `fromLive(liveSeries)` binds a live source as a graph
+  input. Events only mark the node dirty; the snapshot runs once at the next
+  pull, so per-event incremental work stays in the live layer and the graph
+  composes batch transforms over snapshots. The graph has **no partial
+  invalidation** — a dirty node recomputes from a whole snapshot — so for
+  windowed work bind the _aggregation_ (`fromLive(live.aggregate(...))`),
+  which materializes bucket count rather than event count (235x per pull on
+  a 50k buffer). Tradeoff: a live aggregation exposes closed buckets only,
+  so the in-progress bucket is invisible until it closes.

package/CHANGELOG.md

@@ -8,7 +8,8 @@ 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.58.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.59.0...HEAD
+[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
 [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
@@ -61,6 +62,148 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.59.0] — 2026-08-11
+
+### Added
+
+- **charts: `<YAxis scale="symlog">` — linear through zero, logarithmic beyond**
+  ([PND-SYMLOG]). The third `scale` kind, for a **diverging** measure spanning
+  orders of magnitude on both sides of zero. `scale="log"` cannot express that
+  domain at all (no zero, no negatives) and `scale="linear"` flattens everything
+  outside the top decade onto the axis line — so the small and mid-range values,
+  usually the finding, become unreadable.
+
+  The knee is set by the new **`linearWindow`** prop as a _fraction of the
+  domain's largest magnitude_ (default `0.02`): on a ±1M domain the axis is
+  linear through ±20k and logarithmic beyond. Relative rather than absolute so
+  it survives a domain change with no arithmetic at the call site. Values are
+  strictly monotonic across the knee, and zero has a real position. A fraction
+  outside `(0, 1]` is unusable as a knee, so the axis draws with the default and
+  dev-warns which window is in force.
+
+  **The tick ladder is pond's, not d3's.** `scaleSymlog` supplies the transform
+  but ticks it _linearly_, which puts every label in the top decade and none in
+  the linear window the scale exists to open up. `<YAxis scale="symlog">` grids
+  zero, ±the knee, and mirrored decades beyond it, thinned to the tick budget
+  the same way the log path thins its decades, clipped to the domain. When
+  `linearWindow` swallows the domain there is nothing left to grid
+  logarithmically, and the axis defers to the linear ticks — which is correct,
+  not a fallback: inside the knee, symlog _is_ linear.
+
+  It removes a workaround whose cost was **silence**: pre-transforming values
+  into a ±1 plot space with a linear axis pinned to `[-1, 1]` leaves tick
+  positions in plot space while their labels must read in real units, so
+  computing the two by different routes yields a chart that confidently labels
+  positions it does not occupy — no exception, no visual artifact.
+
+  **If you are replacing a hand-rolled curve, the shape will shift.** `symlog` is
+  the single smooth `sign(x) · log1p(|x / knee|)`, not two joined segments; a
+  hand-rolled curve that is exactly linear below the knee and `log10` above is the
+  same family with a different shape. Migrating one, a consumer measured small
+  values at **roughly half** their former height (on a ±9M domain, 283k moved from
+  0.44 to 0.24 of the half-plot above the zero line) with order, tail dominance and
+  the several-fold lift over a linear axis all preserved. No `linearWindow` recovers the piecewise shape — the
+  difference is the curve, not the knee.
+
+- **charts: `<BarChart maxBarWidth>` — cap a bar's ink independently of its slot**
+  ([PND-BARWIDTH]). Applied after the `gap` inset and centred in the slot, with
+  `theme.bar[as].maxWidth` as the fallback (the same relationship `gap` has) and
+  uncapped when neither is set.
+
+  It is the **absolute** half of the width vocabulary. `gap` is _relative_, so
+  with it alone bar width is always `slot - gap` and fattens as the plot widens
+  — and a fixed ink width is what makes a measure comparable **between** panes,
+  since bars that widen with their pane read as different weights of the same
+  thing. Neither existing spelling expresses "spread the slots, pin the bar":
+  `maxBandWidth = barWidth + gap` pins the bar but stops the slots spreading,
+  and `maxBandWidth = slotCap` spreads them but lets the bar grow. The
+  workaround was to compute `gap` from the band width you predicted the library
+  would pick — a re-derivation of pond's layout arithmetic in consumer code,
+  which goes silently wrong the moment that rule changes on either side.
+
+  Pairs with `<ChartContainer maxBandWidth>` (which caps the **slot**) and
+  `minWidth` still wins if the two bounds would invert. **A single-series bar's
+  hit target stays its whole slot**, so narrow ink costs nothing in clickability;
+  on a **stacked** chart the cap does narrow the target, because a stack must
+  hit-test its drawn segment rect to resolve which segment.
+
+- **charts: `<BarChart categories columns>` — a first-class stacked category
+  chart** ([PND-CATSTACK]). Each datum is `{ label, values }` and `columns`
+  names the groups to stack bottom → top, the same relationship
+  `series` + `columns` already has. New `categoryStacks` reader and
+  `CategoryStackDatum` type; geometry, `marks` and the categorical axis are
+  unchanged from the single-value case, so this reaches the shipped
+  `drawStacks` path with no new draw code. A missing or non-finite group reads
+  as a **gap**, not a zero.
+
+  **It removes a workaround with three costs**, the third only visible since
+  0.58.0: composing the picture from one `categories` layer per _cumulative
+  total_ (drawn outermost-first so each overpaints the one beneath) meant a
+  hand-assembled legend, label thinning blind to the sibling layers, and — because
+  a selection entry keys on `(layer id, mark)` — a controlled set replicated
+  across every segment layer, where missing one made a selected bar recede
+  **from the waist up**. Because `marks` is indexed by **bin**, one entry naming
+  `(id, mark)` now matches every segment of a bar, so that failure is not
+  expressible rather than merely fixed.
+
+### Fixed
+
+- **charts: a selected segment of a stack with `colors` no longer collapses to
+  the flat `highlight`.** `StackStyle.groupColored` — the "a selected segment
+  keeps its own fill" exclusion — was gated on the _theme ramp_ having painted
+  the stack, so a call site passing `colors` lost it and both segments of a
+  selected bar went one `highlight` blue, losing the segment distinction exactly
+  where the reader is looking. The gate's stated reason ("a ramp entry the call
+  site overrode is no longer the ramp's colour, so its receded counterpart would
+  be wrong") applies to the _derived_ companions `dimmedFills` / `hoverFills`,
+  which must invent a per-group colour; `groupColored` derives nothing. It now
+  gates on **whether the resolved fills actually differ**, so a `colors` map keeps
+  its colours under selection, while a multi-group stack under a theme that gives
+  its groups no distinct colours at all (no ramp, no roles, no `colors` — e.g.
+  `estelaTheme`) still takes the themed `highlight`, because there is no
+  meaning-carrying colour there to preserve and suppressing the highlight would
+  leave selection invisible. Found building [PND-CATSTACK], where the old gate made
+  the first-class stack render _worse_ under selection than the workaround it
+  replaces; the second half was found in review, since every story and test renders
+  `defaultTheme`, whose ramp hides the difference.
+
+- **all packages: `API.md` now ships inside the npm tarball.** The agent-facing
+  map of every public export across the six packages — one line per export with
+  its purpose and source path — was repo-only, so an agent working in a
+  _consuming_ repo had to crawl `node_modules/*/dist/*.d.ts` or go to the
+  network to learn the surface. It is now copied in by each package's existing
+  `prepack` (the same mechanism that already ships `README`, `LICENSE` and
+  `CHANGELOG`) and listed in `files`. ~69kB per tarball.
+
+  Every package carries the same **monorepo-wide** copy rather than a
+  per-package slice, deliberately: the packages compose, and knowing what is
+  next door is most of the value. The header now names its audience and
+  resolves repo-relative source paths against GitHub, since inside
+  `node_modules` a bare `packages/core/src/…` points nowhere.
+
+- **charts: `BarStyle.dimmed`'s precedence over per-bar and per-band colour is
+  documented, and pinned.** A consumer migrating onto 0.58.0 read
+  `BarStyle.hover`'s documented `binColors` exclusion ("pops each bar's _own_
+  fill"), reasonably generalized it to `dimmed`, concluded their `binColors` and
+  `thresholds` charts would get no de-emphasis, and was about to hand-dim inside
+  their own colour arrays. The opposite is true: **an unselected bar takes
+  `dimmed`, discarding its per-bar colour, and a banded bar draws flat rather
+  than dimming each band.** The asymmetry is deliberate — emphasis preserves a
+  per-bar colour because that colour is what the value means, while a receded
+  bar's job is to stop competing over meaning — but only `hover` said anything,
+  so generalizing was the natural read. `dimmed` now spells out all three paths
+  (`binColors`/`binFills`, bands/thresholds, and the per-group stack fallback
+  through `StackStyle.dimmedFills`), `hover` scopes its exclusion to the live
+  states, and three tests pin the behaviour.
+
+- **charts: the `theme.list` register no longer reads as if it carries
+  `dimmed`.** Its doc mentioned `highlight`/`dimmed` while explaining that a
+  list resolves glyph state through the bar tokens — accurate, but sitting in a
+  sentence about per-metric resolution it read as a field list, and cost the
+  same consumer a couple of passes to rule out a missing `list.dimmed`. Now
+  states explicitly that those are `BarStyle` tokens resolved via
+  `theme.bar[as]`, and that this register carries exactly its five values.
+
 ## [0.58.0] — 2026-08-10
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/process",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "Computations as data over pond-ts: processing graphs authored fluently or composed as JSON, resolved against a declared op vocabulary with content-addressed caching, provenance, and per-node timings. Experimental, pre-1.0.",
   "license": "MIT",
   "repository": {
@@ -27,13 +27,14 @@
   },
   "files": [
     "dist",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "API.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\" \"test-dts/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\" \"test-dts/**/*.ts\"",
-    "prepack": "cp ../../LICENSE ./LICENSE && cp ../../CHANGELOG.md ./CHANGELOG.md && npm run build && cp cjs-fallback.cjs dist/cjs-fallback.cjs && find dist -name '*.map' -delete",
+    "prepack": "cp ../../LICENSE ./LICENSE && cp ../../CHANGELOG.md ./CHANGELOG.md && cp ../../API.md ./API.md && npm run build && cp cjs-fallback.cjs dist/cjs-fallback.cjs && find dist -name '*.map' -delete",
     "test": "npm run test:type && npm run test:dts && npm run test:runtime",
     "test:type": "tsc -p tsconfig.types.json",
     "test:dts": "npm run build && tsc -p tsconfig.dts.json",
@@ -41,7 +42,7 @@
     "verify": "npm run format:check && npm run build && npm test"
   },
   "peerDependencies": {
-    "pond-ts": "^0.58.0"
+    "pond-ts": "^0.59.0"
   },
   "devDependencies": {
     "typescript": "^5.6.3",