@pond-ts/charts 0.69.0 → 0.70.0

package/API.md

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

package/CHANGELOG.md

@@ -8,7 +8,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.69.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.70.0...HEAD
+[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
 [0.68.0]: https://github.com/pond-ts/pond/compare/v0.67.0...v0.68.0
 [0.67.0]: https://github.com/pond-ts/pond/compare/v0.66.0...v0.67.0
@@ -72,6 +73,71 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.70.0] — 2026-09-18
+
+### Added
+
+- `@pond-ts/charts`: **`<BandChart sessionBreaks>`** — the same trading-axis
+  session break `<LineChart>` has had since v0.45.0. On a discontinuous
+  (`discontinuities` / `calendar`) axis the fill previously ran a near-vertical
+  sliver from one session's last sample to the next session's first, because
+  the collapsed overnight gap put them a pixel apart; `sessionBreaks` ends the
+  envelope at the close and re-starts it at the open, so a band and its centre
+  line break in step. A **scale** break, orthogonal to the NaN **data** gaps a
+  band always breaks at; default `false` (unchanged output). Decimation
+  composes: `decimateBand` folds each break instant into the pixel-column
+  edges and bakes a `NaN` sample at it, so no column merges two sessions'
+  envelopes. Stories `Axes/TradingTimeAxis / SessionBreaksBand` and
+  `Performance/Decimation / TradingSessionBreaksBand`.
+- `@pond-ts/process`: **`ArityError`**, and **arity is now part of what `specId`
+  can judge**. A spec whose `inputs` count does not match the op's — including
+  one carrying no `inputs` at all — was named `p1:sma(;period=20)`, a _valid_
+  id for something that cannot compile, and then died at `compile` as a bare
+  `TypeError` reading `.length` of `undefined`, reaching the consumer as a
+  `Skipped` with **no `code`** (which under that contract means "op code
+  threw"). Arity is decidable from the registry alone, so strict `specId` now
+  raises `ArityError` and lenient mode marks the id `p1?:`.
+  `Registry.checkArity(op, inputs)` is the shared check `compile` uses too.
+
+### Changed
+
+- `@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
+  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**
+  multi-output studies that claim the bare prefix (`trix`, `superTrend`,
+  `klinger`, …) it must: process rejects `''` on a multi-output op, because
+  there the column would be named exactly the spec id, itself a legal column
+  reference. The map is `outputs.length > 1 && id === ''` → `'value'` — not
+  `id === ''`, which would rename all seventy-odd single-output columns for
+  nothing. Reported by a consumer that hit the throw at module load and
+  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.
+- `@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
+  _defaulted spec's valid id_ — keying a broken persisted entry's report onto a
+  legitimate node. The selector pass echoed the original all along, so the two
+  passes disagreed. **Migration:** a consumer reading `entry.spec.params` now
+  narrows it (`entry.spec.params as Record<string, unknown>`, or a guard) —
+  which is the point, since the value may be exactly the malformed thing that
+  failed.
+- `@pond-ts/process`: `specId(…, { validate: false })` is **total over
+  arbitrary JSON**, not just over well-typed specs. `params: null`, a
+  non-array `inputs`, and an input entry that is neither a column name nor a
+  spec each used to raise a `TypeError`; they are now named in the `p1?:`
+  namespace, distinctly enough that two differently-broken specs stay two ids.
+  Strict mode reports them as `ParamError` / `ArityError` / `ProcessError`
+  rather than crashing.
+
+  (All three reported by Tidal against 0.62.0, after adopting it.)
+
+
 ## [0.69.0] — 2026-09-13
 
 ### Added

package/dist/BandChart.d.ts

@@ -27,6 +27,23 @@ export interface BandChartCommon<S extends SeriesSchema = SeriesSchema, VS exten
      * Denoise the underlying values with `smooth()`, not this.
      */
     curve?: Curve;
+    /**
+     * Break the envelope 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 fill
+     * connects the last pre-close sample straight to the next open across the
+     * collapsed gap (a near-vertical sliver). `true` ends the fill at the close
+     * and re-starts it at the open — the intraday look, where one session's
+     * envelope shouldn't visually flow into the next. Same semantics as
+     * {@link LineChart}'s `sessionBreaks`, so a band and its centre line break in
+     * step.
+     *
+     * This is a **scale** break (driven by the axis's collapsed gaps), orthogonal
+     * to a **data** break (a NaN run on either edge, which a band always breaks
+     * at). 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 envelope is denser than ~2 samples per device pixel, it is
@@ -34,6 +51,8 @@ export interface BandChartCommon<S extends SeriesSchema = SeriesSchema, VS exten
      * the samples span, so it covers the same pixels from O(plot width) points.
      * Applies with a linear `curve`; pass `false` to always fill every sample, or
      * `{ threshold }` to tune. Shares {@link LineChart}'s `DecimateOption`.
+     * Composes with {@link sessionBreaks}: the break instants are folded into the
+     * pixel-column edges so no column merges two sessions' envelopes.
      */
     decimate?: DecimateOption;
     /**
@@ -92,6 +111,6 @@ export type BandChartProps<S extends SeriesSchema = SeriesSchema, VS extends Val
  * </Layers>
  * ```
  */
-export declare function BandChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, lower, upper, as: semantic, axis, curve, decimate, legend, index, }: BandChartProps<S, VS>): null;
+export declare function BandChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, lower, upper, as: semantic, axis, curve, sessionBreaks, decimate, legend, index, }: BandChartProps<S, VS>): null;
 export {};
 //# sourceMappingURL=BandChart.d.ts.map

package/dist/BandChart.js

@@ -6,6 +6,9 @@ import { resolveCurve } from './curve.js';
 import { ContainerContext, LayersContext } from './context.js';
 import { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
+/** Stable empty boundary list — so `sessionBreaks={false}` keeps a referentially
+ *  constant array and the layer entry isn't rebuilt every render. */
+const NO_BREAKS = [];
 /**
  * A variance-band draw layer: fills the envelope between the `lower` and `upper`
  * columns of `series` (typically `rollingByColumn` percentiles), gap-aware, and
@@ -23,7 +26,7 @@ import { useSlotKey } from './use-slot-key.js';
  * </Layers>
  * ```
  */
-export function BandChart({ series, lower, upper, as: semantic, axis, curve, decimate = true, legend, index = 0, }) {
+export function BandChart({ series, lower, upper, as: semantic, axis, curve, sessionBreaks = false, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<BandChart> must be rendered inside a <ChartContainer>');
@@ -35,6 +38,18 @@ export function BandChart({ series, lower, upper, as: semantic, axis, curve, dec
     const bs = useMemo(() => series instanceof ValueSeries
         ? bandFromValueSeries(series, lower, upper)
         : bandFromTimeSeries(series, lower, upper), [series, lower, upper]);
+    // Trading-axis session breaks: the collapse instants inside this band's span
+    // (session/day/lunch opens the axis skips). Data instants, not pixels — so the
+    // set is view-independent (pan/zoom reuse it). Only computed when opted in and
+    // the container carries a boundary-reporting discontinuity provider. The same
+    // lookup `<LineChart>` does, so a band and its centre line break identically.
+    const sessionBreakInstants = useMemo(() => {
+        const provider = container.discontinuities;
+        if (!sessionBreaks || provider?.boundaries === undefined || bs.length < 2) {
+            return NO_BREAKS;
+        }
+        return provider.boundaries(bs.x[0], bs.x[bs.length - 1]);
+    }, [sessionBreaks, container.discontinuities, bs]);
     // Styling: semantic identifier → theme band style. The single styling channel.
     const { band } = container.theme;
     const style = (semantic !== undefined ? band[semantic] : undefined) ?? band.default;
@@ -118,7 +133,7 @@ export function BandChart({ series, lower, upper, as: semantic, axis, curve, dec
                     },
                 ];
             },
-            draw: (ctx, xScale, yScale) => drawBand(ctx, bs, xScale, yScale, style, curveFactory, decimate),
+            draw: (ctx, xScale, yScale) => drawBand(ctx, bs, xScale, yScale, style, curveFactory, sessionBreakInstants, decimate),
         },
         axisId: axis,
         index,
@@ -129,6 +144,7 @@ export function BandChart({ series, lower, upper, as: semantic, axis, curve, dec
         upper,
         style,
         curveFactory,
+        sessionBreakInstants,
         decimate,
         axis,
         index,

package/dist/band.d.ts

@@ -1,6 +1,6 @@
 import { type CurveFactory } from 'd3-shape';
 import type { BandSeries } from './data.js';
-import type { Scale } from './line.js';
+import { type Scale } from './line.js';
 import type { BandStyle } from './theme.js';
 import type { LayerDrawStats } from './context.js';
 import { type DecimateOption } from './decimate.js';
@@ -25,9 +25,17 @@ export declare function bandExtent(band: BandSeries): [number, number] | null;
  * filled envelope's break wants its own treatment (sharp edge vs. blurred),
  * still to be designed; for now a band always breaks honestly at a gap.
  *
+ * `boundaries` are trading-axis **session-break** instants (`<BandChart
+ * sessionBreaks>`): the envelope is split into per-session runs wherever one
+ * falls between two consecutive samples (see {@link sessionRuns}), each run its
+ * own closed subpath, so the fill ends at the last pre-close sample and re-starts
+ * at the first post-open one — a **scale** break, orthogonal to the NaN **data**
+ * gaps handled within each run. With no boundaries the output is identical to a
+ * single-pass draw. Mirrors `drawLine`'s treatment exactly.
+ *
  * `band.lower` (a `Float64Array`) is the datum iterable; every accessor reads by
  * index, so there's no per-point object allocation. `globalAlpha` carries the
  * opacity and is restored so it doesn't leak into later layers.
  */
-export declare function drawBand(ctx: CanvasRenderingContext2D, band: BandSeries, xScale: Scale, yScale: Scale, style: BandStyle, curve?: CurveFactory, decimate?: DecimateOption): LayerDrawStats;
+export declare function drawBand(ctx: CanvasRenderingContext2D, band: BandSeries, xScale: Scale, yScale: Scale, style: BandStyle, curve?: CurveFactory, boundaries?: readonly number[], decimate?: DecimateOption): LayerDrawStats;
 //# sourceMappingURL=band.d.ts.map

package/dist/band.js

@@ -1,7 +1,11 @@
 import { area as d3area, curveLinear } from 'd3-shape';
+import { sessionRuns } from './line.js';
 import { cullBandSeries } from './culling.js';
 import { decimateBand } from './decimate.js';
 import { gapUnscalable } from './gaps.js';
+/** Shared empty boundary list — passed to `sessionRuns` when a decimated band
+ *  already carries its session breaks as baked-in `NaN` samples. */
+const EMPTY_BOUNDARIES = [];
 /**
  * The `[min, max]` vertical extent of the **drawn** band — the lowest `lower`
  * and highest `upper` over samples where both edges are finite — or `null` if
@@ -37,11 +41,19 @@ export function bandExtent(band) {
  * filled envelope's break wants its own treatment (sharp edge vs. blurred),
  * still to be designed; for now a band always breaks honestly at a gap.
  *
+ * `boundaries` are trading-axis **session-break** instants (`<BandChart
+ * sessionBreaks>`): the envelope is split into per-session runs wherever one
+ * falls between two consecutive samples (see {@link sessionRuns}), each run its
+ * own closed subpath, so the fill ends at the last pre-close sample and re-starts
+ * at the first post-open one — a **scale** break, orthogonal to the NaN **data**
+ * gaps handled within each run. With no boundaries the output is identical to a
+ * single-pass draw. Mirrors `drawLine`'s treatment exactly.
+ *
  * `band.lower` (a `Float64Array`) is the datum iterable; every accessor reads by
  * index, so there's no per-point object allocation. `globalAlpha` carries the
  * opacity and is restored so it doesn't leak into later layers.
  */
-export function drawBand(ctx, band, xScale, yScale, style, curve = curveLinear, decimate = true) {
+export function drawBand(ctx, band, xScale, yScale, style, curve = curveLinear, boundaries = [], decimate = true) {
     const sourceCount = band.length; // pre-cull, pre-decimation (for draw stats)
     // Viewport culling (Phase 2): clip the envelope to the visible slice (+1 each
     // side) before filling, so a pan strokes O(visible). The solid fill has no
@@ -54,11 +66,13 @@ export function drawBand(ctx, band, xScale, yScale, style, curve = curveLinear,
     // pixels. Gated off a smoothing `curve` (which would distort the per-column
     // envelope) and `decimate === false`; `decimateBand` itself no-ops on a sparse
     // envelope or a domainless test scale, so this stays byte-identical there.
+    // The session-break instants ride along so a column never straddles a break
+    // and the decimated envelope carries the breaks as baked-in NaN samples.
     let decimated = false;
     if (decimate !== false && curve === curveLinear) {
         const k = typeof decimate === 'object' ? decimate.threshold : undefined;
         const before = band;
-        band = decimateBand(band, xScale, ctx, k);
+        band = decimateBand(band, xScale, ctx, k, boundaries);
         decimated = band !== before;
     }
     // An edge with no position on the y scale becomes an ordinary NaN gap, so the
@@ -73,18 +87,32 @@ export function drawBand(ctx, band, xScale, yScale, style, curve = curveLinear,
     if (gapLower !== band.lower || gapUpper !== band.upper) {
         band = { ...band, lower: gapLower, upper: gapUpper };
     }
-    const gen = d3area()
-        .defined((_, i) => Number.isFinite(band.lower[i]) && Number.isFinite(band.upper[i]))
-        .x((_, i) => xScale(band.x[i]))
-        .y0((_, i) => yScale(band.lower[i]))
-        .y1((_, i) => yScale(band.upper[i]))
-        .curve(curve)
-        .context(ctx);
+    // Split into independent index runs at each session break; no boundary inside
+    // the data ⇒ one run over the whole envelope (the hot path — no slicing, so the
+    // draw is byte-identical to the pre-boundary single pass). When the band was
+    // decimated, `decimateBand` already baked the breaks in as NaN samples aligned
+    // to the break instants, so re-cutting here would mis-attribute the boundary
+    // samples — pass `[]` and let the baked-in breaks split the sessions.
+    const runs = sessionRuns(band.x, band.length, decimated ? EMPTY_BOUNDARIES : boundaries);
+    const singleRun = runs.length === 1;
     ctx.save();
     ctx.fillStyle = style.fill;
     ctx.globalAlpha = style.opacity;
+    // One path across every run. Each run's generator opens with its own moveTo
+    // (and closes its own polygon), so a run boundary is a clean pen-up — the
+    // session break — and a single fill covers them all.
     ctx.beginPath();
-    gen(band.lower);
+    for (const [s, e] of runs) {
+        const gen = d3area()
+            .defined((_, j) => Number.isFinite(band.lower[s + j]) &&
+            Number.isFinite(band.upper[s + j]))
+            .x((_, j) => xScale(band.x[s + j]))
+            .y0((_, j) => yScale(band.lower[s + j]))
+            .y1((_, j) => yScale(band.upper[s + j]))
+            .curve(curve)
+            .context(ctx);
+        gen(singleRun ? band.lower : band.lower.subarray(s, e));
+    }
     ctx.fill();
     ctx.restore();
     return { sourceCount, drawnCount: band.length, decimated };

package/dist/decimate.d.ts

@@ -224,8 +224,17 @@ export declare function m4Polyline(edges: Float64Array, mn: Float64Array, mx: Fl
  * `upper` are finite **together** per sample (the paired-percentile shape bands
  * are built from); a column where only one edge has finite samples would bin a
  * band segment that no single sample carried.
+ *
+ * `boundaries` are trading-axis session-break instants (`<BandChart
+ * sessionBreaks>`), handled exactly as {@link decimateM4} does for a line: each
+ * in-domain instant is unioned into the bucket edges so no column merges two
+ * sessions' envelopes across the discontinuity, **and** a `NaN` sample is
+ * emitted at the instant so the fill ends at the close and re-starts at the
+ * open — otherwise the closing and opening columns would sit as adjacent finite
+ * samples and the envelope would flow straight across the collapsed gap. The
+ * caller's `sessionRuns` then sees the break baked in and passes no boundaries.
  */
-export declare function decimateBand(band: BandSeries, xScale: Scale, ctx: CanvasRenderingContext2D, k?: number): BandSeries;
+export declare function decimateBand(band: BandSeries, xScale: Scale, ctx: CanvasRenderingContext2D, k?: number, boundaries?: readonly number[]): BandSeries;
 /**
  * Decimate an {@link OhlcSeries} to one **aggregate candle per device-pixel
  * column** — `open = first`, `high = max`, `low = min`, `close = last` over the

package/dist/decimate.js

@@ -400,8 +400,17 @@ export function m4Polyline(edges, mn, mx, first, last, W, breakAt = NO_BREAKS) {
  * `upper` are finite **together** per sample (the paired-percentile shape bands
  * are built from); a column where only one edge has finite samples would bin a
  * band segment that no single sample carried.
+ *
+ * `boundaries` are trading-axis session-break instants (`<BandChart
+ * sessionBreaks>`), handled exactly as {@link decimateM4} does for a line: each
+ * in-domain instant is unioned into the bucket edges so no column merges two
+ * sessions' envelopes across the discontinuity, **and** a `NaN` sample is
+ * emitted at the instant so the fill ends at the close and re-starts at the
+ * open — otherwise the closing and opening columns would sit as adjacent finite
+ * samples and the envelope would flow straight across the collapsed gap. The
+ * caller's `sessionRuns` then sees the break baked in and passes no boundaries.
  */
-export function decimateBand(band, xScale, ctx, k = 2) {
+export function decimateBand(band, xScale, ctx, k = 2, boundaries = []) {
     if (!shouldDecimateCount(band.length, ctx, k))
         return band;
     const dom = scaleDomain(xScale);
@@ -412,18 +421,50 @@ export function decimateBand(band, xScale, ctx, k = 2) {
     if (invert === null || plotWidthCss === null)
         return band;
     const W = deviceBucketCount(ctx);
-    const edges = pixelEdges(invert, plotWidthCss, W);
+    const pixels = pixelEdges(invert, plotWidthCss, W);
+    // Session-break instants inside the visible domain — unioned into the edges
+    // (so a column never straddles a break) AND marked as explicit break samples.
+    // `mergeGapEdges` keeps their exact values, so the set matches the edges.
+    const breaks = boundaries.length > 0
+        ? boundaries.filter((b) => b > dom[0] && b < dom[1])
+        : [];
+    const edges = breaks.length > 0 ? mergeGapEdges(pixels, breaks, dom[0], dom[1]) : pixels;
+    const buckets = edges.length - 1;
     const lowerMin = new Float64Column(band.lower, band.length).binBy(band.x, edges, 'min');
     const upperMax = new Float64Column(band.upper, band.length).binBy(band.x, edges, 'max');
-    const x = new Float64Array(W);
-    const lower = new Float64Array(W);
-    const upper = new Float64Array(W);
-    for (let b = 0; b < W; b += 1) {
-        x[b] = (edges[b] + edges[b + 1]) / 2; // column centre
-        lower[b] = lowerMin[b]; // NaN on an empty column → the fill break
-        upper[b] = upperMax[b];
+    const breakAt = breaks.length > 0 ? new Set(breaks) : null;
+    // One sample per column + one NaN break slot per session break. `breaks` are
+    // strictly inside the domain and `mergeGapEdges` keeps every one, so each
+    // lands on some `edges[b]` with `b > 0` and the arrays fill exactly; the
+    // subarray trim below is a guard against a provider instant that sorts ahead
+    // of the first pixel edge under float rounding, not an expected path.
+    const cap = buckets + (breakAt === null ? 0 : breakAt.size);
+    const x = new Float64Array(cap);
+    const lower = new Float64Array(cap);
+    const upper = new Float64Array(cap);
+    let n = 0;
+    for (let b = 0; b < buckets; b += 1) {
+        // Explicit session break: this column opens a new session → end the fill
+        // first. A NaN on both edges is the band's own gap signal (`.defined`).
+        if (breakAt !== null && b > 0 && breakAt.has(edges[b])) {
+            x[n] = edges[b];
+            lower[n] = NaN;
+            upper[n] = NaN;
+            n += 1;
+        }
+        x[n] = (edges[b] + edges[b + 1]) / 2; // column centre
+        lower[n] = lowerMin[b]; // NaN on an empty column → the fill break
+        upper[n] = upperMax[b];
+        n += 1;
     }
-    return { x, lower, upper, length: W };
+    return n === cap
+        ? { x, lower, upper, length: n }
+        : {
+            x: x.subarray(0, n),
+            lower: lower.subarray(0, n),
+            upper: upper.subarray(0, n),
+            length: n,
+        };
 }
 /**
  * Decimate an {@link OhlcSeries} to one **aggregate candle per device-pixel

package/dist/tradingAxis.fixture.d.ts

@@ -50,6 +50,25 @@ export declare function ticks(sessions: Session[], stepMs: number): TimeSeries<t
  *  pen-up. (Plain {@link ticks} walks continuously across sessions, so close ≈
  *  next open and the break is invisible — this is the fixture that shows it.) */
 export declare function gappingTicks(sessions: Session[], stepMs: number): TimeSeries<typeof tickSchema>;
+export declare const envelopeSchema: readonly [{
+    readonly name: "time";
+    readonly kind: "time";
+}, {
+    readonly name: "price";
+    readonly kind: "number";
+}, {
+    readonly name: "lo";
+    readonly kind: "number";
+}, {
+    readonly name: "hi";
+    readonly kind: "number";
+}];
+/** {@link gappingTicks} plus a `lo` / `hi` envelope around the price (a slowly
+ *  breathing spread), so a `<BandChart>` on the trading axis shows the same
+ *  overnight jump the line does: connected, the fill runs a near-vertical sliver
+ *  from one session's close to the next open; with `sessionBreaks` it ends at
+ *  the close and re-starts at the open. */
+export declare function gappingEnvelope(sessions: Session[], stepMs: number): TimeSeries<typeof envelopeSchema>;
 export declare const OHLC: {
     readonly open: {
         readonly from: "price";

package/dist/tradingAxis.fixture.js

@@ -195,6 +195,30 @@ export function gappingTicks(sessions, stepMs) {
     });
     return new TimeSeries({ name: 'ticks', schema: tickSchema, rows });
 }
+export const envelopeSchema = [
+    { name: 'time', kind: 'time' },
+    { name: 'price', kind: 'number' },
+    { name: 'lo', kind: 'number' },
+    { name: 'hi', kind: 'number' },
+];
+/** {@link gappingTicks} plus a `lo` / `hi` envelope around the price (a slowly
+ *  breathing spread), so a `<BandChart>` on the trading axis shows the same
+ *  overnight jump the line does: connected, the fill runs a near-vertical sliver
+ *  from one session's close to the next open; with `sessionBreaks` it ends at
+ *  the close and re-starts at the open. */
+export function gappingEnvelope(sessions, stepMs) {
+    const rows = [];
+    let i = 0;
+    sessions.forEach((s, si) => {
+        const base = 100 + si * 6; // each session gaps ~6 above the last
+        for (let t = s.open; t < s.close; t += stepMs, i++) {
+            const price = base + 4 * Math.sin(i / 18) + 1.5 * Math.sin(i / 3.5);
+            const spread = 1.5 + 0.8 * Math.sin(i / 40);
+            rows.push([t, price, price - spread, price + spread]);
+        }
+    });
+    return new TimeSeries({ name: 'envelope', schema: envelopeSchema, rows });
+}
 export const OHLC = {
     open: { from: 'price', using: 'first' },
     high: { from: 'price', using: 'max' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.69.0",
+  "version": "0.70.0",
   "private": false,
   "description": "Canvas-rendered, streaming-first React time-series charts for pond-ts: line, area, band, bar, scatter, box, candlestick, with cursors, selection and annotations",
   "keywords": [
@@ -62,8 +62,8 @@
     "perf": "PERF_BENCH=1 playwright test perf.spec.ts --workers=1"
   },
   "peerDependencies": {
-    "@pond-ts/react": "^0.69.0",
-    "pond-ts": "^0.69.0",
+    "@pond-ts/react": "^0.70.0",
+    "pond-ts": "^0.70.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {