@pond-ts/charts 0.44.1 → 0.46.0

package/dist/tickLadder.js

@@ -0,0 +1,286 @@
+const SEC_MS = 1_000;
+const MIN_MS = 60_000;
+const HOUR_MS = 3_600_000;
+/** The sub-day rungs, finest first, with their clock step — the 1/5/15/30
+ *  second and minute steps terminals use, then the hour steps. */
+const SUB_DAY_GRAINS = [
+    { g: 'second1', step: 1 * SEC_MS },
+    { g: 'second5', step: 5 * SEC_MS },
+    { g: 'second15', step: 15 * SEC_MS },
+    { g: 'second30', step: 30 * SEC_MS },
+    { g: 'minute1', step: 1 * MIN_MS },
+    { g: 'minute5', step: 5 * MIN_MS },
+    { g: 'minute15', step: 15 * MIN_MS },
+    { g: 'minute30', step: 30 * MIN_MS },
+    { g: 'hour1', step: 1 * HOUR_MS },
+    { g: 'hour3', step: 3 * HOUR_MS },
+    { g: 'hour6', step: 6 * HOUR_MS },
+    { g: 'hour12', step: 12 * HOUR_MS },
+];
+/** Whether `g` is one of the sub-day (clock-step) rungs. */
+function isSubDay(g) {
+    return g !== 'day' && SUB_DAY_GRAINS.some((r) => r.g === g);
+}
+/**
+ * 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.
+ */
+export function bucketKey(t, g) {
+    if (isSubDay(g))
+        return t;
+    const d = new Date(t);
+    switch (g) {
+        case 'day':
+            return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+        case 'week': {
+            const dow = (d.getDay() + 6) % 7; // 0 = Monday
+            // Local midnight of this week's Monday (Date normalizes a negative date).
+            return new Date(d.getFullYear(), d.getMonth(), d.getDate() - dow).getTime();
+        }
+        case 'month':
+            return d.getFullYear() * 12 + d.getMonth();
+        case 'quarter':
+            return d.getFullYear() * 4 + Math.floor(d.getMonth() / 3);
+        case 'year':
+            return d.getFullYear();
+        default:
+            return t;
+    }
+}
+/** The first instant of each distinct `g`-bucket in the ascending list `opens`. */
+function firstOfEachBucket(opens, g) {
+    const out = [];
+    let prev;
+    for (const t of opens) {
+        const k = bucketKey(t, g);
+        if (k !== prev) {
+            out.push(t);
+            prev = k;
+        }
+    }
+    return out;
+}
+const COARSENING_LADDER = [
+    'week',
+    'month',
+    'quarter',
+    'year',
+];
+/**
+ * Thin an ascending run of **session opens** down to about `count` axis ticks by
+ * **calendar grain** — the trading-terminal habit of labelling week / month /
+ * year starts rather than an arbitrary every-nth session. Picks the finest grain
+ * on the ladder (day → week → month → quarter → year) that yields at most
+ * `count` buckets and returns the first open in each; beyond yearly it decimates
+ * every-nth so the axis never crowds. Exported so the container can draw session
+ * dividers at the same instants the axis labels.
+ *
+ * `count` is a **cap**, not a target: grains jump by 4–12× up the ladder, so a
+ * small fixed count over-coarsens long spans (a mid-year-anchored 12-month daily
+ * run spans 6 quarter buckets — capped at 5 it collapses to year grain, 2
+ * ticks). Callers size the cap to the room the labels have — the container
+ * derives it from plot width — rather than passing a small constant.
+ *
+ * This is the day-and-coarser half of the ladder; {@link buildTicks} adds the
+ * sub-day rungs.
+ */
+export function coarsenCalendar(opens, count) {
+    if (opens.length <= count)
+        return { ticks: [...opens], granularity: 'day' };
+    for (const g of COARSENING_LADDER) {
+        const ticks = firstOfEachBucket(opens, g);
+        if (ticks.length <= count)
+            return { ticks, granularity: g };
+    }
+    // Coarser than yearly isn't a calendar grain — decimate the year starts.
+    const yearly = firstOfEachBucket(opens, 'year');
+    const step = Math.ceil(yearly.length / count);
+    return {
+        ticks: yearly.filter((_, i) => i % step === 0),
+        granularity: 'year',
+    };
+}
+/** The first clock-aligned `stepMs` multiple at or after `t`, relative to `t`'s
+ *  own local midnight — so a 3-hour step lands on 00:00 / 03:00 / 06:00 local,
+ *  whatever the session open was. Fixed-ms stepping from midnight, so on a DST
+ *  transition day the later anchors drift off the wall-clock grid by the shift
+ *  (labels stay truthful — they format the real instant); exchange-tz grain is
+ *  the already-deferred refinement. */
+function nextAligned(t, stepMs) {
+    const d = new Date(t);
+    const midnight = new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+    return midnight + Math.ceil((t - midnight) / stepMs) * stepMs;
+}
+/**
+ * The sub-day anchors at `stepMs`: each session open, plus each clock-aligned
+ * step instant strictly inside that session's **live** span. (The caller may
+ * still drop the very first anchor as a cramped lead — see {@link buildTicks}.) An instant is
+ * in-session iff live distance-then-offset round-trips it — so a lunch-break
+ * gap, an early close, or a collapsed overnight never gets an anchor, and no
+ * new provider surface is needed. Bails once `cap` is exceeded (the caller
+ * only needs to know the grain doesn't fit).
+ */
+function stepAnchors(provider, opens, domainEnd, stepMs, cap) {
+    const out = [];
+    for (let i = 0; i < opens.length; i++) {
+        const open = opens[i];
+        const end = i + 1 < opens.length ? opens[i + 1] : domainEnd;
+        out.push(open);
+        for (let t = nextAligned(open + 1, stepMs); t < end; t += stepMs) {
+            if (provider.offset(open, provider.distance(open, t)) === t) {
+                out.push(t);
+                if (out.length > cap)
+                    return out;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The full-ladder grain selection: given the provider, the domain, and the
+ * width-derived `cap`, walk the clock rungs (1s … 30s, 1m … 30m, 1h … 12h)
+ * then day → week → month → quarter → year (then decimate) and return the
+ * first rung that fits.
+ * `opens` are the session-open anchors (`[domain start, ...boundaries]`) the
+ * caller already has. Sub-day rungs are only reachable when the opens
+ * themselves fit — a year of daily sessions never wastes time generating hour
+ * anchors.
+ */
+export function buildTicks(provider, opens, domainEnd, cap) {
+    const result = (() => {
+        if (opens.length <= cap) {
+            // Pick the clock rung from the **live-span estimate**, not the
+            // enumerated anchor count. On a live chart the domain slides every
+            // frame, and the number of aligned marks inside a sliding window
+            // oscillates ±1 with its phase — an exact count sitting at the cap
+            // flips the grain back and forth for single frames (the LiveSine
+            // flicker). The span is constant while sliding, so the estimate is
+            // stable; the enumerated count may then exceed the cap by a tick or
+            // two at some phases, which the per-tick pixel budget absorbs.
+            const liveSpan = provider.distance(opens[0], domainEnd);
+            for (const { g, step } of SUB_DAY_GRAINS) {
+                if (opens.length + Math.floor(liveSpan / step) > cap)
+                    continue;
+                const ticks = stepAnchors(provider, opens, domainEnd, step, cap + 4);
+                // A clock rung must earn its labels: if it adds no intraday anchor
+                // beyond the opens themselves, it's really day grain (a row of
+                // "09:30"s under every session is a worse day axis, not a clock
+                // axis) — and every coarser rung would earn even less.
+                if (ticks.length > opens.length)
+                    return { ticks, granularity: g };
+                break;
+            }
+            return { ticks: [...opens], granularity: 'day' };
+        }
+        return coarsenCalendar(opens, cap);
+    })();
+    // Round anchors to integer milliseconds: a pan/zoom domain comes from
+    // `scale.invert(pixel)` and is fractional, and a fractional anchor breaks
+    // the label pipeline — formatters pass through `new Date(ms)`, which
+    // truncates, so the instant no longer matches its own anchor set and the
+    // label falls through to the d3 multi-scale default (a bare `.259`
+    // millisecond tick). Sub-ms precision is invisible at any ladder grain.
+    result.ticks = result.ticks.map((t) => Math.round(t));
+    // Drop a cramped **leading partial-period** anchor: the first tick is the
+    // domain start, which usually sits mid-period (a "1Y back from today" view
+    // starts mid-month), so it can land arbitrarily close to the first full
+    // period start and the two labels collide (the classic "Jun 23Jul 07"
+    // pile-up). When the lead gap is under half a typical period (in **live**
+    // time, so a collapsed weekend doesn't fake a gap), the partial anchor
+    // isn't earning its label — the boundary row moves to the next tick.
+    const t = result.ticks;
+    if (t.length >= 3 &&
+        provider.distance(t[0], t[1]) < 0.5 * provider.distance(t[1], t[2])) {
+        t.shift();
+    }
+    return result;
+}
+/**
+ * The **boundary grain** for ticks at grain `g` — the next-coarser unit a
+ * tick's own label doesn't already carry, rendered as the axis's second label
+ * row. Clock labels (`14:00`) need the date; day/week labels (`Feb 02`)
+ * already carry the month, so they need only the year — as do month/quarter
+ * labels (`Feb`); a year label already says everything.
+ */
+export function boundaryGrainFor(g) {
+    if (isSubDay(g))
+        return 'day';
+    switch (g) {
+        case 'day':
+        case 'week':
+        case 'month':
+        case 'quarter':
+            return 'year';
+        default:
+            return undefined;
+    }
+}
+/** d3 time-format specifier for the **major** (first-row) label at grain `g`. */
+export function majorFormatFor(g) {
+    switch (g) {
+        case 'second1':
+        case 'second5':
+        case 'second15':
+        case 'second30':
+            return '%H:%M:%S';
+        case 'minute1':
+        case 'minute5':
+        case 'minute15':
+        case 'minute30':
+        case 'hour1':
+        case 'hour3':
+        case 'hour6':
+        case 'hour12':
+            return '%H:%M';
+        case 'day':
+        case 'week':
+            return '%b %d';
+        case 'month':
+        case 'quarter':
+            return '%b';
+        case 'year':
+            return '%Y';
+    }
+}
+/** d3 time-format specifier for the **boundary** (second-row) label at the
+ *  boundary grain `g` — a date under clock ticks, the bare year under
+ *  everything else. Never repeat a unit the first row already shows
+ *  (`Jan 2026` under a `Jan 05` tick reads as noise). */
+export function boundaryFormatFor(g) {
+    return g === 'day' ? '%b %d' : '%Y';
+}
+/**
+ * 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
+ * **crossing**, the first tick of a new day / year. The first tick is *not*
+ * automatically flagged: the reader's left-edge context is the pinned
+ * {@link TradingTimeScale.boundaryContext} label (a property of the domain
+ * start, not of any tick — anchoring it to the first tick made it hop
+ * tick-to-tick on a live sliding window). Empty when the grain has no
+ * boundary row (year grain).
+ */
+export function boundaryTicks(ticks, granularity, domainStart) {
+    const bg = boundaryGrainFor(granularity);
+    if (bg === undefined)
+        return [];
+    const out = [];
+    // Seed with the domain start's bucket when given: a first tick in a
+    // different period than the left edge IS a crossing (a 23:55-anchored
+    // window whose cramped 23:55 lead was dropped still marks 00:00 as the
+    // day turn); a first tick in the same period is not (no tick-hopping
+    // context on a live window).
+    let prev = domainStart !== undefined ? bucketKey(domainStart, bg) : undefined;
+    for (const t of ticks) {
+        const k = bucketKey(t, bg);
+        if (prev !== undefined && k !== prev)
+            out.push(t);
+        prev = k;
+    }
+    return out;
+}
+//# sourceMappingURL=tickLadder.js.map

package/dist/tradingTimeScale.d.ts

@@ -47,12 +47,16 @@ export interface TradingCalendarLike {
  * wherever the container's `xScale` goes.
  *
  * Ticks are **calendar-aware** when the provider enumerates its gaps: `.ticks`
- * returns the session opens thinned to a calendar grain (week / month / year
- * starts, whichever fits ~`count`), and `.tickFormat` labels each anchor with a
- * **date** (`%b %d`) — or the **year** (`%Y`) when ticks are a year apart —
- * while formatting any other instant (a mid-session tick, the cursor readout)
- * with the d3 multi-scale default. Without a provider `boundaries` method it
- * falls back to interior even-spaced time ticks.
+ * walks the logical ladder (hour1 → hour3 → hour6 → hour12 → day → week →
+ * month → quarter → year) and returns the finest rung that fits `count`, and
+ * `.tickFormat` labels each anchor at that grain (`%H:%M` for hours, `%b %d`
+ * for days/weeks, `%b` for months/quarters, `%Y` for years) while formatting
+ * any other instant (the cursor readout) with the d3 multi-scale default. The
+ * coarser context a label drops lives on `.tickBoundaries` — the second-row
+ * boundary labels (the date over a clock axis, the year over a day / week /
+ * month axis), one per boundary crossing plus the first tick.
+ * Without a provider `boundaries` method it falls back to interior even-spaced
+ * time ticks.
  *
  * **Out-of-domain behavior.** Within the calendar the scale extrapolates like a
  * normal scale — a live instant *before* the domain start maps to a negative
@@ -67,37 +71,45 @@ export interface TradingTimeScale {
     invert(pixel: number): number;
     ticks(count?: number): number[];
     tickFormat(count?: number, specifier?: string): (date: Date) => string;
+    /**
+     * The **second-row** (boundary) label for a tick value, or `undefined` for
+     * ticks that don't open a new boundary period. Same grain selection as
+     * {@link ticks} at the same `count`, so the rows agree: each tick starting
+     * a new day / year (whichever is the next-coarser unit the first-row label
+     * omits) carries the label — a **crossing**. The left-edge context (what
+     * period the domain starts in) is {@link boundaryContext}, pinned by the
+     * axis rather than riding a tick; year-grain ticks have no second row.
+     */
+    tickBoundaries(count?: number): (value: number) => string | undefined;
+    /**
+     * The boundary-row label for the **domain start** — the reader's left-edge
+     * context (`Jan 01` over an intraday axis, the year over a month axis),
+     * rendered pinned at the plot's left edge. A property of the domain, not of
+     * any tick — so it stays put on a live sliding window instead of hopping
+     * from tick to tick. `undefined` when the grain has no boundary row.
+     */
+    boundaryContext(count?: number): string | undefined;
     domain(): [number, number];
     domain(next: readonly [number, number]): TradingTimeScale;
     range(): [number, number];
     range(next: readonly [number, number]): TradingTimeScale;
     copy(): TradingTimeScale;
 }
-/** The calendar grain a run of session opens is bucketed to for axis ticks. */
-type TickGranularity = 'session' | 'week' | 'month' | 'quarter' | 'year';
+export { coarsenCalendar } from './tickLadder.js';
+export type { TickGranularity } from './tickLadder.js';
 /**
- * Thin an ascending run of **session opens** down to about `count` axis ticks by
- * **calendar grain** — the trading-terminal habit of labelling week / month /
- * year starts rather than an arbitrary every-nth session. Picks the finest grain
- * on the ladder (session → week → month → quarter → year) that yields at most
- * `count` buckets and returns the first open in each; beyond yearly it decimates
- * every-nth so the axis never crowds. Exported so the container can draw session
- * dividers at the same instants the axis labels.
- *
- * `count` is a **cap**, not a target: grains jump by 4–12× up the ladder, so a
- * small fixed count over-coarsens long spans (a mid-year-anchored 12-month daily
- * run spans 6 quarter buckets — capped at 5 it collapses to year grain, 2
- * ticks). Callers size the cap to the room the labels have — the container
- * derives it from plot width — rather than passing a small constant.
+ * The trivial gap-free {@link DiscontinuityProvider}: live time **is** wall
+ * time, and every local midnight is a "session open". Backing a plain
+ * continuous time axis with `scaleTradingTime(identityProvider())` runs it
+ * through the same logical tick ladder as a trading-calendar axis — calendar
+ * days are the day anchors, so a year of data ticks on month starts and an
+ * afternoon ticks on clock-aligned hours, instead of d3's mixed multi-scale
+ * default.
  */
-export declare function coarsenCalendar(opens: readonly number[], count: number): {
-    ticks: number[];
-    granularity: TickGranularity;
-};
+export declare function identityProvider(): DiscontinuityProvider;
 /**
  * Build a {@link TradingTimeScale} over the given discontinuity `provider`.
  * Configure like a d3 scale: `scaleTradingTime(provider).domain([t0, t1]).range([0, width])`.
  */
 export declare function scaleTradingTime(provider: DiscontinuityProvider): TradingTimeScale;
-export {};
 //# sourceMappingURL=tradingTimeScale.d.ts.map

package/dist/tradingTimeScale.js

@@ -1,79 +1,39 @@
 import { scaleTime } from 'd3-scale';
+import { boundaryFormatFor, boundaryGrainFor, boundaryTicks, buildTicks, majorFormatFor, } from './tickLadder.js';
+// Grain selection lives in `tickLadder.ts` (the full hour1…year ladder plus
+// the boundary-row helpers); re-exported here so existing imports keep working.
+export { coarsenCalendar } from './tickLadder.js';
 /**
- * The local-time bucket key for `t` at grain `g` — two instants in the same
- * 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.
+ * The trivial gap-free {@link DiscontinuityProvider}: live time **is** wall
+ * time, and every local midnight is a "session open". Backing a plain
+ * continuous time axis with `scaleTradingTime(identityProvider())` runs it
+ * through the same logical tick ladder as a trading-calendar axis — calendar
+ * days are the day anchors, so a year of data ticks on month starts and an
+ * afternoon ticks on clock-aligned hours, instead of d3's mixed multi-scale
+ * default.
  */
-function bucketKey(t, g) {
-    if (g === 'session')
-        return t; // every open its own bucket
-    const d = new Date(t);
-    switch (g) {
-        case 'week': {
-            const dow = (d.getDay() + 6) % 7; // 0 = Monday
-            // Local midnight of this week's Monday (Date normalizes a negative date).
-            return new Date(d.getFullYear(), d.getMonth(), d.getDate() - dow).getTime();
-        }
-        case 'month':
-            return d.getFullYear() * 12 + d.getMonth();
-        case 'quarter':
-            return d.getFullYear() * 4 + Math.floor(d.getMonth() / 3);
-        case 'year':
-            return d.getFullYear();
-    }
-}
-/** The first instant of each distinct `g`-bucket in the ascending list `opens`. */
-function firstOfEachBucket(opens, g) {
-    const out = [];
-    let prev;
-    for (const t of opens) {
-        const k = bucketKey(t, g);
-        if (k !== prev) {
-            out.push(t);
-            prev = k;
-        }
-    }
-    return out;
-}
-const COARSENING_LADDER = [
-    'week',
-    'month',
-    'quarter',
-    'year',
-];
-/**
- * Thin an ascending run of **session opens** down to about `count` axis ticks by
- * **calendar grain** — the trading-terminal habit of labelling week / month /
- * year starts rather than an arbitrary every-nth session. Picks the finest grain
- * on the ladder (session → week → month → quarter → year) that yields at most
- * `count` buckets and returns the first open in each; beyond yearly it decimates
- * every-nth so the axis never crowds. Exported so the container can draw session
- * dividers at the same instants the axis labels.
- *
- * `count` is a **cap**, not a target: grains jump by 4–12× up the ladder, so a
- * small fixed count over-coarsens long spans (a mid-year-anchored 12-month daily
- * run spans 6 quarter buckets — capped at 5 it collapses to year grain, 2
- * ticks). Callers size the cap to the room the labels have — the container
- * derives it from plot width — rather than passing a small constant.
- */
-export function coarsenCalendar(opens, count) {
-    if (opens.length <= count)
-        return { ticks: [...opens], granularity: 'session' };
-    for (const g of COARSENING_LADDER) {
-        const ticks = firstOfEachBucket(opens, g);
-        if (ticks.length <= count)
-            return { ticks, granularity: g };
-    }
-    // Coarser than yearly isn't a calendar grain — decimate the year starts.
-    const yearly = firstOfEachBucket(opens, 'year');
-    const step = Math.ceil(yearly.length / count);
-    return {
-        ticks: yearly.filter((_, i) => i % step === 0),
-        granularity: 'year',
+export function identityProvider() {
+    const self = {
+        clampUp: (t) => t,
+        clampDown: (t) => t,
+        distance: (from, to) => to - from,
+        offset: (v, amount) => v + amount,
+        copy: () => self,
+        boundaries: (from, to) => {
+            const out = [];
+            const d = new Date(from);
+            // First local midnight strictly after `from`; step by calendar day (not
+            // 24h) so DST transitions stay on midnight.
+            let cur = new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1);
+            while (cur.getTime() < to) {
+                if (cur.getTime() > from)
+                    out.push(cur.getTime());
+                cur = new Date(cur.getFullYear(), cur.getMonth(), cur.getDate() + 1);
+            }
+            return out;
+        },
     };
+    return self;
 }
 /**
  * Build a {@link TradingTimeScale} over the given discontinuity `provider`.
@@ -103,17 +63,35 @@ export function scaleTradingTime(provider) {
         const bounds = provider.boundaries?.(domain[0], domain[1]) ?? [];
         return [domain[0], ...bounds];
     };
+    /** Whether the provider has calendar structure to ladder on. Without a
+     *  `boundaries` method there are no anchors — the even-spacing fallback. */
+    const hasCalendar = () => provider.boundaries !== undefined;
+    /** The ladder result for this domain at `count` — the single source `ticks`,
+     *  `tickFormat`, and `tickBoundaries` all derive from, so the three agree.
+     *  Memoized on `(domain, count)`: the three callers (plus gridlines /
+     *  dividers) hit the same resolution per render, and on a wide continuous
+     *  domain re-walking every day-open is the expensive part. */
+    let laddered = null;
+    const resolved = (count) => {
+        const key = `${domain[0]}:${domain[1]}:${count}`;
+        if (laddered?.key !== key) {
+            laddered = {
+                key,
+                value: buildTicks(provider, sessionOpens(), domain[1], count),
+            };
+        }
+        return laddered.value;
+    };
     scale.ticks = (count = 10) => {
         const live = totalLive();
         if (live <= 0 || count < 1)
             return [domain[0]];
-        const opens = sessionOpens();
-        // Calendar-aware: label the session opens (each a new day), thinned to
-        // week / month / year starts by grain rather than an arbitrary every-nth
-        // session — the trading-terminal look.
-        if (opens.length > 1)
-            return coarsenCalendar(opens, count).ticks;
-        // No boundaries (a single session / no calendar): fall back to interior
+        // Calendar-aware: walk the logical ladder over the session-open anchors
+        // (hour steps inside sessions, then day / week / month / quarter / year
+        // starts) — the trading-terminal look, never an arbitrary every-nth.
+        if (hasCalendar())
+            return resolved(count).ticks;
+        // No boundaries (no calendar structure at all): fall back to interior
         // even-spaced ticks — endpoints excluded so none sits on the plot edge.
         const out = [];
         for (let i = 1; i < count; i++) {
@@ -124,20 +102,44 @@ export function scaleTradingTime(provider) {
     scale.tickFormat = (count = 10, specifier) => {
         if (specifier !== undefined)
             return base.tickFormat(count, specifier);
-        const opens = sessionOpens();
         const defFmt = base.tickFormat(count);
-        if (opens.length <= 1)
+        if (!hasCalendar())
             return defFmt; // no calendar → d3 multi-scale default
-        // Anchor label at each coarsened session-open tick: a **date** (`%b %d`), or
-        // the **year** when ticks are a year apart (a plain date would drop the year
-        // the reader needs). Any other instant — a cursor readout — uses the d3
-        // multi-scale default. Same grain as {@link ticks}, so labels and the
-        // dividers drawn at these instants agree.
-        const { ticks, granularity } = coarsenCalendar(opens, count);
+        // Anchor labels at the grain {@link ticks} chose — one uniform format per
+        // grain (hours as `%H:%M`, days/weeks as `%b %d`, months/quarters as `%b`,
+        // years as `%Y`); the coarser context the label omits is the second row
+        // ({@link tickBoundaries}). Any other instant — a cursor readout — uses
+        // the d3 multi-scale default. Same grain as {@link ticks}, so labels and
+        // the dividers drawn at these instants agree.
+        const { ticks, granularity } = resolved(count);
         const anchors = new Set(ticks);
-        const anchorFmt = base.tickFormat(count, granularity === 'year' ? '%Y' : '%b %d');
+        const anchorFmt = base.tickFormat(count, majorFormatFor(granularity));
         return (d) => (anchors.has(+d) ? anchorFmt(d) : defFmt(d));
     };
+    scale.tickBoundaries = (count = 10) => {
+        if (!hasCalendar())
+            return () => undefined;
+        const { ticks, granularity } = resolved(count);
+        const bg = boundaryGrainFor(granularity);
+        if (bg === undefined)
+            return () => undefined;
+        const fmt = base.tickFormat(count, boundaryFormatFor(bg));
+        const labelled = new Map();
+        for (const t of boundaryTicks(ticks, granularity, domain[0])) {
+            labelled.set(t, fmt(new Date(t)));
+        }
+        return (value) => labelled.get(value);
+    };
+    scale.boundaryContext = (count = 10) => {
+        if (!hasCalendar())
+            return undefined;
+        const { granularity } = resolved(count);
+        const bg = boundaryGrainFor(granularity);
+        if (bg === undefined)
+            return undefined;
+        const fmt = base.tickFormat(count, boundaryFormatFor(bg));
+        return fmt(new Date(domain[0]));
+    };
     function domainFn(next) {
         if (next === undefined)
             return [domain[0], domain[1]];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.44.1",
+  "version": "0.46.0",
   "private": false,
   "description": "Canvas-rendered, streaming-first time-series charts for pond-ts",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "perf": "PERF_BENCH=1 playwright test perf.spec.ts --workers=1"
   },
   "peerDependencies": {
-    "@pond-ts/react": "^0.44.0",
-    "pond-ts": "^0.44.0",
+    "@pond-ts/react": "^0.46.0",
+    "pond-ts": "^0.46.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {