@pond-ts/charts 0.52.0 → 0.53.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/pond-ts/pond/compare/v0.52.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.53.0...HEAD
+[0.53.0]: https://github.com/pond-ts/pond/compare/v0.52.0...v0.53.0
 [0.52.0]: https://github.com/pond-ts/pond/compare/v0.51.0...v0.52.0
 [0.51.0]: https://github.com/pond-ts/pond/compare/v0.50.0...v0.51.0
 [0.50.0]: https://github.com/pond-ts/pond/compare/v0.49.0...v0.50.0
@@ -52,6 +53,91 @@ and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.53.0] — 2026-07-25
+
+### Changed
+
+- **fit (breaking):** **Power bins and zones now use pond's canonical bin
+  edges**, so they feed `@pond-ts/charts` with no mapping step:
+
+  ```tsx
+  <BarChart bins={power.distribution} column="seconds" />
+  <BarChart bins={power.zones} column="seconds" orientation="horizontal" ordinal />
+  ```
+
+  Each type previously spoke its own dialect for the same concept —
+  `PowerBin.wattsFrom` (with **no upper edge at all**), `ZoneTime.lo`/`hi`, and
+  `PowerZone.minWatts`/`maxWatts` — while core's `byColumn` and charts' `BinRecord`
+  both use `{ start, end, …aggregates }`. Every caller had to hand-map before
+  drawing, even though the internals already computed the canonical shape and
+  discarded it.
+
+  **Migration** (pre-1.0, so the old names are gone rather than deprecated):
+
+  | Was                   | Now                                    |
+  | --------------------- | -------------------------------------- |
+  | `PowerBin.wattsFrom`  | `PowerBin.start` (+ new `end`)         |
+  | `ZoneTime.lo` / `.hi` | `ZoneTime.start` / `.end`, `openEnded` |
+  | `PowerZone.minWatts`  | `PowerZone.start`                      |
+  | `PowerZone.maxWatts`  | `PowerZone.end`, `openEnded`           |
+
+  Only **`PowerZone.maxWatts`** — a zone's upper edge — is affected. The
+  identically-named `PowerSummary.maxWatts` and the per-lap / per-section peak
+  power are a different concept and are unchanged.
+
+  `end` is now **always finite and always `> start`** — the guarantee core
+  enforces (`byColumn` throws on a zero-width bin) and charts need (an infinite
+  edge blows up an axis domain). The open-ended top band, which previously
+  carried only `Infinity`, gets a **drawable stand-in** edge: wide enough to
+  cover the highest value observed, and at least as wide as the band below it.
+  Treat it as a drawing bound rather than data, and test for the band with the
+  new **`openEnded`** flag rather than comparing an edge against `Infinity`
+  (`openEnded` is now also strictly positional — only the final band can carry
+  it). Rounding zone edges to whole watts no longer collapses bands at very low
+  FTPs.
+
+### Added
+
+- **charts:** **Duration (elapsed) x axis** — `<ChartContainer origin>` labels
+  the shared x axis as offsets from a zero point instead of absolute values, so
+  a workout / lab run / load test reads `00:00 00:05 00:10` rather than
+  `10:35 10:40 10:45`:
+
+  ```tsx
+  <ChartContainer width={620} origin="data">
+    …
+    <XAxis label="Elapsed" />
+  </ChartContainer>
+  ```
+
+  `'data'` zeroes at the start of the data (and stays there as you pan); a
+  **number** sets an explicit zero point — a gun, a trigger, a lap — with ticks
+  before it reading negative (`-00:05`). Ticks are placed at round durations
+  **measured from the origin** (a ride starting at 10:33:17 ticks 10:33:17,
+  10:38:17, …), off a clock ladder (…15s, 30s, 1m, 2m, 5m, …, 12h, then whole
+  days) rather than the 1-2-5 ladder — the part a formatter alone can't do.
+  Labels pick their shape from the step and the axis's magnitude
+  (`00:00.500` · `00:15` · `01:01:30` · `1d 12:00` · `5d`), gridlines follow the
+  same ticks, and the cursor / marker pills read one grain finer (`00:05:12`).
+
+  It's a **labelling** mode, not a data transform: `range`, `<Marker at>`,
+  `onRegionSelect`, `trackerPosition` all stay in absolute axis units. The same
+  prop works on a **value** x axis (distance travelled, not distance recorded).
+  An explicit format still wins — on a time axis a d3 _time_ specifier can only
+  describe an instant, so it labels the wall clock, which is the lever for
+  stacking a wall-clock strip under a duration strip on one shared tick set; on
+  a value axis a number specifier formats the offset. Ignored on a category
+  axis; on a trading calendar the durations are wall-clock, so ticks spanning a
+  collapsed session gap sit unevenly.
+
+- **fit:** `computePower` takes an options object — **`{ binWatts }`** sets the
+  width of the `distribution` buckets (default `1`, unchanged). 1 W bins draw as
+  hairlines, so pass the width you intend to render rather than re-bucketing the
+  output yourself. It throws `RangeError` on a non-positive or non-finite
+  `binWatts`. New exported type `ComputePowerOptions`, also accepted by the
+  activity façade: `Activity.power(ftp, options)` and
+  `ProfiledActivity.power(options)`.
+
 ## [0.52.0] — 2026-07-23
 
 ### Changed

package/dist/ChartContainer.d.ts

@@ -377,6 +377,35 @@ export interface ChartContainerProps {
      * `cursorFormat`.)
      */
     cursorFormat?: CursorFormat;
+    /**
+     * Label the x axis as **offsets from a zero point** instead of absolute
+     * values — the *duration* (elapsed-time) axis. A time axis reads
+     * `00:00 00:05 00:10` where it read `10:35 10:40 10:45`; a value axis reads
+     * distance-from-the-origin (`0 500 1000`) where it read absolute distance.
+     *
+     * - **`'data'`** — the start of the data (the union of the layers' x extents),
+     *   so the labels are "since the beginning of the series" and stay put as you
+     *   pan.
+     * - **a number** — an explicit zero point in axis units: a race gun, a trigger
+     *   instant, a lap marker. Ticks before it read negative (`-00:05` — the
+     *   T-minus case).
+     *
+     * Ticks are placed at round durations **measured from the origin**, not at the
+     * wall-clock boundaries the calendar ladder would pick — that's the difference
+     * between `00:00 00:05 00:10` and `00:01:43 00:06:43`. Gridlines follow them,
+     * and so does the cursor pill (one grain finer, as ever: `00:05:12`).
+     *
+     * This is a **labelling** mode, not a data transform: `range`, an annotation's
+     * `at`, an `onRegionSelect` span, `trackerPosition` are all still absolute
+     * axis units. Ignored on a category axis. An explicit `timeFormat` /
+     * `<XAxis format>` still wins — on a time axis a d3 *time* specifier can only
+     * describe an instant, so it labels the underlying wall clock (the lever for
+     * stacking a wall-clock strip under a duration strip, on shared ticks); on a
+     * value axis a number specifier formats the offset. On a trading-calendar
+     * axis the durations are **wall-clock**, so ticks spanning a collapsed session
+     * gap sit unevenly — elapsed *trading* time is not implemented.
+     */
+    origin?: number | 'data';
     /** Visual theme for all rows; defaults to {@link defaultTheme}. */
     theme?: ChartTheme;
     children?: ReactNode;
@@ -390,5 +419,5 @@ export interface ChartContainerProps {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom, bounds, onTimeRangeChange, minDuration, cursor, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, cursorFormat, theme, discontinuities, calendar, spacing, grid, sessionDividers, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom, bounds, onTimeRangeChange, minDuration, cursor, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, cursorFormat, origin, theme, discontinuities, calendar, spacing, grid, sessionDividers, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartContainer.d.ts.map

package/dist/ChartContainer.js

@@ -3,6 +3,7 @@ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } f
 import { scaleLinear } from 'd3-scale';
 import { identityProvider, scaleTradingTime, } from './tradingTimeScale.js';
 import { scaleBand } from './bandScale.js';
+import { scaleElapsed } from './elapsed.js';
 import { Sequence } from 'pond-ts';
 import { ContainerContext, CursorContext, } from './context.js';
 import { maxSlotWidths, sum } from './slots.js';
@@ -44,7 +45,7 @@ function normalizeRange(range) {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom = false, bounds, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat, theme, discontinuities, calendar, spacing, grid = true, sessionDividers = 'none', children, }) {
+export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom = false, bounds, onTimeRangeChange, minDuration = 1, cursor = DEFAULT_CURSOR_MODE, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime = false, crosshairSnap = true, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat, origin, theme, discontinuities, calendar, spacing, grid = true, sessionDividers = 'none', children, }) {
     // Normalize the `panZoom` mode (boolean shorthand or the three-way string)
     // into the two gesture flags the event surface reads. `true` ⇒ both; `'pan'`
     // ⇒ drag only; `false`/`'none'` ⇒ neither. Zoom implies pan (there is no
@@ -391,6 +392,17 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
     const xTickCount = resolvedKind === 'time'
         ? Math.max(2, Math.floor(plotWidth / TRADING_TICK_PX))
         : TIME_TICK_COUNT;
+    // The elapsed-axis zero point (`origin`), resolved to a number: `'data'` is
+    // the start of the data, which before any layer registers falls back to the
+    // domain start (the same two-pass settle `resolvedKind` makes). A category
+    // axis has no numeric origin to offset from, and a non-finite one is ignored
+    // rather than poisoning every tick.
+    const elapsedOrigin = useMemo(() => {
+        if (origin === undefined || resolvedKind === 'category')
+            return undefined;
+        const at = origin === 'data' ? (autoExtent?.[0] ?? d0) : origin;
+        return Number.isFinite(at) ? at : undefined;
+    }, [origin, resolvedKind, autoExtent, d0]);
     const { xScale, formatTime, formatReadout } = useMemo(() => {
         if (resolvedKind === 'category') {
             // Ordinal column-domain axis: a band scale over the category slots. The
@@ -411,6 +423,24 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         }
         if (resolvedKind === 'value') {
             const s = scaleLinear().domain([d0, d1]).range([0, plotWidth]);
+            if (elapsedOrigin !== undefined) {
+                // Offset (elapsed) value axis: same pixels, ticks anchored at the
+                // origin, labels reading `v - origin`. A `timeFormat` / `cursorFormat`
+                // number specifier resolves through the *offset* domain (that's what
+                // the wrapper's `tickFormat` does), so a specifier describes the number
+                // actually on show.
+                const e = scaleElapsed(s, { origin: elapsedOrigin, kind: 'value' });
+                const labels = resolveAxisFormat(e, xTickCount, timeFormat);
+                return {
+                    xScale: e,
+                    formatTime: labels,
+                    formatReadout: typeof cursorFormat === 'function'
+                        ? (v) => cursorFormat(v, { grain: undefined, defaultText: labels(v) })
+                        : cursorFormat !== undefined
+                            ? resolveAxisFormat(e, xTickCount, cursorFormat)
+                            : undefined,
+                };
+            }
             const labels = resolveAxisFormat(s, xTickCount, timeFormat);
             // The value-axis readout channel: a `cursorFormat` **string** is a d3
             // *number* specifier here (resolved through the linear scale, exactly as
@@ -447,6 +477,42 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
             }
             return undefined;
         };
+        // The **elapsed** (duration) flavour of both channels — the same scale
+        // wrapped so its ticks are anchored at `at` and its labels are durations.
+        // `at` is passed rather than closed over so the caller's `!== undefined`
+        // narrowing carries in.
+        const elapsedTime = (s, at) => {
+            const e = scaleElapsed(s, {
+                origin: at,
+                kind: 'time',
+                // An explicit d3 time specifier can only describe an instant, so it
+                // labels the wall clock underneath — the wall-clock-strip-under-a-
+                // duration-strip lever (see the `origin` prop docs).
+                absolute: (count, specifier) => {
+                    const f = s.tickFormat(count, specifier);
+                    return (v) => f(new Date(v));
+                },
+            });
+            // Labels: durations, unless a container `timeFormat` owns them.
+            const labels = timeFormat !== undefined
+                ? resolveTimeFormat(e, xTickCount, timeFormat)
+                : e.tickFormat(xTickCount);
+            // Readout: one grain finer than the ticks (`00:05:12` under a `00:05`
+            // axis) — the elapsed twin of the calendar axis's `readoutFormat`. Set
+            // explicitly (not left `undefined` to fall back to the labels) because
+            // here the labels ARE the terse tick text: an elapsed axis runs no
+            // date-style ladder, so nothing else would restore the precision.
+            const fine = e.readoutFormat(xTickCount);
+            const readout = typeof cursorFormat === 'function'
+                ? (v) => cursorFormat(v, {
+                    grain: s.grain(xTickCount),
+                    defaultText: fine(v),
+                })
+                : cursorFormat !== undefined
+                    ? resolveTimeFormat(e, xTickCount, cursorFormat)
+                    : fine;
+            return { xScale: e, formatTime: labels, formatReadout: readout };
+        };
         if (xDiscontinuities !== undefined) {
             // Trading-time axis: closed-market gaps collapse, time proportional within
             // sessions. Same tickFormat surface as scaleTime, so the readout is shared.
@@ -455,6 +521,8 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
             const s = scaleTradingTime(xDiscontinuities)
                 .domain([d0, d1])
                 .range([0, plotWidth]);
+            if (elapsedOrigin !== undefined)
+                return elapsedTime(s, elapsedOrigin);
             return {
                 xScale: s,
                 formatTime: timeLabels(s),
@@ -470,6 +538,8 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         const s = scaleTradingTime(identityProvider())
             .domain([d0, d1])
             .range([0, plotWidth]);
+        if (elapsedOrigin !== undefined)
+            return elapsedTime(s, elapsedOrigin);
         return {
             xScale: s,
             formatTime: timeLabels(s),
@@ -483,6 +553,7 @@ export function ChartContainer({ range, width, rowGap = 0, showAxis = true, trac
         plotWidth,
         timeFormat,
         cursorFormat,
+        elapsedOrigin,
         xDiscontinuities,
         xTickCount,
     ]);

package/dist/context.d.ts

@@ -5,6 +5,7 @@ import type { LegendItemSpec } from './swatch.js';
 import type { Interval } from 'pond-ts';
 import type { TradingTimeScale, DiscontinuityProvider } from './tradingTimeScale.js';
 import type { ScaleBand } from './bandScale.js';
+import type { ElapsedScale } from './elapsed.js';
 /**
  * The frame a {@link ChartContainer} provides to its rows and the time axis.
  * The container owns the **shared x geometry**: each side is split into *slots*
@@ -219,8 +220,14 @@ export interface ContainerFrame {
      * container is given `discontinuities`) is the third kind — same callable /
      * `invert` / `ticks` / `tickFormat` surface, but the mapping runs through
      * trading time so closed-market gaps collapse (see {@link discontinuities}).
-     */
-    readonly xScale: ScaleTime<number, number> | ScaleLinear<number, number> | TradingTimeScale | ScaleBand;
+     *
+     * A container given an `origin` wraps whichever of these it built in an
+     * {@link ElapsedScale} — the same pixel mapping, but ticks anchored at the
+     * origin and labelled as offsets (`00:05`), which is how the whole frame
+     * (axis labels, gridlines, cursor pill) reads durations without any consumer
+     * knowing about the mode.
+     */
+    readonly xScale: ScaleTime<number, number> | ScaleLinear<number, number> | TradingTimeScale | ScaleBand | ElapsedScale;
     /**
      * The discontinuity provider backing a **trading-time** x axis, if one was
      * supplied to the container — closed-market time (weekends, holidays,

package/dist/elapsed.d.ts

@@ -0,0 +1,140 @@
+/**
+ * The **elapsed (duration) x axis** — the shared x scale relabelled as *offsets
+ * from an origin*, so an axis reads `00:00 00:05 00:10` (time since the start of
+ * the series) instead of `10:35 10:40 10:45` (wall clock), and a value axis
+ * reads distance-from-the-start instead of absolute distance.
+ *
+ * Two things change, and only these two: **where the ticks sit** and **what they
+ * say**. The pixel mapping is untouched, and so are the data coordinates — a
+ * mark's `at`, the container's `range`, an `onRegionSelect` span are all still
+ * absolute axis units. Relabeling only.
+ *
+ * Where the ticks sit is the part that can't be done with `<XAxis transform>`:
+ * an elapsed axis wants ticks at **round durations measured from the origin**
+ * (a run starting at 10:33:17 ticks at 10:33:17, 10:38:17, … so its labels read
+ * `00:00 00:05`), not at the wall-clock boundaries a calendar ladder picks. So
+ * the walk here is `origin + k·step` with `step` off a **duration ladder**
+ * (…15s, 30s, 1m, 2m, 5m… — not the 1-2-5 ladder, which would offer a
+ * 200-second tick). A value axis runs the identical walk on the plain 1-2-5
+ * ladder.
+ *
+ * Pure — no DOM, no React; {@link scaleElapsed} wraps a base scale with these
+ * ticks + labels and the container hands the result out as its `xScale`, so
+ * every consumer (axis labels, gridlines, cursor pill, marker indicators) reads
+ * the elapsed axis without knowing it exists.
+ */
+/** The smallest 1-2-5 nice step ≥ `target` (the value-axis ladder). */
+export declare function niceStep(target: number): number;
+/**
+ * The tick step for a **duration** axis: the smallest ladder step that keeps the
+ * tick total at or under `count` across `span` ms. Past a day the ladder runs
+ * out and 1-2-5 whole days take over (2d, 5d, 10d, 20d, …) — calendar months
+ * are deliberately not a rung, since an elapsed axis measures duration, and
+ * "1 month later" is not a duration.
+ */
+export declare function durationStep(span: number, count: number): number;
+/**
+ * Tick values in **absolute axis units** at `origin + k·step`, covering
+ * `domain` — the anchored walk that makes `00:05` land exactly five minutes
+ * after the origin rather than on the nearest clock boundary. `k` runs negative
+ * where the domain reaches back before the origin (a T-minus axis), so the walk
+ * is origin-anchored, not domain-anchored. Ascending; `[]` for a degenerate
+ * domain or step.
+ */
+export declare function originTicks(domain: readonly [number, number], origin: number, step: number): number[];
+/**
+ * Which components a duration label shows. Resolved once from the tick step and
+ * the axis's magnitude ({@link durationShape}) so every label on one axis has
+ * the same shape — and so the cursor readout can add seconds to the *same*
+ * shape rather than picking its own (a `00:05` axis must not read `05:12` under
+ * the pointer).
+ */
+export interface DurationShape {
+    /** Prefix a `Nd ` day part (only rendered when the day count is non-zero). */
+    readonly days: boolean;
+    /** Head the clock with hours (`HH:MM`) rather than minutes (`MM:SS`). */
+    readonly hours: boolean;
+    readonly seconds: boolean;
+    readonly millis: boolean;
+    /** Whole days only (`0d 1d 2d`) — a day-or-coarser step has no clock to show. */
+    readonly dayGrain: boolean;
+}
+/**
+ * Pick the label shape for a duration axis from its tick `step` (which sets the
+ * *finest* component shown — a 5-minute step has no business printing seconds)
+ * and `maxAbs`, the largest offset the axis reaches (which sets the *coarsest*).
+ *
+ * The one non-obvious rung: an axis whose step is a minute or coarser heads its
+ * clock with **hours even when they're zero** (`00:05` = five minutes in),
+ * because that is what the wall-clock axis it replaces looked like. Only an axis
+ * fine enough to show seconds drops to `MM:SS`.
+ */
+export declare function durationShape(step: number, maxAbs: number): DurationShape;
+/**
+ * Render an elapsed `ms` in the given {@link DurationShape}: `00:05`, `12:30`,
+ * `01:15:30`, `2d 06:00`, `0d`, `-00:05`. Negative offsets (a domain reaching
+ * back before the origin — the T-minus case) carry a leading `-`.
+ *
+ * Truncates rather than rounds, so a label reads like a clock: 59.7s at second
+ * grain is `00:59`, not `01:00`. Hours accumulate past 24 when the shape has no
+ * day part, so an off-axis readout can't silently wrap.
+ */
+export declare function formatDuration(ms: number, shape: DurationShape): string;
+/**
+ * The x scale a container in elapsed mode hands out — the base scale's pixel
+ * mapping (`invert`, `domain`, `range` all pass straight through) with
+ * origin-anchored {@link originTicks} and offset labels layered on. Deliberately
+ * *not* a {@link TradingTimeScale}: it exposes no `tickBoundaries` / `bands` /
+ * `gridLevels`, which is exactly how `<XAxis>` knows to skip the calendar date
+ * styles and how `Layers` knows to draw its gridlines at the labelled (elapsed)
+ * ticks instead of the calendar grain populations.
+ */
+export interface ElapsedScale {
+    (value: number): number;
+    invert(pixel: number): number;
+    ticks(count?: number): number[];
+    /**
+     * The label formatter. With no `specifier` this is the **offset** formatter —
+     * a duration on a time axis, the d3 default over the offset domain on a value
+     * axis. With one, see {@link ElapsedOptions.absolute}.
+     */
+    tickFormat(count?: number, specifier?: string): (value: number | Date) => string;
+    domain(): [number, number];
+    range(): [number, number];
+    /** The zero point, in absolute axis units. */
+    readonly origin: number;
+    /** A formatter one grain finer than the tick labels (seconds always shown on a
+     *  time axis), for the cursor pill / marker indicators — the same
+     *  precise-readout-over-terse-ticks split the calendar axis makes. */
+    readoutFormat(count?: number): (value: number) => string;
+}
+/** The slice of the base scale {@link scaleElapsed} wraps — d3's `ScaleLinear`
+ *  and a `TradingTimeScale` both satisfy it. */
+interface ElapsedBase {
+    (value: number): number;
+    invert(pixel: number): number;
+    domain(): number[];
+    range(): number[];
+}
+export interface ElapsedOptions {
+    /** The zero point in absolute axis units — what `00:00` (or `0`) means. */
+    readonly origin: number;
+    readonly kind: 'time' | 'value';
+    /**
+     * Formatter for an explicit d3 **specifier** on a *time* axis, in absolute
+     * units (the container passes its wall-clock scale's `tickFormat`). A d3 time
+     * specifier can only describe an instant — `%H:%M` of a duration is not a
+     * thing — so an explicit format on an elapsed time axis labels the underlying
+     * wall clock. That's the lever for pairing a wall-clock strip with a duration
+     * strip on the same ticks. A **value** axis needs none: a number specifier
+     * describes the offset perfectly well, so it formats the offset.
+     */
+    absolute?(count: number, specifier: string): (value: number) => string;
+}
+/**
+ * Wrap `base` as an {@link ElapsedScale}: same pixels, ticks anchored at
+ * `origin`, labels in offsets.
+ */
+export declare function scaleElapsed(base: ElapsedBase, options: ElapsedOptions): ElapsedScale;
+export {};
+//# sourceMappingURL=elapsed.d.ts.map

package/dist/elapsed.js

@@ -0,0 +1,247 @@
+/**
+ * The **elapsed (duration) x axis** — the shared x scale relabelled as *offsets
+ * from an origin*, so an axis reads `00:00 00:05 00:10` (time since the start of
+ * the series) instead of `10:35 10:40 10:45` (wall clock), and a value axis
+ * reads distance-from-the-start instead of absolute distance.
+ *
+ * Two things change, and only these two: **where the ticks sit** and **what they
+ * say**. The pixel mapping is untouched, and so are the data coordinates — a
+ * mark's `at`, the container's `range`, an `onRegionSelect` span are all still
+ * absolute axis units. Relabeling only.
+ *
+ * Where the ticks sit is the part that can't be done with `<XAxis transform>`:
+ * an elapsed axis wants ticks at **round durations measured from the origin**
+ * (a run starting at 10:33:17 ticks at 10:33:17, 10:38:17, … so its labels read
+ * `00:00 00:05`), not at the wall-clock boundaries a calendar ladder picks. So
+ * the walk here is `origin + k·step` with `step` off a **duration ladder**
+ * (…15s, 30s, 1m, 2m, 5m… — not the 1-2-5 ladder, which would offer a
+ * 200-second tick). A value axis runs the identical walk on the plain 1-2-5
+ * ladder.
+ *
+ * Pure — no DOM, no React; {@link scaleElapsed} wraps a base scale with these
+ * ticks + labels and the container hands the result out as its `xScale`, so
+ * every consumer (axis labels, gridlines, cursor pill, marker indicators) reads
+ * the elapsed axis without knowing it exists.
+ */
+import { scaleLinear } from 'd3-scale';
+const SECOND = 1000;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+/**
+ * The duration tick ladder in ms — the steps a *clock* subdivides by, which is
+ * not the 1-2-5 ladder: 15s and 30s are round durations where 20s and 50s are
+ * not, and an hour divides by 2/3/6/12 rather than by 2/5. Steps coarser than a
+ * day fall back to 1-2-5 whole days (see {@link durationStep}).
+ */
+const DURATION_STEPS = [
+    1,
+    2,
+    5,
+    10,
+    20,
+    50,
+    100,
+    200,
+    500,
+    SECOND,
+    2 * SECOND,
+    5 * SECOND,
+    10 * SECOND,
+    15 * SECOND,
+    30 * SECOND,
+    MINUTE,
+    2 * MINUTE,
+    5 * MINUTE,
+    10 * MINUTE,
+    15 * MINUTE,
+    30 * MINUTE,
+    HOUR,
+    2 * HOUR,
+    3 * HOUR,
+    6 * HOUR,
+    12 * HOUR,
+    DAY,
+];
+/** The smallest 1-2-5 nice step ≥ `target` (the value-axis ladder). */
+export function niceStep(target) {
+    if (!(target > 0) || !Number.isFinite(target))
+        return 1;
+    const pow = 10 ** Math.floor(Math.log10(target));
+    for (const m of [1, 2, 5]) {
+        if (m * pow >= target)
+            return m * pow;
+    }
+    return 10 * pow;
+}
+/**
+ * The tick step for a **duration** axis: the smallest ladder step that keeps the
+ * tick total at or under `count` across `span` ms. Past a day the ladder runs
+ * out and 1-2-5 whole days take over (2d, 5d, 10d, 20d, …) — calendar months
+ * are deliberately not a rung, since an elapsed axis measures duration, and
+ * "1 month later" is not a duration.
+ */
+export function durationStep(span, count) {
+    const target = span / Math.max(1, count);
+    if (!(target > 0) || !Number.isFinite(target))
+        return 1;
+    for (const step of DURATION_STEPS) {
+        if (step >= target)
+            return step;
+    }
+    return niceStep(target / DAY) * DAY;
+}
+/** Backstop against a pathological (step, domain) pair flooding the axis; the
+ *  step is derived from the domain span, so a real axis never comes close. */
+const MAX_TICKS = 10_000;
+/**
+ * Tick values in **absolute axis units** at `origin + k·step`, covering
+ * `domain` — the anchored walk that makes `00:05` land exactly five minutes
+ * after the origin rather than on the nearest clock boundary. `k` runs negative
+ * where the domain reaches back before the origin (a T-minus axis), so the walk
+ * is origin-anchored, not domain-anchored. Ascending; `[]` for a degenerate
+ * domain or step.
+ */
+export function originTicks(domain, origin, step) {
+    const lo = Math.min(domain[0], domain[1]);
+    const hi = Math.max(domain[0], domain[1]);
+    if (!Number.isFinite(lo) ||
+        !Number.isFinite(hi) ||
+        !Number.isFinite(origin) ||
+        !(step > 0) ||
+        hi < lo) {
+        return [];
+    }
+    // ±1e-9 relative slack so a tick sitting exactly on a domain edge (the very
+    // common `origin === lo` case — the `00:00` tick) is not lost to float drift.
+    const eps = 1e-9 * Math.max(1, Math.abs(hi - lo) / step);
+    const k0 = Math.ceil((lo - origin) / step - eps);
+    const k1 = Math.floor((hi - origin) / step + eps);
+    if (k1 < k0 || k1 - k0 > MAX_TICKS)
+        return [];
+    const out = [];
+    for (let k = k0; k <= k1; k++)
+        out.push(origin + k * step);
+    return out;
+}
+/**
+ * Pick the label shape for a duration axis from its tick `step` (which sets the
+ * *finest* component shown — a 5-minute step has no business printing seconds)
+ * and `maxAbs`, the largest offset the axis reaches (which sets the *coarsest*).
+ *
+ * The one non-obvious rung: an axis whose step is a minute or coarser heads its
+ * clock with **hours even when they're zero** (`00:05` = five minutes in),
+ * because that is what the wall-clock axis it replaces looked like. Only an axis
+ * fine enough to show seconds drops to `MM:SS`.
+ */
+export function durationShape(step, maxAbs) {
+    const seconds = step < MINUTE;
+    return {
+        dayGrain: step >= DAY,
+        days: maxAbs >= DAY,
+        hours: maxAbs >= HOUR || !seconds,
+        seconds,
+        millis: step < SECOND,
+    };
+}
+const pad = (n, width = 2) => String(n).padStart(width, '0');
+/**
+ * Render an elapsed `ms` in the given {@link DurationShape}: `00:05`, `12:30`,
+ * `01:15:30`, `2d 06:00`, `0d`, `-00:05`. Negative offsets (a domain reaching
+ * back before the origin — the T-minus case) carry a leading `-`.
+ *
+ * Truncates rather than rounds, so a label reads like a clock: 59.7s at second
+ * grain is `00:59`, not `01:00`. Hours accumulate past 24 when the shape has no
+ * day part, so an off-axis readout can't silently wrap.
+ */
+export function formatDuration(ms, shape) {
+    if (!Number.isFinite(ms))
+        return '';
+    const sign = ms < 0 ? '-' : '';
+    let rest = Math.floor(Math.abs(ms));
+    const dayPart = Math.floor(rest / DAY);
+    if (shape.dayGrain)
+        return `${sign}${dayPart}d`;
+    if (shape.days)
+        rest -= dayPart * DAY;
+    const hours = Math.floor(rest / HOUR);
+    rest -= hours * HOUR;
+    const mins = Math.floor(rest / MINUTE);
+    rest -= mins * MINUTE;
+    const secs = Math.floor(rest / SECOND);
+    rest -= secs * SECOND;
+    // The day part shows only when there is one — an axis's first day reads
+    // `06:00`, its second `1d 06:00`, exactly as the flat date style promotes a
+    // tick that opens a coarser period.
+    const prefix = shape.days && dayPart > 0 ? `${dayPart}d ` : '';
+    const clock = shape.hours
+        ? `${pad(hours)}:${pad(mins)}${shape.seconds ? `:${pad(secs)}` : ''}`
+        : `${pad(mins)}:${pad(secs)}`;
+    const frac = shape.millis ? `.${pad(rest, 3)}` : '';
+    return `${sign}${prefix}${clock}${frac}`;
+}
+/** Default tick target when a caller passes none (d3's convention). */
+const DEFAULT_COUNT = 10;
+/**
+ * Wrap `base` as an {@link ElapsedScale}: same pixels, ticks anchored at
+ * `origin`, labels in offsets.
+ */
+export function scaleElapsed(base, options) {
+    const { origin, kind, absolute } = options;
+    const bounds = () => {
+        const d = base.domain();
+        return [Number(d[0] ?? 0), Number(d[1] ?? 0)];
+    };
+    const stepFor = (count) => {
+        const [lo, hi] = bounds();
+        const span = Math.abs(hi - lo);
+        return kind === 'time'
+            ? durationStep(span, count)
+            : niceStep(span / Math.max(1, count));
+    };
+    const shapeFor = (count) => {
+        const [lo, hi] = bounds();
+        const maxAbs = Math.max(Math.abs(lo - origin), Math.abs(hi - origin));
+        return durationShape(stepFor(count), maxAbs);
+    };
+    /** The value-axis offset formatter — resolved against a scale over the
+     *  *offset* domain, so d3 picks its precision from the numbers on show. */
+    const offsetFormat = (count, specifier) => {
+        const [lo, hi] = bounds();
+        const s = scaleLinear().domain([lo - origin, hi - origin]);
+        const f = specifier !== undefined
+            ? s.tickFormat(count, specifier)
+            : s.tickFormat(count);
+        return (v) => f(v - origin);
+    };
+    const scale = ((value) => base(value));
+    Object.assign(scale, {
+        origin,
+        invert: (pixel) => Number(base.invert(pixel)),
+        domain: () => bounds(),
+        range: () => {
+            const r = base.range();
+            return [Number(r[0] ?? 0), Number(r[1] ?? 0)];
+        },
+        ticks: (count = DEFAULT_COUNT) => originTicks(bounds(), origin, stepFor(count)),
+        tickFormat: (count = DEFAULT_COUNT, specifier) => {
+            if (kind === 'value')
+                return offsetFormat(count, specifier);
+            if (specifier !== undefined && absolute !== undefined) {
+                return absolute(count, specifier);
+            }
+            const shape = shapeFor(count);
+            return (value) => formatDuration(+value - origin, shape);
+        },
+        readoutFormat: (count = DEFAULT_COUNT) => {
+            if (kind === 'value')
+                return offsetFormat(count);
+            // Seconds on top of the ticks' own shape — never a *different* shape, so
+            // a `00:05` axis reads `00:05:12` under the pointer, not `05:12`.
+            const shape = { ...shapeFor(count), seconds: true, dayGrain: false };
+            return (value) => formatDuration(value - origin, shape);
+        },
+    });
+    return scale;
+}
+//# sourceMappingURL=elapsed.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.52.0",
+  "version": "0.53.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.52.0",
-    "pond-ts": "^0.52.0",
+    "@pond-ts/react": "^0.53.0",
+    "pond-ts": "^0.53.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {