@pond-ts/charts 0.68.0 → 0.70.0

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/ChartContainer.d.ts

@@ -192,6 +192,29 @@ export interface ChartContainerProps {
      * calendar reference (build it once, not inline in JSX).
      */
     calendar?: TradingCalendarLike;
+    /**
+     * The IANA **time zone the time axis renders in** — ticks land on that
+     * zone's midnights / Mondays / month starts, labels, grid, date bands,
+     * session dividers and every cursor / marker readout read in it.
+     * **Omitted ⇒ the viewer's own zone** (the runtime's), which is what every
+     * chart did before this prop existed; `'UTC'` or any id `Intl` knows
+     * (`'Europe/Berlin'`, `'Australia/Sydney'`, …) names one. A trading
+     * {@link calendar} that carries a `timeZone` (a `@pond-ts/financial`
+     * `TradingCalendar.fromRules`) supplies the default, so a NYSE chart reads
+     * New York time wherever it is viewed; an explicit prop still wins. The
+     * calendar's zone is used even when a low-level {@link discontinuities}
+     * provider overrides its gap topology — the calendar still says which
+     * exchange this is.
+     *
+     * Pair it with the aggregate that produced the data — the same primitive
+     * (`TimeZone`) places these ticks and cuts `Sequence.calendar` buckets, so
+     * `Sequence.calendar('day', { timeZone })` and `<ChartContainer timeZone>`
+     * given the same zone put a bucket edge and its tick on one instant.
+     * Function formatters (`timeFormat`, `cursorFormat`) still receive epoch ms;
+     * read the resolved zone from the chart context. An unknown id throws
+     * `RangeError`. Only affects a **time** axis.
+     */
+    timeZone?: string | undefined;
     /**
      * The trading axis **metric**, when a {@link calendar} is supplied
      * (trading-calendar RFC Q7). `'proportional'` (default) keeps time

package/dist/ChartContainer.js

@@ -4,7 +4,7 @@ import { scaleLinear, scaleLog, scaleSymlog } from 'd3-scale';
 import { identityProvider, scaleTradingTime, } from './tradingTimeScale.js';
 import { scaleBand } from './bandScale.js';
 import { scaleElapsed } from './elapsed.js';
-import { Sequence } from 'pond-ts';
+import { Sequence, TimeZone } from 'pond-ts';
 import { ContainerContext, CursorContext, } from './context.js';
 import { LegacyCursor, legacyCursorWarning, presetNameFor, warnOnDuplicateGestureOwners, } from './cursors.js';
 import { effectiveSelectorEntries, resolveControlledHovered, resolveControlledSelected, selectorEntryEqual, warnInertClick, } from './selectors.js';
@@ -198,7 +198,7 @@ function AutoSizeContainer(props) {
  *  pass; a chart legitimately gated this long is not painting anyway. */
 const ZERO_SIZE_WARNING_MS = 600;
 /** {@link ChartContainer} with its width resolved to a concrete pixel number. */
-function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidth, bandAlign = 'start', width, height, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, onDrawStats, panZoom = false, axisPanZoom = false, bounds, onTimeRangeChange, minDuration = 1, cursor: cursorProp, cursorSequence: cursorSequenceProp, onRegionSelect, regionSelectModifier, cursorTime: cursorTimeProp, crosshairSnap: crosshairSnapProp, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat: cursorFormatProp, origin, theme, discontinuities, calendar, spacing, xScale: xScaleKind = 'linear', grid = true, sessionDividers = 'none', children, }) {
+function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidth, bandAlign = 'start', width, height, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, onDrawStats, panZoom = false, axisPanZoom = false, bounds, onTimeRangeChange, minDuration = 1, cursor: cursorProp, cursorSequence: cursorSequenceProp, onRegionSelect, regionSelectModifier, cursorTime: cursorTimeProp, crosshairSnap: crosshairSnapProp, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat: cursorFormatProp, origin, theme, discontinuities, calendar, timeZone: timeZoneProp, spacing, xScale: xScaleKind = 'linear', grid = true, sessionDividers = 'none', children, }) {
     // ── Legacy cursor props (deprecated) ───────────────────────────────────────
     // The string surface keeps working for one minor: the resolved mode is
     // synthesized into the equivalent mounted preset below (`<LegacyCursor>`),
@@ -967,6 +967,13 @@ function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidt
         ? calendar.discontinuities(spacing ? { spacing } : undefined)
         : undefined, [resolvedKind, discontinuities, calendar, spacing]);
     const xDiscontinuities = resolvedKind === 'time' ? (discontinuities ?? calendarProvider) : undefined;
+    // The axis zone: the explicit prop, else the calendar's exchange zone, else
+    // runtime-local (`undefined`). Canonicalised through `TimeZone.of` so a bad
+    // id fails here, once, with its name, and so `'utc'` and `'UTC'` are one key.
+    const timeZone = useMemo(() => {
+        const id = timeZoneProp ?? calendar?.timeZone;
+        return id === undefined ? undefined : TimeZone.of(id).id;
+    }, [timeZoneProp, calendar]);
     // The shared x-side tick count — labels, x gridlines, session dividers, and
     // `formatTime` all pass this one value, so they derive from the same instants
     // (the alignment previously held by three hardcoded constants agreeing).
@@ -1147,7 +1154,7 @@ function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidt
             // sessions. Same tickFormat surface as scaleTime, so the readout is shared.
             // `xTickCount` reaches `tickFormat` too: the trading scale picks its anchor
             // grain from the count, so labels sit on the exact instants the ticks do.
-            const s = scaleTradingTime(xDiscontinuities)
+            const s = scaleTradingTime(xDiscontinuities, { timeZone })
                 .domain([d0, d1])
                 .range([0, plotWidth]);
             if (elapsedOrigin !== undefined)
@@ -1164,7 +1171,7 @@ function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidt
         // never d3's mixed multi-scale default. Interactions stay on continuous
         // time math: the frame's `discontinuities` remains undefined, and identity
         // distance/offset are plain subtraction/addition anyway.
-        const s = scaleTradingTime(identityProvider())
+        const s = scaleTradingTime(identityProvider({ timeZone }), { timeZone })
             .domain([d0, d1])
             .range([0, plotWidth]);
         if (elapsedOrigin !== undefined)
@@ -1187,6 +1194,7 @@ function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidt
         elapsedOrigin,
         xDiscontinuities,
         xTickCount,
+        timeZone,
     ]);
     // The crosshair pixel (see resolveCursorX). A stored hoverX is a *plot* pixel;
     // if plotWidth changes mid-hover (a gutter reserving, or a width change) it's
@@ -1361,6 +1369,8 @@ function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidt
         onEditAnnotation,
         formatTime,
         formatReadout,
+        timeZone,
+        timeFormat,
         xFormatCustom: timeFormat !== undefined,
         xReadoutCustom: cursorFormat !== undefined,
         xTickCount,
@@ -1445,6 +1455,7 @@ function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidt
         onEditAnnotation,
         formatTime,
         formatReadout,
+        timeZone,
         timeFormat,
         cursorFormat,
         xTickCount,

package/dist/XAxis.d.ts

@@ -90,6 +90,18 @@ export interface XAxisProps {
      *   measured fit (thin + middle-ellipsize) is what prevents collisions.
      */
     align?: 'auto' | 'center' | 'right';
+    /**
+     * Render **this strip** in an IANA zone other than the container's — the
+     * second axis of a two-zone pair (`<XAxis />` in the container's zone below
+     * the plot, `<XAxis side="top" timeZone="Asia/Tokyo" />` above it). Same
+     * pixel mapping, its own calendar: day ticks on *this* zone's midnights,
+     * labels, the date bands and this strip's cursor / marker pills reading in
+     * it. Time axis only; ignored under a `transform` or explicit `ticks`. A
+     * container `cursorFormat` still wins for the pill (it is its own channel);
+     * a container `timeFormat` string is re-resolved in this zone. Omit to
+     * follow the container's `timeZone` (or the viewer's zone).
+     */
+    timeZone?: string | undefined;
     /**
      * How a **time** axis lays out its date context (ignored on value / category
      * axes, and whenever a custom `format`, `transform`, or explicit `ticks`
@@ -140,6 +152,6 @@ export interface XAxisProps {
  * plot's own drag, including `bounds` / `minDuration` and the trading calendar.
  * A category axis has no continuous domain and stays inert.
  */
-export declare function XAxis({ format, label, side, height, ticks: customTicks, transform, color, align, dateStyle, onMouseEvent, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function XAxis({ format, label, side, height, ticks: customTicks, transform, color, align, dateStyle, timeZone, onMouseEvent, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
 export {};
 //# sourceMappingURL=XAxis.d.ts.map

package/dist/XAxis.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Fragment, useContext, useRef } from 'react';
+import { Fragment, useContext, useMemo, useRef } from 'react';
 import { scaleLinear } from 'd3-scale';
+import { TimeZone } from 'pond-ts';
 import { derivedTicks } from './derivedTicks.js';
 import { ContainerContext, CursorContext, } from './context.js';
 import { tickValues } from './yticks.js';
@@ -166,7 +167,7 @@ export function thinCategoryLabels(ticks, slot, plotWidth, fontSize, fontFamily)
  * plot's own drag, including `bounds` / `minDuration` and the trading calendar.
  * A category axis has no continuous domain and stays inert.
  */
-export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, transform, color, align = 'center', dateStyle = 'flat', onMouseEvent, } = {}) {
+export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, transform, color, align = 'center', dateStyle = 'flat', timeZone, onMouseEvent, } = {}) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<XAxis> must be rendered inside a <ChartContainer>');
@@ -175,7 +176,38 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     // `xTickCount` is the container's shared x-side count — the same value the x
     // gridlines and `formatTime` use, so labels and grid stay on the same instants
     // (width-derived on a trading-time axis).
-    const { xScale, plotWidth, leftGutter, theme, formatTime, xKind, xTickCount, } = container;
+    const { xScale: containerScale, plotWidth, leftGutter, theme, formatTime: containerFormatTime, xKind, xTickCount, } = container;
+    // A per-strip zone: the container's shared scale re-derived with its
+    // calendar in `timeZone` — identical pixel mapping, so every `xScale(v)`
+    // below lands where the plot puts it, but ticks / labels / bands / this
+    // strip's pills come from this zone's ladder. Canonicalised (and validated)
+    // so an unknown id throws by name and `'utc'` / `'UTC'` memoize as one.
+    const zonedScale = useMemo(() => {
+        if (timeZone === undefined ||
+            xKind !== 'time' ||
+            !('withTimeZone' in containerScale)) {
+            return undefined;
+        }
+        const id = TimeZone.of(timeZone).id;
+        const s = containerScale;
+        return s.timeZone() === id ? undefined : s.withTimeZone(id);
+    }, [containerScale, timeZone, xKind]);
+    const xScale = zonedScale ?? containerScale;
+    // The label formatter this strip falls back to when no explicit `format`
+    // shapes it. The container's `formatTime` was resolved in the container's
+    // zone; a zoned strip needs the same channel in its own — the grain-aware
+    // default, or the container's `timeFormat` specifier re-resolved (a
+    // function `timeFormat` receives epoch ms and is used verbatim either way).
+    const formatTime = useMemo(() => {
+        if (zonedScale === undefined)
+            return containerFormatTime;
+        const custom = container.timeFormat;
+        if (typeof custom === 'function')
+            return custom;
+        return custom === undefined
+            ? zonedScale.readoutFormat(xTickCount)
+            : resolveTimeFormat(zonedScale, xTickCount, custom);
+    }, [zonedScale, containerFormatTime, container.timeFormat, xTickCount]);
     // The cursor's x-axis slot: did the mounted cursor in effect register one
     // (`renderXAxis` — the crosshair's time pill)? While hovering, that is the
     // **hovered row's** effective cursor — so a per-row override reaches this

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/context.d.ts

@@ -270,6 +270,20 @@ export interface ContainerFrame {
      * tick labels) without moving them.
      */
     readonly formatReadout?: ((value: number) => string) | undefined;
+    /**
+     * The IANA zone the time axis renders in — the container's resolved
+     * `timeZone` (explicit prop, else the calendar's), canonical id; `undefined`
+     * when the axis is in the runtime's local zone. For a consumer's own
+     * formatter (`timeFormat` / `cursorFormat` functions receive epoch ms) to
+     * read the same zone the ticks do.
+     */
+    readonly timeZone: string | undefined;
+    /**
+     * The container's raw `timeFormat` prop, for a strip that must re-resolve it
+     * in another zone (`<XAxis timeZone>`): a specifier string is re-resolved
+     * against that strip's zoned scale, a function is used verbatim.
+     */
+    readonly timeFormat: AxisFormat | undefined;
     /** Whether an explicit container `timeFormat` shaped {@link formatTime}. The
      *  x axis suppresses its boundary (second) label row when it's set — a
      *  custom format owns the whole label, so the ladder mustn't second-line it. */

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/index.d.ts

@@ -68,8 +68,8 @@ export type { ChartLegend, LegendRow, LegendItem } from './useChartLegend.js';
 export { useChartFrame } from './useChartFrame.js';
 export type { ChartFrame, ChartFrameRow, ChartBands, ChartBand, } from './useChartFrame.js';
 export type { ChartXScale } from './context.js';
-export { scaleTradingTime } from './tradingTimeScale.js';
-export type { TradingTimeScale, DiscontinuityProvider, TimeGrain, } from './tradingTimeScale.js';
+export { scaleTradingTime, identityProvider } from './tradingTimeScale.js';
+export type { TradingTimeScale, DiscontinuityProvider, TradingCalendarLike, ScaleTimeZoneOptions, TimeGrain, } from './tradingTimeScale.js';
 export { scaleBand } from './bandScale.js';
 export type { ScaleBand } from './bandScale.js';
 export { Region, Baseline, Marker, Zone } from './annotations.js';

package/dist/index.js

@@ -58,7 +58,7 @@ export { useChartLegend } from './useChartLegend.js';
 // by mirroring the library's own gutter arithmetic — a duplicate that drifts
 // silently the moment the library changes how a gutter is sized.
 export { useChartFrame } from './useChartFrame.js';
-export { scaleTradingTime } from './tradingTimeScale.js';
+export { scaleTradingTime, identityProvider } from './tradingTimeScale.js';
 // The ordinal category (band) scale — the transpose view's "columns on x" axis.
 export { scaleBand } from './bandScale.js';
 // Annotations — user-authored marks in the turquoise register (distinct from the