pond-ts 0.41.0 → 0.42.0

package/CHANGELOG.md

@@ -3,12 +3,13 @@
 All notable changes to this project are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
-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.
+The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
+`@pond-ts/fit`, and `@pond-ts/financial` — 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.41.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.42.0...HEAD
+[0.42.0]: https://github.com/pjm17971/pond-ts/compare/v0.41.0...v0.42.0
 [0.41.0]: https://github.com/pjm17971/pond-ts/compare/v0.40.0...v0.41.0
 [0.40.0]: https://github.com/pjm17971/pond-ts/compare/v0.39.0...v0.40.0
 [0.39.0]: https://github.com/pjm17971/pond-ts/compare/v0.38.0...v0.39.0
@@ -39,6 +40,74 @@ patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.42.0] — 2026-07-10
+
+The **trading-calendar** release: a new `@pond-ts/financial` package (its first
+publish) and a discontinuous **trading-time x axis** in `@pond-ts/charts` that
+collapses closed-market time (weekends, holidays, overnight, lunch breaks).
+
+### Added
+
+- **`@pond-ts/financial` — new package (first release).** A calendar/analytics
+  layer on `pond-ts` (peer dep; ESM, no React; `@js-temporal/polyfill` for
+  DST-correct session generation):
+  - **`TradingCalendar`** — `fromSessions` (explicit schedule) and `fromRules`
+    (weekmask / holidays / early-closes / breaks, DST-correct via Temporal);
+    query surface (`sessionOn`, `sessionContaining`, `isOpen`, `sessionsInRange`,
+    `nextSession`, `previousSession`).
+  - **Bucketing seam** — `sessionSequence()` / `barSequence(period)` return a
+    `BoundedSequence` that flows straight through `aggregate` / `materialize`,
+    so every bucket is a real trading session/bar (no weekend/holiday buckets,
+    no bucket spanning a closure). Zero core edits.
+  - **`tagSessions(series, { column?, stamped? })`** — appends a session-id
+    column (`number | undefined`) for `partitionBy` so stateful ops don't bridge
+    a session boundary. `stamped: 'close'` bins a bar stamped at its close into
+    the closing session (`(open, close]`) for OHLC feeds.
+  - **`DiscontinuityProvider`** — the d3fc-style 5-method provider
+    (`clampUp`/`clampDown`/`distance`/`offset`/`copy` + optional `boundaries`);
+    `identityDiscontinuity`, `weekendSkip` (bundled reference), and
+    `segmentDiscontinuity(segments, { spacing })`.
+  - **`TradingCalendar.discontinuities({ range?, spacing?, period? })`** — the
+    chart-ready provider; `spacing: 'proportional'` (default, true-time) or
+    `'uniform'` (equal-width per session/bar, the TradingView ordinal look).
+- **`@pond-ts/charts`: trading-time x axis.** Pass a `@pond-ts/financial`
+  provider (structurally — charts never imports that package) to collapse
+  closed-market gaps:
+  - **`ChartContainer` `discontinuities` prop** (low-level) and **`calendar` +
+    `spacing` props** (high-level sugar; `calendar` is a structural
+    `TradingCalendarLike`, `spacing` defaults to proportional).
+  - **`scaleTradingTime`** — a d3-scale-shaped discontinuous time scale; ticks
+    coarsen to a **calendar grain** (week/month/quarter/year starts) with
+    date/year labels, and **session dividers** draw at the collapse points
+    (`theme.axis.sessionDivider`), aligned with the labels.
+  - `Charts/TradingTimeAxis` stories (weekend/holiday/half-day/intraday,
+    continuous-vs-trading, daily-months, proportional-vs-uniform).
+- **`@pond-ts/charts`:** selection now has a stable series identity. `SelectInfo`
+  carries an `id`, and `BarChart` / `ScatterChart` take an optional `id` prop —
+  the series identity used for selection + hover. An `id` **gates interactivity**:
+  a layer is selectable/hoverable only when given one (a layer with no `id`
+  renders and reads out but can't be selected). A dev-warning fires when
+  `selected`/`onSelect` is wired but no layer carries an `id`. First slice of the
+  selection RFC (`docs/rfcs/selection.md`, Amendments 2–3).
+- **`pond-ts`: `bin(W, 'minMaxFirstLast')`** — the four-channel M4 downsampling
+  reducer (per-bin min/max/first/last, validity-aware, chunked-delegating); the
+  foundation for the charts decimator wave.
+- **`pond-ts`: `binBy`** — key-domain bucketed reduction (the M4 gappy-data
+  decimation path).
+
+### Changed
+
+- **BREAKING (`@pond-ts/charts`):** `SelectInfo` gained a required `id` field
+  (`{ id, key, value, color, label }`) — `id` is the selection identity, `key` /
+  `value` are now click provenance. Code that constructs a `SelectInfo` by hand
+  must add `id`, and selection equality/dedup now keys on `id`, not the sample
+  `begin`.
+- **BREAKING (`@pond-ts/charts`):** `BarChart` / `ScatterChart` selection now
+  requires an explicit `id` prop — the previous implicit `as ?? column` selection
+  identity is gone. A selectable bar/scatter layer must add `id` (e.g.
+  `<BarChart series={s} column="v" id="v" />`); without it the layer is
+  display-only.
+
 ## [0.41.0] — 2026-07-06
 
 ### Added

package/dist/column.d.ts

@@ -69,9 +69,14 @@ export type PublicColumnForKind<K extends 'number' | 'boolean' | 'string' | 'arr
  * convention (e.g. `'p95'`, `'p99.9'`) where `q` is in `[0, 100]` —
  * runtime check enforces the range. The fused `'minMax'` is special:
  * it returns a two-channel `{ lo, hi }` rather than a single
- * `Float64Array`.
+ * `Float64Array`. The fused `'minMaxFirstLast'` extends that to four
+ * channels `{ lo, hi, first, last }` — the M4 downsampling reducer
+ * (Jugel et al., VLDB 2014): `first`/`last` are the first/last
+ * defined value in each bin, which keep a decimated polyline
+ * continuous across bin boundaries (the line enters at `first`,
+ * exits at `last`).
  */
-export type BinReducerName = 'min' | 'max' | 'sum' | 'mean' | 'stdev' | 'median' | 'count' | `p${number}` | 'minMax';
+export type BinReducerName = 'min' | 'max' | 'sum' | 'mean' | 'stdev' | 'median' | 'count' | `p${number}` | 'minMax' | 'minMaxFirstLast';
 /**
  * Output type for `Float64Column.bin(W, reducer)`. Narrows
  * on the reducer name so consumers don't need a runtime cast:
@@ -84,6 +89,12 @@ export type BinReducerName = 'min' | 'max' | 'sum' | 'mean' | 'stdev' | 'median'
  *   — stride-1 access per channel matches the canvas-2D inner draw
  *   loop's per-pixel `lo[px]` / `hi[px]` reads. Empty bins on both
  *   channels are `NaN`.
+ * - `'minMaxFirstLast'` produces the four-channel
+ *   `{ lo, hi, first, last }` (all `Float64Array(W)`) — the M4
+ *   reducer. `first`/`last` carry the bin's first/last defined
+ *   value so a decimated line stays continuous at bin seams. Empty
+ *   bins are `NaN` on all four channels (canvas-friendly: a `NaN`
+ *   vertex breaks the sub-path, the correct "no data here" visual).
  *
  * Generalized for future multi-point reducers (e.g. LTTB) — those
  * would land as their own output shape (e.g. `{ keys, values }`
@@ -92,6 +103,11 @@ export type BinReducerName = 'min' | 'max' | 'sum' | 'mean' | 'stdev' | 'median'
 export type BinOutput<R extends BinReducerName> = R extends 'minMax' ? {
     lo: Float64Array;
     hi: Float64Array;
+} : R extends 'minMaxFirstLast' ? {
+    lo: Float64Array;
+    hi: Float64Array;
+    first: Float64Array;
+    last: Float64Array;
 } : Float64Array;
 /**
  * Public key-column class for a single first-column kind.
@@ -239,8 +255,9 @@ declare module './columnar/column.js' {
          * and §8 worked example.
          *
          * Returns a fresh `Float64Array(bins)` for scalar reducers,
-         * or `{ lo: Float64Array(bins); hi: Float64Array(bins) }` for
-         * `'minMax'`. An earlier revision exposed an optional
+         * `{ lo, hi }` for `'minMax'`, or the four-channel
+         * `{ lo, hi, first, last }` for `'minMaxFirstLast'` (the M4
+         * downsampling reducer). An earlier revision exposed an optional
          * `{ out }` parameter for buffer reuse; the
          * chart-experiment M2.3 measurement showed it contributed
          * nothing on top of the chart-side Y-from-bin-output
@@ -250,6 +267,16 @@ declare module './columnar/column.js' {
          * V8 nursery GC budget.
          */
         bin<R extends BinReducerName>(bins: number, reducer: R): BinOutput<R>;
+        /**
+         * Key-domain bucketed reduction — buckets by explicit sorted
+         * `edges` over a parallel monotonic `key`, rather than by equal
+         * index count. The M4 decimator's correct form for irregular /
+         * gappy data (a bin maps to a range of the key axis, not of
+         * indices). Same reducers and output shapes as `bin`. O(n + W).
+         * See the impl JSDoc for the merge-walk and edge/precondition
+         * semantics.
+         */
+        binBy<R extends BinReducerName>(key: ArrayLike<number>, edges: ArrayLike<number>, reducer: R): BinOutput<R>;
     }
     interface BooleanColumn {
         at(i: number): boolean | undefined;
@@ -320,6 +347,7 @@ declare module './columnar/chunked-column.js' {
          */
         toFloat64Array(): Float64Array;
         bin<R extends BinReducerName>(bins: number, reducer: R): BinOutput<R>;
+        binBy<R extends BinReducerName>(key: ArrayLike<number>, edges: ArrayLike<number>, reducer: R): BinOutput<R>;
     }
     interface ChunkedBooleanColumn {
         at(i: number): boolean | undefined;

package/dist/column.js

@@ -233,43 +233,117 @@ Float64Column.prototype.bin = function (bins, reducer) {
         throw new RangeError(`Float64Column.bin: bins must be a positive integer, got ${bins}`);
     }
     const n = this.length;
+    // Equal-width **index** boundaries: bucket b spans the index range
+    // [bounds[b], bounds[b + 1]). `Math.floor((b * n) / bins)` is the
+    // same split the per-bin loops used inline before the boundary
+    // derivation was factored out (see `reduceFloat64ByBounds`).
+    const bounds = new Int32Array(bins + 1);
+    for (let b = 1; b < bins; b += 1)
+        bounds[b] = Math.floor((b * n) / bins);
+    bounds[bins] = n;
+    return reduceFloat64ByBounds(this, bounds, reducer, 'bin');
+};
+/**
+ * Key-domain bucketed reduction — the M4 decimator's correct form
+ * for **irregular / gappy** data. Where `bin` splits by equal index
+ * count (right only for uniformly spaced samples — see its
+ * uniform-sampling precondition), `binBy` buckets by an explicit set
+ * of sorted `edges` over a parallel monotonic `key`, so a bin maps
+ * to a range of the **key axis** (pixel-time, or a value axis), not
+ * a range of indices. Chart use:
+ *
+ * ```ts
+ * // edges = W+1 device-pixel column boundaries in time, unioned
+ * // with any gap edges (so no bucket spans a gap).
+ * const { lo, hi, first, last } = valueCol.binBy(
+ *   timeKeys, edges, 'minMaxFirstLast',
+ * );
+ * ```
+ *
+ * Because `key` is non-decreasing, every key-interval maps to a
+ * **contiguous** index range, so `binBy` derives per-bucket index
+ * boundaries in one O(n + W) merge walk and then runs the exact same
+ * per-bucket reducer engine as `bin` — only the boundary derivation
+ * differs. Bucket `b` covers samples with `edges[b] <= key <
+ * edges[b + 1]`; the **final** upper edge is inclusive so a sample
+ * exactly at the max edge lands in the last bucket. An empty bucket
+ * (a gap with no samples) reduces to `NaN` — the canvas
+ * sub-path-break sentinel, same as `bin`'s empty bins.
+ *
+ * **Preconditions** (documented, not re-asserted per frame — this is
+ * a per-pixel hot path): `key` is non-decreasing and `key.length ===
+ * this.length`; `edges` is ascending. A non-ascending `edges` is
+ * caught (cheap, once per bucket); a non-monotonic `key` is the
+ * caller's responsibility (the chart adapter and `byValue` both
+ * guarantee it by construction).
+ *
+ * Reducers and output shapes are identical to `bin` (`'minMax'` →
+ * `{ lo, hi }`, `'minMaxFirstLast'` → `{ lo, hi, first, last }`,
+ * scalars → `Float64Array(W)`).
+ */
+Float64Column.prototype.binBy = function (key, edges, reducer) {
+    const n = this.length;
+    if (key.length !== n) {
+        throw new RangeError(`Float64Column.binBy: key length ${key.length} must equal column length ${n}`);
+    }
+    const W = edges.length - 1;
+    if (W < 1) {
+        throw new RangeError(`Float64Column.binBy: edges must have at least 2 entries (1 bucket), got length ${edges.length}`);
+    }
+    // Merge-walk the monotonic key against the sorted edges → per-bucket
+    // index boundaries. `i` only moves forward (both key and edges
+    // ascend), so this is a single O(n + W) pass. bounds[b] = first
+    // index with key >= edges[b]; the final bound uses key > edges[W]
+    // so the max edge is inclusive.
+    const bounds = new Int32Array(W + 1);
+    let i = 0;
+    let prevEdge = edges[0];
+    for (let b = 0; b <= W; b += 1) {
+        const e = edges[b];
+        if (b > 0 && e < prevEdge) {
+            throw new RangeError(`Float64Column.binBy: edges must be ascending; edges[${b}]=${e} < edges[${b - 1}]=${prevEdge}`);
+        }
+        prevEdge = e;
+        if (b < W) {
+            while (i < n && key[i] < e)
+                i += 1;
+        }
+        else {
+            while (i < n && key[i] <= e)
+                i += 1;
+        }
+        bounds[b] = i;
+    }
+    return reduceFloat64ByBounds(this, bounds, reducer, 'binBy');
+};
+/**
+ * Shared per-bucket reduction engine behind `bin` and `binBy`. Given
+ * ascending index boundaries (`bounds[b]..bounds[b + 1]` is bucket
+ * b's index range) and a reducer, produces the per-bucket output.
+ * `bin` supplies equal-index boundaries; `binBy` supplies
+ * key-edge-derived boundaries — the reduction is identical either
+ * way. `method` names the caller for error messages.
+ *
+ * The three fused-`minMax*` paths hoist the validity / finiteness
+ * branch **outside** the bucket loop (it's the same for every
+ * bucket), which is why they're inlined here rather than dispatching
+ * through `sliceByRange().minMax()` per bucket.
+ */
+function reduceFloat64ByBounds(col, bounds, reducer, method) {
+    const W = bounds.length - 1;
+    const values = col._values;
+    const validity = col.validity;
     // ─── Fused minMax — two-channel output ─────────────────────────
-    //
-    // Special-cased because it's the chart's per-pixel hot path and
-    // its output shape ({lo, hi}) doesn't fit the scalar Float64Array
-    // mold. Each bin walks once, fuses both reductions, writes both
-    // channels — half the memory traffic of `[min(), max()]`.
     if (reducer === 'minMax') {
-        const lo = new Float64Array(bins);
-        const hi = new Float64Array(bins);
-        // Inlined per-bin walk over `this._values[start..end)` rather
-        // than `this.sliceByRange(start, end).minMax()` per bin. The
-        // sliced version allocated a Float64Column + Float64Array
-        // subarray view + optionally a validity-bitmap slice on every
-        // bin, then dispatched into the minMax method. Inlining
-        // hoists the validity branch (it's the same for every bin)
-        // and removes the per-bin construction overhead.
-        //
-        // Measured wins (`scripts/perf-bin.mjs`, median of 30 × 3
-        // runs): ~23% on fine-bins (N=100k, W=1024) where per-bin
-        // overhead is the biggest fraction of work; ~9% on chart-
-        // typical (N=1M, W=1024); within noise (~5%) on N=10M where
-        // the inner buffer walk dominates.
-        //
-        // The inner-loop math is byte-identical to
-        // `Float64Column.prototype.minMax` (same NaN parity, same
-        // empty handling) — just over a (start, end) slice of the
-        // underlying buffer.
-        const values = this._values;
-        const validity = this.validity;
-        if (!this.allFinite) {
-            // Guarded path: skip non-finite values (reducer non-finite policy —
-            // docs/notes/reducer-nan-policy.md), matching `minMax()` / the reducer
-            // min/max. A bin with no finite value (all-missing or all-non-finite)
-            // keeps the NaN empty-bin sentinel.
-            for (let b = 0; b < bins; b += 1) {
-                const start = Math.floor((b * n) / bins);
-                const end = Math.floor(((b + 1) * n) / bins);
+        const lo = new Float64Array(W);
+        const hi = new Float64Array(W);
+        if (!col.allFinite) {
+            // Guarded path: skip non-finite values (reducer non-finite
+            // policy — docs/notes/reducer-nan-policy.md). A bucket with no
+            // finite value keeps the NaN empty-bucket sentinel.
+            for (let b = 0; b < W; b += 1) {
+                const start = bounds[b];
+                const end = bounds[b + 1];
                 let loVal;
                 let hiVal;
                 for (let i = start; i < end; i += 1) {
@@ -301,9 +375,9 @@ Float64Column.prototype.bin = function (bins, reducer) {
             return { lo, hi };
         }
         if (validity === undefined) {
-            for (let b = 0; b < bins; b += 1) {
-                const start = Math.floor((b * n) / bins);
-                const end = Math.floor(((b + 1) * n) / bins);
+            for (let b = 0; b < W; b += 1) {
+                const start = bounds[b];
+                const end = bounds[b + 1];
                 if (end <= start) {
                     lo[b] = NaN;
                     hi[b] = NaN;
@@ -321,12 +395,10 @@ Float64Column.prototype.bin = function (bins, reducer) {
             }
         }
         else {
-            // Validity path — use isDefined directly on the original
-            // bitmap with the original index. Avoids the per-bin
-            // validity-bitmap slice that sliceByRange would have done.
-            for (let b = 0; b < bins; b += 1) {
-                const start = Math.floor((b * n) / bins);
-                const end = Math.floor(((b + 1) * n) / bins);
+            // Validity path — isDefined directly on the original bitmap.
+            for (let b = 0; b < W; b += 1) {
+                const start = bounds[b];
+                const end = bounds[b + 1];
                 if (end <= start) {
                     lo[b] = NaN;
                     hi[b] = NaN;
@@ -336,7 +408,6 @@ Float64Column.prototype.bin = function (bins, reducer) {
                 while (i < end && !validity.isDefined(i))
                     i += 1;
                 if (i >= end) {
-                    // All cells in this bin are undefined.
                     lo[b] = NaN;
                     hi[b] = NaN;
                     continue;
@@ -356,39 +427,154 @@ Float64Column.prototype.bin = function (bins, reducer) {
         }
         return { lo, hi };
     }
+    // ─── Fused minMaxFirstLast — four-channel output (M4) ──────────
+    //
+    // Extends fused minMax with per-bucket first/last (first/last
+    // defined-and-finite value), so a downsampled polyline enters each
+    // bucket at `first` and leaves at `last` — continuous across bucket
+    // seams. All four channels agree on which cells count; an empty
+    // bucket is NaN on all four.
+    if (reducer === 'minMaxFirstLast') {
+        const lo = new Float64Array(W);
+        const hi = new Float64Array(W);
+        const first = new Float64Array(W);
+        const last = new Float64Array(W);
+        if (!col.allFinite) {
+            for (let b = 0; b < W; b += 1) {
+                const start = bounds[b];
+                const end = bounds[b + 1];
+                let loVal;
+                let hiVal = 0;
+                let firstVal = 0;
+                let lastVal = 0;
+                for (let i = start; i < end; i += 1) {
+                    if (validity !== undefined && !validity.isDefined(i))
+                        continue;
+                    const x = values[i];
+                    if (!Number.isFinite(x))
+                        continue;
+                    if (loVal === undefined) {
+                        loVal = x;
+                        hiVal = x;
+                        firstVal = x;
+                    }
+                    else {
+                        if (x < loVal)
+                            loVal = x;
+                        if (x > hiVal)
+                            hiVal = x;
+                    }
+                    lastVal = x;
+                }
+                if (loVal === undefined) {
+                    lo[b] = NaN;
+                    hi[b] = NaN;
+                    first[b] = NaN;
+                    last[b] = NaN;
+                }
+                else {
+                    lo[b] = loVal;
+                    hi[b] = hiVal;
+                    first[b] = firstVal;
+                    last[b] = lastVal;
+                }
+            }
+            return { lo, hi, first, last };
+        }
+        if (validity === undefined) {
+            for (let b = 0; b < W; b += 1) {
+                const start = bounds[b];
+                const end = bounds[b + 1];
+                if (end <= start) {
+                    lo[b] = NaN;
+                    hi[b] = NaN;
+                    first[b] = NaN;
+                    last[b] = NaN;
+                    continue;
+                }
+                let loVal = values[start];
+                let hiVal = loVal;
+                for (let i = start + 1; i < end; i += 1) {
+                    const x = values[i];
+                    loVal = loVal <= x ? loVal : x;
+                    hiVal = hiVal >= x ? hiVal : x;
+                }
+                lo[b] = loVal;
+                hi[b] = hiVal;
+                first[b] = values[start];
+                last[b] = values[end - 1];
+            }
+            return { lo, hi, first, last };
+        }
+        for (let b = 0; b < W; b += 1) {
+            const start = bounds[b];
+            const end = bounds[b + 1];
+            if (end <= start) {
+                lo[b] = NaN;
+                hi[b] = NaN;
+                first[b] = NaN;
+                last[b] = NaN;
+                continue;
+            }
+            let i = start;
+            while (i < end && !validity.isDefined(i))
+                i += 1;
+            if (i >= end) {
+                lo[b] = NaN;
+                hi[b] = NaN;
+                first[b] = NaN;
+                last[b] = NaN;
+                continue;
+            }
+            const firstVal = values[i];
+            let loVal = firstVal;
+            let hiVal = firstVal;
+            let lastVal = firstVal;
+            for (i += 1; i < end; i += 1) {
+                if (!validity.isDefined(i))
+                    continue;
+                const x = values[i];
+                loVal = loVal <= x ? loVal : x;
+                hiVal = hiVal >= x ? hiVal : x;
+                lastVal = x;
+            }
+            lo[b] = loVal;
+            hi[b] = hiVal;
+            first[b] = firstVal;
+            last[b] = lastVal;
+        }
+        return { lo, hi, first, last };
+    }
     // ─── Scalar reducers ──────────────────────────────────────────
     //
-    // Dispatch to the registered reducer's reduceColumn fast path
-    // (PR #153) once per bin. The 'mean' → 'avg' mapping mirrors
-    // the public Float64Column.mean() shim. Percentile-via-string
-    // ('p95', 'p99.9', etc.) routes through resolveReducer's
-    // parsePercentile.
+    // Dispatch to the registered reducer's reduceColumn fast path once
+    // per bucket. 'mean' → 'avg' mirrors the Float64Column.mean() shim;
+    // percentile-via-string ('p95', …) routes through resolveReducer.
     const internalName = reducer === 'mean' ? 'avg' : reducer;
     let reducerDef;
     try {
         reducerDef = resolveReducer(internalName);
     }
     catch {
-        throw new TypeError(`Float64Column.bin: unknown reducer '${reducer}'`);
+        throw new TypeError(`Float64Column.${method}: unknown reducer '${reducer}'`);
     }
     if (reducerDef.reduceColumn === undefined) {
-        throw new TypeError(`Float64Column.bin: reducer '${reducer}' has no reduceColumn fast path`);
+        throw new TypeError(`Float64Column.${method}: reducer '${reducer}' has no reduceColumn fast path`);
     }
-    const out = new Float64Array(bins);
-    for (let b = 0; b < bins; b += 1) {
-        const start = Math.floor((b * n) / bins);
-        const end = Math.floor(((b + 1) * n) / bins);
+    const out = new Float64Array(W);
+    for (let b = 0; b < W; b += 1) {
+        const start = bounds[b];
+        const end = bounds[b + 1];
         if (end <= start) {
-            // Preserve mathematical-empty for sum / count (both = 0);
-            // NaN for reducers whose empty is undefined.
+            // Mathematical-empty for sum / count (0); NaN otherwise.
             out[b] = reducer === 'sum' || reducer === 'count' ? 0 : NaN;
             continue;
         }
-        const result = reducerDef.reduceColumn(this.sliceByRange(start, end));
+        const result = reducerDef.reduceColumn(col.sliceByRange(start, end));
         out[b] = typeof result === 'number' ? result : NaN;
     }
     return out;
-};
+}
 // ─── BooleanColumn runtime implementations ───────────────────────
 BooleanColumn.prototype.at = function (i) {
     return this.read(i);
@@ -691,6 +877,12 @@ ChunkedFloat64Column.prototype.bin = function (bins, reducer) {
     // equal-sized chunks at a chart-friendly bin count).
     return materializeChunkedFloat64(this).bin(bins, reducer);
 };
+ChunkedFloat64Column.prototype.binBy = function (key, edges, reducer) {
+    // v1: materialize then delegate, mirroring `bin`. The key array is
+    // parallel to the logical row order, so it needs no per-chunk
+    // remap — materialize preserves row order.
+    return materializeChunkedFloat64(this).binBy(key, edges, reducer);
+};
 // ─── ChunkedBooleanColumn runtime implementations ────────────────
 ChunkedBooleanColumn.prototype.at = function (i) {
     return this.read(i);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pond-ts",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "TypeScript-first time series primitives",
   "license": "MIT",
   "repository": {