@pond-ts/charts 0.44.0 → 0.45.0

package/CHANGELOG.md

@@ -8,7 +8,9 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 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/pjm17971/pond-ts/compare/v0.44.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.45.0...HEAD
+[0.45.0]: https://github.com/pjm17971/pond-ts/compare/v0.44.1...v0.45.0
+[0.44.1]: https://github.com/pjm17971/pond-ts/compare/v0.44.0...v0.44.1
 [0.44.0]: https://github.com/pjm17971/pond-ts/compare/v0.43.0...v0.44.0
 [0.43.0]: https://github.com/pjm17971/pond-ts/compare/v0.42.0...v0.43.0
 [0.42.0]: https://github.com/pjm17971/pond-ts/compare/v0.41.0...v0.42.0
@@ -42,6 +44,120 @@ and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.45.0] — 2026-07-14
+
+### Added
+
+- **charts:** the time axis now walks a **logical tick ladder** — clock/calendar
+  units (1s…30s, 1m…30m, 1H…12H, day / week / month / quarter / year), picking
+  the finest grain that fits the width-derived cap — and renders **two-tier labels**:
+  a first row at the tick grain (`14:00`, `Feb 02`, `Feb`, `2026`) plus a
+  **boundary row** carrying the coarser context the first row omits (the date
+  under clock ticks, the year under day/week/month ticks — never a unit the
+  first row already shows), shown once under
+  the first tick of each new period. Hour anchors are generated in **live**
+  trading time, so none lands in a collapsed gap, an early close, or a lunch
+  break. `TradingTimeScale` gains `tickBoundaries(count)`; a cramped leading
+  partial-period anchor (the `"Jun 23Jul 07"` pile-up) is dropped. Systematic
+  story matrix under `Charts/TimeAxisTicks`.
+- **financial:** the rest of the first study batch — `rollingStdev`,
+  `rollingMin`, `rollingMax`, `rollingPercentile` (linear interpolation),
+  `zScore` (rolling), `envelope` (MA ± percent, `maType` sma/ema), and
+  `percentChange` (n-bar rate of change). Same shape as the others — `column` /
+  `output` (or `prefix`) on every one, bar-count periods, length-preserving
+  warm-up — and each has a fluent method (`bars.zScore({ period: 20 })`) and a
+  **pandas oracle** case (values cross-validated bar-for-bar). This completes the
+  #449 first batch.
+- **financial:** opt-in **fluent studies** via `import '@pond-ts/financial/fluent'`
+  — mounts `sma` / `ema` / `bollinger` as chainable `TimeSeries` methods so
+  composition reads like the core operators beside it:
+  `bars.sma({ period: 20 }).ema({ period: 12 }).bollinger({ period: 20 })`.
+  Opt-in by import (the default entry leaves `TimeSeries` untouched, so a
+  non-financial series never sees `.sma()`); the methods are exactly the
+  standalone functions bound to `this`, fully typed (each appends its column to
+  the schema). Same prototype-augmentation pattern core uses for column methods.
+- **financial:** `@pond-ts/financial` gains its first **studies** — `sma`, `ema`,
+  and `bollinger` (Bollinger Bands®) — pure functions that append a column (or a
+  `${prefix}Middle/Upper/Lower` family) to a bar series. Every study takes a
+  `column` source (default `'close'`) and an `output` name, so a study runs over
+  any numeric column including another study's output; periods are **bar counts**
+  (on core's count window, gap-correct); warm-up rows are `undefined`
+  (length-preserving). Plus the `OhlcvColumns` contract + `DEFAULT_OHLCV`. (Core
+  `AppendColumn` is now exported so study return types name their appended
+  column.)
+- **core:** `smooth(col, 'ema', …)` gains the financial **`span`** rate
+  convention (`α = 2/(span+1)`, e.g. `{ span: 12 }` for a 12-period EMA) as an
+  alternative to `alpha` (exactly one required), and a length-preserving
+  **`minSamples`** warm-up that emits `undefined` for the first `N` present
+  values while **keeping the row count** — mirroring `rolling`'s `minSamples`,
+  the one warm-up convention studies use so a smoothed line aligns on its
+  source's time axis. (The existing `warmup` option is unchanged — it still
+  *drops* the head rows; `minSamples` is the length-preserving counterpart.)
+- **core:** `TimeSeries.rolling` accepts a **count-based** window —
+  `rolling({ count: N }, mapping, opts?)` reduces the last / next / centered
+  `N` _rows_ (bars) by position instead of a time span. Unlike a duration
+  window, an N-bar window stays correct across session gaps (weekends,
+  overnight) where `N` bars do not equal `N × barSize` of time — the load-
+  bearing primitive for financial N-bar studies (SMA-20, Bollinger-20, rolling
+  stdev). Honours `alignment` and `minSamples` exactly like a duration window
+  (`minSamples: N` gives the conventional first-`N-1`-rows-`undefined` warmup);
+  per-row output only (not supported with a sequence). Same amortized-O(1)-per-
+  row sweep as the duration path.
+- **charts:** `<LineChart sessionBreaks>` breaks the line at each trading-axis
+  discontinuity (a session / day / lunch close→open) instead of connecting the
+  prior close straight to the next open across the collapsed gap. For intraday
+  data on a `discontinuities` / `calendar` axis this gives the terminal look —
+  the line ends at the close and re-starts at the open, so one session's price
+  doesn't visually flow into the next. It's a **scale** break (driven by the
+  axis's collapsed gaps), orthogonal to `gaps` (a **data** break, a NaN run) —
+  set both independently. Default `false`; a no-op on a continuous axis or a
+  provider without `boundaries`. New `Charts/TradingTimeAxis/SessionBreaks`
+  story (connected vs broken) + `sessionRuns` / `gappingTicks` helpers.
+
+### Changed
+
+- **charts:** a **plain continuous time axis** now runs the same ladder as a
+  trading-calendar axis (via an internal gap-free identity provider) instead of
+  d3's multi-scale default — so a year of daily data ticks cleanly on month
+  starts (`Jul Aug … Jun` + the year underneath) rather than mixed
+  `"Jun 23" / "Sep" / "Dec"` labels, and its tick count is now width-derived
+  like the trading axis's. Month/quarter-grain anchor labels are now bare
+  months (`Feb`, was `Feb 02`) with the year on the boundary row;
+  `coarsenCalendar`'s finest granularity is renamed `'session'` → `'day'`.
+
+### Fixed
+
+- **core:** `TimeSeries.withColumn` now appends an **optional** column
+  (`required: false`) rather than a required one. It already accepted
+  `(number | undefined)[]`, but marking the column required meant a later
+  strict-intake rebuild (`smooth`, any row reconstruction) threw on the gaps —
+  so a column with a warm-up (a rolling study fed into an EMA, e.g.
+  `ema(sma(bars, …), …)`) crashed. The appended column's type is now
+  `number | undefined`, matching `smooth`'s optional append. (`OptionalNumberColumn`
+  is exported for the widened return type.)
+
+## [0.44.1] — 2026-07-13
+
+A `@pond-ts/charts` patch: fixes trading-time axis tick density. `pond-ts`,
+`@pond-ts/react`, `@pond-ts/fit`, and `@pond-ts/financial` carry no code
+changes — republished in lock-step; their `^0.44.0` peer ranges already
+admit this patch.
+
+### Fixed
+
+- **charts:** trading-time axis tick density now derives from plot width
+  instead of a fixed count of 5. The trading scale's tick `count` caps how many
+  calendar buckets `coarsenCalendar` may keep, so the fixed count coarsened any
+  ≳6-month daily view to quarter or year grain — a 1-year daily chart on a
+  ~900px plot showed 2 ticks; it now lands on month grain (~12). Continuous
+  (non-trading) time and value axes keep the fixed default, unchanged. The
+  count is shared through the container frame (`xTickCount`), so axis labels,
+  x gridlines, session dividers, and the cursor-time formatter all derive from
+  the same instants — previously the label formatter anchored at the scale's
+  internal default (10) while ticks used 5, which is why sparse year-grain
+  ticks were labelled with dates (`Jun 22`) instead of years. (Tidal friction
+  report, charts 0.44.)
+
 ## [0.44.0] — 2026-07-11
 
 The **value-axis charts** release: cross-sectional data (a volatility smile keyed

package/dist/ChartContainer.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
-import { scaleLinear, scaleTime } from 'd3-scale';
-import { scaleTradingTime, } from './tradingTimeScale.js';
+import { scaleLinear } from 'd3-scale';
+import { identityProvider, scaleTradingTime, } from './tradingTimeScale.js';
 import { scaleBand } from './bandScale.js';
 import { Sequence } from 'pond-ts';
 import { ContainerContext, } from './context.js';
@@ -11,9 +11,18 @@ import { resolveCursorX, DEFAULT_CURSOR_MODE } from './tracker.js';
 import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
 import { TimeAxis } from './TimeAxis.js';
 import { defaultTheme } from './theme.js';
-/** Time-axis tick count — matches `<TimeAxis>` so the cursor-time formatter is
- *  calibrated as the time-axis labels are. */
+/** Tick count for a **continuous** (non-trading) x axis — the `ticks(count)`
+ *  request `<TimeAxis>`, the x gridlines, and the cursor-time formatter share
+ *  (as the frame's `xTickCount`). */
 const TIME_TICK_COUNT = 5;
+/** Target px of plot width per tick on a **trading-time** axis. That scale's
+ *  `ticks(count)` treats `count` as a **cap on calendar buckets** (see
+ *  `coarsenCalendar` — it picks the finest grain that fits), so the count must
+ *  scale with the room the labels actually have: a fixed 5 coarsens any
+ *  ≳6-month daily view to year grain — 2 ticks on a 900px plot. ~65px fits a
+ *  `%b %d` anchor label at the default font plus breathing room, so a ~900px
+ *  year-long daily view lands on month grain. */
+const TRADING_TICK_PX = 65;
 /**
  * Normalize the `range` prop — a `[begin, end]` tuple or a `TimeRange` — to a
  * plain `[number, number]`, or `undefined` when omitted (→ auto-fit). The
@@ -323,6 +332,16 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         ? calendar.discontinuities(spacing ? { spacing } : undefined)
         : undefined, [resolvedKind, discontinuities, calendar, spacing]);
     const xDiscontinuities = resolvedKind === 'time' ? (discontinuities ?? calendarProvider) : undefined;
+    // 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).
+    // Time axis (trading or plain — both run the logical tick ladder):
+    // width-derived, since the ladder's `count` caps its calendar buckets rather
+    // than targeting a tick total; floored at 2 so a pre-layout zero width still
+    // requests a drawable tick set. Value/category axes keep the d3 target count.
+    const xTickCount = resolvedKind === 'time'
+        ? Math.max(2, Math.floor(plotWidth / TRADING_TICK_PX))
+        : TIME_TICK_COUNT;
     const { xScale, formatTime } = useMemo(() => {
         if (resolvedKind === 'category') {
             // Ordinal column-domain axis: a band scale over the category slots. The
@@ -339,24 +358,34 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
             const s = scaleLinear().domain([d0, d1]).range([0, plotWidth]);
             return {
                 xScale: s,
-                formatTime: resolveAxisFormat(s, TIME_TICK_COUNT, timeFormat),
+                formatTime: resolveAxisFormat(s, xTickCount, timeFormat),
             };
         }
         if (xDiscontinuities !== undefined) {
             // Trading-time axis: closed-market gaps collapse, time proportional within
             // 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)
                 .domain([d0, d1])
                 .range([0, plotWidth]);
             return {
                 xScale: s,
-                formatTime: resolveTimeFormat(s, TIME_TICK_COUNT, timeFormat),
+                formatTime: resolveTimeFormat(s, xTickCount, timeFormat),
             };
         }
-        const s = scaleTime().domain([d0, d1]).range([0, plotWidth]);
+        // Plain continuous time axis: the same trading-time scale over the
+        // gap-free identity provider, so it runs the same logical tick ladder
+        // (month starts over a year, clock-aligned hours over an afternoon) —
+        // 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())
+            .domain([d0, d1])
+            .range([0, plotWidth]);
         return {
             xScale: s,
-            formatTime: resolveTimeFormat(s, TIME_TICK_COUNT, timeFormat),
+            formatTime: resolveTimeFormat(s, xTickCount, timeFormat),
         };
     }, [
         resolvedKind,
@@ -366,6 +395,7 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         plotWidth,
         timeFormat,
         xDiscontinuities,
+        xTickCount,
     ]);
     // 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
@@ -478,6 +508,8 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         onHoverAnnotation,
         onEditAnnotation,
         formatTime,
+        xFormatCustom: timeFormat !== undefined,
+        xTickCount,
         registerTrackerSource,
         unregisterTrackerSource,
         registerSelectable,
@@ -531,6 +563,8 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         onHoverAnnotation,
         onEditAnnotation,
         formatTime,
+        timeFormat,
+        xTickCount,
         registerTrackerSource,
         unregisterTrackerSource,
         registerSelectable,

package/dist/Layers.js

@@ -7,10 +7,12 @@ import { resolveSelection } from './select.js';
 import { panRange, zoomRange, panRangeTrading, zoomRangeTrading, } from './viewport.js';
 import { flagChipStyle, flagChipX, axisPillX, axisPillStyle } from './chip.js';
 import { ContainerContext, LayersContext, RowContext, } from './context.js';
-/** Gridline tick count. **Must match the axis label counts** (`XAxis`
- *  `TICK_COUNT`, `ChartContainer` `TIME_TICK_COUNT`, `YAxis`) — the grid, the
- *  session dividers, and the axis labels are all derived from `ticks(count)`, so
- *  they only line up while the counts agree. Kept at 5 across all four. */
+/** **Y**-gridline tick count. **Must match the y-axis label counts** (`YAxis`
+ *  `TICK_COUNT`, `ChartRow` `AXIS_TICK_COUNT`) — horizontal gridlines and the y
+ *  labels are both derived from `ticks(count)`, so they only line up while the
+ *  counts agree; kept at 5 across all three. The **x** side instead reads the
+ *  container's shared `xTickCount` (as `<XAxis>` and `formatTime` do), which is
+ *  width-derived on a trading-time axis. */
 const GRID_TICKS = 5;
 /** Minimum px between session dividers — thins dense collapse points (e.g. a
  *  daily chart where every candle is a new session) so the axis never crowds. */
@@ -56,8 +58,10 @@ export function Layers({ children }) {
     const background = container.theme.background;
     const { grid: gridColor, gridDash } = container.theme.axis;
     const { layers, yScales, formats, defaultAxisId, tickValues, axisSides } = row;
-    // x geometry is shared and lives on the container (uniform across rows).
-    const { xScale, plotWidth } = container;
+    // x geometry is shared and lives on the container (uniform across rows), and
+    // so is the x tick count — vertical gridlines must sit under the `<XAxis>`
+    // labels, which pass the same `xTickCount` to the same scale.
+    const { xScale, plotWidth, xTickCount } = container;
     const draw = useCallback((ctx, w, h) => {
         if (background !== undefined) {
             ctx.fillStyle = background;
@@ -71,7 +75,7 @@ export function Layers({ children }) {
         const explicitY = tickValues.get(defaultAxisId);
         // A category axis draws no vertical gridlines — a line through each bar
         // centre reads as noise; the bars are the structure.
-        const xTickVals = container.xKind === 'category' ? [] : xScale.ticks(GRID_TICKS);
+        const xTickVals = container.xKind === 'category' ? [] : xScale.ticks(xTickCount);
         const xTicks = xTickVals.map((d) => xScale(+d));
         const yTicks = gridY
             ? (explicitY ?? gridY.ticks(GRID_TICKS)).map((t) => gridY(t))
@@ -104,6 +108,7 @@ export function Layers({ children }) {
         layers,
         yScales,
         xScale,
+        xTickCount,
         defaultAxisId,
         tickValues,
         background,

package/dist/LineChart.d.ts

@@ -49,6 +49,20 @@ export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      * `gap.connectorOpacity`.)
      */
     gaps?: GapMode;
+    /**
+     * Break the line 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 line
+     * connects the last pre-close point straight to the next open across the
+     * collapsed gap (the near-vertical connector). `true` ends the line at the
+     * close and re-starts it at the open — the intraday look, where a session's
+     * price shouldn't visually flow into the next.
+     *
+     * This is a **scale** break (driven by the axis's collapsed gaps), orthogonal
+     * to {@link gaps} (a **data** break, a NaN run) — set both independently. A
+     * no-op on a continuous axis (no provider) or a provider without `boundaries`.
+     */
+    sessionBreaks?: boolean;
     /**
      * @internal Declaration position among the `<Layers>` children, injected by
      * `Layers` so z-order follows JSX order. Do not set.
@@ -61,5 +75,5 @@ export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extend
  * (scaling against its `axis`), and renders nothing to the DOM — the row draws
  * it. The line breaks at gaps rather than spanning them.
  */
-export declare function LineChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, axis, curve, gaps, index, }: LineChartProps<S, VS>): null;
+export declare function LineChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, axis, curve, gaps, sessionBreaks, index, }: LineChartProps<S, VS>): null;
 //# sourceMappingURL=LineChart.d.ts.map

package/dist/LineChart.js

@@ -6,13 +6,16 @@ import { resolveCurve } from './curve.js';
 import { DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
 import { ContainerContext, LayersContext } from './context.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 line draw layer. Reads `column` from `series` into a {@link ChartSeries}
  * (columnar, gaps as NaN), registers itself into the enclosing {@link Layers}
  * (scaling against its `axis`), and renders nothing to the DOM — the row draws
  * it. The line breaks at gaps rather than spanning them.
  */
-export function LineChart({ series, column, as: semantic, axis, curve, gaps = DEFAULT_GAP_MODE, index = 0, }) {
+export function LineChart({ series, column, as: semantic, axis, curve, gaps = DEFAULT_GAP_MODE, sessionBreaks = false, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<LineChart> must be rendered inside a <ChartContainer>');
@@ -33,6 +36,17 @@ export function LineChart({ series, column, as: semantic, axis, curve, gaps = DE
     // Faintness of the inferred dashed connectors (dashed / step) — theme-level,
     // falling back to the shared default so a theme without it still renders faint.
     const gapConnectorOpacity = container.theme.gap?.connectorOpacity ?? DEFAULT_GAP_CONNECTOR_OPACITY;
+    // Trading-axis session breaks: the collapse instants inside this series' 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.
+    const sessionBreakInstants = useMemo(() => {
+        const provider = container.discontinuities;
+        if (!sessionBreaks || provider?.boundaries === undefined || cs.length < 2) {
+            return NO_BREAKS;
+        }
+        return provider.boundaries(cs.x[0], cs.x[cs.length - 1]);
+    }, [sessionBreaks, container.discontinuities, cs]);
     const entry = useMemo(() => ({
         layer: {
             yExtent: () => yExtent(cs),
@@ -67,7 +81,7 @@ export function LineChart({ series, column, as: semantic, axis, curve, gaps = DE
                     ? [{ x: e.begin(), value: v, color: style.color, label }]
                     : [];
             },
-            draw: (ctx, xScale, yScale) => drawLine(ctx, cs, xScale, yScale, style, curveFactory, gaps, gapConnectorOpacity),
+            draw: (ctx, xScale, yScale) => drawLine(ctx, cs, xScale, yScale, style, curveFactory, gaps, gapConnectorOpacity, sessionBreakInstants),
         },
         axisId: axis,
         index,
@@ -80,6 +94,7 @@ export function LineChart({ series, column, as: semantic, axis, curve, gaps = DE
         curveFactory,
         gaps,
         gapConnectorOpacity,
+        sessionBreakInstants,
         axis,
         index,
     ]);

package/dist/XAxis.js

@@ -7,7 +7,8 @@ import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
 const TICK_STRIP = 22;
 /** Extra height reserved for an axis `label` line. */
 const LABEL_STRIP = 16;
-const TICK_COUNT = 5;
+/** Extra height reserved for the boundary (second) label row. */
+const BOUNDARY_STRIP = 15;
 /**
  * Thin + truncate a **category** axis's labels so a dense axis stays legible: keep
  * every `stride`-th label (so a kept label has room), and ellipsize one that still
@@ -53,7 +54,10 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     if (container === null) {
         throw new Error('<XAxis> must be rendered inside a <ChartContainer>');
     }
-    const { xScale, plotWidth, leftGutter, theme, formatTime, xKind } = container;
+    // `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;
     // The crosshair's x-time pill: when the container cursor is `'crosshair'` and a
     // cursor is live in-bounds, pin the hovered time to this axis (covering the
     // tick behind it), matching the on-axis y value pills the rows draw. Gated on
@@ -76,8 +80,8 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     format === undefined || xKind === 'category'
         ? formatTime
         : xKind === 'time'
-            ? resolveTimeFormat(xScale, TICK_COUNT, format)
-            : resolveAxisFormat(xScale, TICK_COUNT, format);
+            ? resolveTimeFormat(xScale, xTickCount, format)
+            : resolveAxisFormat(xScale, xTickCount, format);
     // Marker annotations that opted into an axis indicator (`<Marker indicator>`)
     // pin their **time** to this shared x-axis — a pill at `at`, in the annotation
     // colour, reading like a tick. An indicator always shows the axis coordinate
@@ -124,11 +128,25 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
         markerLanes.set(t.id, lane);
     }
     const maxPillLane = Math.max(0, pillLaneEnds.length - 1);
+    // The boundary (second) label row — the coarser calendar unit the first-row
+    // label omits (the year under day / week / month ticks, the date under
+    // clock ticks), placed under the first tick of each new
+    // period. Only a ladder-driven time scale supplies it; explicit `ticks`, an
+    // explicit axis `format`, and a container-level `timeFormat` all opt out (a
+    // custom format owns the whole label, and custom ticks have no grain).
+    const boundaryOf = xKind === 'time' &&
+        customTicks === undefined &&
+        format === undefined &&
+        !container.xFormatCustom &&
+        'tickBoundaries' in xScale
+        ? xScale.tickBoundaries(xTickCount)
+        : undefined;
     const rawTicks = customTicks
         ? customTicks.map((t) => ({ x: xScale(t.at), label: t.label }))
-        : xScale.ticks(TICK_COUNT).map((d) => ({
+        : xScale.ticks(xTickCount).map((d) => ({
             x: xScale(d),
             label: fmt(+d),
+            boundary: boundaryOf?.(+d),
         }));
     // A category axis ticks once per category; thin + truncate its labels when they
     // crowd (an explicit `customTicks` axis keeps its labels verbatim).
@@ -141,7 +159,10 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     const pillOffset = align === 'right' ? 2 : 6;
     // Per-lane vertical step for stacked pills; grow the strip to fit the stack.
     const PILL_LANE_H = theme.font.size + 6;
+    // Any boundary label in view grows the strip by one row (like pill lanes do).
+    const hasBoundary = placed.some((t) => t.boundary !== undefined);
     const stripHeight = (height ?? TICK_STRIP + (label ? LABEL_STRIP : 0)) +
+        (hasBoundary ? BOUNDARY_STRIP : 0) +
         maxPillLane * PILL_LANE_H;
     return (_jsxs("div", { style: {
             position: 'relative',
@@ -183,7 +204,14 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                                 [onTop ? 'bottom' : 'top']: `${labelOffset}px`,
                                 transform: labelTransform,
                                 whiteSpace: 'nowrap',
-                            }, children: t.label })] }, `${t.x}-${i}`));
+                            }, children: t.label }), t.boundary !== undefined && (_jsx("div", { "data-boundary-label": true, style: {
+                                position: 'absolute',
+                                left: `${labelLeft}px`,
+                                [onTop ? 'bottom' : 'top']: `${labelOffset + theme.font.size + 3}px`,
+                                transform: labelTransform,
+                                whiteSpace: 'nowrap',
+                                opacity: 0.75,
+                            }, children: t.boundary }))] }, `${t.x}-${i}`));
             }), label !== undefined && (_jsx("div", { style: {
                     position: 'absolute',
                     left: 0,

package/dist/context.d.ts

@@ -151,6 +151,21 @@ export interface ContainerFrame {
     /** Format an epoch-ms instant the same way the time axis labels its ticks —
      *  shared by `<TimeAxis>` and the cursor-time readout. */
     readonly formatTime: (epochMs: number) => string;
+    /** 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. */
+    readonly xFormatCustom: boolean;
+    /**
+     * The shared **x-side tick count** — the `count` every x-side `ticks()` /
+     * `tickFormat()` call passes (`<XAxis>` labels, the canvas x gridlines and
+     * session dividers, {@link formatTime}), so labels, grid, and dividers all
+     * derive from the same instants. A fixed default on a continuous axis;
+     * **width-derived on a trading-time axis**, where the count caps how many
+     * calendar buckets `coarsenCalendar` may keep — a fixed small count would
+     * coarsen any long daily view to year grain (2 ticks) no matter how wide
+     * the plot is.
+     */
+    readonly xTickCount: number;
     /**
      * Register a draw layer as a tracker source so the container can fan in every
      * series' value at the cursor for `onTrackerChanged`. Keyed by the layer's

package/dist/format.d.ts

@@ -42,8 +42,10 @@ interface TimeTickable {
  * - a **function** → used as-is (called with epoch ms);
  * - a **specifier string** → `scale.tickFormat(count, specifier)` (one format for
  *   every value), wrapped to take epoch ms;
- * - **`undefined`** → `scale.tickFormat()` — d3's **multi-scale** time format (the
- *   time axis's default; no `count` so it matches `<TimeAxis>` exactly).
+ * - **`undefined`** → `scale.tickFormat(count)` — the scale's default. On a d3
+ *   `scaleTime` that is the **multi-scale** time format (which ignores `count`);
+ *   a trading-time scale picks its **anchor grain** from `count`, so passing the
+ *   axis's count here is what keeps the labels on the same grain as the ticks.
  *
  * The cursor time is epoch ms, so the resolved formatter wraps the d3 `Date`
  * formatter in `new Date(ms)`.

package/dist/format.js

@@ -32,8 +32,10 @@ export function resolveAxisFormat(scale, count, format) {
  * - a **function** → used as-is (called with epoch ms);
  * - a **specifier string** → `scale.tickFormat(count, specifier)` (one format for
  *   every value), wrapped to take epoch ms;
- * - **`undefined`** → `scale.tickFormat()` — d3's **multi-scale** time format (the
- *   time axis's default; no `count` so it matches `<TimeAxis>` exactly).
+ * - **`undefined`** → `scale.tickFormat(count)` — the scale's default. On a d3
+ *   `scaleTime` that is the **multi-scale** time format (which ignores `count`);
+ *   a trading-time scale picks its **anchor grain** from `count`, so passing the
+ *   axis's count here is what keeps the labels on the same grain as the ticks.
  *
  * The cursor time is epoch ms, so the resolved formatter wraps the d3 `Date`
  * formatter in `new Date(ms)`.
@@ -41,7 +43,9 @@ export function resolveAxisFormat(scale, count, format) {
 export function resolveTimeFormat(scale, count, format) {
     if (typeof format === 'function')
         return format;
-    const tf = format !== undefined ? scale.tickFormat(count, format) : scale.tickFormat();
+    const tf = format !== undefined
+        ? scale.tickFormat(count, format)
+        : scale.tickFormat(count);
     return (ms) => tf(new Date(ms));
 }
 //# sourceMappingURL=format.js.map

package/dist/line.d.ts

@@ -41,6 +41,30 @@ export declare function yExtent(cs: ChartSeries): [number, number] | null;
  * The generator writes path ops to `ctx`; we bracket with `beginPath`/`stroke`.
  * `cs.y` (a `Float64Array`) is the datum iterable — `y` reads the value, `x`
  * reads `cs.x[i]` by index, so there's no per-point object allocation.
+ *
+ * **`boundaries`** (default none) are discontinuity instants — a trading-axis
+ * session/day/lunch close→open where the line should *break* even though a data
+ * point sits on each side (see {@link sessionRuns}). Each run between boundaries
+ * draws as its own subpath, so the line ends at the last pre-boundary point and
+ * re-starts at the first post-boundary one — a **scale** break, orthogonal to
+ * the NaN **data** gaps (`gaps`) handled within each run. With no boundaries the
+ * output is identical to a single-pass draw.
+ */
+export declare function drawLine(ctx: CanvasRenderingContext2D, cs: ChartSeries, xScale: Scale, yScale: Scale, style: LineStyle, curve?: CurveFactory, gaps?: GapMode, gapConnectorOpacity?: number, boundaries?: readonly number[]): void;
+/**
+ * Split a sorted columnar x-axis into contiguous index runs `[start, endEx)`,
+ * cutting wherever a `boundaries` instant falls in `(x[i-1], x[i]]` — i.e. a
+ * discontinuity (a trading session / day / lunch close→open) sits between two
+ * consecutive points. A point that lands exactly on a boundary starts the new
+ * run (the open). No boundary inside the data (or an empty list) ⇒ a single run
+ * over the whole series. This is what turns `<LineChart sessionBreaks>` into a
+ * per-session polyline. Pure + O(N).
+ *
+ * The sweep relies on **ascending** boundaries; the `DiscontinuityProvider`
+ * contract doesn't guarantee order, so an unsorted list is sorted defensively
+ * (a copy, so the caller's array isn't mutated) rather than silently dropping a
+ * break. The list is tiny — one entry per session boundary — so the sort is
+ * negligible next to the row sweep.
  */
-export declare function drawLine(ctx: CanvasRenderingContext2D, cs: ChartSeries, xScale: Scale, yScale: Scale, style: LineStyle, curve?: CurveFactory, gaps?: GapMode, gapConnectorOpacity?: number): void;
+export declare function sessionRuns(x: Float64Array, length: number, boundaries: readonly number[]): Array<[number, number]>;
 //# sourceMappingURL=line.d.ts.map