@pond-ts/charts 0.45.0 → 0.46.0

package/CHANGELOG.md

@@ -8,7 +8,8 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 tag, so this file covers them all. Pre-1.0: minor bumps may include new features
 and type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.45.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.46.0...HEAD
+[0.46.0]: https://github.com/pjm17971/pond-ts/compare/v0.45.0...v0.46.0
 [0.45.0]: https://github.com/pjm17971/pond-ts/compare/v0.44.1...v0.45.0
 [0.44.1]: https://github.com/pjm17971/pond-ts/compare/v0.44.0...v0.44.1
 [0.44.0]: https://github.com/pjm17971/pond-ts/compare/v0.43.0...v0.44.0
@@ -44,6 +45,54 @@ and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.46.0] — 2026-07-14
+
+### Changed
+
+- **charts:** the boundary (second-row) axis label's **context** now pins to
+  the plot's left edge instead of riding the first tick: it shows the period
+  the *domain start* is in, and a crossing label sliding toward the edge
+  pushes it off (the sticky-header behavior). On a live sliding window the
+  old first-tick anchoring made `Jan 01` hop tick-to-tick as ticks scrolled
+  out; pinned, it stays put until the period actually changes. Crossing
+  labels (day/year turns) still ride their ticks — including a first tick
+  whose period differs from the domain start's. `TradingTimeScale` gains
+  `boundaryContext(count)`; `tickBoundaries` now labels crossings only.
+
+### Fixed
+
+- **charts:** a live (sliding-window) time axis no longer flickers between two
+  tick grains: the clock-rung choice now derives from the window's live span
+  (constant while sliding) instead of the enumerated anchor count, which
+  oscillates ±1 with the window's phase and flipped the grain for single
+  frames whenever it sat exactly at the width-derived cap.
+
+### Added
+
+- **charts:** **dual x-axes** — two tick layouts on one shared scale. A second
+  `<XAxis>` stacks by declaration order (above/below the plot, either side,
+  same side twice); the new **`transform`** prop (`{ to, from }`, exported
+  `AxisTransform`) relabels an axis into a derived unit: strike ↔ moneyness on
+  a top axis, or a nonlinear BS-delta strip under a std-moneyness chart. Ticks
+  are nice derived-unit values chosen by a pixel-aware multi-resolution fill
+  (1-2-5 steps, coarsest first, admitted where they keep room), so a span the
+  transform compresses gets coarse ticks and a stretched span picks up finer
+  ones — and a label-honesty filter drops any tick whose formatted label would
+  lie about its position. Gridlines stay on the container's primary ticks; the
+  cursor pill on a transformed axis reads in the derived unit. Stories under
+  `Charts/Axes/DualX`. Each `<XAxis>` **and `<YAxis>`** also takes a
+  per-instance **`color`** (labels, tick marks, rule, title) — the lever that
+  distinguishes stacked x strips (a blue delta strip under a grey primary) and
+  colours a y axis to match its series (the dual-axis convention).
+
+### Fixed
+
+- **charts:** annotation label chips now clip to the plot: a marker whose pole
+  pans off-plot no longer leaves its chip floating in the axis gutter, and a
+  partially visible region's chip clamps to the plot's left edge (culled only
+  when the region is entirely out of view). The lines/fills were already
+  SVG-clipped — only the DOM chips escaped.
+
 ## [0.45.0] — 2026-07-14
 
 ### Added

package/dist/ChartContainer.js

@@ -470,7 +470,7 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
     }, [cursorX, xScale, sources, plotWidth]);
     // Pack overlapping top-flag labels (markers + regions) into stacked lanes so
     // close-in-x labels don't collide; chips read their lane back off the frame.
-    const labelLanes = useMemo(() => computeLabelLanes(annotations, (v) => xScale(v), draggingKey), [annotations, xScale, draggingKey]);
+    const labelLanes = useMemo(() => computeLabelLanes(annotations, (v) => xScale(v), draggingKey, plotWidth), [annotations, xScale, draggingKey]);
     const frame = useMemo(() => ({
         timeRange: [d0, d1],
         width,

package/dist/XAxis.d.ts

@@ -1,3 +1,4 @@
+import { type AxisTransform } from './derivedTicks.js';
 import { type AxisFormat } from './format.js';
 export interface XAxisProps {
     /**
@@ -24,6 +25,31 @@ export interface XAxisProps {
         readonly at: number;
         readonly label: string;
     }>;
+    /**
+     * Relabel this axis into a **derived unit on the same scale** — a second
+     * tick layout, not a second scale (the pixel mapping never changes). E.g. a
+     * BS-delta strip under a std-moneyness chart (`transform={{ to: sigmaToDelta,
+     * from: deltaToSigma }}`) or a moneyness axis over a strike chart
+     * (`transform={{ to: (k) => k / spot, from: (m) => m * spot }}`). `to`/`from`
+     * are monotonic inverses (either direction); they may be **nonlinear** —
+     * ticks are nice derived-unit values at mixed 1-2-5 step sizes, admitted
+     * wherever they keep pixel room, so a span the transform compresses gets
+     * coarser ticks and a span it stretches gets finer ones. `format` (or the
+     * d3 number default) formats the derived values; the cursor pill and marker
+     * indicators on this axis read in the derived unit too. Ignored on a
+     * category axis; explicit {@link ticks} win. Typically used on a second
+     * `<XAxis>` stacked with the primary one — declaration order places the
+     * strips; gridlines stay on the container's own (primary) ticks.
+     */
+    transform?: AxisTransform;
+    /**
+     * This axis instance's colour — tick marks, labels, the plot-facing rule,
+     * and the `label` title all take it, overriding the theme's `axis.label` /
+     * `axis.grid` / `axis.title.color`. The lever that distinguishes stacked
+     * dual axes (a blue derived-unit strip under a grey primary). Cursor and
+     * marker pills keep their own colours. Omit for the theme's axis colours.
+     */
+    color?: string;
     /**
      * Horizontal placement of each tick label relative to its tick.
      * - **`'center'` (default)** — every label centred on its tick. Note the
@@ -48,5 +74,5 @@ export interface XAxisProps {
  *
  * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
  */
-export declare function XAxis({ format, label, side, height, ticks: customTicks, align, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function XAxis({ format, label, side, height, ticks: customTicks, transform, color, align, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=XAxis.d.ts.map

package/dist/XAxis.js

@@ -1,5 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Fragment, useContext } from 'react';
+import { scaleLinear } from 'd3-scale';
+import { derivedTicks } from './derivedTicks.js';
 import { ContainerContext } from './context.js';
 import { axisPillStyle } from './chip.js';
 import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
@@ -9,6 +11,10 @@ const TICK_STRIP = 22;
 const LABEL_STRIP = 16;
 /** Extra height reserved for the boundary (second) label row. */
 const BOUNDARY_STRIP = 15;
+/** Minimum pixel gap between derived-unit (`transform`) ticks — the room a
+ *  short numeric label needs plus breathing space, in the spirit of the
+ *  ladder's per-tick budget (a hair tighter: derived labels are short). */
+const TRANSFORM_TICK_PX = 48;
 /**
  * Thin + truncate a **category** axis's labels so a dense axis stays legible: keep
  * every `stride`-th label (so a kept label has room), and ellipsize one that still
@@ -49,7 +55,7 @@ function thinCategoryLabels(ticks, plotWidth, fontSize) {
  *
  * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
  */
-export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, align = 'center', } = {}) {
+export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, transform, color, align = 'center', } = {}) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<XAxis> must be rendered inside a <ChartContainer>');
@@ -69,19 +75,37 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
         cursorX <= plotWidth;
     const cursorColor = theme.cursor ?? theme.axis.label;
     const annotationColor = theme.annotation?.color ?? '#0d9488';
+    // Derived-unit (`transform`) layout: nice ticks in the derived unit at
+    // mixed step sizes, admitted where they keep pixel room (see derivedTicks).
+    // Explicit `ticks` win; a category axis has no numeric unit to derive from.
+    const derived = transform !== undefined && xKind !== 'category' && customTicks === undefined
+        ? derivedTicks(transform, xScale.domain(), (v) => xScale(v), plotWidth, TRANSFORM_TICK_PX)
+        : null;
+    // Formatter for derived-unit values — `format` resolved against a u-space
+    // linear scale (so `'+.2f'` and the d3 number default both work).
+    const uFmt = transform !== undefined && xKind !== 'category'
+        ? (() => {
+            const [d0, d1] = xScale.domain();
+            const u = [transform.to(d0), transform.to(d1)].sort((a, b) => a - b);
+            return resolveAxisFormat(scaleLinear().domain(u), xTickCount, format);
+        })()
+        : null;
     // Tick formatter: an explicit `format` is resolved against the axis kind
     // (a time specifier through the time scale, a number specifier through the
     // value scale); otherwise the container's shared formatter — the one the
-    // cursor readout uses, so a tick and the cursor read identically.
-    const fmt = 
-    // A category axis labels by name (the container's `formatTime` = the band
-    // scale's label lookup); a d3 number/time `format` can't name a category, so
-    // it's ignored here (customize the labels in the `categories` data instead).
-    format === undefined || xKind === 'category'
-        ? formatTime
-        : xKind === 'time'
-            ? resolveTimeFormat(xScale, xTickCount, format)
-            : resolveAxisFormat(xScale, xTickCount, format);
+    // cursor readout uses, so a tick and the cursor read identically. On a
+    // transformed axis every readout (cursor pill, marker indicator) speaks the
+    // **derived unit** — the axis's own language.
+    const fmt = transform !== undefined && uFmt !== null && xKind !== 'category'
+        ? (v) => uFmt(transform.to(v))
+        : // A category axis labels by name (the container's `formatTime` = the band
+            // scale's label lookup); a d3 number/time `format` can't name a category, so
+            // it's ignored here (customize the labels in the `categories` data instead).
+            format === undefined || xKind === 'category'
+                ? formatTime
+                : xKind === 'time'
+                    ? resolveTimeFormat(xScale, xTickCount, format)
+                    : resolveAxisFormat(xScale, xTickCount, format);
     // Marker annotations that opted into an axis indicator (`<Marker indicator>`)
     // pin their **time** to this shared x-axis — a pill at `at`, in the annotation
     // colour, reading like a tick. An indicator always shows the axis coordinate
@@ -136,18 +160,54 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     // custom format owns the whole label, and custom ticks have no grain).
     const boundaryOf = xKind === 'time' &&
         customTicks === undefined &&
+        transform === undefined &&
         format === undefined &&
         !container.xFormatCustom &&
         'tickBoundaries' in xScale
         ? xScale.tickBoundaries(xTickCount)
         : undefined;
+    // The pinned left-edge **context** label — what period the domain starts in
+    // (`Jan 01` over an intraday axis, the year over a month axis). A property
+    // of the domain, not of any tick: anchoring it to the first tick made it
+    // hop tick-to-tick on a live sliding window. Crossing labels ride their
+    // ticks and **push it off** the left edge as they approach (below).
+    const boundaryContext = boundaryOf !== undefined && 'boundaryContext' in xScale
+        ? xScale.boundaryContext(xTickCount)
+        : undefined;
+    // Derived ticks pass a **label-honesty filter**: the fill can descend below
+    // the format's resolution (a delta tick at u = 0.498 renders as "+0.50" under
+    // `+.2f` — a lie about its position), so a tick survives only when its
+    // formatted label parses back to a value that maps to (±1px of) the tick's
+    // own pixel. This also caps density at the format's precision and drops
+    // would-be duplicate labels. Non-numeric labels (a custom format function)
+    // are trusted as-is.
+    const honestDerived = () => {
+        const out = [];
+        const seen = new Set();
+        for (const t of derived) {
+            const text = uFmt(t.u);
+            if (seen.has(text))
+                continue;
+            const back = parseFloat(text.replace(/\u2212/g, '-').replace(/,/g, ''));
+            if (Number.isFinite(back)) {
+                const bx = xScale(transform.from(back));
+                if (!Number.isFinite(bx) || Math.abs(bx - t.x) > 1)
+                    continue;
+            }
+            seen.add(text);
+            out.push({ x: t.x, label: text });
+        }
+        return out;
+    };
     const rawTicks = customTicks
         ? customTicks.map((t) => ({ x: xScale(t.at), label: t.label }))
-        : xScale.ticks(xTickCount).map((d) => ({
-            x: xScale(d),
-            label: fmt(+d),
-            boundary: boundaryOf?.(+d),
-        }));
+        : derived !== null
+            ? honestDerived()
+            : xScale.ticks(xTickCount).map((d) => ({
+                x: xScale(d),
+                label: fmt(+d),
+                boundary: boundaryOf?.(+d),
+            }));
     // A category axis ticks once per category; thin + truncate its labels when they
     // crowd (an explicit `customTicks` axis keeps its labels verbatim).
     const placed = xKind === 'category' && customTicks === undefined && rawTicks.length > 1
@@ -160,7 +220,31 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     // Per-lane vertical step for stacked pills; grow the strip to fit the stack.
     const PILL_LANE_H = theme.font.size + 6;
     // Any boundary label in view grows the strip by one row (like pill lanes do).
-    const hasBoundary = placed.some((t) => t.boundary !== undefined);
+    const hasBoundary = boundaryContext !== undefined ||
+        placed.some((t) => t.boundary !== undefined);
+    // The pinned context anchors at the plot's left edge (the y-axis line) with
+    // the SAME alignment as the tick labels — centred on it in `center` mode
+    // (exactly where a first-tick label at x=0 sat, half into the gutter by the
+    // same documented rule), left-anchored in `auto`, beside the line in
+    // `right`. As the leftmost crossing label slides toward the edge it would
+    // collide, so the context CULLS once the crossing label's left edge reaches
+    // the context's right edge (plus a gap) — no overlap, and nothing slides
+    // loose into the gutter. Widths from the same rough glyph metric the pills
+    // use; the crossing's label is centred on its tick.
+    const charW = theme.font.size * 0.62;
+    const contextWidth = (boundaryContext?.length ?? 0) * charW;
+    const contextRight = align === 'center'
+        ? contextWidth / 2
+        : align === 'right'
+            ? 4 + contextWidth
+            : contextWidth;
+    const firstCrossing = placed.find((t) => t.boundary !== undefined);
+    const crossingLeft = firstCrossing
+        ? align === 'right'
+            ? firstCrossing.x + 4
+            : firstCrossing.x - (firstCrossing.boundary.length * charW) / 2
+        : Infinity;
+    const showContext = boundaryContext !== undefined && crossingLeft > contextRight + 6;
     const stripHeight = (height ?? TICK_STRIP + (label ? LABEL_STRIP : 0)) +
         (hasBoundary ? BOUNDARY_STRIP : 0) +
         maxPillLane * PILL_LANE_H;
@@ -170,10 +254,10 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
             width: `${plotWidth}px`,
             height: `${stripHeight}px`,
             // The plot-facing edge carries the rule; a top axis rules its bottom.
-            [onTop ? 'borderBottom' : 'borderTop']: `1px solid ${theme.axis.grid}`,
+            [onTop ? 'borderBottom' : 'borderTop']: `1px solid ${color ?? theme.axis.grid}`,
             fontFamily: theme.font.family,
             fontSize: `${theme.font.size}px`,
-            color: theme.axis.label,
+            color: color ?? theme.axis.label,
         }, children: [placed.map((t, i) => {
                 const isFirst = i === 0;
                 const isLast = i === placed.length - 1;
@@ -197,7 +281,7 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                                 [onTop ? 'bottom' : 'top']: 0,
                                 width: '1px',
                                 height: `${tickHeight}px`,
-                                background: theme.axis.grid,
+                                background: color ?? theme.axis.grid,
                             } }), _jsx("div", { style: {
                                 position: 'absolute',
                                 left: `${labelLeft}px`,
@@ -212,7 +296,14 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                                 whiteSpace: 'nowrap',
                                 opacity: 0.75,
                             }, children: t.boundary }))] }, `${t.x}-${i}`));
-            }), label !== undefined && (_jsx("div", { style: {
+            }), showContext && (_jsx("div", { "data-boundary-label": true, "data-boundary-context": true, style: {
+                    position: 'absolute',
+                    left: `${align === 'right' ? 4 : 0}px`,
+                    [onTop ? 'bottom' : 'top']: `${(align === 'right' ? 2 : 6) + theme.font.size + 3}px`,
+                    transform: align === 'center' ? 'translateX(-50%)' : 'none',
+                    whiteSpace: 'nowrap',
+                    opacity: 0.75,
+                }, children: boundaryContext })), label !== undefined && (_jsx("div", { style: {
                     position: 'absolute',
                     left: 0,
                     width: '100%',
@@ -220,7 +311,7 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                     [onTop ? 'top' : 'bottom']: 0,
                     // Themeable axis-title text (shared with the rotated y-axis title).
                     fontSize: `${theme.axis.title?.size ?? theme.font.size + 1}px`,
-                    color: theme.axis.title?.color ?? theme.axis.label,
+                    color: color ?? theme.axis.title?.color ?? theme.axis.label,
                     opacity: theme.axis.title?.opacity ?? 0.85,
                     whiteSpace: 'nowrap',
                 }, children: label })), markerTags.map((t) => {

package/dist/YAxis.d.ts

@@ -70,6 +70,14 @@ export interface YAxisProps {
     boundaryLabels?: boolean;
     /** Gutter width in CSS pixels (default 50). */
     width?: number;
+    /**
+     * This axis instance's colour — tick labels and the axis title take it,
+     * overriding the theme's `axis.label` / `axis.title.color`. The multi-axis
+     * convention of colouring each y axis to match its series (`color`
+     * matching the layer's) — busy, but standard. Omit for the theme's axis
+     * colours. Presentation-only: it never re-registers the axis.
+     */
+    color?: string;
     /**
      * @internal Declaration position among the row's children, injected by
      * `ChartRow` so the first-declared axis stays the default. Do not set.
@@ -84,5 +92,5 @@ export interface YAxisProps {
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export declare function YAxis({ id, side, label, min, max, format, ticks, pad, boundaryLabels, width, labelPlacement, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function YAxis({ id, side, label, min, max, format, ticks, pad, boundaryLabels, width, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=YAxis.d.ts.map

package/dist/YAxis.js

@@ -13,7 +13,7 @@ const TICK_COUNT = 5;
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export function YAxis({ id, side = 'left', label, min, max, format, ticks, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, labelPlacement = 'rotated', index = 0, }) {
+export function YAxis({ id, side = 'left', label, min, max, format, ticks, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, labelPlacement = 'rotated', color, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
@@ -76,7 +76,7 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, pad =
                 height: `${row.height}px`,
                 fontFamily: theme.font.family,
                 fontSize: `${theme.font.size}px`,
-                color: theme.axis.label,
+                color: color ?? theme.axis.label,
             }, children: [yScale &&
                     tickList.map(({ value, label }, i) => {
                         // Drop just the top & bottom labels when boundary labels are off
@@ -102,7 +102,7 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, pad =
                         // labels' alignment, rather than floating at the outer gutter edge.
                         [side === 'left' ? 'right' : 'left']: '4px',
                         fontSize: `${theme.axis.title?.size ?? theme.font.size + 1}px`,
-                        color: theme.axis.title?.color ?? theme.axis.label,
+                        color: color ?? theme.axis.title?.color ?? theme.axis.label,
                         opacity: theme.axis.title?.opacity ?? 0.85,
                         whiteSpace: 'nowrap',
                         pointerEvents: 'none',
@@ -116,7 +116,7 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, pad =
                         alignItems: 'center',
                         justifyContent: 'center',
                         fontSize: `${theme.axis.title?.size ?? theme.font.size + 1}px`,
-                        color: theme.axis.title?.color ?? theme.axis.label,
+                        color: color ?? theme.axis.title?.color ?? theme.axis.label,
                         opacity: theme.axis.title?.opacity ?? 0.85,
                         pointerEvents: 'none',
                     }, children: _jsx("span", { style: {

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/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/tickLadder.d.ts

@@ -79,11 +79,14 @@ export declare function majorFormatFor(g: TickGranularity): string;
  *  (`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: the first
- * tick always (the reader needs context immediately), then every tick whose
- * boundary-grain bucket differs from the previous tick's — i.e. the first tick
- * of each new day / year. Returns the boundary-flagged tick values;
- * empty when the grain has no boundary row (year grain).
+ * 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): number[];
+export declare function boundaryTicks(ticks: readonly number[], granularity: TickGranularity, domainStart?: number): number[];
 //# sourceMappingURL=tickLadder.d.ts.map

package/dist/tickLadder.js

@@ -154,13 +154,26 @@ function stepAnchors(provider, opens, domainEnd, stepMs, cap) {
 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) {
-                const ticks = stepAnchors(provider, opens, domainEnd, step, cap);
+                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).
-                if (ticks.length <= cap && ticks.length > opens.length)
+                // "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' };
         }
@@ -242,21 +255,29 @@ export function boundaryFormatFor(g) {
     return g === 'day' ? '%b %d' : '%Y';
 }
 /**
- * Which of `ticks` (at grain `granularity`) carry a boundary label: the first
- * tick always (the reader needs context immediately), then every tick whose
- * boundary-grain bucket differs from the previous tick's — i.e. the first tick
- * of each new day / year. Returns the boundary-flagged tick values;
- * empty when the grain has no boundary row (year grain).
+ * 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) {
+export function boundaryTicks(ticks, granularity, domainStart) {
     const bg = boundaryGrainFor(granularity);
     if (bg === undefined)
         return [];
     const out = [];
-    let prev;
+    // 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)
+        if (prev !== undefined && k !== prev)
             out.push(t);
         prev = k;
     }

package/dist/tradingTimeScale.d.ts

@@ -74,12 +74,21 @@ export interface TradingTimeScale {
     /**
      * 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: the first tick and
-     * each tick starting a new day / year (whichever is the next-coarser
-     * unit the first-row label omits) carry the label; year-grain ticks have no
-     * second row.
+     * {@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];

package/dist/tradingTimeScale.js

@@ -125,11 +125,21 @@ export function scaleTradingTime(provider) {
             return () => undefined;
         const fmt = base.tickFormat(count, boundaryFormatFor(bg));
         const labelled = new Map();
-        for (const t of boundaryTicks(ticks, granularity)) {
+        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.45.0",
+  "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.45.0",
-    "pond-ts": "^0.45.0",
+    "@pond-ts/react": "^0.46.0",
+    "pond-ts": "^0.46.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {