pond-ts 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -3,11 +3,14 @@
 All notable changes to this project are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
-`pond-ts` and `@pond-ts/react` release together under a single `v*` tag, so this
-file covers both packages. Pre-1.0: minor bumps may include new features and
-type-level changes; patch bumps are strictly additive.
-
-[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.29.0...HEAD
+The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`, and
+`@pond-ts/fit` — release together under a single `v*` tag, so this file covers
+them all. Pre-1.0: minor bumps may include new features and type-level changes;
+patch bumps are strictly additive.
+
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.31.0...HEAD
+[0.31.0]: https://github.com/pjm17971/pond-ts/compare/v0.30.0...v0.31.0
+[0.30.0]: https://github.com/pjm17971/pond-ts/compare/v0.29.0...v0.30.0
 [0.29.0]: https://github.com/pjm17971/pond-ts/compare/v0.28.0...v0.29.0
 [0.28.0]: https://github.com/pjm17971/pond-ts/compare/v0.27.0...v0.28.0
 [0.27.0]: https://github.com/pjm17971/pond-ts/compare/v0.26.0...v0.27.0
@@ -21,7 +24,94 @@ type-level changes; patch bumps are strictly additive.
 [0.19.0]: https://github.com/pjm17971/pond-ts/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/pjm17971/pond-ts/compare/v0.17.1...v0.18.0
 
-## [Unreleased]
+## [0.31.0] — 2026-06-28
+
+First published release of **`@pond-ts/charts`** and **`@pond-ts/fit`** (both were
+previously `private`). All four packages — `pond-ts`, `@pond-ts/react`,
+`@pond-ts/charts`, `@pond-ts/fit` — now release together, lock-step, under one
+`v*` tag.
+
+### Added — `pond-ts` (core)
+
+- **`ValueSeries` + `TimeSeries.byValue(axis)` — the value axis as a closed
+  type.** `byValue` re-keys a series onto a monotonic non-time **value axis**
+  (distance, cumulative work, …), returning a `ValueSeries` — the value-keyed
+  counterpart of `TimeSeries`. It carries the ordering-based operators
+  (`axisValues`, `axisAt`, `column`, `nearestIndex`, `sliceByValue`); the
+  calendar/clock operators are deliberately absent — a value axis has no
+  wall-clock semantics, and the disjoint `ValueSeriesSchema` makes them
+  type-impossible. The axis must be **defined, finite, and non-decreasing at
+  every row** (it becomes the index); it is dropped from the value columns (it
+  is now the key) and the rest reshare zero-copy. Substrate: a new `'value'`
+  `KeyKind` + `ValueKeyColumn`. Projection is O(N + C); `nearestIndex` is
+  O(log N); `sliceByValue` is O(log N + C) zero-copy. (value-axis RFC Phase 1.)
+- **`scan(source, step, init, options?)` — typed-accumulator running fold.** The
+  general form of `cumulative` (the classic `mapAccumL`): the accumulator `A`
+  (any value, seeded from `init`) is **decoupled** from the numeric `output` and
+  the output column. `step(acc, value, i)` returns `[nextAcc, output]`. With no
+  `options.output` the source column is **replaced** in place (as `cumulative`
+  does); with `options.output` a **new** column is appended and the source is
+  left intact. Missing-cell carry, stored-`NaN`, and multi-entity semantics are
+  inherited from `cumulative` (scope per entity with
+  `partitionBy(col).scan(...).collect()`). Column-native, O(N + C), no event
+  materialization. Enables `split = scan + byColumn` — materialize cross-bin
+  state (e.g. hysteresis elevation gain) into a column, then segment it with
+  `byColumn`'s pure, order-free reducers. (estela F-geo-2-splits; value-axis
+  RFC wave lead.)
+
+### Added — `@pond-ts/charts` (initial release)
+
+- **First public release.** A React charting layer over pond-ts — a canvas data
+  plane with SVG interactive overlays. `ChartContainer` / `ChartRow` / `Layers`
+  composition; `LineChart`, `AreaChart`, `BarChart`, `Scatter`, `BoxPlot`;
+  `TimeAxis` / `YAxis` / `XAxis` (time **and** value x-axes); the cursor system
+  (staffed flag, per-row cursor modes); shared gap-rendering modes; and the
+  estela theme. Peer-depends on `pond-ts`, `@pond-ts/react`, and React 18/19.
+
+### Added — `@pond-ts/fit` (initial release)
+
+- **First public release.** A fitness / activity domain library over pond-ts — the
+  `Activity` / `Section` façade, unit-safe quantities (`Distance` / `Speed` /
+  `Power` / … with `.format()`), geo / power / zones analytics, `Profile` +
+  `usingProfile()` → `ProfiledActivity` / `ProfiledSection`, and the `Track`
+  value object. Façade-first: one curated flat barrel, with the functional
+  operator surface kept internal. Peer-depends on `pond-ts`.
+
+### Changed
+
+- **All `@pond-ts/*` peer / dependency ranges widened to `^0.31.0`** for the
+  lock-step release.
+
+## [0.30.0] — 2026-06-17
+
+### Added
+
+- **`rollingByColumn(col, { radius, at }, mapping)` — evaluate at explicit
+  centers.** `at` takes a **non-decreasing** array of center values (e.g. a chart's
+  coarse display grid) and returns **one record per center**, instead of the
+  default one-per-row. A center with no rows within `±radius` yields each
+  reducer's empty value. Same O(n + centers) two-pointer. Closes the
+  evaluate-at-grid gap surfaced adopting `rollingByColumn` for a chart variance
+  band. (estela F-rolling-by-row.)
+- **`smooth(col, 'movingAverage' | 'loess', { …, missing: 'skip' })` —
+  validity-respecting smoothing.** By default (`missing: 'bridge'`) a cell whose
+  own value is missing is still assigned a smoothed value from its present
+  neighbours — the line is drawn _across_ the hole. `missing: 'skip'` keeps a
+  missing cell **missing** in the output, so a sustained dropout (a coast, a
+  sensor gap) is preserved as a break rather than fabricated through. Present
+  cells smooth over only the present values in their window either way. `ema`
+  takes no `missing` option (it is causal and never fabricates across a gap). A
+  `maxGap` hard segment boundary is a deferred follow-on. (estela
+  F-smooth-interactive.)
+
+### Changed
+
+- **`byColumn(…, { inclusive: '(]' })` floor edge is now inclusive.** Under
+  `'(]'`, interior bins stay upper-inclusive (`(eᵢ, eᵢ₊₁]`) but the **floor `e₀`
+  is inclusive** (bin 0 is `[e₀, e₁]`), so a value at exactly the minimum edge —
+  e.g. a `0` W coast/stop sample at a zone floor of 0 — lands in bin 0 instead of
+  being dropped (the `include_lowest` convention). Previously the floor was
+  exclusive. (estela F-inclusive-floor.)
 
 ## [0.29.0] — 2026-06-17
 

package/dist/batch/by-column.js

@@ -47,17 +47,21 @@ export function computeByColumn(store, binColName, spec, columnSpecs) {
         const last = edges.length - 1;
         // `inclusive` picks the bin a value exactly on an interior edge falls into.
         // `'[)'` (default): bins are `[eᵢ, eᵢ₊₁)`, lower-inclusive — a boundary value
-        // goes to the bin ABOVE; range is `[e₀, eₙ)`. `'(]'`: bins are `(eᵢ, eᵢ₊₁]`,
-        // upper-inclusive (Coggan power/HR zones — a sample at exactly a zone's top
-        // edge is the LOWER zone) — a boundary value goes to the bin BELOW; range is
-        // `(e₀, eₙ]`, so the first edge is an exclusive floor (set it below your
-        // minimum to keep the minimum in bin 0).
+        // goes to the bin ABOVE; range is `[e₀, eₙ)`. `'(]'`: interior bins are
+        // `(eᵢ, eᵢ₊₁]`, upper-inclusive (Coggan power/HR zones — a sample at exactly
+        // a zone's top edge is the LOWER zone) — a boundary value goes to the bin
+        // BELOW. The **floor `e₀` is inclusive** (bin 0 is `[e₀, e₁]`), so a value at
+        // exactly the minimum edge — e.g. a `0` W coast/stop sample — lands in bin 0
+        // rather than being dropped (the `include_lowest` convention; estela
+        // F-inclusive-floor). Range is `[e₀, eₙ]`.
         binOf =
             spec.inclusive === '(]'
                 ? (v) => {
-                    if (v <= edges[0] || v > edges[last])
-                        return NaN; // out of (e₀, eₙ]
-                    // rightmost edge STRICTLY less than v, clamped to a valid bin [0, last)
+                    if (v < edges[0] || v > edges[last])
+                        return NaN; // out of [e₀, eₙ]
+                    // rightmost edge STRICTLY less than v (so an interior edge goes to
+                    // the bin below), clamped to [0, last); v === e₀ → bin 0 (floor
+                    // inclusive).
                     let lo = 0;
                     let hi = last;
                     while (lo < hi) {

package/dist/batch/operators/by-value.d.ts

@@ -0,0 +1,19 @@
+import { ColumnarStore, type ColumnSchema } from '../../columnar/index.js';
+/**
+ * **Column-native `byValue`** — the raw `TimeSeries → ValueSeries` projection
+ * (RFC `value-axis.md` §6). Re-keys the store onto the monotonic `axis` column
+ * (a no-op reindex: the rows already sit in axis order, since the axis is
+ * non-decreasing in storage order) and **drops `axis` from the value columns**
+ * — it is now the key, and `fromTrustedStore` rejects the duplicate name
+ * otherwise. The non-axis value columns + their buffers are shared by reference
+ * (zero-copy); only the key column is newly allocated.
+ *
+ * Returns the reshaped store + the value-keyed output schema. The schema cast
+ * is the trust boundary; `TimeSeries.byValue` wraps the store in a
+ * `ValueSeries` with the precise `ValueKeyedSchema<S, Axis>` type.
+ */
+export declare function byValueOp(store: ColumnarStore<ColumnSchema>, schema: ColumnSchema, axis: string): {
+    store: ColumnarStore<ColumnSchema>;
+    schema: ColumnSchema;
+};
+//# sourceMappingURL=by-value.d.ts.map

package/dist/batch/operators/by-value.js

@@ -0,0 +1,91 @@
+import { ColumnarStore, Float64Column, ValueKeyColumn, } from '../../columnar/index.js';
+/**
+ * Validates that the `axis` column is a usable value axis — **every cell
+ * defined + finite + non-decreasing** — and returns the `Float64Array` to key
+ * on. Throws otherwise.
+ *
+ * This is the monotonicity contract for `byValue`: it lives on the *projection*,
+ * not on `ValueKeyColumn` or `byColumn` (Codex review #1). An order-free
+ * value-bin aggregation has no monotonic precondition, but promoting a column to
+ * the *index* of a series does — and a missing/non-finite cell can't be placed
+ * in the ordering, so (unlike a value column, where a gap is fine) the axis must
+ * be dense.
+ *
+ * **Zero-copy fast path (Lever 1).** A packed {@link Float64Column} (every batch
+ * value column is one) already holds a contiguous backing buffer. Once the scan
+ * has proven `[0, n)` is dense + finite, that buffer *is* the key data, so we
+ * hand back a `subarray(0, n)` view rather than allocating and copying a fresh
+ * array — the source axis column and the new key then share it read-only (the
+ * same zero-copy contract as a slice). `_values.length` can exceed the logical
+ * length (capacity-grown columns), hence the `subarray`. A chunked column has no
+ * single contiguous buffer, so it falls back to materializing one.
+ *
+ * Trade-off of the reuse: the returned `subarray` view retains the source
+ * column's whole `ArrayBuffer` (including any capacity slack on a grown
+ * column), where the old copy released it. Negligible for batch (`_values`
+ * is sized to the column) and for a single live projection; only worth
+ * revisiting if a path holds many such views at once.
+ *
+ * The validation read-loop is unavoidable here (it enforces dense + finite +
+ * sorted). A future `{ assumeSorted }` fast path could skip it for a
+ * caller-guaranteed axis (e.g. a `scan`-produced cumulative distance); that's a
+ * trusted-construction seam, deferred until a re-projection hot path earns it.
+ */
+function assertMonotonicAxis(store, axis) {
+    const col = store.columns.get(axis);
+    if (col === undefined) {
+        throw new RangeError(`byValue: unknown column '${axis}'`);
+    }
+    const n = store.length;
+    let prev = -Infinity;
+    for (let i = 0; i < n; i += 1) {
+        const v = col.read(i);
+        if (typeof v !== 'number' || !Number.isFinite(v)) {
+            throw new RangeError(`byValue: axis '${axis}' must be defined and finite at every row to be the index; ` +
+                `row ${i} is ${v === undefined ? 'missing' : String(v)}`);
+        }
+        if (v < prev) {
+            throw new RangeError(`byValue: axis '${axis}' must be non-decreasing; row ${i} (${v}) < previous (${prev})`);
+        }
+        prev = v;
+    }
+    // Validation passed → `[0, n)` is dense + finite. Reuse the packed backing
+    // buffer zero-copy; materialize only for a (rare) chunked axis column.
+    if (col instanceof Float64Column) {
+        return col._values.subarray(0, n);
+    }
+    const out = new Float64Array(n);
+    for (let i = 0; i < n; i += 1) {
+        out[i] = col.read(i);
+    }
+    return out;
+}
+/**
+ * **Column-native `byValue`** — the raw `TimeSeries → ValueSeries` projection
+ * (RFC `value-axis.md` §6). Re-keys the store onto the monotonic `axis` column
+ * (a no-op reindex: the rows already sit in axis order, since the axis is
+ * non-decreasing in storage order) and **drops `axis` from the value columns**
+ * — it is now the key, and `fromTrustedStore` rejects the duplicate name
+ * otherwise. The non-axis value columns + their buffers are shared by reference
+ * (zero-copy); only the key column is newly allocated.
+ *
+ * Returns the reshaped store + the value-keyed output schema. The schema cast
+ * is the trust boundary; `TimeSeries.byValue` wraps the store in a
+ * `ValueSeries` with the precise `ValueKeyedSchema<S, Axis>` type.
+ */
+export function byValueOp(store, schema, axis) {
+    const values = assertMonotonicAxis(store, axis);
+    // `fromValidatedSubarray`, not `new ValueKeyColumn` — `assertMonotonicAxis`
+    // already proved finiteness, so skip the constructor's redundant finite scan.
+    const keyCol = ValueKeyColumn.fromValidatedSubarray(values, store.length);
+    // Drop the axis column from the value columns (it becomes the key).
+    const newColumns = new Map(store.columns);
+    newColumns.delete(axis);
+    const newSchema = [
+        { name: axis, kind: 'value' },
+        ...schema.slice(1).filter((c) => c.name !== axis),
+    ];
+    const newStore = ColumnarStore.fromTrustedStore(newSchema, keyCol, newColumns);
+    return { store: newStore, schema: newSchema };
+}
+//# sourceMappingURL=by-value.js.map

package/dist/batch/operators/scan.d.ts

@@ -0,0 +1,47 @@
+import { type ColumnarStore } from '../../columnar/index.js';
+import type { SeriesSchema } from '../../schema/index.js';
+/**
+ * The step function for {@link TimeSeries.scan} — the classic `mapAccumL`:
+ * given the carried accumulator, the current (defined) source value, and the
+ * row index, return the next accumulator and this row's numeric output. The
+ * accumulator type `A` is **decoupled** from the numeric output, which is what
+ * `cumulative` — where the accumulator *is* the output *is* a `number` — cannot
+ * express (e.g. hysteresis elevation gain carries `(ref, gain)` but emits only
+ * `gain`).
+ */
+export type ScanStep<A> = (acc: A, value: number, index: number) => readonly [next: A, output: number];
+/**
+ * **Column-native `scan`** — a typed-accumulator running fold, the
+ * generalization of `cumulativeOp`. Threads `acc: A` (any value, seeded from
+ * `init`) across the source column's defined cells, emits one numeric `output`
+ * per row, and either **replaces** the source column (`output === undefined`,
+ * `cumulative`'s convention) or **appends** a new column (`output` named,
+ * `withColumn`'s convention; the source stays intact). Reads straight off
+ * `Column.read(i)` — no event materialization, one pass, **O(n)**.
+ *
+ * Semantics are inherited from `cumulativeOp` so `scan` is consistent, not a
+ * new dialect:
+ * - A **defined numeric cell** calls `step(acc, value, i)`; the accumulator and
+ *   the last-emitted output both advance.
+ * - A **missing / undefined cell** does *not* call `step`: the accumulator is
+ *   carried unchanged and the row re-emits the last output, so the output holds
+ *   flat across a gap (exactly as `cumulative`'s accumulator holds). The output
+ *   is `undefined` only until the first defined value produces one
+ *   (`float64ColumnFromArray` derives validity from the `undefined`s).
+ * - A **stored `NaN`** is a defined number — `step` is called with it, and a
+ *   computed non-finite output lands as a defined cell. This is the
+ *   *trusted-compute* path (matching `cumulative`), not the validated
+ *   `withColumn` intake; the step author owns output finiteness.
+ *
+ * Returns the reshaped store + the output schema. The result-schema cast is the
+ * single trust boundary; `TimeSeries.scan` wraps the store via
+ * `#fromTrustedStore`. A non-numeric source is unreachable through the typed
+ * surface (`scan<Source extends NumericColumnNameForSchema<S>>`); on the
+ * replace path it fails fast (`withColumnReplaced`'s kind guard), matching
+ * `cumulative`.
+ */
+export declare function scanOp<S extends SeriesSchema, OutSchema extends SeriesSchema, A>(store: ColumnarStore<S>, schema: S, source: string, step: ScanStep<A>, init: A, output: string | undefined): {
+    store: ColumnarStore<OutSchema>;
+    schema: OutSchema;
+};
+//# sourceMappingURL=scan.d.ts.map

package/dist/batch/operators/scan.js

@@ -0,0 +1,81 @@
+import { float64ColumnFromArray, withColumnAppended, withColumnReplaced, } from '../../columnar/index.js';
+/**
+ * **Column-native `scan`** — a typed-accumulator running fold, the
+ * generalization of `cumulativeOp`. Threads `acc: A` (any value, seeded from
+ * `init`) across the source column's defined cells, emits one numeric `output`
+ * per row, and either **replaces** the source column (`output === undefined`,
+ * `cumulative`'s convention) or **appends** a new column (`output` named,
+ * `withColumn`'s convention; the source stays intact). Reads straight off
+ * `Column.read(i)` — no event materialization, one pass, **O(n)**.
+ *
+ * Semantics are inherited from `cumulativeOp` so `scan` is consistent, not a
+ * new dialect:
+ * - A **defined numeric cell** calls `step(acc, value, i)`; the accumulator and
+ *   the last-emitted output both advance.
+ * - A **missing / undefined cell** does *not* call `step`: the accumulator is
+ *   carried unchanged and the row re-emits the last output, so the output holds
+ *   flat across a gap (exactly as `cumulative`'s accumulator holds). The output
+ *   is `undefined` only until the first defined value produces one
+ *   (`float64ColumnFromArray` derives validity from the `undefined`s).
+ * - A **stored `NaN`** is a defined number — `step` is called with it, and a
+ *   computed non-finite output lands as a defined cell. This is the
+ *   *trusted-compute* path (matching `cumulative`), not the validated
+ *   `withColumn` intake; the step author owns output finiteness.
+ *
+ * Returns the reshaped store + the output schema. The result-schema cast is the
+ * single trust boundary; `TimeSeries.scan` wraps the store via
+ * `#fromTrustedStore`. A non-numeric source is unreachable through the typed
+ * surface (`scan<Source extends NumericColumnNameForSchema<S>>`); on the
+ * replace path it fails fast (`withColumnReplaced`'s kind guard), matching
+ * `cumulative`.
+ */
+export function scanOp(store, schema, source, step, init, output) {
+    const col = store.columns.get(source);
+    if (col === undefined) {
+        throw new RangeError(`scan: unknown column '${source}'`);
+    }
+    const n = store.length;
+    const out = new Array(n);
+    let acc = init;
+    let last;
+    for (let i = 0; i < n; i += 1) {
+        const raw = col.read(i);
+        if (typeof raw === 'number') {
+            const r = step(acc, raw, i);
+            acc = r[0];
+            last = r[1];
+        }
+        out[i] = last;
+    }
+    const column = float64ColumnFromArray(out);
+    const base = store;
+    // Output omitted ⇒ replace the source column in place (cumulative's
+    // convention; the source is widened to optional `number`).
+    if (output === undefined) {
+        const result = withColumnReplaced(base, source, column);
+        const outSchema = Object.freeze(schema.map((c, i) => i === 0 || c.name !== source
+            ? c
+            : { ...c, kind: 'number', required: false }));
+        return {
+            store: result,
+            schema: outSchema,
+        };
+    }
+    // Output named ⇒ append a new column, leaving the source intact. The name
+    // must not collide with the key or an existing value column (the schema
+    // includes the key at index 0). `withColumnAppended` re-checks, but the
+    // explicit guard gives a scan-specific message pointing at the replace path.
+    if (schema.some((c) => c.name === output)) {
+        throw new RangeError(`scan: output column '${output}' already exists; omit options.output to replace the source column`);
+    }
+    const result = withColumnAppended(base, output, column);
+    const outSchema = Object.freeze([
+        ...schema,
+        { name: output, kind: 'number' },
+    ]);
+    return {
+        store: result,
+        schema: outSchema,
+    };
+}
+//# sourceMappingURL=scan.js.map

package/dist/batch/partitioned-time-series.d.ts

@@ -4,7 +4,8 @@ import { Sequence } from '../sequence/sequence.js';
 import type { DurationInput } from '../core/duration.js';
 import type { TemporalLike } from '../core/temporal.js';
 import type { BatchSampleStrategy } from '../sequence/sample.js';
-import type { AggregateSchema, AlignSchema, BaselineSchema, DedupeKeep, DiffSchema, EventDataForSchema, FillMapping, FillStrategy, MaterializeSchema, NumericColumnNameForSchema, RollingAlignment, RollingSchema, SeriesSchema, SmoothAppendSchema, SmoothMethod, SmoothSchema, ValidatedAggregateMap } from '../schema/index.js';
+import type { AggregateSchema, AlignSchema, AppendColumn, BaselineSchema, DedupeKeep, DiffSchema, EventDataForSchema, FillMapping, FillStrategy, MaterializeSchema, NumericColumnNameForSchema, RollingAlignment, RollingSchema, SeriesSchema, SmoothAppendSchema, SmoothMethod, SmoothSchema, ValidatedAggregateMap } from '../schema/index.js';
+import type { ScanStep } from './operators/scan.js';
 type SequenceLike = Sequence | BoundedSequence;
 type AlignMethod = 'hold' | 'linear';
 type AlignSample = 'begin' | 'center' | 'end';
@@ -303,6 +304,11 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
     cumulative<const Targets extends NumericColumnNameForSchema<S>>(spec: {
         [K in Targets]: 'sum' | 'max' | 'min' | 'count' | ((acc: number, value: number) => number);
     }): PartitionedTimeSeries<DiffSchema<S, Targets>, K>;
+    /** Per-partition `scan`. See {@link TimeSeries.scan}. */
+    scan<const Source extends NumericColumnNameForSchema<S>, A>(source: Source, step: ScanStep<A>, init: A): PartitionedTimeSeries<DiffSchema<S, Source>, K>;
+    scan<const Source extends NumericColumnNameForSchema<S>, const Name extends string, A>(source: Source, step: ScanStep<A>, init: A, options: {
+        output: Name;
+    }): PartitionedTimeSeries<AppendColumn<S, Name, 'number'>, K>;
     /** Per-partition `shift`. See {@link TimeSeries.shift}. */
     shift<const Target extends NumericColumnNameForSchema<S>>(columns: Target | readonly Target[], n: number): PartitionedTimeSeries<DiffSchema<S, Target>, K>;
     /** Per-partition `aggregate`. See {@link TimeSeries.aggregate}. */

package/dist/batch/partitioned-time-series.js

@@ -419,6 +419,9 @@ export class PartitionedTimeSeries {
     cumulative(spec) {
         return this.rewrap(PartitionedTimeSeries.applyToSource(this.source, this.by, (g) => g.cumulative(spec)));
     }
+    scan(source, step, init, options) {
+        return this.rewrap(PartitionedTimeSeries.applyToSource(this.source, this.by, (g) => g.scan(source, step, init, options)));
+    }
     /** Per-partition `shift`. See {@link TimeSeries.shift}. */
     shift(columns, n) {
         return this.rewrap(PartitionedTimeSeries.applyToSource(this.source, this.by, (g) => g.shift(columns, n)));

package/dist/batch/rolling-by-column.d.ts

@@ -3,12 +3,19 @@ import type { ColumnValue } from '../schema/index.js';
 import type { AggregateColumnSpec } from './aggregate-columns.js';
 /**
  * Window spec for {@link TimeSeries.rollingByColumn}: a **centered** window of
- * half-width `radius`, in the axis column's own units. The window for a row is
- * every row whose axis value lies within `±radius` of it. See
+ * half-width `radius`, in the axis column's own units.
+ *
+ * By default a window is evaluated at **every input row** (one record per row).
+ * Pass `at` — a **non-decreasing** array of explicit center values (e.g. a chart's
+ * coarse display grid) — to evaluate at those centers instead, returning one
+ * record per center. Each center's window is the rows whose axis value lies
+ * within `±radius` of it; a center need not coincide with any row, and a center
+ * with no rows in range yields each reducer's empty value. See
  * `docs/notes/rolling-by-column.md`.
  */
 export type WindowSpec = {
     radius: number;
+    at?: readonly number[];
 };
 /** One windowed record: the mapped aggregates over the window centered at a row. */
 export type WindowRecord = Record<string, ColumnValue | undefined>;

package/dist/batch/rolling-by-column.js

@@ -55,6 +55,50 @@ export function computeRollingByColumn(store, axisColName, spec, columnSpecs) {
     // the whole sweep — this is what makes it O(n) rather than O(n · window).
     const states = columnSpecs.map((s) => rollingStateFor(s.reducer));
     const specCount = columnSpecs.length;
+    // `at` mode (estela F-rolling-by-row): evaluate at explicit ascending centers
+    // (e.g. a chart's display grid) rather than at every input row. One record per
+    // center; the two-pointer sweeps the same shared states across the centers, so
+    // it stays O(n + at.length). A center with no rows in `±radius` empties the
+    // window and yields each reducer's empty value.
+    if (spec.at !== undefined) {
+        const at = spec.at;
+        for (let k = 0; k < at.length; k += 1) {
+            if (!Number.isFinite(at[k])) {
+                throw new RangeError(`rollingByColumn: at[${k}] is not finite`);
+            }
+            if (k > 0 && at[k] < at[k - 1]) {
+                throw new RangeError('rollingByColumn: at centers must be non-decreasing');
+            }
+        }
+        const atOut = new Array(at.length);
+        let alo = 0;
+        let ahi = 0; // window holds compact positions [alo, ahi)
+        for (let k = 0; k < at.length; k += 1) {
+            const c = at[k];
+            const wlo = c - radius;
+            const whi = c + radius;
+            while (ahi < m && ax[ahi] <= whi) {
+                const r = idx[ahi];
+                for (let cc = 0; cc < specCount; cc += 1) {
+                    states[cc].add(r, sourceCols[cc].read(r));
+                }
+                ahi += 1;
+            }
+            while (alo < ahi && ax[alo] < wlo) {
+                const r = idx[alo];
+                for (let cc = 0; cc < specCount; cc += 1) {
+                    states[cc].remove(r, sourceCols[cc].read(r));
+                }
+                alo += 1;
+            }
+            const rec = {};
+            for (let cc = 0; cc < specCount; cc += 1) {
+                rec[columnSpecs[cc].output] = states[cc].snapshot();
+            }
+            atOut[k] = rec;
+        }
+        return atOut;
+    }
     const out = new Array(n);
     let lo = 0;
     let hi = 0; // the window currently holds compact positions [lo, hi)