@pond-ts/charts 0.71.0 → 0.73.0

package/API.md

@@ -118,7 +118,8 @@ Value-axis wire types
 - **Temporal range**: `timeRange()`, `overlaps()`, `contains()`,
   `intersection()`, `overlapping(range)`, `containedBy(range)`, `trim(range)`,
   `after()`, `before()`, `within()`, `tail(duration)`
-- **Key-type conversion**: `asTime({ at })`, `asTimeRange()`, `asInterval()`
+- **Key-type conversion**: `asTime({ at })`, `asTimeRange()`, `asInterval()`;
+  `offsetTime(by)` moves every key by a constant (kind kept)
 - **Filter/slice**: `filter()`, `sample(strategy)`, `slice(begin, end)`
 - **Column reshape**: `select()`, `rename()`, `map()`, `mapColumns()`,
   `withColumn()`, `collapse()`
@@ -161,8 +162,8 @@ Deliberately small — the ordering-based slice of the algebra, no calendar ops
 
 | 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` |
+| Schema contract   | `SeriesSchema`, `RowForSchema`, `EventForSchema`, `EventDataForSchema`, `EventKeyForSchema`, `TimeSeriesInput`, `TimeSeriesJsonInput`, `BatchOrderingMode`                                                      | `packages/core/src/schema/index.ts`                                |
+| Aggregation specs | `AggregateReducer`, `AggregateMap`, `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`                                |
@@ -723,7 +724,7 @@ the default for pipelines known at authoring time — see the package README.
 | 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`                     |
+| Range output buffers    | `prepareRange(length, keep, prior)` → `RangeOutput` (`values`, `set`, `clear`; a gap is `NaN` in `values`) carrying `[0, keep)` forward as one block copy; `sealRange(out, length)` → `Float64Column`. 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`               |

package/CHANGELOG.md

@@ -8,7 +8,9 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 under a single `v*` tag, so this file covers them all. Pre-1.0: minor bumps may
 include new features and type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pond-ts/pond/compare/v0.71.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.73.0...HEAD
+[0.73.0]: https://github.com/pond-ts/pond/compare/v0.72.0...v0.73.0
+[0.72.0]: https://github.com/pond-ts/pond/compare/v0.71.0...v0.72.0
 [0.71.0]: https://github.com/pond-ts/pond/compare/v0.70.0...v0.71.0
 [0.70.0]: https://github.com/pond-ts/pond/compare/v0.69.0...v0.70.0
 [0.69.0]: https://github.com/pond-ts/pond/compare/v0.68.0...v0.69.0
@@ -74,6 +76,334 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.73.0] — 2026-10-12
+
+### Added
+
+- **core**: **`ordering: 'strict' | 'reorder' | 'clamp'` on every loader**
+  (`new TimeSeries`, `TimeSeries.fromJSON` / `fromColumns` / `fromArrow`,
+  `ValueSeries.fromJSON` / `fromColumns` / `fromArrow`), with the new
+  `BatchOrderingMode` type exported. Same option name and vocabulary as
+  `LiveSeries`' `ordering` (`'strict'` / `'reorder'`), so one concept has one
+  name across batch and live. `'strict'` is the default (unchanged);
+  `'reorder'` is what `sort: true` did. **`'clamp'`** is new: rows stay in place and a key
+  earlier than its predecessor's takes that key (the running max), so a noisy
+  feed's lone backwards timestamp lands on its neighbour instead of failing the
+  ingest or being moved. Values are untouched, ties pass through, non-finite
+  keys are still rejected, value-column `Float64Array`s stay zero-copy, and a
+  caller's key buffer is never mutated. `time` keys and `ValueSeries` axes
+  only — a `timeRange` / `interval` key throws under `'clamp'`. [PND-INGEST]
+
+- `pond-ts`: **`series.offsetTime(by)` moves every key by a constant** —
+  milliseconds or a duration string, negative for earlier
+  (`yesterday.offsetTime('1d')` overlays yesterday on today; `'1d'` is a fixed
+  24 hours, not a calendar day). The key kind is kept; a `timeRange` /
+  `interval` key moves both edges and keeps its labels.
+  Value columns are shared, not copied, so the cost is one pass over the key:
+  0.26 ms on 97k rows × 118 columns, where rebuilding the series through its
+  rows took ~990 ms (`packages/core/scripts/perf-offset-time.mjs`). `0` returns
+  the series itself; a non-finite or unparseable offset throws.
+
+- **charts**: **`xOffset` on `<LineChart>`, `<AreaChart>` and `<BandChart>`
+  draws each row a fixed time after its key**, without touching the series. A
+  1-minute bar is keyed at its open but its `close` is the price at its end, so
+  `<LineChart column="close" xOffset="1m">` puts the line where the closes
+  happened — the session's last close on the close, not a bar early — while a
+  `<Candlestick>` from the same series still draws at the key. Previously this
+  meant rebuilding the whole series with shifted keys. Everything the layer
+  reports is in drawn time: the tracker's nearest row and dot, its auto-fit
+  x-extent, `sessionBreaks`, a sweep's span. Time series only; a non-zero
+  offset on a `ValueSeries` throws.
+
+- **charts**: **`<AreaChart sessionBreaks>`** ends the fill and its outline at
+  each trading-axis session close and re-starts them at the next open, as
+  `<LineChart>` and `<BandChart>` already did — so the line and area styles of
+  one intraday series break alike. `gaps="none"` still interpolates a dropout
+  inside a session but never across a break, and no inferred gap connector
+  spans one.
+
+- **charts:** `TradingTimeScale.flatFormat(count, drawn?)` — `drawn` is the
+  subset of `ticks(count)` actually rendered; flat promotions walk only those,
+  so a dropped tick's period turn carries to the next drawn one. Omitted, it
+  labels every tick as before.
+
+- **docs**: **The versioning policy is now published** — a "Versioning"
+  section in the root README and each package README, and a
+  [Versioning](https://pond-ts.org/docs/reference/versioning) page on the
+  docs site. Pre-1.0 a minor may break (always marked **breaking** here with a
+  migration note), patches never break, all packages release in lock-step,
+  and from 1.0 the project follows semver. The page also defines the public
+  API: each package's entry-point exports as mapped in `API.md`, excluding
+  anything marked experimental or internal.
+
+### Changed
+
+- **core** (**breaking**): **A `NaN` in a number column now always means
+  missing.** Typed-array intake (`fromColumns`, `withColumn` with a
+  `Float64Array`) already turned `NaN` into a gap and row intake already
+  rejected it, but an operator's own arithmetic could still write a
+  _defined_ `NaN` — `diff` / `rate` / `pctChange` of `Infinity - Infinity`,
+  a `cumulative` sum that reaches
+  `Infinity` and then meets `-Infinity`, or a `cumulative` custom fold,
+  `scan` step or numeric `collapse` reducer that returns `NaN`. Those
+  cells are now stored as **missing**: `at(i)` / `get` / `read` return
+  `undefined`, `scan()` skips them, and `nullCount()` / `hasMissing()` count
+  them. Same in live `diff` / `rate` / `pctChange` / `cumulative` views, in a
+  live `map` whose function writes `NaN` into a number field, and in
+  `@pond-ts/process` `RangeOutput.set` / `sealRange`. A `cumulative` that hits
+  `NaN` keeps its accumulator, so built-in folds read missing from that row on.
+  `±Infinity` now follows the same rule — see the next entry. The storage
+  switch this unlocked landed in the same release — see "number columns store
+  a missing cell as `NaN`" below. **Migration:** code that tested
+  `Number.isNaN(v)` on an operator's output should test `v === undefined`.
+
+- **core** (**breaking**): **Any non-finite number — `NaN`, `Infinity` or
+  `-Infinity` — in a number column means missing.** `Infinity` used to get five
+  different answers; it now gets one. A non-finite result is stored as a
+  **missing** cell (`undefined` on read, counted by `nullCount()` /
+  `hasMissing()`, skipped by `scan()`), so `count() + nullCount() === length`
+  always holds. What changed:
+  - **No longer throws:** `mapColumns` (a mapper returning `NaN` /
+    `±Infinity` — was a `RangeError`), and `rolling` / `aggregate` / `smooth`
+    / `baseline` / `byColumn` / `pivotByGroup` / `arrayAggregate` whose result
+    overflows (was a `ValidationError`). Those cells are now missing.
+  - **No longer a defined value:** `diff` / `rate` / `pctChange` /
+    `cumulative` / `scan` / `collapse` results that overflow to `±Infinity`
+    (e.g. `diff` of `MAX - (-MAX)`, a `cumulative` sum past `Number.MAX_VALUE`
+    — missing from that row on, as its accumulator stays `Infinity`).
+  - **Reducers never answer non-finite:** a reducer result that overflows
+    (`sum`, `avg`, `stdev`, or a custom reducer returning `Infinity`) is
+    `undefined` — in `reduce()` too, which used to return `Infinity`. A
+    rolling `sum` / `avg` / `stdev` (batch, live, and `smooth('movingAverage')`)
+    reads missing only while the current window overflows, and reads finite
+    again once the large values leave it. A mean is still sum-then-divide, so
+    `avg([MAX_VALUE, MAX_VALUE])` reads missing although the mean is finite.
+    (The column methods `col.sum()` / `col.mean()` are unchanged.)
+  - **Doors:** `withColumn` with a `Float64Array` reads `±Infinity` as a gap,
+    as it already read `NaN` (was a `ValidationError`). Row intake
+    (`new TimeSeries`, `fromJSON`, `LiveSeries.push`) and `withColumn` with a
+    plain array still reject `NaN` and `±Infinity` alike; `fromColumns` /
+    `fromArrow` already read both as a gap.
+  - **Live:** `diff` / `rate` / `pctChange` / `cumulative` / `map` views and
+    every live accumulator (`aggregate`, `rolling`, `reduce`) emit `undefined`
+    for a non-finite result, so a library view's `toTimeSeries()` no longer
+    throws on an overflow. A user `map` keeps the source schema, so a `map` fn
+    that writes a non-finite value reads missing too — and `toTimeSeries()`
+    then works if that column is optional, but throws the required-column
+    `ValidationError` if it is required. `@pond-ts/process` `RangeOutput.set` / `sealRange` / `packColumn`
+    store `±Infinity` as missing too.
+
+  **Migration:** code that caught a `ValidationError` / `RangeError` from these
+  operators to detect overflow, or tested `v === Infinity` on their output,
+  should test `v === undefined`. Code relying on
+  `withColumn(name, float64Array)` to reject `Infinity` must check it before
+  the call.
+
+- **core** (**breaking**, mostly internal): **Number columns store a missing
+  cell as `NaN` in their own `Float64Array`, and keep no separate validity
+  bitmap** ([PND-NANREP]). Now that any non-finite number in a number column
+  means missing (entries above), the `NaN` is the only marker the column needs.
+  Answers do not change, with one exception: a gappy `sum` / `avg` over a
+  sub-range (an `aggregate` bucket of 32+ cells) can differ from before in
+  the last digit, because the blocked sum now groups its eight lanes from the
+  range start rather than from a multiple of 8 — the same kind of rounding
+  difference blocked summation already allows. Speed improves — on 1M rows with 4% gaps, `fromColumns`
+  is 70% faster, `reduce` `sum` / `avg` / `min` 30–38%, `diff` / `cumulative` /
+  `shift` 14–18%, and `nullCount()` on a fresh column 35%. Dense columns are
+  mostly unchanged or faster (`fromColumns` 32%); dense `cumulative` measured
+  ~11% slower. String, boolean and array columns keep their bitmaps. What you
+  can see:
+  - **`toFloat64Array()` returns `NaN` at a missing cell** (it used to be
+    whatever the buffer held, often `0`). A draw loop now breaks the line at a
+    gap with no extra check, and `withColumn(name, col.toFloat64Array())` now
+    round-trips gaps.
+  - **`fromArrow` copies a `Float64` column that has nulls** (one bulk copy,
+    writing `NaN` at each null) instead of sharing Arrow's buffers. Gap-free
+    columns are still shared with no copy. `toArrow` builds a number column's
+    `nullBitmap` from its `NaN` cells (once, then cached).
+  - **`Float64Column` constructor** (trusted, internal) is now
+    `(values, length, allFinite = false)` — the `validity` argument is gone,
+    and the old four-argument call shape throws a `TypeError`. `allFinite` now means "no
+    missing cells". `col.validity` still exists for kind-generic code but is
+    built from the `NaN` cells on first read. A column built this way with a
+    `NaN` partition value or interval label now reads it as missing (it used
+    to be a `NaN` partition / a "not a finite number" error).
+  - **`@pond-ts/process`:** `RangeOutput`, `ColumnView` and `ColumnBuffers`
+    lose their `bits` field — a gap is `NaN` in `values`. `ColumnBuffers`
+    gains `allFinite`. `validityByteCount` is removed (nothing to size). `columnBytes` no longer counts a bitmap for number
+    columns.
+
+  **Migration:** code that read `validity.bits` of a number column, or passed
+  `bits` across a worker boundary, should test `Number.isNaN(values[i])`
+  instead. Code that relied on `fromArrow` sharing a null-bearing column's
+  buffer with the Arrow table should not.
+
+- **core**: Out-of-order ingest errors now suggest `{ ordering: 'reorder' }`
+  (and `'clamp'` where it applies) instead of `{ sort: true }`. Code matching
+  on the old message text needs updating.
+
+- **core** (**breaking**): **`select(...keys)` throws on a key that isn't a
+  column, and on an array argument.** It used to drop unknown keys silently, so
+  a typo — or `select(['a', 'b'])` instead of `select('a', 'b')` — returned an
+  empty-payload series with no error. Now an unknown key throws a `RangeError`
+  naming it and listing the valid columns, and an array argument throws a
+  `TypeError` telling you to spread it (`select(...names)`). Applies to
+  `TimeSeries`, `LiveSeries`, `LiveView`, `LiveAggregation` and
+  `LiveRollingAggregation` (the live ones throw when the view is built, not on
+  the first event). `Event.select` rejects an array argument but still
+  tolerates absent keys, since an event payload may omit optional fields.
+  Duplicate keys are still accepted and select the column once. **Migration:**
+  fix the misspelled column, or spread the array.
+
+- **core / react**: **The live column reads are no longer experimental.**
+  `LiveView.column()`, `LiveView.keyColumn()`, `LiveView.partitionBy().toMap()`,
+  the `LiveColumnGroup` class and `@pond-ts/react`'s `useLiveVersion` shipped in
+  v0.19.0 labelled "experimental — may change in 0.19.x". They are now part of
+  the stable surface that 1.0 will commit to, with no change to their shape.
+
+- **charts** (**breaking**): **An `<AreaChart>`'s `baseline` no longer changes
+  the y-axis range.** Since v0.71.0 the default zero baseline (and any numeric baseline)
+  was pulled into the auto-fit domain, so an area over data running $100–$200
+  drew on a $0–$200 axis, and switching `baseline` rescaled the chart — and
+  every other layer sharing its axis. The axis now fits the data, exactly as it
+  does for a `<LineChart>` of the same column; `baseline` only moves where the
+  fill stops. A baseline outside the axis range rests the fill on the nearest
+  edge, so on data that never crosses zero the default now draws the same as
+  `baseline="floor"`. **Migration:** where the fill should read from zero — a
+  stack, a quantity like throughput — put zero on the axis with
+  `<YAxis min={0}>` (`max={0}` for an all-negative series). Areas whose data
+  already reaches their baseline, or whose axis is pinned, are unchanged.
+
+- `pond-ts` (**breaking**, types only): **`TimeSeries.toJSON()`'s return
+  type narrows on `rowFormat`**, matching `LiveSeries.toJSON()`. The default
+  / `'array'` form returns `TimeSeriesJsonOutputArray<S>` and
+  `{ rowFormat: 'object' }` returns `TimeSeriesJsonOutputObject<S>`, so
+  `result.rows` is typed against your schema with no cast; a `rowFormat`
+  typed as `JsonRowFormat` gets the union. It used to return the loose
+  `TimeSeriesJsonInput<SeriesSchema>`. **Migration:** drop any
+  `as TimeSeriesJsonInput<…>` / `as TimeSeriesJsonOutput…<…>` casts (they
+  still compile). Two patterns now fail to compile: annotating an
+  **object**-form result as `TimeSeriesJsonInput<SeriesSchema>` — including
+  a `JsonRowFormat`-typed (union) result, since it can be the object form —
+  (use `TimeSeriesJsonInput<typeof schema>`, or no annotation), and reading a
+  column by name off a default (tuple) row, which was always `undefined` at
+  runtime. `LiveSeries.toJSON()` also gains the `JsonRowFormat` overload, which
+  previously had no matching signature. [PND-TSJSONT]
+
+- `pond-ts`: **`TimeSeries.toJSON()` tuple rows are ~2.5–3.5× faster at 100k
+  rows** — one array per row, filled in place, instead of a mapped array spread
+  into a second one. Tuple rows were slower than object rows; they now match or
+  beat them. Output unchanged.
+
+- **core** (**breaking**): **Every `on()` overload on `LiveAggregation` and
+  `LiveRollingAggregation` now returns an unsubscribe function**, matching
+  `LiveSeries.on` / `LiveView.on`. `on('bucket')` and `on('update')` used to
+  return `this`, so those listeners could never be removed. **Migration:** a
+  chained `live.aggregate(…).on('bucket', fn)` now yields the unsubscribe
+  function, not the operator (same for `live.rolling(…).on('update', fn)`) —
+  assign the operator first, then subscribe.
+
+- **core** (**breaking, type-level**): **`LiveAggregation` listeners
+  (`'event'`, `'bucket'`) and `LiveRollingAggregation`'s `'event'` listener
+  receive the schema-narrowed `EventForSchema<Out>`** — the same type `at()`
+  and the `closed()` series hand out — instead of a widened
+  `Event<Interval, Record<string, …>>` / `any`. `e.get('col')` is now typed
+  per output column, and naming a column the aggregation doesn't produce is a
+  compile error. As a result a `LiveAggregation<S, Out>` is now assignable to
+  `LiveSource<Out>` ([PND-LIVESRC]). The same narrowing applies to the
+  `'event'` listener of the keyed-form fused `live.rolling({...})`
+  (`LiveFusedRolling`), `live.reduce(…)` (`LiveReduce`), and the
+  clock-triggered partitioned `rolling(…)` variants
+  (`LivePartitionedSyncRolling` / `LivePartitionedFusedRolling`), which
+  previously typed it `(event: any)`. Both `LiveAggregation` /
+  `LiveRollingAggregation` `on()` methods now throw a
+  `TypeError` on an unknown event type instead of silently registering the
+  listener.
+
+### Deprecated
+
+- **core**: **`sort?: boolean`** on the loaders above — use
+  `ordering: 'reorder'`. `sort: true` still works for this release and maps to
+  `'reorder'`; it will be removed in the next minor. Passing `sort` together with
+  a conflicting `ordering` (e.g. `sort: true, ordering: 'clamp'`)
+  throws a `ValidationError`.
+
+### Removed
+
+- **core** (**breaking**): **`LiveAggregation.on('close', fn)` is removed —
+  use `on('event', fn)`**, which it was an alias for. Untyped callers that
+  still pass `'close'` get a `TypeError` naming the replacement.
+
+- `pond-ts` (**breaking**, types only): **the back-compat type alias
+  `AggregateOutputMap` is gone — use `AggregateMap`.** It has been an exact
+  alias of `AggregateMap` since v0.23.0, when the shorthand and
+  `{ from, using }` spec forms were unified into one map type. The internal
+  schema aliases `RollingOutputMapSchema` (identical to `RollingSchema`) and
+  `AggregateOutputMapResultSchema` (identical to `AggregateSchema`) are removed
+  with it; neither was reachable from a public entry point. **Migration:**
+  replace `AggregateOutputMap<S>` with `AggregateMap<S>` — no runtime change.
+  The fused-rolling duplicate-output error message now says "use a
+  `{ from, using }` spec entry" instead of naming the removed type.
+
+### Fixed
+
+- **charts: time-axis tick labels no longer overprint each other.** The tick
+  ladder places every session open unconditionally, so two anchors could land
+  closer than a label is wide — a session calendar derived from the bars turns
+  one stray pre-market print into a one-minute session whose `Sep 29` open sat
+  a pixel left of the real `15:30` open, and a seam could crowd the last clock
+  tick before it (`21:00` against the next day's `Sep 23`). A time axis now
+  measures its labels and drops the one that would collide — a date / month /
+  year turn outlasts a session-open clock label, which outlasts a plain one,
+  which outlasts a tick in closed-market time (an elapsed axis no longer labels
+  a seam with the shut night); of two colliding turns (or opens) the later is
+  drawn — then re-labels the
+  ticks it kept, so the dates they show stay correct (a stray New Year's print
+  can't take `2027` with it; a Sunday-evening futures open can't caption
+  Monday), and puts back any dropped tick that fits once a neighbour's label
+  narrowed. A blank label (a custom `format` returning `''`) never blocks one.
+  Under `align="auto"` the edge labels anchor by the full tick list, so a drop
+  never re-anchors another label. Applies to every `align` mode and to custom
+  `format`s; explicit `ticks` and `transform` ticks are untouched.
+
+- **charts**: a **decimated** `<LineChart sessionBreaks>` with
+  `gaps="none"` interpolated straight across each session break, and
+  `dashed` / `step` / `fade` drew a gap connector over it — dense intraday data
+  decimates, so this was the common case. Decimation marks the break as a gap
+  at the break instant, and the draw now cuts there instead of reading it as a
+  dropout.
+
+## [0.72.0] — 2026-10-08
+
+### Changed
+
+- `pond-ts`: **`join` and `joinMany` work on columns now, not events** — 20
+  to 190× faster in the cases below, with the same output. `join` used to
+  build an event for every row on both sides, merge them row by row and
+  rebuild the columns. Now it walks the two key columns once, then either
+  adopts each column as is or gathers it in one pass. A side's value columns
+  are adopted as is whenever all its rows land in the output once and in order:
+  always the left side of a `left` join, the right side of a `right` join, and
+  both sides when the keys match one for one (`joinMany` over a shared grid).
+  One year of 1-minute bars, ~97.5k rows a side, `type: 'left'` unless noted
+  (`packages/core/scripts/perf-join.mjs`):
+
+  | Value columns per side   | Before   | After    |
+  | ------------------------ | -------- | -------- |
+  | 59 and 59                | 1,868 ms | 24 ms    |
+  | 5 and 5                  | 168 ms   | 4.2 ms   |
+  | 59 and 2                 | 766 ms   | 4.1 ms   |
+  | `joinMany`, 4 × 5, outer | 457 ms   | 15–20 ms |
+
+  A left join now costs about as much as the **other** side is wide. To bring
+  across only the columns you read, narrow that side first; `select` and
+  `rename` don't copy:
+  `bars.join(spy.select('close').rename({ close: 'spy' }), { type: 'left' })`.
+
+  One visible difference: on a row with no match, `event.data()` now lists the
+  other side's fields as `undefined`, as every other operator's events do. It
+  used to leave them out. `get()` returns `undefined` either way.
+
 ## [0.71.0] — 2026-09-24
 
 ### Added
@@ -213,8 +543,8 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 - `@pond-ts/financial`: **`StudyOutput.id` documents the `@pond-ts/process`
   bridge**, and a new `test/catalog-process.test.ts` pins it. The field is a
-  *financial column suffix*; process's `OutputDef.id` is a *process outlet
-  id*; they share a name and are different namespaces. Process names its own
+  _financial column suffix_; process's `OutputDef.id` is a _process outlet
+  id_; they share a name and are different namespaces. Process names its own
   columns (`specId + OutputDef.id`) and matches an op's return to its outputs
   positionally, so a study's own column names never reach it — which means a
   registry bridging the two chooses its own suffixes, and for the **twelve**
@@ -227,7 +557,7 @@ include new features and type-level changes; patch bumps are strictly additive.
   worked around it by hand. No API change: the descriptors, the studies and
   the guard are all unchanged, and the round-trip test is what stops the two
   packages drifting — `catalog.test.ts` validates a descriptor against its
-  *study*, so it is structurally blind to a cross-package disagreement.
+  _study_, so it is structurally blind to a cross-package disagreement.
 - `@pond-ts/process`: **`Skipped.spec` echoes the request verbatim**, and its
   `params` / `inputs` are typed `unknown` accordingly. The plan pass normalized
   `params: null` to `{}`, so recomputing an id from the echo produced the
@@ -247,7 +577,6 @@ include new features and type-level changes; patch bumps are strictly additive.
 
   (All three reported by Tidal against 0.62.0, after adopting it.)
 
-
 ## [0.69.0] — 2026-09-13
 
 ### Added

package/README.md

@@ -69,6 +69,17 @@ Guides, the component reference, and live examples live at
 **<https://pond-ts.org/docs/charts/>**. Source and issues:
 [github.com/pond-ts/pond](https://github.com/pond-ts/pond).
 
+## Versioning
+
+Released in lock-step with `pond-ts` and the other `@pond-ts/*` packages
+under one version — keep them in step. Pre-1.0, a minor release may contain
+breaking changes (each marked **breaking** in the
+[CHANGELOG](https://github.com/pond-ts/pond/blob/main/CHANGELOG.md) with a
+migration note); patch releases never break. From 1.0 the project follows
+semver. See
+[Versioning](https://pond-ts.org/docs/reference/versioning) for what
+counts as the public API.
+
 ## License
 
 MIT

package/dist/AreaChart.d.ts

@@ -4,6 +4,7 @@ import type { NumericColumn, ValueNumericColumn } from './column-names.js';
 import type { DecimateOption } from './decimate.js';
 import { type Curve } from './curve.js';
 import { type GapMode } from './gaps.js';
+import { type XOffset } from './x-offset.js';
 export interface AreaChartCommon<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
      * The series' semantic identifier — what the data _is_ / how it should read
@@ -33,23 +34,23 @@ export interface AreaChartCommon<S extends SeriesSchema = SeriesSchema, VS exten
     /**
      * The value the fill rests on — the flat edge opposite the value line.
      *
-     * - **Omitted ⇒ `0`**: an area measures size from zero, so values above zero
-     *   fill up and values below it fill down, each side's shade fading toward
-     *   the zero line. Zero is pulled into the auto-fit domain, so the axis always
-     *   shows where the fill starts.
+     * - **Omitted ⇒ `0`**: values above zero fill up and values below it fill
+     *   down, each side's shade fading toward the zero line.
      * - **Another number ⇒ that reference level**, with the same behaviour (e.g.
      *   `baseline={100}` for an index that fills above and below 100). For the
      *   esnet two-colour traffic look, compose two `<AreaChart>`s (an "in" column
      *   and an "out" column, distinct `as` roles).
      * - **`'floor'` ⇒ the axis's lower bound** (the bottom of the plot): the fill
-     *   rests on whatever the axis starts at, and nothing is added to the domain.
-     *   For a series that never nears zero where zero would flatten the shape — a
-     *   price, an elevation profile.
+     *   rests on whatever the axis starts at, even when zero is on screen.
      *
-     * On a **log** axis zero has no position, so a baseline at or below zero
-     * falls back to the axis floor and is not pulled into the domain. On an axis
-     * pinned so that it excludes the baseline, the fill rests on the nearest
-     * edge (the baseline is clamped into the domain, as a bar's is).
+     * **The baseline never changes the axis range.** The axis fits the data, as
+     * it does for a `<LineChart>`, so switching `baseline` only moves where the
+     * fill stops, never the scale. A baseline outside the axis range rests the
+     * fill on the nearest edge (it is clamped into the domain, as a bar's is), so
+     * on data that never crosses zero the default looks the same as `'floor'`.
+     * To show the fill from zero, put zero on the axis: `<YAxis min={0}>`. On a
+     * **log** axis zero has no position, so a baseline at or below zero falls
+     * back to the axis floor.
      */
     baseline?: number | 'floor';
     /**
@@ -71,6 +72,21 @@ export interface AreaChartCommon<S extends SeriesSchema = SeriesSchema, VS exten
      * `'dashed'` / `'step'` connector faintness is the theme's `gap.connectorOpacity`.)
      */
     gaps?: GapMode;
+    /**
+     * End the fill (and its outline) at each **trading-axis discontinuity** — a
+     * session / day / lunch close→open — when the container renders on a
+     * trading-time axis (a `discontinuities` / `calendar` provider). **Omitted ⇒
+     * `false`**: the area runs from the last pre-close point straight to the next
+     * open, filling the collapsed gap. `true` ends the shade at the close and
+     * re-starts it at the open, the same break `<LineChart sessionBreaks>` draws,
+     * so the line and area styles of one intraday series read the same.
+     *
+     * A **scale** break, orthogonal to {@link gaps} (a **data** break, a NaN run):
+     * `gaps="none"` interpolates across a dropout but never across a session
+     * break, and no inferred gap connector spans one. A no-op on a continuous
+     * axis (no provider) or a provider without `boundaries`.
+     */
+    sessionBreaks?: boolean;
     /**
      * **M4 viewport decimation** (charts decimator wave). **Omitted ⇒ `true`**:
      * once the visible data is denser than ~2 samples per device pixel, the fill +
@@ -140,6 +156,13 @@ export interface AreaChartCommon<S extends SeriesSchema = SeriesSchema, VS exten
      * identity** (`as` ?? `column`). The swatch is the resolved area style.
      */
     legend?: boolean | string;
+    /**
+     * Draw each row this long **after its key** — milliseconds or a duration
+     * string. **Omitted ⇒ `0`**. Time series only. Same knob as
+     * {@link LineChartCommon.xOffset}, so an area and the line it pairs with
+     * move together.
+     */
+    xOffset?: XOffset;
     /**
      * @internal Declaration position among the `<Layers>` children, injected by
      * `Layers` so z-order follows JSX order. Do not set.
@@ -211,6 +234,6 @@ export declare function resolveAreaBaseline(baseline: number | undefined, yScale
  * </Layers>
  * ```
  */
-export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, readout, as: semantic, axis, id, baseline, curve, gaps, decimate, thresholds, bandColors, legend, index, }: AreaChartProps<S, VS>): null;
+export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series: source, column, readout, as: semantic, axis, id, baseline, curve, gaps, sessionBreaks, decimate, thresholds, bandColors, legend, xOffset, index, }: AreaChartProps<S, VS>): null;
 export {};
 //# sourceMappingURL=AreaChart.d.ts.map

package/dist/AreaChart.js

@@ -1,14 +1,15 @@
 import { useContext, useEffect, useMemo } from 'react';
 import { ValueSeries } from 'pond-ts';
 import { assertNumericColumn, fromTimeSeries, fromValueSeries, } from './data.js';
-import { areaExtent, areaHitIndex, areaStateStyle, drawArea } from './area.js';
-import { drawPartitioned, plotExtentOf, strokeSpanEdges, } from './line.js';
+import { areaHitIndex, areaStateStyle, drawArea } from './area.js';
+import { drawPartitioned, plotExtentOf, strokeSpanEdges, yExtent, } from './line.js';
 import { sweepSpan } from './sweep.js';
 import { resolveCurve } from './curve.js';
 import { DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
 import { ContainerContext, LayersContext, } from './context.js';
 import { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
+import { useXOffset } from './x-offset.js';
 import { useBandLadder } from './use-band-ladder.js';
 /** Read a d3 linear scale's domain lower bound (the axis floor) from the plain
  *  `(value) => pixel` function the row hands to `draw`. The runtime object is a
@@ -37,13 +38,17 @@ export function resolveAreaBaseline(baseline, yScale) {
         return floor;
     if (!d || d.length === 0)
         return baseline;
-    // Clamped into the domain, as a bar's baseline is: under an explicit
-    // `<YAxis min={40}>` the default 0 is off the plot, and a fill resting
+    // Clamped into the domain, as a bar's baseline is: the baseline never
+    // widens the axis, so on data that never crosses zero (or under an explicit
+    // `<YAxis min={40}>`) the default 0 is off the plot, and a fill resting
     // there would anchor its fade (and a gap's `'fade'` connector) off-plot.
     const lo = Math.min(d[0], d[d.length - 1]);
     const hi = Math.max(d[0], d[d.length - 1]);
     return Math.min(hi, Math.max(lo, baseline));
 }
+/** Stable empty boundary list — so `sessionBreaks={false}` keeps a referentially
+ *  constant array and the layer entry isn't rebuilt every render. */
+const NO_BREAKS = [];
 /**
  * An area draw layer: fills between a value `column` and a `baseline`, with a
  * graded (gradient) shade — opaque at the line, transparent at the baseline —
@@ -64,7 +69,7 @@ export function resolveAreaBaseline(baseline, yScale) {
  * </Layers>
  * ```
  */
-export function AreaChart({ series, column, readout, as: semantic, axis, id, baseline, curve, gaps = DEFAULT_GAP_MODE, decimate = true, thresholds, bandColors, legend, index = 0, }) {
+export function AreaChart({ series: source, column, readout, as: semantic, axis, id, baseline, curve, gaps = DEFAULT_GAP_MODE, sessionBreaks = false, decimate = true, thresholds, bandColors, legend, xOffset, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<AreaChart> must be rendered inside a <ChartContainer>');
@@ -73,11 +78,24 @@ export function AreaChart({ series, column, readout, as: semantic, axis, id, bas
     if (layers === null) {
         throw new Error('<AreaChart> must be rendered inside a <Layers>');
     }
+    // The series as drawn: moved by `xOffset` (the source itself when there is
+    // none), so every read below shares one axis.
+    const series = useXOffset(source, xOffset, 'AreaChart');
     // `undefined` below means "the axis floor" — the internal helpers' spelling.
     const baseValue = baseline === 'floor' ? undefined : (baseline ?? 0);
     const cs = useMemo(() => series instanceof ValueSeries
         ? fromValueSeries(series, column)
         : fromTimeSeries(series, column), [series, column]);
+    // Trading-axis session breaks: the collapse instants inside this series' span.
+    // Data instants, not pixels — view-independent, so pan/zoom reuse them. The
+    // same lookup `<LineChart>` / `<BandChart>` do, so the three break alike.
+    const sessionBreakInstants = useMemo(() => {
+        const provider = container.discontinuities;
+        if (!sessionBreaks || provider?.boundaries === undefined || cs.length < 2) {
+            return NO_BREAKS;
+        }
+        return provider.boundaries(cs.x[0], cs.x[cs.length - 1]);
+    }, [sessionBreaks, container.discontinuities, cs]);
     // Readout column values for a value-axis series (time path reads it off the
     // event) — the tracker reports it alongside the plotted fill so an off-chart
     // readout can show a source value. See AreaChartProps.readout.
@@ -150,13 +168,9 @@ export function AreaChart({ series, column, readout, as: semantic, axis, id, bas
     const entry = useMemo(() => ({
         layer: {
             as: semantic,
-            // A baseline with no position on a log axis (zero, the default) is
-            // left out of the fit: the draw rests it on the floor anyway, and an
-            // extent of `[0, max]` gives the log fit no positive low end, so it
-            // would collapse the domain onto the max and clip the series.
-            yExtent: (scale) => areaExtent(cs, scale === 'log' && baseValue !== undefined && baseValue <= 0
-                ? undefined
-                : baseValue),
+            // The values alone: the baseline never widens the axis (see
+            // `baseline`), so an area fits the same domain a line would.
+            yExtent: () => yExtent(cs),
             // The container infers the shared x scale's kind from its layers — a
             // ValueSeries plots on a value axis, a TimeSeries on time.
             xKind: series instanceof ValueSeries ? 'value' : 'time',
@@ -289,7 +303,7 @@ export function AreaChart({ series, column, readout, as: semantic, axis, id, bas
                     // `NaN` and poison every coordinate in the fill path. Fall back
                     // to the axis floor, which is exactly what `'floor'`
                     // already resolves to.
-                    resolveAreaBaseline(baseValue, yScale), curveFactory, gaps, gapConnectorOpacity, decimate, bandLadder);
+                    resolveAreaBaseline(baseValue, yScale), curveFactory, gaps, gapConnectorOpacity, decimate, bandLadder, sessionBreakInstants);
                 }
             },
         },
@@ -307,6 +321,7 @@ export function AreaChart({ series, column, readout, as: semantic, axis, id, bas
         curveFactory,
         gaps,
         gapConnectorOpacity,
+        sessionBreakInstants,
         decimate,
         bandLadder,
         axis,