@pond-ts/charts 0.67.0 → 0.69.0

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.67.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.69.0...HEAD
+[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
 [0.66.0]: https://github.com/pond-ts/pond/compare/v0.65.0...v0.66.0
 [0.65.0]: https://github.com/pond-ts/pond/compare/v0.64.0...v0.65.0
@@ -70,6 +72,112 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.69.0] — 2026-09-13
+
+### Added
+
+- **`<ChartContainer timeZone>` — the time axis in any IANA zone
+  ([PND-TZAXIS]).** Day / week / month ticks land on that zone's midnights,
+  Mondays and month starts; labels, the stacked date bands, the hierarchical
+  grid, session dividers and every cursor / marker / annotation readout read
+  in it. **Omitted ⇒ the viewer's zone**, exactly as before. The d3 specifier
+  strings on `timeFormat` / `cursorFormat` are unchanged; `%Z` / `%z` now read
+  the zone's abbreviation / offset. Sub-day ticks align to the zone's wall
+  clock, so a 6 h grain reads 00 / 06 / 12 / 18 across a DST jump instead of
+  drifting by an hour until the next midnight. The resolved zone is on the
+  chart context as `timeZone`. Built on core's `TimeZone` ([PND-TZCAL]), so a
+  `Sequence.calendar('day', { timeZone })` bucket edge and the tick that
+  labels it are one instant — pinned by a cross-package test.
+- **`<XAxis timeZone>` — a second strip in another zone.** Two time axes
+  over one shared mapping, each ticking and labelling (and pilling) in its
+  own zone: `<XAxis side="top" timeZone="America/New_York" />` above a
+  UTC container's own strip below. Backed by
+  `TradingTimeScale.withTimeZone(zone)` / `.timeZone()` and an optional
+  `DiscontinuityProvider.withTimeZone` (the identity provider re-derives its
+  day anchors; a trading calendar's session opens are zone-independent).
+- **`TradingCalendarLike.timeZone?`** — a calendar that carries its exchange
+  zone supplies the axis default (`calendar={cal}` renders in exchange time
+  wherever it is viewed); an explicit `timeZone` prop wins.
+- `scaleTradingTime(provider, { timeZone })` and
+  `identityProvider({ timeZone })` take the zone directly for consumers
+  building the scale themselves; `identityProvider`, `TradingCalendarLike`
+  and `ScaleTimeZoneOptions` are now exported. Internally the tick ladder
+  runs on a `TickCalendar` seam whose local implementation is the previous
+  `Date` arithmetic verbatim — the default path is unchanged.
+- **`TradingCalendar.timeZone` ([PND-TZFIN]).** `@pond-ts/financial`'s
+  calendar keeps the zone its sessions were resolved in — `fromRules` carries
+  `rules.timeZone`, `fromSessions(list, { timeZone })` takes it — so
+  `<ChartContainer calendar={cal}>` renders the axis in exchange time with no
+  further wiring.
+- `@pond-ts/charts` now depends on `d3-time-format` directly (it was already
+  a transitive dependency via `d3-scale`).
+- **`TimeZone` — the zone-calendar primitive ([PND-TZCAL]).** `pond-ts`
+  exports `TimeZone.of(id)` (interned; also `TimeZone.UTC`,
+  `TimeZone.local()`) with `startOf(unit, t)`, `next(unit, t)`, `parts(t)`,
+  `instant(parts, { disambiguation })`, `offsetAt(t)` and
+  `abbreviation(t, { locale })`. Temporal underneath, but each zone caches its
+  offset transitions as it discovers them, so steady-state calls are integer
+  arithmetic: `startOf('day')` went from ~24 µs to ~23 ns per call, and a
+  three-year hourly series aggregated to `America/New_York` days from 38 ms
+  to 0.5 ms. `Sequence.calendar`, `TimeRange.fromCalendar` and
+  `Interval.fromCalendar` now bucket through it (no behaviour change; pinned
+  against Temporal on eight zones including southern-hemisphere DST, a
+  30-minute DST shift, a +05:30 zone, a day with no midnight and Samoa's
+  skipped day). This is the primitive the charts' time axis will place and
+  label ticks with, so a bucket edge and the tick that labels it are one
+  instant. First task of the time-zone plan
+  (`docs/plans/PND_TIMEZONE_PLAN.md`).
+- **`CalendarUnit` gains `'quarter'` and `'year'`** for
+  `Sequence.calendar`, `TimeRange.fromCalendar` and `Interval.fromCalendar`.
+
+### Changed
+
+- **`Sequence.calendar` validates its inputs at construction.** An unknown
+  unit (`'hour'`) or zone (`'Nowhere'`) now throws `RangeError` immediately;
+  before, an unknown unit silently produced wrong buckets (the two unit
+  dispatchers fell through to different defaults — the 2026-06 audit's §6
+  finding) and an unknown zone failed only on first `bounded()`.
+
+### Fixed
+
+- **`pond-ts`: two type-level corners of [PND-PARTCOL] (0.68.0) found by the Codex pass on #724.** (1) On a broad `TimeSeries<SeriesSchema>` with a _literal_ partition column, the injected `'first'` could not look up a kind and typed the column as `undefined`; `WithPartitionColumns` now takes the schema and leaves the mapping alone when the schema is broad, so the result type is exactly 0.67's. (2) `By` had no variance pin, so `PartitionedTimeSeries<S, K, 'host'>` accepted a view partitioned by `region` (and an untyped view could be narrowed to any column); a phantom contravariant member now rejects both while a specialised view still assigns to the legacy `PartitionedTimeSeries<S>` shape. Type tests cover both plus the `K`-survives-`smooth`/`baseline` claim. No runtime change.
+- **Docs said a wall-clock string without `parse.timeZone` throws. It never
+  did** ([PND-TZDOCS]) — it is read as UTC, silently. `creating.mdx`, the
+  agent guide (`AGENTS.md`) and the decision table now say so and describe
+  how the shift shows up. The agent guide also gains the one time-zone rule:
+  pass the same `timeZone` to `Sequence.calendar` and `<ChartContainer>`.
+  The aggregation page cross-links `Sequence.calendar` for weekly / monthly
+  bars (issue #358 item 1, supersedes #359). The finance gallery's off-chart
+  readout takes the calendar's zone instead of hard-coding New York; the
+  Niño 3.4 heat map's year grain uses `Sequence.calendar('year')`.
+
+## [0.68.0] — 2026-09-13
+
+### Added
+
+- **Agent adoption tranche ([PND-ADOPTMETA] / [PND-ADOPTLINKS] /
+  [PND-LLMSTXT] / [PND-AGENTGUIDE] / [PND-SKILL] / [PND-CONTEXT7]).** Every
+  package now declares `keywords`, `homepage` and `bugs` (there were none —
+  `pond-ts` ranked last in `npm search "time series"`). Every tarball ships an
+  `AGENTS.md` (source `docs/agents/USING_POND.md`): which package for which
+  task, the core idioms, the mistakes agents make. `pond-ts.org/llms.txt` is
+  now llmstxt.org-shaped (titles + descriptions per page, one section per
+  docs area, `Optional` links to `API.md` / the agent guide) with per-area
+  `llms-<area>.txt` dumps so a single fetch stays small. A Claude Code plugin
+  marketplace lives in the repo (`/plugin marketplace add pond-ts/pond`) with
+  `pond-ts`, `pond-charts` and `pond-financial` skills. `context7.json`
+  configures docs-MCP indexing. Plan and baseline:
+  `docs/plans/PND_ADOPTION_PLAN.md`.
+
+- **Agent guide + skill hardened by the first cold-start run** (`docs/agents/USING_POND.md`, shipped as `AGENTS.md`; `plugins/pond-ts/skills/pond-ts`): install with `@latest` and the `.d.ts` paths that carry signatures. Cold-start harness committed at `docs/adoption/cold-start/`.
+
+### Fixed
+
+- **`pond-ts`: the partition column is now in the static type after a partitioned `aggregate` / `rolling` ([PND-PARTCOL]).** `series.partitionBy('host').aggregate(seq, { p95: { from: 'ms', using: 'p95' } }).collect()` always carried `host` at runtime (auto-injected as `'first'`) but the result type omitted it, so `e.get('host')` failed to compile — every fresh agent in the cold-start experiment hit or pre-empted it. `PartitionedTimeSeries` gains a third type parameter `By` (the partition column names, captured by `partitionBy`, default `never`), and the two schema-replacing operators are typed over `WithPartitionColumns<Mapping, By>` — the user's keys win, kind and all; missing partition columns are added as `'first'`. Composite partitions and typed `groups` carry through; `smooth` / `baseline` under `partitionBy` now also keep `K`. Additive: untyped views are unchanged.
+- `@pond-ts/charts` and `@pond-ts/fit` READMEs (rendered on npm) and eight
+  docs pages pointed at the retired `pjm17971.github.io/pond-ts` site /
+  `pjm17971/pond-ts` repo; now `pond-ts.org` / `pond-ts/pond`.
+
 ## [0.67.0] — 2026-09-11
 
 ### Added

package/README.md

@@ -1,5 +1,9 @@
 # @pond-ts/charts
 
+[![npm](https://img.shields.io/npm/v/@pond-ts/charts?label=%40pond-ts%2Fcharts)](https://www.npmjs.com/package/@pond-ts/charts)
+[![CI](https://github.com/pond-ts/pond/actions/workflows/ci.yml/badge.svg)](https://github.com/pond-ts/pond/actions/workflows/ci.yml)
+[![docs](https://img.shields.io/badge/docs-pond--ts.org-1f6feb)](https://pond-ts.org/docs/charts/)
+
 **React charts for [pond-ts](https://www.npmjs.com/package/pond-ts) time series.**
 
 A composable charting layer built directly on pond-ts series: a canvas data
@@ -62,8 +66,8 @@ instead of time, with no axis-type prop.
 ## Documentation
 
 Guides, the component reference, and live examples live at
-**<https://pjm17971.github.io/pond-ts/>**. Source and issues:
-[github.com/pjm17971/pond-ts](https://github.com/pjm17971/pond-ts).
+**<https://pond-ts.org/docs/charts/>**. Source and issues:
+[github.com/pond-ts/pond](https://github.com/pond-ts/pond).
 
 ## License
 

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/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/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

package/dist/tickLadder.d.ts

@@ -1,3 +1,4 @@
+import { TimeZone } from 'pond-ts';
 import type { DiscontinuityProvider } from './tradingTimeScale.js';
 /**
  * The logical tick ladder — grain selection for a time axis. Ticks sit on real
@@ -34,16 +35,62 @@ export type TickGranularity = 'second1' | 'second5' | 'second15' | 'second30' |
 export type TimeGrain = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
 /** Collapse a {@link TickGranularity} to its coarse {@link TimeGrain} unit. */
 export declare function coarseUnitOf(g: TickGranularity): TimeGrain;
+/** The calendar operations the tick ladder needs. Months are `1…12`. */
+export interface TickCalendar {
+    /** Midnight of the day containing `t`. */
+    startOfDay(t: number): number;
+    /** Midnight of the day after the one containing `t`. */
+    nextDay(t: number): number;
+    /** Midnight of the Monday of the week containing `t`. */
+    startOfWeek(t: number): number;
+    /** The civil date of `t`. */
+    parts(t: number): {
+        year: number;
+        month: number;
+        day: number;
+    };
+    /** Midnight of the first of `month` (`1…12`; `13` carries into the next year, `0` into the previous). */
+    monthStart(year: number, month: number): number;
+    /** Days in `month` of `year`. */
+    daysInMonth(year: number, month: number): number;
+    /**
+     * The first clock-aligned `stepMs` multiple at or after `t`, counted from
+     * `t`'s own midnight — 00:00 / 03:00 / 06:00 … for a 3 h step. The local
+     * calendar steps **fixed milliseconds** from midnight (so on a DST day the
+     * later anchors drift off the wall clock by the shift, until the next
+     * midnight re-anchors — the pre-seam behaviour, kept); a zoned calendar
+     * aligns to the **wall clock**, so 6 h anchors read 00 / 06 / 12 / 18 on
+     * both sides of the jump, with one short or long gap at the transition.
+     * Always `>= t`.
+     */
+    nextAligned(t: number, stepMs: number): number;
+    /**
+     * The anchor after an aligned anchor `t` at `stepMs`. The local calendar
+     * steps `t + stepMs` — fixed elapsed milliseconds, the pre-seam loop
+     * verbatim, which is what keeps a session that spans a DST midnight (a
+     * futures 18:00 → 17:00 session) ticking exactly as it did. A zoned
+     * calendar re-aligns through {@link nextAligned} so the anchors stay on
+     * the wall clock across the jump.
+     */
+    nextAnchor(t: number, stepMs: number): number;
+}
+/** The runtime-local calendar — `Date`'s local accessors, exactly as the
+ *  ladder computed before it had a zone. The default {@link TickCalendar}. */
+export declare const localTickCalendar: TickCalendar;
+/** A {@link TickCalendar} for an IANA zone, on core's `TimeZone`. */
+export declare function zonedTickCalendar(zone: TimeZone): TickCalendar;
+/** Resolve an optional IANA id to the calendar the ladder should use: the
+ *  runtime-local calendar when `timeZone` is undefined, else the zone's. */
+export declare function tickCalendarFor(timeZone: string | undefined): TickCalendar;
 /**
- * The local-time bucket key for `t` at grain `g` — two instants in the same
- * day / week / month / quarter / year share a key. Local time (not UTC) so it
- * agrees with the local `scaleTime` label formatter; the exchange's own time
- * zone is unknown to the scale (the deferred refinement), and a session open
- * sits well inside its local day, so runtime-local grouping matches the
- * exchange day in every ordinary case. Hour grains are never bucketed (each
- * anchor is its own tick), so they key by identity.
+ * The calendar bucket key for `t` at grain `g` — two instants in the same
+ * day / week / month / quarter / year share a key. Computed in `cal`'s zone
+ * (runtime-local by default) so it agrees with the label formatter for the
+ * same zone; a trading axis passes its exchange zone so the grain buckets by
+ * the exchange day rather than the viewer's. Hour grains are never bucketed
+ * (each anchor is its own tick), so they key by identity.
  */
-export declare function bucketKey(t: number, g: TickGranularity): number;
+export declare function bucketKey(t: number, g: TickGranularity, cal?: TickCalendar): number;
 /**
  * Thin an ascending run of **session opens** down to about `count` axis ticks.
  * Picks the finest rung: every session → **per-month uniform session stride**
@@ -82,7 +129,7 @@ export declare function bucketKey(t: number, g: TickGranularity): number;
  * This is the day-and-coarser half of the ladder; {@link buildTicks} adds the
  * sub-day rungs.
  */
-export declare function coarsenCalendar(opens: readonly number[], count: number, spanDays?: number, provider?: DiscontinuityProvider): {
+export declare function coarsenCalendar(opens: readonly number[], count: number, spanDays?: number, provider?: DiscontinuityProvider, cal?: TickCalendar): {
     ticks: number[];
     granularity: TickGranularity;
 };
@@ -105,7 +152,7 @@ export declare function coarsenCalendar(opens: readonly number[], count: number,
  * the live-span estimate first (like {@link buildTicks}) and skipped when they
  * add no anchor beyond the session opens themselves (that is the day level).
  */
-export declare function buildGridLevels(provider: DiscontinuityProvider, opens: readonly number[], domainEnd: number, cap: number): Array<{
+export declare function buildGridLevels(provider: DiscontinuityProvider, opens: readonly number[], domainEnd: number, cap: number, cal?: TickCalendar): Array<{
     granularity: TickGranularity;
     values: number[];
 }>;
@@ -130,7 +177,7 @@ export declare function nominalStepMs(g: TickGranularity): number;
  * themselves fit — a year of daily sessions never wastes time generating hour
  * anchors.
  */
-export declare function buildTicks(provider: DiscontinuityProvider, opens: readonly number[], domainEnd: number, cap: number): {
+export declare function buildTicks(provider: DiscontinuityProvider, opens: readonly number[], domainEnd: number, cap: number, cal?: TickCalendar): {
     ticks: number[];
     granularity: TickGranularity;
 };
@@ -181,14 +228,13 @@ export declare function bandFormatFor(g: TickGranularity): string;
  * same-shade day-bands side by side on a gappy calendar. A rare, cosmetic
  * consequence of keeping the shade fixed to the date rather than the slot.
  */
-export declare function bandShaded(t: number, g: TickGranularity): boolean;
-/** The local-time start of the band grain `g` containing `t` (the band's left
- *  edge): local midnight, month start, or Jan 1. Through the Date ctor so DST
- *  and month/year overflow normalize correctly. */
-export declare function bandStartOf(t: number, g: TickGranularity): number;
+export declare function bandShaded(t: number, g: TickGranularity, cal?: TickCalendar): boolean;
+/** The start of the band grain `g` containing `t` (the band's left edge) in
+ *  `cal`'s zone: midnight, month start, or Jan 1. */
+export declare function bandStartOf(t: number, g: TickGranularity, cal?: TickCalendar): number;
 /** The start of the band grain `g` **after** the one containing `t` — the next
- *  local midnight / month start / Jan 1. */
-export declare function bandNext(t: number, g: TickGranularity): number;
+ *  midnight / month start / Jan 1 in `cal`'s zone. */
+export declare function bandNext(t: number, g: TickGranularity, cal?: TickCalendar): number;
 /**
  * Which of `ticks` (at grain `granularity`) carry a boundary label: every tick
  * whose boundary-grain bucket differs from the previous tick's — i.e. a
@@ -199,7 +245,7 @@ export declare function bandNext(t: number, g: TickGranularity): number;
  * tick-to-tick on a live sliding window). Empty when the grain has no
  * boundary row (year grain).
  */
-export declare function boundaryTicks(ticks: readonly number[], granularity: TickGranularity, domainStart?: number): number[];
+export declare function boundaryTicks(ticks: readonly number[], granularity: TickGranularity, domainStart?: number, cal?: TickCalendar): number[];
 /**
  * The terse **base** (non-promoted) flat label format for grain `g` — the label
  * a tick carries when it opens no coarser period: the clock time for a sub-day
@@ -228,5 +274,5 @@ export declare function flatBaseFormatFor(g: TickGranularity): string;
  * opening at May 1 midnight reads `May 16 …`, not `1 16 …`). Without
  * `domainStart` the first tick is never promoted.
  */
-export declare function flatFormats(ticks: readonly number[], granularity: TickGranularity, domainStart?: number): string[];
+export declare function flatFormats(ticks: readonly number[], granularity: TickGranularity, domainStart?: number, cal?: TickCalendar): string[];
 //# sourceMappingURL=tickLadder.d.ts.map