@pond-ts/charts 0.46.0 → 0.48.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.46.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.48.0...HEAD
+[0.48.0]: https://github.com/pond-ts/pond/compare/v0.47.0...v0.48.0
+[0.47.0]: https://github.com/pond-ts/pond/compare/v0.46.0...v0.47.0
 [0.46.0]: https://github.com/pjm17971/pond-ts/compare/v0.45.0...v0.46.0
 [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
@@ -45,13 +47,138 @@ and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.48.0] — 2026-07-17
+
+### Added
+
+- **charts:** `<ChartContainer>` gains **`cursorFormat`** — an independent
+  format for the **cursor / marker readout** (the crosshair time pill, marker
+  axis indicators, annotation auto-labels), separate from the tick-label
+  `timeFormat` / `format`. Unlike `timeFormat` (which _owns the labels_ and so
+  opts the axis out of the `dateStyle` ladder by design), `cursorFormat` shapes
+  only the readout and **keeps the flat / stacked date style** — resolving the
+  "one knob, two concerns" bind where the only way to fix the pill was to give
+  up the styled axis. A d3 specifier **string** formats uniformly; a
+  **function** `(epochMs, { grain, defaultText }) => string` is handed the
+  axis's resolved coarse **`TimeGrain`** (`year` … `second`) and the
+  grain-aware default text, so it can branch on zoom and pass the default
+  through — no re-deriving the grain from the range. New public types
+  **`CursorFormat`** / **`TimeGrain`**; `TradingTimeScale` gains
+  `readoutFormat(count)` and `grain(count)`.
+
+### Fixed
+
+- **charts:** the cursor / marker time readout now formats at the axis's
+  **own grain** by default instead of d3's multi-scale default — a
+  day-or-coarser axis reads a **date** (`Sep 14, 2026`), a sub-day axis reads
+  date + clock. Fixes the 0.47.0 flat-axis regression where a daily bar at a
+  foreign-timezone midnight rendered as a bare time-of-day (`02 AM`) in the
+  crosshair pill (Tidal F-charts-7). Tick labels are unchanged.
+
+## [0.47.0] — 2026-07-17
+
+### Added
+
+- **charts:** `<ChartContainer>` gains **`grid`** (default `true`) and
+  **`sessionDividers`** (`'labeled' | 'all' | 'none'`, default `'none'`).
+  On a calendar (time) axis the vertical gridlines are the **full grain
+  populations** — every day / month / aligned clock instant in view, not just
+  the thinned instants the labels chose (the labels decorate the grid; they
+  don't define it). Each grain fades as a unit by its **calendar density**
+  (nominal gap-free spacing: full ≥ 15 px, gone ≤ 5 px, quadratic), so
+  zooming out dissolves the fine grain into the coarser one — a map-style
+  hierarchical grid with no pop when the label algorithm switches rung — and
+  collapsing weekends draws _fewer_ day lines at the _same_ strength, not
+  wider-spaced lines that jump to full opacity. Session dividers are opt-in
+  emphasis over that grid, and draw only at true collapse **seams** —
+  boundaries that removed time actually precedes, not every session roll
+  (`'all'` = every seam, the TradingView separator look, crowding lines
+  fading out; `'labeled'` = only seams the axis also labels) — so a
+  `grid={false}` plot is actually clean by default and a contiguous-sessions
+  calendar seams only where days were excised. `TradingTimeScale` gains
+  **`gridLevels(minGapPx)`** (the nested per-grain populations + nominal
+  spacing behind it). In `'all'` mode, crowding session-divider lines fade on
+  a quadratic ramp (full ≥ 28 px apart, gone ≤ 6 px) so zooming out dissolves
+  them to a clean plot rather than a permanent gray wash.
+- **charts:** `<TimeAxis>` / `<XAxis>` gain a **`dateStyle`** prop
+  (`'flat' | 'stacked'`). `'flat'` — the new default — lays the date context
+  out on a **single row** the TradingView way: each tick that opens a coarser
+  calendar period is relabelled **inline** to it (the month at a month turn,
+  the year at a year turn, the date at a day turn under an intraday grain),
+  every other tick a terse label (`5`, `Feb`, `14:00`). `'stacked'` is the
+  two-row layout: a terse top row (the grain's bare unit) over a segmented
+  **band** row of the next-coarser period — **day** bands under intraday
+  ticks, **month** bands under day ticks, **year** bands under month/quarter
+  ticks — each a left-aligned label with a divider at its turn, **zebra-shaded**
+  by the band's calendar parity (pan/zoom-stable). The turn tick up top is
+  emphasized and joins its divider as one continuous boundary line; the partial
+  left band pins its label at the plot edge. Themeable via **`theme.axis.band`**
+  (`fill` — the shaded cell, "could be a background color"; `divider`; `label`).
+  `TradingTimeScale` gains `flatFormat(count)` (the flat single-row lookup),
+  `baseFormat(count)` (the terse stacked top row), and `bands(count)` (the band
+  segments); non-tick instants — the cursor readout — still read a full
+  timestamp.
+  The **window edge is never ticked** unless it is a genuine grain anchor (a
+  true session open, or an instant exactly on the grain — a midnight at day
+  grain, a month start at month grain): a mid-period edge tick sat pinned at
+  x=0 relabelling itself as the window panned (a sticky `8` at half-spacing, a
+  `15:23` under an hour grain) — misleading, and not something TradingView
+  draws. The first real calendar anchor now leads the axis.
+
+### Changed
+
+- **Docs hosting.** The documentation site has moved from GitHub Pages
+  (`pjm17971.github.io/pond-ts`) to Cloudflare Pages under the custom domain
+  **<https://pond-ts.org>**. Storybook now deploys as its own project served at
+  `pond-ts.org/storybook/` (via a small routing Worker, `workers/router/`),
+  rather than nested into the docs build. Doc links in the README are repointed;
+  the deploy workflow keeps the same `v*`-tag gate. See `MIGRATION.md`.
+- **charts:** the time axis now renders the **flat** single-row date style by
+  default (previously the two-row stacked layout). Every time chart — trading
+  or plain continuous, auto-rendered or explicit `<TimeAxis>` — picks this up.
+  Pass `dateStyle="stacked"` to keep the old two-row look. (An explicit
+  `format` / container `timeFormat`, a `transform`, or explicit `ticks` opt out
+  of both styles as before.)
+- **charts:** the time-axis tick ladder's sub-month density now thins each
+  month in **session-index space** — the reverse-engineered TradingView
+  algorithm, validated label-for-label against its output on the 2026 NYSE
+  calendar. Marks sit an equal number of _bars_ apart, so on a collapsed
+  trading axis they are **evenly spaced in pixels**, with no weekend snapping:
+  a month opening on a weekend anchors on its first session. Two regimes per
+  month: at dense zooms, a **uniform anchored stride** (the month's first
+  session, then every k-th, truncated so the gap to the next month label
+  stays ≥ the stride — the slack lands at the month end); at coarse zooms
+  (≤ 3 marks per month, where a truncated stride would leave a hole of up to
+  ~2 strides before the month label and each ±1 stride change would crawl the
+  labels), a **balanced division** — mid-month, then thirds — whose marks
+  hold still across every zoom that maps to the same density. Month / year
+  starts stay pinned at every zoom; pans never reshuffle marks (indices are
+  queried per full calendar month, never per window); a stub live-edge month
+  earns proportionally fewer marks. Without a calendar provider the same
+  scheme runs in day-of-month space. Replaces the old day → weekly ~7×
+  density cliff; the separate Monday-anchored week grain was removed — the
+  session-stride band covers everything between every-session and month
+  grain.
+
+### Fixed
+
+- **charts:** a multi-session time axis near the tick cap can no longer come
+  back lopsided — with several sessions each gaining a phase tick while the
+  span estimate sat within a few ticks of the cap, clock-rung enumeration hit
+  its internal bail and the truncated tick array was returned, leaving the
+  final sessions with no ticks at all. The enumeration budget now covers the
+  estimate's per-session undercount (`cap + opens.length + slack`) so
+  enumeration completes, and a still-truncated result is rejected in favor of
+  a coarser rung instead of being returned. (Follow-up to the v0.46.0
+  sliding-window grain-stability fix, flagged in its release spot-check.)
+
 ## [0.46.0] — 2026-07-14
 
 ### Changed
 
 - **charts:** the boundary (second-row) axis label's **context** now pins to
   the plot's left edge instead of riding the first tick: it shows the period
-  the *domain start* is in, and a crossing label sliding toward the edge
+  the _domain start_ is in, and a crossing label sliding toward the edge
   pushes it off (the sticky-header behavior). On a live sliding window the
   old first-tick anchoring made `Jan 01` hop tick-to-tick as ticks scrolled
   out; pinned, it stays put until the period actually changes. Crossing
@@ -141,7 +268,7 @@ and type-level changes; patch bumps are strictly additive.
   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.)
+  _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

package/dist/ChartContainer.d.ts

@@ -3,7 +3,7 @@ import { type DiscontinuityProvider, type TradingCalendarLike } from './tradingT
 import { Sequence, BoundedSequence } from 'pond-ts';
 import type { TimeRange } from 'pond-ts';
 import { type AnnotationKind, type CreateSpec, type CursorMode, type SelectInfo, type TrackerInfo } from './context.js';
-import { type AxisFormat } from './format.js';
+import { type AxisFormat, type CursorFormat } from './format.js';
 import { type ChartTheme } from './theme.js';
 export interface ChartContainerProps {
     /**
@@ -29,8 +29,11 @@ export interface ChartContainerProps {
      * this prop's identity changes, so memoize it — `const disc = useMemo(() =>
      * calendar.discontinuities(), [calendar])` — rather than calling
      * `.discontinuities()` inline in JSX, which would rebuild every render.
+     *
+     * Accepts an explicit `undefined` (a `cond ? provider : undefined` toggle
+     * under `exactOptionalPropertyTypes`), same as omitting it.
      */
-    discontinuities?: DiscontinuityProvider;
+    discontinuities?: DiscontinuityProvider | undefined;
     /**
      * The **high-level** sugar for {@link discontinuities}: a trading calendar the
      * container derives the provider from itself (`calendar.discontinuities({
@@ -53,6 +56,31 @@ export interface ChartContainerProps {
      * carries its own metric).
      */
     spacing?: 'proportional' | 'uniform';
+    /**
+     * Draw the reference gridlines behind the data. On a calendar (time) axis
+     * the verticals are the **full grain populations** — every day / month /
+     * aligned clock instant in view, each grain fading by its calendar density
+     * — not just the labelled ticks (the labels decorate the grid; they don't
+     * define it). **Default `true`.** Set `false` for a clean backdrop —
+     * session dividers (below) are independent and still draw when enabled.
+     */
+    grid?: boolean;
+    /**
+     * Where to draw **session dividers** — the solid verticals at a trading
+     * calendar's collapse **seams**: boundaries that removed (closed-market)
+     * time actually precedes, not every session roll (only with a
+     * `discontinuities` / `calendar` provider). On a real exchange calendar
+     * every session open follows an overnight gap, so seams = session opens; a
+     * calendar of contiguous full-day sessions has seams only where days were
+     * excised (the weekend). **Default `'none'`** — the hierarchical grid
+     * already marks the calendar structure at every zoom, so dividers are
+     * opt-in emphasis: `'all'` draws one at *every* seam in view (the
+     * TradingView session-separator look, crowding lines fading out),
+     * `'labeled'` only at seams the axis also labels. Dividers are independent
+     * of {@link grid} — `'all'` + `grid={false}` is the
+     * separators-on-a-clean-plot look.
+     */
+    sessionDividers?: 'labeled' | 'all' | 'none';
     /** Total width in CSS pixels (plot + axis gutters). */
     width: number;
     /** Vertical space between rows in CSS pixels (not under the axis). Default 0. */
@@ -262,12 +290,33 @@ export interface ChartContainerProps {
      */
     snap?: boolean;
     /**
-     * Time-axis value formatting — a d3 time specifier string (e.g. `'%H:%M'`) or a
-     * `(epochMs) => string` function ({@link AxisFormat}); applies to both the time
-     * axis labels and the cursor-time readout. **Omitted ⇒ d3's multi-scale time
-     * format** (`12 PM`, `12:10`, …).
+     * Time-axis **label** formatting — a d3 time specifier string (e.g. `'%H:%M'`)
+     * or a `(epochMs) => string` function ({@link AxisFormat}). A custom format
+     * **owns the labels**, so it opts the axis out of the `dateStyle` ladder
+     * (flat / stacked) by design. **Omitted ⇒ the flat/stacked date style.** To
+     * shape only the cursor readout while keeping a date style, use
+     * {@link cursorFormat} instead. (For back-compat this also shapes the readout
+     * when `cursorFormat` is absent.)
      */
     timeFormat?: AxisFormat;
+    /**
+     * The **cursor / marker readout** format — the crosshair time pill, marker
+     * axis indicators, and annotation auto-labels — **independent of the tick
+     * labels**, so it does **not** disqualify the `dateStyle` ladder.
+     * **Omitted ⇒ a grain-aware default**: the readout formats at the axis's own
+     * granularity, so a day-or-coarser axis reads a **date** (never a
+     * time-of-day) and a sub-day axis reads date + clock — a daily bar at a
+     * foreign-tz midnight no longer renders as `02 AM`.
+     *
+     * A d3 time-specifier **string** formats uniformly at every zoom; a
+     * **function** `(epochMs, { grain, defaultText }) => string` receives the
+     * axis's resolved coarse {@link TimeGrain} and the grain-aware default text,
+     * so it can branch on the zoom level and pass `defaultText` through for
+     * grains it doesn't override (no re-deriving the grain from the range). See
+     * {@link CursorFormat}. This is the independent readout channel;
+     * {@link timeFormat} owns the labels.
+     */
+    cursorFormat?: CursorFormat;
     /** Visual theme for all rows; defaults to {@link defaultTheme}. */
     theme?: ChartTheme;
     children?: ReactNode;
@@ -281,5 +330,5 @@ export interface ChartContainerProps {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom, onTimeRangeChange, minDuration, cursor, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, theme, discontinuities, calendar, spacing, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom, onTimeRangeChange, minDuration, cursor, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, cursorFormat, theme, discontinuities, calendar, spacing, grid, sessionDividers, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartContainer.d.ts.map

package/dist/ChartContainer.js

@@ -43,7 +43,7 @@ function normalizeRange(range) {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, theme, discontinuities, calendar, spacing, children, }) {
+export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, selected, onSelect, hovered, onHover, panZoom = false, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat, theme, discontinuities, calendar, spacing, grid = true, sessionDividers = 'none', children, }) {
     // The explicit base domain from `range` (a tuple or a TimeRange). `undefined`
     // ⇒ auto-fit (resolved from the layers below). Pan/zoom seeds from it; `seed`
     // is the placeholder while auto-fitting.
@@ -361,6 +361,30 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
                 formatTime: resolveAxisFormat(s, xTickCount, timeFormat),
             };
         }
+        // The cursor / marker / annotation **readout** formatter. `cursorFormat`
+        // wins (the independent readout channel — it never disqualifies the date
+        // style); else a container `timeFormat` (back-compat: shapes the readout
+        // too, and already opts labels out of the ladder); else the scale's
+        // **grain-aware** default (a day-or-coarser axis reads a date, not a
+        // time-of-day — the F-charts-7 `02 AM` fix), never d3's multi-scale default.
+        const timeReadout = (s) => {
+            // A `cursorFormat` **function** gets the axis's resolved coarse grain and
+            // the grain-aware default text per instant, so it can branch on zoom and
+            // pass the default through. A **string** formats uniformly (d3 specifier).
+            if (typeof cursorFormat === 'function') {
+                const grain = s.grain(xTickCount);
+                const def = s.readoutFormat(xTickCount);
+                return (v) => cursorFormat(v, { grain, defaultText: def(v) });
+            }
+            if (cursorFormat !== undefined) {
+                return resolveTimeFormat(s, xTickCount, cursorFormat);
+            }
+            // No cursorFormat: a container timeFormat still shapes the readout
+            // (back-compat); else the scale's grain-aware default.
+            return timeFormat !== undefined
+                ? resolveTimeFormat(s, xTickCount, timeFormat)
+                : s.readoutFormat(xTickCount);
+        };
         if (xDiscontinuities !== undefined) {
             // Trading-time axis: closed-market gaps collapse, time proportional within
             // sessions. Same tickFormat surface as scaleTime, so the readout is shared.
@@ -369,10 +393,7 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
             const s = scaleTradingTime(xDiscontinuities)
                 .domain([d0, d1])
                 .range([0, plotWidth]);
-            return {
-                xScale: s,
-                formatTime: resolveTimeFormat(s, xTickCount, timeFormat),
-            };
+            return { xScale: s, formatTime: timeReadout(s) };
         }
         // Plain continuous time axis: the same trading-time scale over the
         // gap-free identity provider, so it runs the same logical tick ladder
@@ -383,10 +404,7 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         const s = scaleTradingTime(identityProvider())
             .domain([d0, d1])
             .range([0, plotWidth]);
-        return {
-            xScale: s,
-            formatTime: resolveTimeFormat(s, xTickCount, timeFormat),
-        };
+        return { xScale: s, formatTime: timeReadout(s) };
     }, [
         resolvedKind,
         categories,
@@ -394,6 +412,7 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         d1,
         plotWidth,
         timeFormat,
+        cursorFormat,
         xDiscontinuities,
         xTickCount,
     ]);
@@ -521,6 +540,8 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         xScale,
         xKind: resolvedKind,
         discontinuities: xDiscontinuities,
+        grid,
+        sessionDividers,
         panZoom,
         minDuration,
         applyRange,
@@ -576,6 +597,8 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         xScale,
         resolvedKind,
         xDiscontinuities,
+        grid,
+        sessionDividers,
         panZoom,
         minDuration,
         applyRange,

package/dist/Layers.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { Children, cloneElement, isValidElement, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { Canvas } from './Canvas.js';
-import { drawGrid, drawDividers, thinPixels } from './grid.js';
+import { drawGrid, drawDividers, dividerAlphas, thinPixels } from './grid.js';
 import { cursorParts, bandRect, regionSpan } from './tracker.js';
 import { resolveSelection } from './select.js';
 import { panRange, zoomRange, panRangeTrading, zoomRangeTrading, } from './viewport.js';
@@ -14,9 +14,31 @@ import { ContainerContext, LayersContext, RowContext, } from './context.js';
  *  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. */
+/** Minimum px between `'labeled'` session dividers — thins dense collapse
+ *  points (e.g. a daily chart where every candle is a new session) so the axis
+ *  never crowds. (`'all'` mode fades instead of thinning — see below.) */
 const MIN_DIVIDER_PX = 40;
+/** Calendar gridlines (one per day / month / aligned hour — the full grain
+ *  populations, `TradingTimeScale.gridLevels`) are full-strength while their
+ *  **nominal** spacing (`level.spacing` — calendar density, gap-free; NOT the
+ *  measured on-screen gaps, so hiding weekends doesn't brighten the grid) is
+ *  at least this — a day grain reaches full at a ~1.5-month window on a
+ *  default-width plot, in either mode. Dashed faint lines tolerate more
+ *  density than the solid session dividers, hence the tighter pair. */
+const GRID_LINE_FULL_PX = 15;
+/** …and fully faded once nominal spacing falls to this (the same quadratic
+ *  wash-aware ramp as the session lines — alpha `t²`, so total ink → 0).
+ *  Also the enumeration floor: a grain denser than this is skipped
+ *  outright. */
+const GRID_LINE_GONE_PX = 5;
+/** `'all'`-mode session lines are full-strength while spaced at least this
+ *  far apart (the ~1M-view session width on a default-width plot). */
+const SESSION_LINE_FULL_PX = 28;
+/** …and fully invisible once spacing falls to this — a smooth quadratic
+ *  falloff between the two, so nothing pops in/out as you pan/zoom (a hard
+ *  drop keyed to pixel clusters shifts phase with the window) and the plot
+ *  zooms out to *clean*, not to a gray wash (see `dividerAlphas`). */
+const SESSION_LINE_GONE_PX = 6;
 /** Wheel-zoom sensitivity: `factor = exp(deltaY * k)` (one ~100px notch ≈ ±15%). */
 const ZOOM_SENSITIVITY = 0.0015;
 /** Pointer slop (px): a drag must exceed this before it pans, and a click within
@@ -76,27 +98,107 @@ export function Layers({ children }) {
         // 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(xTickCount);
-        const xTicks = xTickVals.map((d) => xScale(+d));
-        const yTicks = gridY
-            ? (explicitY ?? gridY.ticks(GRID_TICKS)).map((t) => gridY(t))
-            : [];
-        drawGrid(ctx, xTicks, yTicks, w, h, gridColor, gridDash);
+        // The reference grid — behind the data, opt-out via `grid={false}` for
+        // a clean backdrop (session dividers below stay independent of it).
+        if (container.grid) {
+            const yTicks = gridY
+                ? (explicitY ?? gridY.ticks(GRID_TICKS)).map((t) => gridY(t))
+                : [];
+            // On a calendar axis the verticals are the FULL grain populations —
+            // every day in the month, every month in the year, every aligned
+            // clock instant — not just the thinned instants the labels chose:
+            // the labels decorate the grid, they don't define it. Each grain
+            // fades AS A UNIT by its **nominal** (gap-free, calendar-density)
+            // spacing — `level.spacing`, the same wash-aware quadratic ramp as
+            // the session lines — so zooming out dissolves the fine grain into
+            // the coarser one instead of popping when the label algorithm
+            // switches rung, and collapsing weekends draws *fewer* day lines at
+            // the *same* strength (not wider-spaced lines that jump to full —
+            // the owner's same-zoom, different-weight complaint). Levels nest,
+            // so walk coarsest→finest and let the first (widest-spaced,
+            // strongest) claim shared anchors — a month start draws once, at
+            // month strength, never dimmed by the day crowd around it.
+            const levels = container.xKind === 'time' && 'gridLevels' in xScale
+                ? xScale.gridLevels(GRID_LINE_GONE_PX)
+                : [];
+            if (levels.length > 0) {
+                const xs = [];
+                const alphas = [];
+                const claimed = new Set();
+                for (let i = levels.length - 1; i >= 0; i--) {
+                    const { values, spacing } = levels[i];
+                    const t = Math.max(0, Math.min(1, (spacing - GRID_LINE_GONE_PX) /
+                        (GRID_LINE_FULL_PX - GRID_LINE_GONE_PX)));
+                    const alpha = t * t;
+                    if (alpha <= 0.02)
+                        continue;
+                    for (const v of values) {
+                        if (claimed.has(v))
+                            continue;
+                        claimed.add(v);
+                        xs.push(xScale(v));
+                        alphas.push(alpha);
+                    }
+                }
+                drawGrid(ctx, xs, yTicks, w, h, gridColor, gridDash, alphas);
+            }
+            else {
+                // Value axis / no-calendar provider: verticals at the labelled
+                // ticks, the pre-hierarchical behavior.
+                const xTicks = xTickVals.map((d) => xScale(+d));
+                drawGrid(ctx, xTicks, yTicks, w, h, gridColor, gridDash);
+            }
+        }
         // Session dividers: solid verticals at the trading calendar's collapse
-        // points (session/day opens), where closed time was removed from the axis.
-        // Draw them at the axis ticks that are collapse points — the same
-        // calendar-coarsened instants the axis labels — so a divider sits under
-        // each date/month/year label, not at every session (which crowds).
+        // SEAMS — where closed time was actually removed from the axis. Opt-in
+        // emphasis over the grid (default 'none' — the grid's grain populations
+        // already mark the calendar): `'all'` draws one at every seam in view
+        // (the TradingView separator look, crowding lines fading out);
+        // `'labeled'` only at the axis ticks that are seams.
         const disc = container.discontinuities;
-        if (disc?.boundaries) {
+        if (disc?.boundaries && container.sessionDividers !== 'none') {
             const [d0, d1] = container.timeRange;
             // Call as a method (not a detached reference) so a class-based provider
             // whose `boundaries` reads `this` keeps its receiver.
-            const collapse = new Set(disc.boundaries(d0, d1));
-            const bx = xTickVals
-                .filter((t) => collapse.has(+t))
-                .map((t) => xScale(+t));
+            //
+            // `boundaries` is the provider's session ROSTER — the tick ladder and
+            // the grid consume every session open as a date anchor. A divider,
+            // though, marks removed time, and a roster entry that no gap precedes
+            // (a demo calendar's contiguous 24h weekday "sessions", a seamless
+            // session roll) is roster structure, not a seam — the owner's "why
+            // session lines on every day when only weekends are removed?"
+            // (2026-07-16). Keep exactly the true seams: `b` is one iff the
+            // instant just before it has zero live width. For a real exchange
+            // calendar every open follows an overnight gap, so this keeps all.
+            //
+            // Test `<= 0`, not a positive tolerance: a collapsed gap makes
+            // `distance(b-1, b)` **exactly** 0 (both instants map to the same live
+            // position), so no epsilon is needed — and a positive tolerance is
+            // **unit-dependent**. Under `spacing: 'uniform'` distance is measured
+            // in session-units, where a contiguous (non-seam) boundary reads a
+            // tiny fraction (`1 / sessionMs`) that a `< 0.5` test would misread as
+            // a seam. Exact zero matches the semantic contract in either spacing,
+            // and agrees with the same probe in `buildTicks` (Codex review, #479).
+            const seams = disc
+                .boundaries(d0, d1)
+                .filter((b) => disc.distance(b - 1, b) <= 0);
+            const marks = container.sessionDividers === 'all'
+                ? seams
+                : (() => {
+                    const collapse = new Set(seams);
+                    return xTickVals.map((v) => +v).filter((t) => collapse.has(t));
+                })();
+            const bx = marks.map((t) => xScale(t));
             const dividerColor = container.theme.axis.sessionDivider ?? gridColor;
-            drawDividers(ctx, thinPixels(bx, MIN_DIVIDER_PX), h, dividerColor);
+            if (container.sessionDividers === 'all') {
+                // Draw every boundary — no thinning (dropping a phase-dependent
+                // subset makes lines jump as the window slides). Crowding lines fade
+                // instead, so density falls off smoothly toward a clean plot.
+                drawDividers(ctx, bx, h, dividerColor, dividerAlphas(bx, SESSION_LINE_GONE_PX, SESSION_LINE_FULL_PX));
+            }
+            else {
+                drawDividers(ctx, thinPixels(bx, MIN_DIVIDER_PX), h, dividerColor);
+            }
         }
         for (const entry of layers) {
             const yScale = yScales.get(entry.axisId ?? defaultAxisId);

package/dist/XAxis.d.ts

@@ -63,6 +63,23 @@ export interface XAxisProps {
      *   for dense or wide labels that would collide when centred.
      */
     align?: 'auto' | 'center' | 'right';
+    /**
+     * How a **time** axis lays out its date context (ignored on value / category
+     * axes, and whenever a custom `format`, `transform`, or explicit `ticks`
+     * owns the labels).
+     * - **`'flat'` (default)** — one row: each tick that opens a coarser
+     *   calendar period is relabelled **inline** to it (the month at a month
+     *   turn, the year at a year turn, the date at a day turn under an intraday
+     *   grain), every other tick a terse label (`5`, `Feb`, `14:00`). The
+     *   TradingView look — the row reads `… 30 31 Feb 2 3 …`.
+     * - `'stacked'` — two rows: a terse top row (the grain's bare unit — `14:00`,
+     *   `12`, `Feb`) over a segmented **band** row of the next-coarser period
+     *   (day bands under intraday ticks, month bands under day ticks, year bands
+     *   under month/quarter ticks). Each band is a left-aligned label + a divider
+     *   at its turn, zebra-shaded by the band's calendar parity; the top-row tick
+     *   on each turn is emphasized and joins its divider as one boundary line.
+     */
+    dateStyle?: 'flat' | 'stacked';
 }
 /**
  * The shared **x axis**, a sibling of {@link YAxis} for the horizontal axis. A
@@ -74,5 +91,5 @@ export interface XAxisProps {
  *
  * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
  */
-export declare function XAxis({ format, label, side, height, ticks: customTicks, transform, color, align, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function XAxis({ format, label, side, height, ticks: customTicks, transform, color, align, dateStyle, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=XAxis.d.ts.map