@pond-ts/charts 0.46.0 → 0.48.0

package/dist/tickLadder.js

@@ -1,6 +1,17 @@
+/** Collapse a {@link TickGranularity} to its coarse {@link TimeGrain} unit. */
+export function coarseUnitOf(g) {
+    if (g.startsWith('second'))
+        return 'second';
+    if (g.startsWith('minute'))
+        return 'minute';
+    if (g.startsWith('hour'))
+        return 'hour';
+    return g; // 'day' | 'week' | 'month' | 'quarter' | 'year'
+}
 const SEC_MS = 1_000;
 const MIN_MS = 60_000;
 const HOUR_MS = 3_600_000;
+const DAY_MS = 86_400_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 = [
@@ -66,32 +77,247 @@ function firstOfEachBucket(opens, g) {
     return out;
 }
 const COARSENING_LADDER = [
-    'week',
     'month',
     'quarter',
     'year',
 ];
+/** Nominal days per month — the band gate: the session-stride band applies
+ *  while a nominal month still affords ≥ 2 marks at the span-derived budget. */
+const DAYS_PER_MONTH = 30.44;
+/** Days in the local month containing `d`. */
+function daysInLocalMonth(d) {
+    return new Date(d.getFullYear(), d.getMonth() + 1, 0).getDate();
+}
+/**
+ * Whether index `i` marks in a month of `n` sessions/days at stride `k`. Two
+ * regimes, split on `m = floor(n / k)` — the whole stride-intervals the month
+ * affords:
+ *
+ * - **`m ≥ 4` (dense): anchored stride** — the month start (index 0), then
+ *   every `k`-th index, stopping so the gap to the next month start stays
+ *   ≥ `k` (slack at the month end, never a cramped tick before the month
+ *   label). This is the decoded TradingView rule, validated label-for-label
+ *   against owner-supplied 2026 captures: `apr | 8 14 20 24 | may` is session
+ *   indices `0 4 8 12 16` of April's 21 sessions at stride 4, index 20
+ *   dropped because `may` would sit only 1 session away.
+ * - **`m ≤ 3` (coarse): balanced division** — marks at `round(j·n/m)`. An
+ *   anchored stride here leaves a hole of up to ~2k before the next month
+ *   (the `Mar 9 17 ……… Apr` look), and each ±1 stride change relabels every
+ *   mark even though density barely moves (the 9/17 → 10/19 → 11/21 crawl).
+ *   Division splits the month into near-equal parts (gaps differ ≤ 1), and —
+ *   since the marks depend only on `(n, m)` — they hold still across the
+ *   whole stride range that maps to one `m`: mid-month, then thirds, exactly
+ *   the coarse-zoom look the anchored data converges to as it densifies.
+ */
+function monthMark(i, k, n) {
+    const m = Math.floor(n / k);
+    if (m <= 1)
+        return i === 0;
+    if (m <= 3) {
+        for (let j = 0; j < m; j++) {
+            if (Math.round((j * n) / m) === i)
+                return true;
+        }
+        return false;
+    }
+    return i === 0 || (i % k === 0 && i <= n - k);
+}
+/**
+ * Day-of-month subdivision — the **no-provider fallback** for direct
+ * {@link coarsenCalendar} calls: each month's marks land on calendar days at
+ * a uniform `ceil(gapDays)` stride from the 1st (day `1` = index 0), under
+ * the identity assumption that every calendar day is a session (where
+ * day-space and session-space coincide). A stride day with no open in the
+ * list **snaps to the next open**: a mark is taken when any stride day lies
+ * in `(previous open's date, own date]`. Membership depends only on dates and
+ * the span-derived stride, so a pan cannot reshuffle the marks. (The window's
+ * first open has no known predecessor and marks only on its own exact day — a
+ * snapped edge mark would appear/disappear with the pan phase.)
+ */
+function subdivideMonthsByDay(opens, gapDays) {
+    const k = Math.max(2, Math.ceil(gapDays - 1e-9));
+    const out = [];
+    let prev = null;
+    for (const t of opens) {
+        const d = new Date(t);
+        const month = d.getFullYear() * 12 + d.getMonth();
+        const dom = d.getDate();
+        const monthLen = daysInLocalMonth(d);
+        // Scan window: same month → since the previous open's date; the first
+        // open of a new month → from day 1 (a weekend month-start snaps here);
+        // the window's first open → its own exact day only (see doc above).
+        const from = prev === null ? dom - 1 : prev.month === month ? prev.dom : 0;
+        prev = { month, dom };
+        for (let g = from + 1; g <= dom; g++) {
+            if (monthMark(g - 1, k, monthLen)) {
+                out.push(t);
+                break;
+            }
+        }
+    }
+    return out;
+}
 /**
- * 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.
+ * **Session-index** subdivision — the decoded TradingView algorithm, used
+ * whenever the provider can enumerate the calendar. Each month's sessions are
+ * indexed `0…M−1` from the month's first session, and marks land on a
+ * **uniform integer stride** of those indices ({@link monthMark}: the month
+ * start, then every `k`-th session, truncated so the gap to the next month
+ * start stays ≥ `k`). Marks therefore sit an equal number of *bars* apart —
+ * evenly spaced pixels on a collapsed (and especially a uniform) trading axis
+ * — with the slack at the month **end**, and no weekend/holiday snapping at
+ * all: non-sessions simply aren't indices, and a month whose 1st is a Sunday
+ * anchors on Monday-the-2nd (index 0). Validated label-for-label against
+ * owner-supplied TradingView captures (Feb/Apr/May 2026, NYSE calendar) at
+ * strides 4, 3, and 2.
  *
- * `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 stride is per-month — `ceil(gapDays / (extentDays/M))`, i.e. the
+ * span-derived day budget divided by the month's own days-per-session — so a
+ * full month lands on the global density while a stub month (the live edge, a
+ * fixture that ends mid-month) earns proportionally fewer marks. Zooming
+ * steps the stride through the integers (…4 → 3 → 2 → 1), re-labelling some
+ * interior marks at each step (strides don't nest; the deliberate trade,
+ * owner-confirmed 2026-07-16 after their own TradingView samples showed the
+ * same: month anchors never move and density shifts by ~one bar, so it
+ * doesn't read as flicker — unlike the dyadic halving this replaces, which
+ * nested perfectly but stepped density 2× and wobbled ±1 day inside non-power
+ * months). Panning never reshuffles anything: rosters are queried over each
+ * **full calendar month** (`boundaries(monthStart−1ms, nextMonthStart)`), so
+ * an index is a property of the calendar, never of the window.
+ *
+ * The window's left edge (`opens[0]`) is indexed via point queries: the count
+ * of its month's sessions opening strictly before it, and whether it is
+ * itself exactly a session open — only then is it markable (a mid-gap edge
+ * has no honest index and would ride the pan). A calendar's **absolute
+ * start** — whose first session follows no collapsed gap, so some providers
+ * never report it — is detected by live-time flow and indexed 0, keeping the
+ * world-start month pinned.
+ */
+function subdivideMonthsBySession(opens, gapDays, provider) {
+    const monthKeyOf = (t) => {
+        const d = new Date(t);
+        return d.getFullYear() * 12 + d.getMonth();
+    };
+    const monthStartOf = (key) => new Date(Math.floor(key / 12), key % 12, 1).getTime();
+    const strideOf = (count, extentDays) => Math.max(2, Math.ceil((gapDays * count) / Math.max(1, extentDays) - 1e-9));
+    // Full-month roster: session count + the per-month stride its calendar-day
+    // extent affords. Cached per call; ≤ (visible months + 1) provider queries,
+    // and the whole resolution is memoized upstream per (domain, count).
+    const rosters = new Map();
+    const rosterOf = (key) => {
+        let r = rosters.get(key);
+        if (r === undefined) {
+            const sessions = provider.boundaries(monthStartOf(key) - 1, monthStartOf(key + 1));
+            const count = Math.max(1, sessions.length);
+            const extentDays = sessions.length === 0
+                ? 0
+                : new Date(sessions[sessions.length - 1]).getDate() -
+                    new Date(sessions[0]).getDate() +
+                    1;
+            r = { count, stride: strideOf(count, extentDays) };
+            rosters.set(key, r);
+        }
+        return r;
+    };
+    const out = [];
+    let curKey = -1;
+    let idx = 0;
+    for (let i = 0; i < opens.length; i++) {
+        const t = opens[i];
+        const key = monthKeyOf(t);
+        if (i === 0) {
+            // Index the window's left edge within its month (see doc above).
+            curKey = key;
+            const monthStart = monthStartOf(key);
+            const sessions = provider.boundaries(monthStart - 1, monthStartOf(key + 1));
+            const pre = provider.boundaries(monthStart - 1, t).length;
+            const exact = provider.boundaries(t - 1, t + 1).length > 0;
+            // The calendar's absolute start (see doc above): unreported by the
+            // roster, detected by live-time flow — it is the month's session 0.
+            const worldStart = !exact && pre === 0 && provider.distance(t, t + MIN_MS) > 0;
+            const count = Math.max(1, sessions.length + (worldStart ? 1 : 0));
+            const rosterFirstDom = sessions.length > 0 ? new Date(sessions[0]).getDate() : 31;
+            const firstDom = worldStart
+                ? Math.min(new Date(t).getDate(), rosterFirstDom)
+                : rosterFirstDom;
+            const lastDom = sessions.length > 0
+                ? new Date(sessions[sessions.length - 1]).getDate()
+                : new Date(t).getDate();
+            const stride = strideOf(count, lastDom - firstDom + 1);
+            rosters.set(key, { count, stride });
+            if ((exact || worldStart) && monthMark(pre, stride, count)) {
+                out.push(t);
+            }
+            idx = exact || worldStart ? pre + 1 : pre;
+            continue;
+        }
+        if (key !== curKey) {
+            // A month transition: this open is its month's first session, index 0.
+            curKey = key;
+            idx = 0;
+        }
+        const { count, stride } = rosterOf(key);
+        if (monthMark(idx, stride, count))
+            out.push(t);
+        idx++;
+    }
+    return out;
+}
+/**
+ * Thin an ascending run of **session opens** down to about `count` axis ticks.
+ * Picks the finest rung: every session → **per-month uniform session stride**
+ * (still day grain, month starts pinned) → month → quarter → year; 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.
+ *
+ * The day band thins each month to a **uniform session stride** — the month's
+ * first session, then every `k`-th session, truncated so the gap to the next
+ * month start stays ≥ `k` (slack at the month end, never a cramped tick
+ * before the month label). The decoded-and-validated TradingView algorithm:
+ * with a `provider` the stride runs in **session-index space**
+ * ({@link subdivideMonthsBySession}) — marks an equal number of bars apart,
+ * evenly spaced pixels on a collapsed axis, no weekend snapping; without one
+ * it falls back to day-of-month space ({@link subdivideMonthsByDay}).
+ * Zooming steps the stride through the integers (…4 → 3 → 2 → 1), a ~one-bar
+ * density change that re-labels some interior marks; month / year starts stay
+ * pinned at every zoom, and pans never reshuffle anything (the stride derives
+ * from the span, the indices from the calendar). Schemes tried and rejected
+ * on the way here: a global even day-stride (can't pin month starts — the
+ * `Feb` label drifted with zoom), `round(i·L/div)` division (beats against
+ * the month length), and dyadic midpoint halving (perfect zoom-nesting, but
+ * 2× density jumps and ±1-day wobble inside non-power months; the owner's
+ * TradingView captures showed uniform strides re-labelling on zoom reads
+ * calmer than either wobble). There is deliberately no week rung: a
+ * Monday-anchored week can't pin month starts either, so the day band owns
+ * everything between every-session and month grain.
+ *
+ * `count` is a **cap**, not a target: coarser grains jump by 3–4× (month →
+ * quarter → year), so a small fixed count over-coarsens long spans. Callers
+ * size the cap to the room the labels have — the container derives it from plot
+ * width — rather than passing a small constant. `spanDays` is the domain's
+ * calendar-day span from the caller (stable at a fixed zoom); absent (a direct
+ * call), it falls back to the opens' own span.
  *
  * This is the day-and-coarser half of the ladder; {@link buildTicks} adds the
  * sub-day rungs.
  */
-export function coarsenCalendar(opens, count) {
+export function coarsenCalendar(opens, count, spanDays, provider) {
     if (opens.length <= count)
         return { ticks: [...opens], granularity: 'day' };
+    // Per-month uniform session stride. Band-gated to spans where a nominal
+    // month still affords ≥ 2 marks (below that a month is down to one mark,
+    // which *is* month grain — the bucket ladder), and to daily-dense opens: a
+    // synthetic run of month/year starts has no days to stride over.
+    const openSpanDays = (opens[opens.length - 1] - opens[0]) / DAY_MS || Infinity;
+    const dailyDense = opens.length >= 0.5 * openSpanDays;
+    const gapDays = (spanDays ?? openSpanDays) / count;
+    if (dailyDense && DAYS_PER_MONTH / gapDays >= 2) {
+        const ticks = provider?.boundaries !== undefined
+            ? subdivideMonthsBySession(opens, gapDays, provider)
+            : subdivideMonthsByDay(opens, gapDays);
+        if (ticks.length > 0)
+            return { ticks, granularity: 'day' };
+    }
     for (const g of COARSENING_LADDER) {
         const ticks = firstOfEachBucket(opens, g);
         if (ticks.length <= count)
@@ -105,6 +331,117 @@ export function coarsenCalendar(opens, count) {
         granularity: 'year',
     };
 }
+/**
+ * The **grid populations** behind {@link buildTicks}' labels: every ladder rung
+ * that fits `cap` lines, each carrying its FULL anchor population — every
+ * aligned clock instant, every session open, every month / quarter / year
+ * start — finest rung first. The axis *labels* are a thinned subset of one
+ * rung; the grid is the calendar structure itself, so the container draws
+ * every anchor of each returned level and fades a level's lines by their pixel
+ * spacing (a crowding level dissolves while the coarser ones persist — the
+ * map-style hierarchical grid). Levels **nest** (a month start is a session
+ * open; an aligned hour sits inside its session; there is no week rung), so a
+ * consumer de-duplicates shared anchors coarsest-first and each line draws
+ * once, at its coarsest membership's (widest-spaced, so strongest) alpha.
+ *
+ * `cap` is the max lines per level — the caller derives it from plot width ÷
+ * the fade-out spacing, so a level too dense to be visible at all is simply
+ * absent rather than enumerated and thrown away. Sub-day rungs are gated on
+ * the live-span estimate first (like {@link buildTicks}) and skipped when they
+ * add no anchor beyond the session opens themselves (that is the day level).
+ */
+export function buildGridLevels(provider, opens, domainEnd, cap) {
+    const out = [];
+    if (cap < 1 || opens.length === 0)
+        return out;
+    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 budget = cap + opens.length + 4;
+        const anchors = stepAnchors(provider, opens, domainEnd, step, budget);
+        if (anchors.length > budget)
+            continue;
+        if (anchors.length > opens.length) {
+            out.push({ granularity: g, values: anchors });
+        }
+    }
+    if (opens.length <= cap) {
+        out.push({ granularity: 'day', values: [...opens] });
+    }
+    for (const g of COARSENING_LADDER) {
+        const values = firstOfEachBucket(opens, g);
+        if (values.length <= cap)
+            out.push({ granularity: g, values });
+    }
+    return out;
+}
+/**
+ * The **nominal wall-clock step** of grain `g` in ms — the calendar time one
+ * grid cell of that grain covers (a day is a day whether or not its weekend
+ * neighbours are drawn; a month is ~30.44 days). This is what the grid's
+ * density fade keys off: `width × step / wallSpan` is a grain's spacing on a
+ * gap-free axis, and using it (rather than the measured on-screen gaps) makes
+ * the fade **mode-invariant** — collapsing weekends draws fewer day lines at
+ * the *same* strength, instead of wider-spaced lines that jump to full
+ * opacity at the same zoom.
+ */
+export function nominalStepMs(g) {
+    const sub = SUB_DAY_GRAINS.find((r) => r.g === g);
+    if (sub !== undefined)
+        return sub.step;
+    switch (g) {
+        case 'day':
+            return DAY_MS;
+        case 'week':
+            return 7 * DAY_MS;
+        case 'month':
+            return DAYS_PER_MONTH * DAY_MS;
+        case 'quarter':
+            return 3 * DAYS_PER_MONTH * DAY_MS;
+        default:
+            // 'year' (the sub-day grains are handled above).
+            return 365.25 * DAY_MS;
+    }
+}
+/**
+ * Whether `t` sits exactly on a calendar instant of grain `g` — a local
+ * midnight at day grain, a month / quarter / year start, a clock-aligned
+ * step multiple (relative to `t`'s own local midnight, the same convention
+ * as {@link nextAligned}) on the sub-day rungs. The window-edge genuineness
+ * test in {@link buildTicks} — the only way a **continuous** axis's edge tick
+ * survives, since a gap-free provider has no dead time to probe.
+ *
+ * The sub-day test shares {@link nextAligned}'s **fixed-elapsed-ms** rung
+ * convention **by design** — so an edge tick is judged aligned iff it is one
+ * of the instants {@link stepAnchors} would actually generate. On the two DST
+ * transition days a wall-clock `03:00` is then *not* "aligned" to `hour3`
+ * (only 2h elapsed since midnight) while `04:00` is — the same drift the
+ * anchors themselves take, and the already-deferred exchange-tz grain
+ * refinement (see `nextAligned`), not a fresh inconsistency. It only decides
+ * whether the *window-edge* tick is kept on those days — nil practical impact
+ * (Codex review, #479).
+ */
+function alignedToGrain(t, g) {
+    const d = new Date(t);
+    const midnight = new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+    const sub = SUB_DAY_GRAINS.find((r) => r.g === g);
+    if (sub !== undefined)
+        return (t - midnight) % sub.step === 0;
+    if (t !== midnight)
+        return false;
+    switch (g) {
+        case 'month':
+            return d.getDate() === 1;
+        case 'quarter':
+            return d.getDate() === 1 && d.getMonth() % 3 === 0;
+        case 'year':
+            return d.getDate() === 1 && d.getMonth() === 0;
+        default:
+            // 'day' (and the unreachable 'week' — there is no week rung).
+            return true;
+    }
+}
 /** 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
@@ -144,8 +481,8 @@ function stepAnchors(provider, opens, domainEnd, stepMs, cap) {
 /**
  * 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.
+ * then day (thinned by a per-month uniform session stride) → 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
@@ -166,7 +503,21 @@ export function buildTicks(provider, opens, domainEnd, cap) {
             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);
+                // The estimate can undercount the real anchor count by up to one
+                // phase tick per session (each session's aligned marks can exceed
+                // floor(sessionSpan/step) by one, and per-session floors sum below
+                // the floor of the sum), so the enumeration budget must cover
+                // cap + opens.length or a near-cap multi-session window truncates.
+                // A truncated array must never be returned: it passes the
+                // earns-its-labels check below while leaving the later sessions
+                // with no ticks at all (a lopsided axis) — if the budget is still
+                // exceeded (multiple live segments per session can add further
+                // phase ticks), try the coarser rungs, whose smaller estimates
+                // leave the budget room to finish.
+                const budget = cap + opens.length + 4;
+                const ticks = stepAnchors(provider, opens, domainEnd, step, budget);
+                if (ticks.length > budget)
+                    continue;
                 // 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
@@ -177,7 +528,13 @@ export function buildTicks(provider, opens, domainEnd, cap) {
             }
             return { ticks: [...opens], granularity: 'day' };
         }
-        return coarsenCalendar(opens, cap);
+        // Pass the domain's **calendar-day span** (wall time, domain start → end)
+        // so the day-stride is picked from a quantity that's constant at a fixed
+        // zoom — panning slides the window but never changes it, so the marks stay
+        // put instead of reshuffling when the enumerated open count wobbles ±1.
+        // The provider routes the day band to session-index space (screen-even
+        // marks; see subdivideMonthsBySession).
+        return coarsenCalendar(opens, cap, (domainEnd - opens[0]) / DAY_MS, provider);
     })();
     // Round anchors to integer milliseconds: a pan/zoom domain comes from
     // `scale.invert(pixel)` and is fractional, and a fractional anchor breaks
@@ -186,14 +543,38 @@ export function buildTicks(provider, opens, domainEnd, cap) {
     // 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.
+    // Drop the **window-edge rider**: the first tick is `opens[0]` (the raw
+    // domain start), which is a calendar anchor only when it happens to BE one.
+    // A mid-period edge otherwise becomes a tick pinned at x=0 that relabels
+    // itself as the window pans (`8 → 9 → 10` mid-day, a `15:23` under an hour
+    // grain) — sticky and misleading (owner, 2026-07-16); TradingView never
+    // labels the window edge. Genuine ⇔ the instant is **live** and either a
+    // true session open (dead time immediately before — incl. the calendar's
+    // absolute start) or sits **exactly on a calendar instant of the chosen
+    // grain** (a midnight at day grain, a month start at month grain, a clock
+    // multiple on an hour rung) — the latter is how a gap-free continuous axis,
+    // which has no dead time to probe, keeps a window cut exactly on a boundary
+    // (a Jan-1-to-Jan-1 year fixture keeps its `2026`). Probe the **rounded**
+    // tick `edge` (what actually renders), not the raw fractional `opens[0]`:
+    // a fractional pan/zoom start that rounds onto a grain instant is aligned
+    // by the value the reader sees, and the two agree exactly on the integer-ms
+    // instants that aren't pan/zoom-derived.
     const t = result.ticks;
+    if (t.length > 0 && t[0] === Math.round(opens[0])) {
+        const edge = t[0];
+        const genuine = provider.distance(edge, edge + 1) > 0 && // live (a dead edge never ticks)
+            (provider.distance(edge - 1, edge) === 0 || // a session open, or…
+                alignedToGrain(edge, result.granularity)); // …exactly on the grain
+        if (!genuine)
+            t.shift();
+    }
+    // Drop a cramped **leading partial-period** anchor: a genuine first tick
+    // (a "1Y back from today" view starting exactly on a mid-month session)
+    // can still 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.
     if (t.length >= 3 &&
         provider.distance(t[0], t[1]) < 0.5 * provider.distance(t[1], t[2])) {
         t.shift();
@@ -254,6 +635,124 @@ export function majorFormatFor(g) {
 export function boundaryFormatFor(g) {
     return g === 'day' ? '%b %d' : '%Y';
 }
+// --- Stacked date **bands** (the segmented second row; owner design 2026-07-16) ---
+//
+// The stacked style's second row is a strip of segmented **bands** — one per
+// next-coarser calendar period, labelled at its left edge, zebra-shaded, with a
+// divider at each turn. `bandGrainFor` is the band grain, one step finer than
+// {@link boundaryGrainFor}'s day→year jump: sub-day ticks band by DAY, day/week
+// ticks by MONTH (not year), month/quarter ticks by YEAR. The matching top row
+// reads the terse unit ({@link flatBaseFormatFor}) with the band-turn tick
+// emphasized; a year-grain axis has no band row (nothing coarser to show here).
+/** The **band grain** under `g`-grain ticks (the segmented stacked second row):
+ *  the next coarser unit — sub-day → day, day/week → month, month/quarter →
+ *  year, year → none. */
+export function bandGrainFor(g) {
+    if (isSubDay(g))
+        return 'day';
+    switch (g) {
+        case 'day':
+        case 'week':
+            return 'month';
+        case 'month':
+        case 'quarter':
+            return 'year';
+        default:
+            return undefined; // year — no coarser band
+    }
+}
+/**
+ * d3 specifier for the **cursor / marker readout** at grain `g` — a hovered
+ * instant formatted at the axis's own granularity, never finer. A day-or-coarser
+ * axis reads a **date** (no time-of-day), so a daily bar at a foreign-tz
+ * midnight can't render as `02 AM`; a sub-day axis reads date **+** clock. This
+ * is the grain-aware default that replaces d3's multi-scale default for the
+ * readout (a `cursorFormat` override, when given, wins over it). Unambiguous by
+ * design — the readout carries the year / date the terse tick labels omit.
+ */
+export function readoutFormatFor(g) {
+    if (g === 'second1' ||
+        g === 'second5' ||
+        g === 'second15' ||
+        g === 'second30')
+        return '%b %-d, %H:%M:%S';
+    if (isSubDay(g))
+        return '%b %-d, %H:%M';
+    switch (g) {
+        case 'day':
+        case 'week':
+            return '%b %-d, %Y';
+        case 'month':
+        case 'quarter':
+            return '%b %Y';
+        default:
+            return '%Y'; // year
+    }
+}
+/** d3 specifier for a **band** label at band grain `g`: the date for a day band
+ *  (`Jan 12`), the full month for a month band (`January`), the year for a year
+ *  band (`2031`). Left-aligned in the band by the renderer. */
+export function bandFormatFor(g) {
+    switch (g) {
+        case 'day':
+            return '%b %-d';
+        case 'month':
+            return '%B';
+        default:
+            return '%Y'; // year (band grains are only day / month / year)
+    }
+}
+/**
+ * The **zebra parity** of the band starting at `t` (band grain `g`) — `true`
+ * when the band is shaded. A stable, pan/zoom-invariant flag derived from the
+ * band's own calendar identity: the year number, the months-since-epoch, or
+ * the **UTC**-day index (UTC so a DST shift never flips a band's shade). Odd
+ * index → shaded, matching the reference frames (2031 / 2033 grey).
+ *
+ * Parity is **absolute** (per calendar period), not per-visible-position — the
+ * price of pan-stability. Calendar-consecutive bands always differ, and
+ * collapsed **weekends** stay clean (Fri→Mon is a 3-index step, odd), but a
+ * lone skipped weekday — a single **holiday**, a 2-index step — can place two
+ * same-shade day-bands side by side on a gappy calendar. A rare, cosmetic
+ * consequence of keeping the shade fixed to the date rather than the slot.
+ */
+export function bandShaded(t, g) {
+    const d = new Date(t);
+    let index;
+    switch (g) {
+        case 'day':
+            // UTC of the local Y/M/D — an integer calendar-day count, DST-immune.
+            index = Math.floor(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()) / 86_400_000);
+            break;
+        case 'month':
+            index = d.getFullYear() * 12 + d.getMonth();
+            break;
+        default: // year
+            index = d.getFullYear();
+    }
+    return ((index % 2) + 2) % 2 === 1;
+}
+/** The local-time start of the band grain `g` containing `t` (the band's left
+ *  edge): local midnight, month start, or Jan 1. Through the Date ctor so DST
+ *  and month/year overflow normalize correctly. */
+export function bandStartOf(t, g) {
+    const d = new Date(t);
+    if (g === 'day')
+        return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+    if (g === 'month')
+        return new Date(d.getFullYear(), d.getMonth(), 1).getTime();
+    return new Date(d.getFullYear(), 0, 1).getTime(); // year
+}
+/** The start of the band grain `g` **after** the one containing `t` — the next
+ *  local midnight / month start / Jan 1. */
+export function bandNext(t, g) {
+    const d = new Date(t);
+    if (g === 'day')
+        return new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1).getTime();
+    if (g === 'month')
+        return new Date(d.getFullYear(), d.getMonth() + 1, 1).getTime();
+    return new Date(d.getFullYear() + 1, 0, 1).getTime(); // year
+}
 /**
  * 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
@@ -283,4 +782,114 @@ export function boundaryTicks(ticks, granularity, domainStart) {
     }
     return out;
 }
+/**
+ * The calendar units a **flat**-style tick can be promoted to, coarsest first —
+ * the levels coarser than a tick's own label that a single-row axis relabels an
+ * opening tick to. A sub-day tick can open a date / month / year; a day or week
+ * tick a month / year; a month or quarter tick a year; a year tick nothing.
+ */
+function flatPromotionLevels(g) {
+    if (isSubDay(g))
+        return ['year', 'month', 'day'];
+    switch (g) {
+        case 'day':
+        case 'week':
+            return ['year', 'month'];
+        case 'month':
+        case 'quarter':
+            return ['year'];
+        default:
+            // 'year' (and, unreachably, the sub-day grains handled above).
+            return [];
+    }
+}
+/**
+ * The terse **base** (non-promoted) flat label format for grain `g` — the label
+ * a tick carries when it opens no coarser period: the clock time for a sub-day
+ * grain, a bare day-of-month for day / week (`5`, not `Jan 5` — the month rides
+ * the promoted month-start tick), the month abbrev for month / quarter, the
+ * year for year. Terser than {@link majorFormatFor} (which carries the month on
+ * every day tick) because the flat row leans on inline promotions for context.
+ */
+export function flatBaseFormatFor(g) {
+    if (isSubDay(g)) {
+        return g.startsWith('second') ? '%H:%M:%S' : '%H:%M';
+    }
+    switch (g) {
+        case 'day':
+        case 'week':
+            return '%-d';
+        case 'month':
+        case 'quarter':
+            return '%b';
+        default:
+            // 'year' (sub-day grains are handled by the isSubDay branch above).
+            return '%Y';
+    }
+}
+/**
+ * The flat label format for a tick **promoted** to calendar level `level`. A
+ * day turn keeps its month (`Jan 5`) so an intraday day boundary reads
+ * unambiguously among clock ticks; a month turn shows the bare month, a year
+ * turn the year. Only `day` / `month` / `year` are produced by
+ * {@link flatPromotionLevels}; other levels fall back to their major format.
+ */
+function flatPromotionFormatFor(level) {
+    switch (level) {
+        case 'day':
+            return '%b %-d';
+        case 'month':
+            return '%b';
+        case 'year':
+            return '%Y';
+        default:
+            return majorFormatFor(level);
+    }
+}
+/**
+ * The **flat** (single-row) label format specifier for each tick, parallel to
+ * `ticks` (already at grain `granularity`). Each tick shows the coarsest
+ * calendar period it *opens* — a year / month / date promotion — and its terse
+ * {@link flatBaseFormatFor} label otherwise, so the one row reads
+ * `… 30 31 Feb 2 3 …` with `Feb` where the month turns and the year where it
+ * turns. A tick "opens" level L when its L-bucket differs from the previous
+ * tick's; the coarsest changed level wins (a Jan-1 tick promotes to the year,
+ * not the month).
+ *
+ * `domainStart` seeds the walk (like {@link boundaryTicks}): the first tick is
+ * promoted only if it crosses a period relative to the instant just *before*
+ * the domain's left edge — so a window opening mid-month doesn't falsely
+ * promote its first tick (and a live sliding window doesn't flicker the
+ * leftmost label), while a domain starting *exactly* on a boundary still
+ * promotes the boundary tick (it truly is the period's first instant: a window
+ * opening at May 1 midnight reads `May 16 …`, not `1 16 …`). Without
+ * `domainStart` the first tick is never promoted.
+ */
+export function flatFormats(ticks, granularity, domainStart) {
+    const base = flatBaseFormatFor(granularity);
+    const levels = flatPromotionLevels(granularity);
+    // Last-seen bucket per level; seeded from just before the domain start so a
+    // first tick sharing the edge's period isn't a crossing, but one exactly ON
+    // the period boundary is.
+    const prev = new Map();
+    if (domainStart !== undefined) {
+        for (const L of levels)
+            prev.set(L, bucketKey(domainStart - 1, L));
+    }
+    return ticks.map((t) => {
+        let spec = base;
+        let promoted = false;
+        for (const L of levels) {
+            const k = bucketKey(t, L);
+            // Coarsest changed level wins; still update every level's bucket so a
+            // year turn (which also turns the month/day) leaves them all current.
+            if (!promoted && prev.has(L) && prev.get(L) !== k) {
+                spec = flatPromotionFormatFor(L);
+                promoted = true;
+            }
+            prev.set(L, k);
+        }
+        return spec;
+    });
+}
 //# sourceMappingURL=tickLadder.js.map