@pond-ts/charts 0.51.0 → 0.53.0

package/CHANGELOG.md

@@ -8,7 +8,9 @@ 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.51.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
 [0.49.0]: https://github.com/pond-ts/pond/compare/v0.48.1...v0.49.0
@@ -51,6 +53,164 @@ 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
+
+- **core / financial:** **Market-scale studies are now typed-array fast**
+  (the "SMA/EMA at 1M bars costs hundreds of ms" report). Three cuts along
+  the same path, all behaviour-preserving (identical values, warm-ups,
+  missing-cell semantics, and rejection errors; every fast path falls back
+  to the original sweep when it doesn't apply):
+  - **`smooth('ema')` columnar fast path** — on a packed numeric source
+    column the EMA recurrence runs straight off the typed buffer into a
+    typed result column via trusted construction (key + untouched columns
+    pass through zero-copy), replacing the per-row Event/tuple rebuild +
+    full-series intake re-pack. 1M rows: **530 ms → 4.4 ms (~120×)**.
+  - **`rolling({ count })` numeric fast path** — an all-built-in numeric
+    mapping over packed sources feeds the shared incremental reducer states
+    directly from the typed buffers and writes snapshots into typed columns
+    (no per-row snapshot arrays, no boxed accumulators, no post-pass
+    assert/re-pack). 1M rows, `avg`: **135 ms → 32 ms (~4×)**.
+  - **financial kernel reads columns, not events** — `rollingColumns` /
+    `columnValues` now read study inputs/outputs off the public column API
+    instead of materializing `series.events` (an Event + data object per
+    row, ~400 ms of pure overhead at 1M rows).
+  - End-to-end at 1M bars: `ema()` **603 ms → 2.5 ms (~240×)**, `sma()`
+    **569 ms → 56 ms (~10×)**, `bollinger()` **748 ms → 162 ms (~4.6×)**.
+    Durable benchmarks: `packages/core/scripts/perf-smooth-ema.mjs`,
+    `packages/financial/scripts/perf-studies.mjs`.
+
+### Added
+
+- **core:** **`TimeSeries.fromArrow(table, options?)` — ingest a decoded Apache
+  Arrow `Table`.** pond stays zero-dependency: bring your own Arrow
+  (`tableFromIPC(...)`) and hand the `Table` in; the input is duck-typed against
+  a small structural surface (`ArrowTableLike` / `ArrowVectorLike` / …, all
+  exported). Ingest is the zero-copy path — every `Float64` column's backing
+  `Float64Array` is adopted as-is (`Float32`/int columns convert; int64 value
+  columns recombine BigInt-free), and the schema is derived from the Arrow
+  fields. The time key is converted **BigInt-free**: Arrow's idiomatic int64
+  timestamps are recombined from their two int32 halves rather than
+  `Number(bigint)` per row — measured **~11× faster** on the time column (0.6ms
+  vs 6.8ms at 500k rows; `scripts/perf-from-arrow.mjs`). Options: `time` (key
+  column, default the `'time'` field), `timeUnit` (default read from the Arrow
+  Arrow type family — a `Timestamp`'s raw-unit int64 is scaled by its
+  `TimeUnit`; `Date32`/`Date64` arrive already normalized to epoch-ms and pass
+  through; overridable), `columns` (subset, in order), `name`, `sort`. Numeric
+  **and string** columns are supported — string columns (Arrow
+  `Utf8`) become dict-encoded `StringColumn`s; any other Arrow type
+  (list/struct) throws, naming it. A null time key throws; numeric nulls map to
+  `NaN` and string nulls to missing.
+- **core:** **`TimeSeries.fromColumns` / `ValueSeries.fromColumns` now accept
+  `string` value columns** (previously numeric-only), packed to dict-encoded
+  `StringColumn`s (`null`/`undefined` → missing) — the shared columnar-ingress
+  engine now dispatches on the schema kind. Other value kinds (`boolean`,
+  arrays) still throw.
+- **charts:** **`<ScatterChart decimate>` — dense scatter plots now decimate**
+  (PND-MARKDEC scatter half — the last un-decimated mark type). **Default
+  `true`.** When the marks are **uniform** (fixed size + colour, no data-driven
+  `radius`/`color`), **opaque**, and denser than the pixel grid, overlapping
+  marks collapse to one representative per **mark-radius cell** via a 2D
+  pixel-**occupancy** sweep. Scatter has no fill, so a line/bar's per-column
+  `[min, max]` envelope would erase interior points — the occupancy grid keeps
+  one mark per occupied cell instead, which is **visually lossless** for uniform
+  opaque marks at that density (same-cell marks overlap). Interaction (hover /
+  click / tracker) still reads **every source point**; the per-point selection
+  ring + labels are suppressed only on the decimated (dense) path. A
+  **translucent** fill (density-encoded — overlap _should_ build up) or a
+  data-driven size/colour keeps the full draw. `decimate={false}` draws every
+  mark; `{ threshold }` tunes the trigger. The occupancy sweep uses the affine
+  fast path for the per-point pixel mapping. Measured (SciChart-suite
+  point-update, real browser): **100k 18 → 73 fps (4×)**, and the ladder now
+  runs to **10M** points (previously dead by 1M). `drawScatter` now returns
+  `LayerDrawStats` (visible via `onDrawStats`).
+
 ## [0.51.0] — 2026-07-22
 
 ### 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/ScatterChart.d.ts

@@ -1,6 +1,7 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
 import { type ColorEncoding, type RadiusEncoding } from './encoding.js';
+import type { DecimateOption } from './decimate.js';
 export interface ScatterChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
      * The source series. A `TimeSeries` scatters against the time axis; a
@@ -85,6 +86,16 @@ export interface ScatterChartProps<S extends SeriesSchema = SeriesSchema, VS ext
      * together, so a nudged point still selects.
      */
     offset?: number;
+    /**
+     * Collapse dense, **uniform** marks to one representative per pixel cell —
+     * lossless at that density, so a scatter of 100k+ points stays interactive.
+     * **Default `true`.** It engages only when the marks are a fixed size + colour
+     * (no data-driven `radius`/`color`), the fill is opaque, and the visible points
+     * are denser than the pixel grid; otherwise every point draws. Interaction
+     * (hover / click / tracker) always reads the source points. `decimate={false}`
+     * draws every mark; `{ threshold }` tunes the samples-per-pixel trigger.
+     */
+    decimate?: DecimateOption;
     /**
      * This layer's `<Legend>` row: `false` ⇒ no row (opt out), a string ⇒ the
      * row's display name. **Omitted ⇒ a row named by the layer's readout
@@ -126,5 +137,5 @@ export interface ScatterChartProps<S extends SeriesSchema = SeriesSchema, VS ext
  * </Layers>
  * ```
  */
-export declare function ScatterChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, id, axis, radius, color, label, offset, legend, index, }: ScatterChartProps<S, VS>): null;
+export declare function ScatterChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, id, axis, radius, color, label, offset, decimate, legend, index, }: ScatterChartProps<S, VS>): null;
 //# sourceMappingURL=ScatterChart.d.ts.map

package/dist/ScatterChart.js

@@ -34,7 +34,7 @@ import { useSlotKey } from './use-slot-key.js';
  * </Layers>
  * ```
  */
-export function ScatterChart({ series, column, as: semantic, id, axis, radius, color, label, offset = 0, legend, index = 0, }) {
+export function ScatterChart({ series, column, as: semantic, id, axis, radius, color, label, offset = 0, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<ScatterChart> must be rendered inside a <ChartContainer>');
@@ -131,7 +131,7 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
                 : {
                     hitTest: (px, py, xScale, yScale) => hitTestScatter(cs, px, py, xScale, yScale, encoding, keyAt, id, seriesLabel, offset),
                 }),
-            draw: (ctx, xScale, yScale) => drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, container.selected, id, offset),
+            draw: (ctx, xScale, yScale) => drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, container.selected, id, offset, decimate),
         },
         axisId: axis,
         index,
@@ -148,6 +148,7 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
         font,
         container.selected,
         offset,
+        decimate,
         axis,
         index,
     ]);

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

@@ -305,4 +305,43 @@ export interface BarColumnEnvelope {
  * `resolveBarBaseline`), so the union is honest about the zero line.
  */
 export declare function decimateBars(cs: BarSeries, xScale: Scale, ctx: CanvasRenderingContext2D, baseline: number, k?: number, visibleCount?: number): BarColumnEnvelope | null;
+/**
+ * Decimate a **uniform** scatter to one representative mark per occupied
+ * **pixel cell** ([PND-MARKDEC] scatter half) — the marks analog of
+ * {@link decimateBars}, but **2D**: scatter has no fill, so a line/bar's
+ * `[min, max]`-per-column envelope would erase interior points. Instead this
+ * bins the plane into `cellPx × cellPx` cells and keeps the **first** point in
+ * each occupied cell.
+ *
+ * **Why it's visually lossless (for uniform, opaque marks):** with `cellPx` set
+ * to the mark **radius**, any two points sharing a cell are at most `cellPx·√2 ≈
+ * 1.4·r` apart — less than `2·r` — so their discs overlap; drawing one paints
+ * (essentially) the pixels of both. Points in different cells are kept, so a
+ * sparse-in-y scatter reduces little (and stays exact); a dense blob collapses to
+ * ~`plotArea / cellPx²` marks regardless of N. The reduction is therefore an
+ * **unconditional** identity for overlapping uniform marks — the caller's job is
+ * only to decide when the O(visible) sweep is worth it (density gate) and that
+ * the marks are in fact uniform + opaque (data-driven size/colour or translucent
+ * fill must **not** decimate — see {@link isOpaqueColor}).
+ *
+ * `cs.x` is sorted, so the sweep visits columns left-to-right and only the
+ * **current** column's occupied rows need tracking (a `Set` cleared on each
+ * column change — bounded memory, O(visible) total). Positions are in CSS px
+ * (`xScale`/`yScale` output), matching the mark radius' units. `[vStart, vEnd)`
+ * is the pre-culled visible window (defaults to the whole series). Gaps
+ * (non-finite y) are skipped, like {@link drawScatter}.
+ */
+export declare function decimateScatter(cs: ChartSeries, xScale: Scale, yScale: Scale, cellPx: number, vStart?: number, vEnd?: number): ChartSeries;
+/**
+ * Whether `color` is fully opaque — the second precondition (beside
+ * {@link ResolvedEncoding.uniform}) for scatter decimation. A **translucent**
+ * fill accumulates opacity where marks overlap (that build-up _is_ the density
+ * signal), so collapsing overlaps would lighten the plot — decimation must not
+ * engage. Returns `false` only when it can **prove** alpha < 1
+ * (`rgba(…, a<1)`, `#rrggbbaa` / `#rgba` with alpha &lt; full, or `transparent`);
+ * every other form (`#rgb` / `#rrggbb`, `rgb()`, a named colour, `hsl()`) is
+ * treated as opaque. Conservative in the safe direction: a colour it can't prove
+ * translucent still decimates, but the realistic translucent cases are caught.
+ */
+export declare function isOpaqueColor(color: string): boolean;
 //# sourceMappingURL=decimate.d.ts.map

package/dist/decimate.js

@@ -46,6 +46,7 @@
  * shrinks the point count, not a second renderer.
  */
 import { Float64Column } from 'pond-ts';
+import { affineOf } from './affine.js';
 import { scaleDomain, cullChartSeries } from './culling.js';
 /** The device-pixel bucket count for `ctx` — the backing buffer width, i.e.
  *  `plotWidthCss × DPR` (so buckets land at device-pixel resolution). Falls back
@@ -606,4 +607,112 @@ export function decimateBars(cs, xScale, ctx, baseline, k = 2, visibleCount = cs
     }
     return { begin, end, lo, hi, length: W };
 }
+/**
+ * Decimate a **uniform** scatter to one representative mark per occupied
+ * **pixel cell** ([PND-MARKDEC] scatter half) — the marks analog of
+ * {@link decimateBars}, but **2D**: scatter has no fill, so a line/bar's
+ * `[min, max]`-per-column envelope would erase interior points. Instead this
+ * bins the plane into `cellPx × cellPx` cells and keeps the **first** point in
+ * each occupied cell.
+ *
+ * **Why it's visually lossless (for uniform, opaque marks):** with `cellPx` set
+ * to the mark **radius**, any two points sharing a cell are at most `cellPx·√2 ≈
+ * 1.4·r` apart — less than `2·r` — so their discs overlap; drawing one paints
+ * (essentially) the pixels of both. Points in different cells are kept, so a
+ * sparse-in-y scatter reduces little (and stays exact); a dense blob collapses to
+ * ~`plotArea / cellPx²` marks regardless of N. The reduction is therefore an
+ * **unconditional** identity for overlapping uniform marks — the caller's job is
+ * only to decide when the O(visible) sweep is worth it (density gate) and that
+ * the marks are in fact uniform + opaque (data-driven size/colour or translucent
+ * fill must **not** decimate — see {@link isOpaqueColor}).
+ *
+ * `cs.x` is sorted, so the sweep visits columns left-to-right and only the
+ * **current** column's occupied rows need tracking (a `Set` cleared on each
+ * column change — bounded memory, O(visible) total). Positions are in CSS px
+ * (`xScale`/`yScale` output), matching the mark radius' units. `[vStart, vEnd)`
+ * is the pre-culled visible window (defaults to the whole series). Gaps
+ * (non-finite y) are skipped, like {@link drawScatter}.
+ */
+export function decimateScatter(cs, xScale, yScale, cellPx, vStart = 0, vEnd = cs.length) {
+    const cell = cellPx > 0 ? cellPx : 1;
+    // Affine fast path ([PND-AFFINE]) for the per-point pixel mapping the sweep
+    // needs — an inline `k·v + b` over the typed arrays instead of a d3-scale
+    // closure per point (each axis independently; a non-affine axis, e.g. a
+    // real-gap trading x, falls back to the exact scale call). Without this the
+    // sweep would re-introduce the per-point d3-scale cost the line/area paths
+    // shed, making the decimation's own cost dominate.
+    const ax = affineOf(xScale);
+    const ay = affineOf(yScale);
+    const outX = [];
+    const outY = [];
+    let curCol = Number.NaN;
+    const rows = new Set();
+    for (let i = vStart; i < vEnd; i += 1) {
+        const y = cs.y[i];
+        if (!Number.isFinite(y))
+            continue; // gap — no mark
+        const xv = cs.x[i];
+        const px = ax !== null ? ax.k * xv + ax.b : xScale(xv);
+        const col = Math.floor(px / cell);
+        if (col !== curCol) {
+            rows.clear();
+            curCol = col;
+        }
+        const py = ay !== null ? ay.k * y + ay.b : yScale(y);
+        const row = Math.floor(py / cell);
+        if (!rows.has(row)) {
+            rows.add(row);
+            outX.push(xv);
+            outY.push(y);
+        }
+    }
+    return {
+        x: Float64Array.from(outX),
+        y: Float64Array.from(outY),
+        length: outX.length,
+    };
+}
+/**
+ * Whether `color` is fully opaque — the second precondition (beside
+ * {@link ResolvedEncoding.uniform}) for scatter decimation. A **translucent**
+ * fill accumulates opacity where marks overlap (that build-up _is_ the density
+ * signal), so collapsing overlaps would lighten the plot — decimation must not
+ * engage. Returns `false` only when it can **prove** alpha &lt; 1
+ * (`rgba(…, a<1)`, `#rrggbbaa` / `#rgba` with alpha &lt; full, or `transparent`);
+ * every other form (`#rgb` / `#rrggbb`, `rgb()`, a named colour, `hsl()`) is
+ * treated as opaque. Conservative in the safe direction: a colour it can't prove
+ * translucent still decimates, but the realistic translucent cases are caught.
+ */
+export function isOpaqueColor(color) {
+    const c = color.trim().toLowerCase();
+    if (c === 'transparent')
+        return false;
+    // rgb/rgba/hsl/hsla, both syntaxes: legacy comma (`rgba(r,g,b,a)`) and modern
+    // slash (`rgb(r g b / a)` / `hsl(h s l / a)`). Extract the alpha either way.
+    const fn = /^(?:rgba?|hsla?)\(([^)]+)\)$/.exec(c);
+    if (fn) {
+        const body = fn[1];
+        const slash = body.split('/');
+        if (slash.length === 2) {
+            const a = parseFloat(slash[1].trim()); // modern: `… / <alpha>`
+            return !(Number.isFinite(a) && a < 1);
+        }
+        const parts = body.split(',').map((p) => p.trim());
+        if (parts.length >= 4) {
+            const a = parseFloat(parts[3]); // legacy: 4th component is alpha
+            return !(Number.isFinite(a) && a < 1);
+        }
+        return true; // 3-component rgb/hsl → opaque
+    }
+    const hex = /^#([0-9a-f]{3,8})$/.exec(c);
+    if (hex) {
+        const h = hex[1];
+        if (h.length === 8)
+            return parseInt(h.slice(6, 8), 16) === 255;
+        if (h.length === 4)
+            return parseInt(h[3] + h[3], 16) === 255;
+        return true; // #rgb / #rrggbb
+    }
+    return true; // named / unknown → opaque
+}
 //# sourceMappingURL=decimate.js.map

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

@@ -62,6 +62,15 @@ export interface ResolvedEncoding {
     radiusAt(i: number): number;
     /** This point's fill colour (base colour if unencoded / non-finite). */
     colorAt(i: number): string;
+    /**
+     * `true` when **neither** radius nor colour is data-driven — every mark is the
+     * same fixed size and colour (`radiusAt`/`colorAt` ignore their index). This is
+     * the precondition for lossless occupancy **decimation** (PND-MARKDEC scatter
+     * half): only same-size, same-colour marks can be collapsed where they overlap
+     * without changing the picture. A `{column, range}` on either channel makes it
+     * `false`, and the scatter draws every point.
+     */
+    readonly uniform: boolean;
 }
 /** A numeric column read into a `Float64Array` (gaps as NaN), by name. */
 export type ColumnReader = (column: string) => Float64Array;

package/dist/encoding.js

@@ -139,6 +139,10 @@ export function resolveEncoding(cs, baseRadius, baseColor, radius, color, readCo
             };
         }
     }
-    return { radiusAt, colorAt };
+    // Uniform iff both channels are fixed: radius a number/omitted and no colour
+    // encoding. Data-driven either side (`{column, range}`) makes every mark
+    // potentially distinct, so decimation must not collapse them.
+    const uniform = (radius === undefined || typeof radius === 'number') && color === undefined;
+    return { radiusAt, colorAt, uniform };
 }
 //# sourceMappingURL=encoding.js.map

package/dist/scatter.d.ts

@@ -2,7 +2,8 @@ import type { ChartSeries } from './data.js';
 import type { Scale } from './line.js';
 import type { ScatterStyle } from './theme.js';
 import type { ResolvedEncoding } from './encoding.js';
-import type { SelectInfo } from './context.js';
+import type { SelectInfo, LayerDrawStats } from './context.js';
+import { type DecimateOption } from './decimate.js';
 /**
  * Index of the point in `cs` **nearest** `time` by `|x − time|`, restricted to
  * finite points, or `-1` if none. `cs.x` is the sorted time axis, so a binary
@@ -52,7 +53,7 @@ export declare function scatterExtent(cs: ChartSeries): [number, number] | null;
 export declare function drawScatter(ctx: CanvasRenderingContext2D, cs: ChartSeries, xScale: Scale, yScale: Scale, style: ScatterStyle, encoding: ResolvedEncoding, keyAt: (i: number) => number, labelAt: ((i: number) => string | undefined) | undefined, font: {
     readonly family: string;
     readonly size: number;
-}, selected: SelectInfo | null, seriesId: string | undefined, offsetPx?: number): void;
+}, selected: SelectInfo | null, seriesId: string | undefined, offsetPx?: number, decimate?: DecimateOption): LayerDrawStats;
 /**
  * Hit-test plot-pixel `(qx, qy)` against the scatter's points — the topmost
  * point whose circle contains the click, or `null`. "Topmost" = the

package/dist/scatter.js

@@ -1,4 +1,5 @@
 import { visiblePointRange } from './culling.js';
+import { shouldDecimateCount, decimateScatter, isOpaqueColor, } from './decimate.js';
 /**
  * Scatter geometry + the canvas draw — pure, like {@link drawLine} /
  * {@link drawBand}, so the recording-mock tests assert the op sequence and the
@@ -117,7 +118,7 @@ export function scatterExtent(cs) {
  *                of the selection match. A point lights only when the selection's
  *                `id` matches, keyed to the sample by its `key`.
  */
-export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, selected, seriesId, offsetPx = 0) {
+export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, selected, seriesId, offsetPx = 0, decimate = true) {
     ctx.save();
     // The selection only lights up a point of *this* series; resolve the key once.
     // A no-id (non-selectable) layer passes `undefined` and never matches.
@@ -158,9 +159,64 @@ export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, lab
     const [vStart, vEnd] = pad > 0
         ? visiblePointRange(cs.x, cs.length, xScale, pad)
         : [w0Start, w0End];
+    // [PND-MARKDEC] scatter decimation. When the marks are **uniform** (fixed
+    // size + colour), **opaque**, and denser than the pixel grid, collapse each
+    // overlapping cluster to one representative per mark-radius cell (2D
+    // occupancy — {@link decimateScatter}). Visually lossless at that density, and
+    // O(visible). Interaction is unaffected ({@link hitTestScatter} still walks
+    // every source point); the selection ring and per-point labels are dropped on
+    // this path — both are illegible under a dense blob — matching the decimated
+    // bar path. Data-driven size/colour (`!encoding.uniform`) or a translucent
+    // fill (density-encoded, where overlap *should* build up) keep the full draw.
+    const visibleCount = vEnd - vStart;
+    const k = typeof decimate === 'object' && decimate.threshold !== undefined
+        ? decimate.threshold
+        : 2;
+    if (decimate !== false &&
+        encoding.uniform &&
+        shouldDecimateCount(visibleCount, ctx, k) &&
+        isOpaqueColor(encoding.colorAt(vStart))) {
+        const r = encoding.radiusAt(vStart);
+        const dec = decimateScatter(cs, xScale, yScale, Math.max(1, r), vStart, vEnd);
+        // Only take the decimated pass if it actually shrank the work (a sparse-in-y
+        // scatter over the threshold may not overlap — then the full draw is fine,
+        // and keeps its selection ring + labels). Compare against the **finite**
+        // visible count, not `vEnd - vStart`: `decimateScatter` skips gaps, so the
+        // raw span would falsely read as a reduction on any gappy series (and wrongly
+        // suppress the ring / labels with zero cell collisions).
+        let finite = 0;
+        for (let i = vStart; i < vEnd; i += 1)
+            if (isPoint(cs, i))
+                finite += 1;
+        if (dec.length < finite) {
+            ctx.fillStyle = encoding.colorAt(vStart);
+            const outlined = style.outlineWidth > 0;
+            if (outlined) {
+                ctx.lineWidth = style.outlineWidth;
+                ctx.strokeStyle = style.outline;
+            }
+            for (let j = 0; j < dec.length; j += 1) {
+                const px = xScale(dec.x[j]) + offsetPx;
+                const py = yScale(dec.y[j]);
+                ctx.beginPath();
+                ctx.arc(px, py, r, 0, Math.PI * 2);
+                ctx.fill();
+                if (outlined)
+                    ctx.stroke();
+            }
+            ctx.restore();
+            return {
+                sourceCount: cs.length,
+                drawnCount: dec.length,
+                decimated: true,
+            };
+        }
+    }
+    let drawn = 0;
     for (let i = vStart; i < vEnd; i += 1) {
         if (!isPoint(cs, i))
             continue;
+        drawn += 1;
         // `offsetPx` nudges the whole scatter in pixel space (zoom-stable) — for
         // pairing same-key marks (call/put at one strike) beside each other.
         const px = xScale(cs.x[i]) + offsetPx;
@@ -212,6 +268,10 @@ export function drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, lab
         }
     }
     ctx.restore();
+    // Full draw (no decimation): every finite mark in the visible window drew.
+    // `drawnCount < sourceCount` here reflects viewport **culling**, not
+    // decimation (`decimated: false`).
+    return { sourceCount: cs.length, drawnCount: drawn, decimated: false };
 }
 /** Gap (px) between a point's edge and its label text. */
 const LABEL_GAP = 4;

package/package.json

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