@pond-ts/charts 0.44.1 → 0.46.0

package/dist/annotations.d.ts

@@ -15,7 +15,7 @@ import { type AnnotationSpec, type ContainerFrame, type LabelPlacement } from '.
  *   the next free lane. The `draggingKey` is excluded (pinned to lane 0, its own
  *   label) so the static labels hold their lanes as it crosses them.
  */
-export declare function computeLabelLanes(annotations: readonly AnnotationSpec[], toPixel: (axisX: number) => number, draggingKey?: symbol | null): Map<symbol, LabelPlacement>;
+export declare function computeLabelLanes(annotations: readonly AnnotationSpec[], toPixel: (axisX: number) => number, draggingKey?: symbol | null, plotWidth?: number): Map<symbol, LabelPlacement>;
 /**
  * Snap a dragged plot-pixel `px` to the nearest **guideline** within
  * {@link SNAP_PX} — another annotation's x, **or** a trading-axis **disjoint

package/dist/annotations.js

@@ -169,7 +169,7 @@ const labelWidth = (text) => text.length * LABEL_CHAR_W + LABEL_PAD;
  *   the next free lane. The `draggingKey` is excluded (pinned to lane 0, its own
  *   label) so the static labels hold their lanes as it crosses them.
  */
-export function computeLabelLanes(annotations, toPixel, draggingKey) {
+export function computeLabelLanes(annotations, toPixel, draggingKey, plotWidth) {
     const out = new Map();
     const byRow = new Map();
     for (const a of annotations) {
@@ -195,22 +195,33 @@ export function computeLabelLanes(annotations, toPixel, draggingKey) {
                     markerGroups.set(a.xs[0], [a]);
             }
             else {
+                // Lane-pack at the position the chip will *render*: a region panned
+                // half off-plot renders clamped to the plot's left edge, and a fully
+                // off-plot region's chip is culled — so it must not hold a lane.
                 const ax = a.kind === 'region' ? Math.min(a.xs[0], a.xs[1]) : a.xs[0];
+                const bx = a.kind === 'region' ? Math.max(a.xs[0], a.xs[1]) : a.xs[0];
+                const rawLeft = toPixel(ax);
+                if (plotWidth !== undefined && (rawLeft > plotWidth || toPixel(bx) < 0))
+                    continue;
                 flags.push({
                     rep: a.key,
                     members: [a.key],
-                    left: toPixel(ax),
+                    left: plotWidth === undefined ? rawLeft : Math.max(rawLeft, 0),
                     width: labelWidth(a.label),
                     label: a.label,
                 });
             }
         }
         for (const [x, group] of markerGroups) {
+            // A culled off-plot marker chip must not hold a lane either.
+            const px = toPixel(x);
+            if (plotWidth !== undefined && (px < 0 || px > plotWidth))
+                continue;
             const label = group.map((g) => g.label).join(', ');
             flags.push({
                 rep: group[0].key,
                 members: group.map((g) => g.key),
-                left: toPixel(x),
+                left: px,
                 width: labelWidth(label),
                 label,
             });
@@ -473,7 +484,7 @@ export function Marker({ at, label, id, selected = false, selectable = true, hov
     // into a lower lane doesn't leave line poking above it. No label ⇒ full height.
     const staffTop = text ? FLAG_TOP + lane * LANE_H : 0;
     return (_jsxs(_Fragment, { children: [_jsxs("svg", { width: container.plotWidth, height: h, style: overlayStyle, children: [_jsx("line", { x1: x, y1: staffTop, x2: x, y2: h, stroke: ann.color, strokeWidth: 1, opacity: opacity, shapeRendering: "crispEdges" }), showHandle && (_jsx(Pill, { cx: x, cy: h / 2, w: HANDLE_SHORT, h: HANDLE_LONG, color: ann.color })), selectable && (_jsx(DragArea, { x: x - HIT_PAD, y: 0, w: 2 * HIT_PAD, h: h, cursor: editing ? 'ew-resize' : 'inherit', editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDrag: (px) => onChange?.(snapToGuides(container, selfKey, px) ??
-                            +container.xScale.invert(px)) }))] }), chipLabel && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
+                            +container.xScale.invert(px)) }))] }), chipLabel && x >= 0 && x <= container.plotWidth && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
                     top: `${FLAG_TOP + lane * LANE_H}px`,
                     ...flagChipX(x, container.plotWidth),
                 }, children: chipLabel }))] }));
@@ -618,9 +629,9 @@ export function Region({ from, to, label, id, selected = false, selectable = tru
                                             +container.xScale.invert(px), edgeRef.current ?? to)) }), _jsx(DragArea, { x: xb - EDGE_GRAB / 2, y: 0, w: EDGE_GRAB, h: h, cursor: "ew-resize", editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDragStart: () => {
                                             edgeRef.current = from; // the fixed pivot = the near edge
                                         }, onDrag: (px) => onChange?.(orderRegion(snapToGuides(container, selfKey, px) ??
-                                            +container.xScale.invert(px), edgeRef.current ?? from)) })] }))] }))] }), text && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
+                                            +container.xScale.invert(px), edgeRef.current ?? from)) })] }))] }))] }), text && left <= container.plotWidth && left + spanW >= 0 && (_jsx(Chip, { theme: container.theme, color: ann.color, style: {
                     top: `${FLAG_TOP + lane * LANE_H}px`,
-                    ...flagChipX(left, container.plotWidth),
+                    ...flagChipX(Math.max(left, 0), container.plotWidth),
                 }, children: text }))] }));
 }
 //# sourceMappingURL=annotations.js.map

package/dist/context.d.ts

@@ -151,6 +151,10 @@ export interface ContainerFrame {
     /** Format an epoch-ms instant the same way the time axis labels its ticks —
      *  shared by `<TimeAxis>` and the cursor-time readout. */
     readonly formatTime: (epochMs: number) => string;
+    /** Whether an explicit container `timeFormat` shaped {@link formatTime}. The
+     *  x axis suppresses its boundary (second) label row when it's set — a
+     *  custom format owns the whole label, so the ladder mustn't second-line it. */
+    readonly xFormatCustom: boolean;
     /**
      * The shared **x-side tick count** — the `count` every x-side `ticks()` /
      * `tickFormat()` call passes (`<XAxis>` labels, the canvas x gridlines and

package/dist/derivedTicks.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tick layout for a **derived-unit axis** — a second labeling of the same
+ * scale (`<XAxis transform>`): strike relabelled as moneyness, std-moneyness
+ * relabelled as BS delta. The transform may be nonlinear, which stretches or
+ * compresses the derived unit across the pixel range — so a single uniform
+ * step can't work (uniform delta ticks pile up mid-axis and leave the
+ * stretched wings empty). Instead: a **pixel-aware multi-resolution fill** —
+ * walk nice step sizes (the 1-2-5 ladder) coarsest→finest, admitting each
+ * candidate tick wherever it keeps `minPx` of room from every tick already
+ * placed. A compressed span ends up with coarse ticks, a stretched span picks
+ * up finer ones (the reference look: `0.10`-step deltas mid-axis, `0.45 /
+ * 0.49` out in the wings). A linear transform degenerates to ordinary
+ * evenly-spaced nice ticks through the same code path.
+ */
+/** A derived-unit transform: `to`/`from` are monotonic inverses (either
+ *  direction — a decreasing transform is fine); they may be nonlinear. */
+export interface AxisTransform {
+    /** Axis value → derived unit (e.g. strike → moneyness). */
+    to(value: number): number;
+    /** Derived unit → axis value (inverse of {@link to}). */
+    from(unit: number): number;
+}
+/** One derived tick: its value in the derived unit and its plot pixel. */
+export interface DerivedTick {
+    readonly u: number;
+    readonly x: number;
+}
+/**
+ * Compute the derived-unit ticks: nice values in `transform.to`-space at
+ * mixed 1-2-5 step sizes, greedily admitted coarsest-first wherever the
+ * mapped pixel keeps `minPx` from every tick already placed (and stays inside
+ * `[0, plotWidth]`). Returns ticks sorted by pixel. Pure — unit-testable
+ * without a DOM.
+ */
+export declare function derivedTicks(transform: AxisTransform, domain: readonly [number, number], toPixel: (value: number) => number, plotWidth: number, minPx: number): DerivedTick[];
+//# sourceMappingURL=derivedTicks.d.ts.map

package/dist/derivedTicks.js

@@ -0,0 +1,92 @@
+/**
+ * Tick layout for a **derived-unit axis** — a second labeling of the same
+ * scale (`<XAxis transform>`): strike relabelled as moneyness, std-moneyness
+ * relabelled as BS delta. The transform may be nonlinear, which stretches or
+ * compresses the derived unit across the pixel range — so a single uniform
+ * step can't work (uniform delta ticks pile up mid-axis and leave the
+ * stretched wings empty). Instead: a **pixel-aware multi-resolution fill** —
+ * walk nice step sizes (the 1-2-5 ladder) coarsest→finest, admitting each
+ * candidate tick wherever it keeps `minPx` of room from every tick already
+ * placed. A compressed span ends up with coarse ticks, a stretched span picks
+ * up finer ones (the reference look: `0.10`-step deltas mid-axis, `0.45 /
+ * 0.49` out in the wings). A linear transform degenerates to ordinary
+ * evenly-spaced nice ticks through the same code path.
+ */
+/** The largest 1-2-5 nice step ≤ `span` (so the coarsest level yields at
+ *  least one interval across the domain). */
+function firstStep(span) {
+    const pow = 10 ** Math.floor(Math.log10(span));
+    for (const m of [5, 2, 1]) {
+        if (m * pow <= span)
+            return m * pow;
+    }
+    return pow / 2; // span < pow can't happen (pow ≤ span), belt-and-braces
+}
+/** The next step down the 1-2-5 ladder: 5→2→1→0.5→0.2→0.1… */
+function nextFiner(step) {
+    const pow = 10 ** Math.floor(Math.log10(step));
+    const m = Math.round(step / pow);
+    if (m === 5)
+        return 2 * pow;
+    if (m === 2)
+        return pow;
+    return pow / 2;
+}
+/** Per-level enumeration cap — a backstop against a pathological transform
+ *  requesting a step so fine the candidate walk explodes. Generous: the
+ *  reference delta axis enumerates ~100 candidates at its finest level. */
+const MAX_CANDIDATES = 4000;
+/**
+ * Compute the derived-unit ticks: nice values in `transform.to`-space at
+ * mixed 1-2-5 step sizes, greedily admitted coarsest-first wherever the
+ * mapped pixel keeps `minPx` from every tick already placed (and stays inside
+ * `[0, plotWidth]`). Returns ticks sorted by pixel. Pure — unit-testable
+ * without a DOM.
+ */
+export function derivedTicks(transform, domain, toPixel, plotWidth, minPx) {
+    const ua = transform.to(domain[0]);
+    const ub = transform.to(domain[1]);
+    const u0 = Math.min(ua, ub);
+    const u1 = Math.max(ua, ub);
+    if (!Number.isFinite(u0) ||
+        !Number.isFinite(u1) ||
+        u1 <= u0 ||
+        !(plotWidth > 0)) {
+        return [];
+    }
+    const kept = [];
+    const fits = (x) => x >= 0 && x <= plotWidth && kept.every((k) => Math.abs(k.x - x) >= minPx);
+    // More ticks than the plot has room for can never be admitted.
+    const maxTicks = Math.ceil(plotWidth / minPx) + 2;
+    let step = firstStep(u1 - u0);
+    // An empty level does NOT end the walk: under a nonlinear transform a
+    // pixel-wide gap can have a tiny u-span (the delta wings — no 0.1-grid
+    // value lands in [0.4, 0.4987], but 0.45 on the 0.05 grid does), so finer
+    // levels may fill where a coarser one placed nothing. Several *consecutive*
+    // empty levels mean the remaining gaps' u-spans are being outrun faster
+    // than the ladder descends — give up then (plus the enumeration backstop).
+    let emptyLevels = 0;
+    for (let level = 0; level < 24 && kept.length < maxTicks; level++) {
+        const i0 = Math.ceil(u0 / step - 1e-9);
+        const i1 = Math.floor(u1 / step + 1e-9);
+        if (i1 - i0 > MAX_CANDIDATES)
+            break;
+        let added = 0;
+        for (let i = i0; i <= i1 && kept.length < maxTicks; i++) {
+            // Clean the float (0.3, not 0.30000000000000004) — the raw `u` reaches
+            // a caller-supplied format function, so it must be presentable.
+            const u = Number((i * step).toPrecision(12));
+            const x = toPixel(transform.from(u));
+            if (Number.isFinite(x) && fits(x)) {
+                kept.push({ u, x });
+                added += 1;
+            }
+        }
+        emptyLevels = added === 0 && level > 0 ? emptyLevels + 1 : 0;
+        if (emptyLevels >= 3)
+            break;
+        step = nextFiner(step);
+    }
+    return kept.sort((a, b) => a.x - b.x);
+}
+//# sourceMappingURL=derivedTicks.js.map

package/dist/index.d.ts

@@ -28,6 +28,7 @@ export { YAxis } from './YAxis.js';
 export type { YAxisProps } from './YAxis.js';
 export { XAxis } from './XAxis.js';
 export type { XAxisProps } from './XAxis.js';
+export type { AxisTransform } from './derivedTicks.js';
 export { TimeAxis } from './TimeAxis.js';
 export { CategoryAxis } from './CategoryAxis.js';
 export type { AxisFormat } from './format.js';

package/dist/line.d.ts

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

package/dist/line.js

@@ -53,20 +53,39 @@ export function yExtent(cs) {
  * The generator writes path ops to `ctx`; we bracket with `beginPath`/`stroke`.
  * `cs.y` (a `Float64Array`) is the datum iterable — `y` reads the value, `x`
  * reads `cs.x[i]` by index, so there's no per-point object allocation.
+ *
+ * **`boundaries`** (default none) are discontinuity instants — a trading-axis
+ * session/day/lunch close→open where the line should *break* even though a data
+ * point sits on each side (see {@link sessionRuns}). Each run between boundaries
+ * draws as its own subpath, so the line ends at the last pre-boundary point and
+ * re-starts at the first post-boundary one — a **scale** break, orthogonal to
+ * the NaN **data** gaps (`gaps`) handled within each run. With no boundaries the
+ * output is identical to a single-pass draw.
  */
-export function drawLine(ctx, cs, xScale, yScale, style, curve = curveLinear, gaps = DEFAULT_GAP_MODE, gapConnectorOpacity = DEFAULT_GAP_CONNECTOR_OPACITY) {
-    // `none` interpolates interior gaps so the line bridges them; every other mode
-    // keeps NaN so d3 breaks the solid path (the inferred bridge, if any, is a
-    // separate overlay pass below).
-    const ys = gaps === 'none' ? bridgeGaps(cs.y, cs.length) : cs.y;
-    const gen = d3line()
-        .defined((v) => Number.isFinite(v))
-        .x((_, i) => xScale(cs.x[i]))
-        .y((v) => yScale(v))
-        .curve(curve)
-        .context(ctx);
+export function drawLine(ctx, cs, xScale, yScale, style, curve = curveLinear, gaps = DEFAULT_GAP_MODE, gapConnectorOpacity = DEFAULT_GAP_CONNECTOR_OPACITY, boundaries = []) {
+    // Split into independent index runs at each boundary; no boundary inside the
+    // data ⇒ one run over the whole series (the hot path — no slicing, so the draw
+    // is byte-identical to the pre-boundary single pass).
+    const runs = sessionRuns(cs.x, cs.length, boundaries);
+    const singleRun = runs.length === 1;
+    // Solid pass: one path across every run. Each run's generator opens with its
+    // own moveTo, so a run boundary is a clean pen-up — the session break.
     ctx.beginPath();
-    gen(ys);
+    for (const [s, e] of runs) {
+        // `none` interpolates interior gaps so the line bridges them — but only
+        // *within* a run (a session break is not a dropout to interpolate over);
+        // every other mode keeps NaN so d3 breaks the solid path (the inferred
+        // bridge, if any, is a separate overlay pass below).
+        const seg = singleRun ? cs.y : cs.y.subarray(s, e);
+        const ys = gaps === 'none' ? bridgeGaps(seg, e - s) : seg;
+        const gen = d3line()
+            .defined((v) => Number.isFinite(v))
+            .x((_, j) => xScale(cs.x[s + j]))
+            .y((v) => yScale(v))
+            .curve(curve)
+            .context(ctx);
+        gen(ys);
+    }
     ctx.strokeStyle = style.color;
     ctx.lineWidth = style.width;
     // Per-series dash (a modeled/forecast line reads dashed). Applied only when
@@ -84,8 +103,15 @@ export function drawLine(ctx, cs, xScale, yScale, style, curve = curveLinear, ga
     }
     // Overlay bridges for the inferred-gap modes. `dashed` / `step` are faint
     // dashed connectors (gapConnectorOpacity); only `fade` drops to the axis floor.
+    // Collect edges **per run** so an inferred bridge never spans a session break
+    // (the break wins — no dashed/step/fade connector across a collapsed gap).
     if (gaps === 'dashed' || gaps === 'step' || gaps === 'fade') {
-        const edges = collectGapEdges(cs.length, cs.x, (i) => cs.y[i], xScale, (i) => yScale(cs.y[i]));
+        const edges = [];
+        for (const [s, e] of runs) {
+            const runEdges = collectGapEdges(e - s, singleRun ? cs.x : cs.x.subarray(s, e), (i) => cs.y[s + i], xScale, (i) => yScale(cs.y[s + i]));
+            for (const ed of runEdges)
+                edges.push(ed);
+        }
         if (gaps === 'dashed') {
             drawGapBridges(ctx, edges, style.color, style.width, gapConnectorOpacity);
         }
@@ -97,4 +123,43 @@ export function drawLine(ctx, cs, xScale, yScale, style, curve = curveLinear, ga
         }
     }
 }
+/**
+ * Split a sorted columnar x-axis into contiguous index runs `[start, endEx)`,
+ * cutting wherever a `boundaries` instant falls in `(x[i-1], x[i]]` — i.e. a
+ * discontinuity (a trading session / day / lunch close→open) sits between two
+ * consecutive points. A point that lands exactly on a boundary starts the new
+ * run (the open). No boundary inside the data (or an empty list) ⇒ a single run
+ * over the whole series. This is what turns `<LineChart sessionBreaks>` into a
+ * per-session polyline. Pure + O(N).
+ *
+ * The sweep relies on **ascending** boundaries; the `DiscontinuityProvider`
+ * contract doesn't guarantee order, so an unsorted list is sorted defensively
+ * (a copy, so the caller's array isn't mutated) rather than silently dropping a
+ * break. The list is tiny — one entry per session boundary — so the sort is
+ * negligible next to the row sweep.
+ */
+export function sessionRuns(x, length, boundaries) {
+    if (boundaries.length === 0 || length === 0)
+        return [[0, length]];
+    const bounds = boundaries.length > 1 ? [...boundaries].sort((a, b) => a - b) : boundaries;
+    const runs = [];
+    let start = 0;
+    let bi = 0;
+    for (let i = 1; i < length; i += 1) {
+        const prev = x[i - 1];
+        const cur = x[i];
+        // Skip boundaries at or before the previous point (already behind the pen).
+        while (bi < bounds.length && bounds[bi] <= prev)
+            bi += 1;
+        if (bi < bounds.length && bounds[bi] <= cur) {
+            // A boundary sits in (prev, cur] → break the run before point i.
+            runs.push([start, i]);
+            start = i;
+            while (bi < bounds.length && bounds[bi] <= cur)
+                bi += 1;
+        }
+    }
+    runs.push([start, length]);
+    return runs;
+}
 //# sourceMappingURL=line.js.map

package/dist/tickLadder.d.ts

@@ -0,0 +1,92 @@
+import type { DiscontinuityProvider } from './tradingTimeScale.js';
+/**
+ * The logical tick ladder — grain selection for a time axis. Ticks sit on real
+ * calendar/clock units (1s…30s, 1m…30m, 1H…12H, day / week / month / quarter /
+ * year — the trading-terminal convention), never on even pixel spacing: the
+ * axis walks the ladder finest→coarsest and picks the first grain whose anchor
+ * count fits the width-derived cap. The same ladder serves a **disjoint
+ * trading-calendar** axis (session opens are the day anchors, hour anchors are
+ * generated in live time so they never land in a collapsed gap) and a **plain
+ * continuous** axis (an identity provider whose "sessions" are calendar days).
+ *
+ * Each grain also knows its **boundary grain** — the next-coarser unit its own
+ * label doesn't carry (hours → the date, days/weeks → the month, months →
+ * the year). The axis renders that as a second label row, once per boundary
+ * crossing, so a month row reads `Dec Jan Feb …` with `2026` appearing exactly
+ * where the year turns.
+ */
+/** The calendar grain a run of tick anchors is bucketed to. */
+export type TickGranularity = 'second1' | 'second5' | 'second15' | 'second30' | 'minute1' | 'minute5' | 'minute15' | 'minute30' | 'hour1' | 'hour3' | 'hour6' | 'hour12' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+/**
+ * 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 declare function bucketKey(t: number, g: TickGranularity): number;
+/**
+ * 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 declare function coarsenCalendar(opens: readonly number[], count: number): {
+    ticks: number[];
+    granularity: TickGranularity;
+};
+/**
+ * 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 declare function buildTicks(provider: DiscontinuityProvider, opens: readonly number[], domainEnd: number, cap: number): {
+    ticks: number[];
+    granularity: TickGranularity;
+};
+/**
+ * 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 declare function boundaryGrainFor(g: TickGranularity): TickGranularity | undefined;
+/** d3 time-format specifier for the **major** (first-row) label at grain `g`. */
+export declare function majorFormatFor(g: TickGranularity): string;
+/** 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 declare function boundaryFormatFor(g: TickGranularity): string;
+/**
+ * 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 declare function boundaryTicks(ticks: readonly number[], granularity: TickGranularity, domainStart?: number): number[];
+//# sourceMappingURL=tickLadder.d.ts.map