pond-ts 0.63.0 → 0.64.0

package/API.md

@@ -164,7 +164,7 @@ Deliberately small — the ordering-based slice of the algebra, no calendar ops
 | Operation schemas | `RollingSchema`, `RollingAlignment`, `AlignSchema`, `DiffSchema`, `SmoothSchema`, `SmoothMethod`, `FillStrategy`, `FillMapping`                    | `packages/core/src/schema/index.ts`                                |
 | Column/data kinds | `Column`, `KeyColumn`, `ColumnKind`, `ScalarKind`, `ScalarValue`, `ColumnValue`, `ArrayValue`, `ValidityBitmap`                                    | `packages/core/src/columnar/`                                      |
 | JSON wire format  | `JsonRowFormat`, `JsonRowForSchema`, `JsonObjectRowForSchema`, `JsonValueForKind`, `JsonTimestampInput`, `JsonTimeRangeInput`, `JsonIntervalInput` | `packages/core/src/schema/index.ts`                                |
-| Temporal utility  | `TemporalLike`, `DurationInput`, `CalendarUnit`, `TimeZoneOptions`, `KeyLike`, `BatchSampleStrategy`                                               | `packages/core/src/core/`, `packages/core/src/sequence/`           |
+| Temporal utility  | `TemporalLike`, `DurationInput`, `CalendarUnit`, `TimeZoneOptions`, `KeyLike`, `BatchSampleStrategy`, `SequenceSample`, `SequenceCoverage`         | `packages/core/src/core/`, `packages/core/src/sequence/`           |
 
 The `pond-ts/types` subpath re-exports the schema-as-contract types with zero
 runtime (`packages/core/src/schema/public.ts`).

package/CHANGELOG.md

@@ -8,7 +8,8 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 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/pond-ts/pond/compare/v0.63.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.64.0...HEAD
+[0.64.0]: https://github.com/pond-ts/pond/compare/v0.63.0...v0.64.0
 [0.63.0]: https://github.com/pond-ts/pond/compare/v0.62.0...v0.63.0
 [0.62.0]: https://github.com/pond-ts/pond/compare/v0.61.0...v0.62.0
 [0.61.0]: https://github.com/pond-ts/pond/compare/v0.60.0...v0.61.0
@@ -66,6 +67,127 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.64.0] — 2026-08-28
+
+### Added
+
+- `pond-ts`: **`Sequence.bounded(range, { coverage })`** — chooses whether a
+  range selects buckets by their sample point (`'sample'`, the default and the
+  existing behaviour) or by their extent (`'overlap'`, every bucket the range
+  touches, including the one containing `range.begin()`). `aggregate` realizes
+  its grid with `'overlap'`; alignment keeps `'sample'`. As a side benefit
+  `bounded({ start: t, end: t }, { coverage: 'overlap' })` is a flooring
+  primitive — it returns exactly the bucket containing `t` — so consumers no
+  longer have to re-derive pond's calendar anchoring by hand to floor a
+  timestamp. New exported type `SequenceCoverage`.
+
+- `@pond-ts/charts`: **`<YAxis zeroAnchored>`** — pins a y-axis's zoom to the
+  value-`0` gridline instead of the pointer, and drops drag-to-pan entirely.
+  For a bar chart, whose baseline must never move: a bar rests on `0` (at the
+  plot floor for all-positive data, or somewhere mid-plot for data that
+  straddles positive and negative), and an ordinary pointer-pivoted gesture
+  would slide that baseline around the plot as you scroll. With
+  `zeroAnchored`, every wheel notch scales the axis around wherever `0`
+  currently renders, so the baseline holds however far in or out you zoom.
+  One qualification: the pivot is clamped into the axis's pixel range, so once
+  `0` has been scrolled off the plot the zoom pivots about the nearer edge and
+  the baseline does creep — benign for bars, where that clamp coincides with
+  the declared floor, but not an unconditional guarantee. Still gated by the
+  container's own `axisPanZoom` opt-in — this changes what the gesture does,
+  not whether it's on.
+
+### Changed
+
+- `pond-ts`: **`aggregate` now emits the bucket containing the first event**,
+  where before it started at the first grid boundary _at or after_ it — so
+  every event between the two aggregated into nothing, silently. 60 daily bars
+  rolled to a calendar month came back holding 38 of them: no error, no
+  warning, no `undefined`, just a well-formed series with a third of the input
+  gone. It contradicted `aggregate`'s own documented membership rule ("point
+  events contribute to the bucket containing their timestamp") and was
+  asymmetric — the trailing partial bucket _was_ emitted. **This changes
+  results for any caller whose first event did not land exactly on a grid
+  boundary**: expect an extra leading bucket, and sums/counts that now account
+  for the previously-dropped events. Callers who worked around it by passing a
+  pre-floored explicit `range` are unaffected — the floor is now what the
+  default does. **Note what `range` does and does not bound:** it selects the
+  grid, not the event scan, so the leading bucket is filled from every event it
+  contains — including events _before_ `range.begin()` when the series has
+  them. On a window narrower than the series (a chart viewport, say) the edge
+  bucket is therefore a complete bucket rather than a clipped one, which is
+  what keeps bar heights stable under a pan; if you need the window to bound
+  the events too, narrow the series rather than the grid. `align(...)` and
+  `materialize(...)` are deliberately unchanged: their grids are _sampled_,
+  and the sample point becomes the output key. A pre-realized
+  `BoundedSequence` argument is an explicit bucket list, used as given and
+  unaffected by any of this. Reported by Tidal (#672).
+
+- `@pond-ts/charts`: **y gutter drag now pans instead of zooming** — matching
+  the x strip's own gesture (drag pans, wheel zooms) instead of the
+  drag-to-zoom behavior it shipped with in `axisPanZoom="y"`/`"xy"`. Wheel
+  still zooms the grabbed axis about the pointer, and double-click still
+  releases it back to its fit; only the drag's own effect changed.
+
+### Fixed
+
+- `@pond-ts/charts`: **a trading-time date band clamped onto a labelled tick
+  keeps its segment boundary.** The F-charts-21 collision fix dropped the whole
+  `{ start, label, shaded }` entry, but `<XAxis>` spans each band
+  `[its start, the next band's start)` and takes its zebra parity from
+  `shaded` — so removing an entry deleted the _period_, not a duplicate label,
+  and the preceding band ran on to the next surviving boundary under its own
+  name and shading. (Aug 1 2026 is a Saturday, so the August band clamps onto
+  Mon Aug 3, already a day tick — August vanished and July painted across it.)
+  `bands()` entries now carry **`showLabel`**, and only the text is suppressed.
+  Found by Codex reviewing the v0.64.0 range.
+- `@pond-ts/charts`: **a controlled y-gutter wheel zoom no longer pivots about
+  the wrong point under a plot-level y zoom.** The `zeroAnchored` pivot was
+  corrected above, but the ordinary (non-anchored) controlled wheel still fed
+  the pointer's _screen_ pixel into the pre-transform scale's pixel space, so
+  the value under the pointer slid out from under it — ~0.14 units per notch at
+  `k = 1.198`. Third and last face of one root cause: a screen-space pixel used
+  where `base`'s pixel space is meant.
+- `@pond-ts/charts`: **a controlled y-gutter pan no longer overshoots the
+  cursor under a plot-level y zoom.** With `onBoundsChange` set, the drag
+  translated the axis's pre-transform scale by a _screen_ pixel delta. Those
+  two pixel spaces differ by the container's `yTransform`, so with the plot's
+  own y pan/zoom engaged (`panZoom="panZoomY"` / `"panZoomXY"`) the axis
+  panned `k`× too far and the grabbed value outran the pointer. Both
+  transforms are applied in pixel space, so the base↔screen relation is
+  exactly affine and the correction is a division, on `log` and `symlog` as
+  well. (The division is exact on all three; end-to-end tracking on `symlog`
+  still drifts, because its knee is re-derived from the panned domain — a
+  pre-existing property the sibling zoom test already documents.) Invisible at
+  `k === 1`.
+- `@pond-ts/charts`: **`<YAxis zeroAnchored>` no longer lets the baseline drift
+  in the controlled path.** With `onBoundsChange` set, the zoom read `0`'s
+  pixel off the axis's _live_ scale but inverted it through `baseYScales`.
+  Those two pixel spaces differ by the container's own `yTransform`, so with
+  the plot's y pan/zoom active (`panZoom="panZoomY"` / `"panZoomXY"`) the
+  baseline crept a few pixels per wheel notch — monotonically, in exactly the
+  gesture whose purpose is to hold it still. It was invisible without a
+  plot-level y zoom, where the two spaces coincide. Found by a post-merge
+  adversarial review of #676.
+- `@pond-ts/charts`: **a `BarChart`'s baseline no longer relocates under a y
+  gutter pan/zoom.** `resolveBarBaseline` decided whether bars rest on zero or
+  on the axis floor by reading the axis's _live, transformed_ domain — the
+  same read a pan/zoom keeps moving — so once a gesture scrolled zero out of
+  view, every bar's rendered top silently snapped to the moving floor instead
+  of its actual value. It now reads the axis's declared (pre-transform)
+  domain for that decision, so a pan/zoom can move the viewport without ever
+  relocating a bar's own baseline.
+- `@pond-ts/charts`: **[F-charts-21] a trading-time axis's stacked date-band
+  row no longer draws a second, colliding label over a collapsed-gap seam.**
+  `scale.bands()` picked its anchors from the raw calendar (a month or day
+  start) without checking whether that instant was live, so a period
+  beginning on a collapsed weekend or holiday clamped its label onto the same
+  seam a tick (or another band) already occupied — rendering as two
+  overlapping labels (`"Aug"` over `"Aug 3"`, or worse at tight zoom, fully
+  interleaved). Bands whose raw start needed clamping now dedupe against a
+  run of other clamped starts landing on the same live instant (picking the
+  genuinely-live member as the representative when one exists) and against
+  an already-labelled tick, so a seam carries exactly one label.
+
 ## [0.63.0] — 2026-08-18
 
 ### Added

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

@@ -722,6 +722,31 @@ export declare class TimeSeries<S extends SeriesSchema> {
      * bucket containing their timestamp. Interval-like events contribute to every bucket they
      * overlap under half-open overlap rules.
      *
+     * The grid **covers** `range` rather than sampling it: the first bucket
+     * emitted is the one *containing* `range.begin()`, even when it starts
+     * before it, so every event in `range` lands in some emitted bucket. This is
+     * what distinguishes bucketing from `align(...)` / `materialize(...)`, whose
+     * grids are sampled — there the bucket's sample point becomes the output
+     * key, so a bucket starting before the range would key a point outside the
+     * window the caller asked for.
+     *
+     * `range` bounds the **grid, not the event scan**. Every bucket is filled
+     * from every event it contains, so a leading bucket that starts before
+     * `range.begin()` also sums the events in front of it when the series has
+     * them. That is what makes a bucket's value independent of the window it is
+     * viewed through — the same bucket reads the same under any `range` — but it
+     * means a narrow `range` over a wide series does *not* clip contributions to
+     * the window. To bound the events as well, narrow the series (`within(...)`)
+     * rather than the grid; note that this instead leaves the edge buckets
+     * partially filled, which is the trade being made either way.
+     *
+     * Coverage applies to a grid this call realizes. A pre-realized
+     * `BoundedSequence` is an explicit bucket list and is used exactly as given
+     * — pond will not extend it with a bucket the caller did not ask for — so
+     * `aggregate(seq.bounded(r), ...)` keeps whatever leading edge `bounded`
+     * produced. Pass the `Sequence` itself with `{ range }` to get the covering
+     * grid.
+     *
      * Defaults:
      * - `range`: `series.timeRange()`
      *

package/dist/batch/time-series.js

@@ -273,10 +273,10 @@ function makeSmoothSchema(schema, target, output) {
         { name: output, kind: 'number', required: false },
     ]);
 }
-function toBoundedSequence(sequence, range, sample) {
+function toBoundedSequence(sequence, range, sample, coverage = 'sample') {
     return sequence instanceof BoundedSequence
         ? sequence
-        : sequence.bounded(range, { sample });
+        : sequence.bounded(range, { sample, coverage });
 }
 function isTimeKeyed(series) {
     return series.firstColumnKind === 'time';
@@ -3967,7 +3967,15 @@ function aggregateInternal(series, sequence, mapping, options = {}) {
             rows: [],
         });
     }
-    const buckets = toBoundedSequence(sequence, range, 'begin').intervals();
+    // Bucketing selects by extent, not by sample point: every event inside
+    // `range` must land in an emitted bucket, including the events between
+    // `range.begin()` and the first grid boundary at or after it. Alignment
+    // and materialization deliberately keep the default 'sample' coverage —
+    // there the sample point becomes the output key, so a bucket starting
+    // before the range would key a point outside the range the caller asked
+    // for. Reported by Tidal in pond-ts#672
+    // (docs/notes/tidal-aggregate-leading-bucket-2026-08.md).
+    const buckets = toBoundedSequence(sequence, range, 'begin', 'overlap').intervals();
     const columns = aggregateColumns;
     if (isTimeKeyed(series)) {
         // Step 3B columnar fast path: when every mapped column is a built-in

package/dist/index.d.ts

@@ -38,6 +38,7 @@ export type { CalendarOptions, CalendarUnit, TimeZoneOptions, } from './core/cal
 export type { EventKey, IntervalInput, IntervalValue, TemporalLike, TimeRangeInput, TimestampInput, } from './core/temporal.js';
 export type { DurationInput } from './core/duration.js';
 export type { SequenceSample } from './sequence/sequence.js';
+export type { SequenceCoverage } from './sequence/sequence.js';
 export type { LiveSeriesOptions, OrderingMode, RetentionPolicy, } from './live/live-series.js';
 export type { LiveRollingOptions, RollingWindow, } from './live/live-rolling-aggregation.js';
 export type { DurationString, FusedMapping, FusedMappingElaborated, FusedMappingValue, FusedRollingSchema, FusedPartitionedRollingSchema, } from './schema/index.js';

package/dist/sequence/index.d.ts

@@ -1,6 +1,7 @@
 export { Sequence } from './sequence.js';
 export { BoundedSequence } from './bounded-sequence.js';
 export type { SequenceSample } from './sequence.js';
+export type { SequenceCoverage } from './sequence.js';
 export type { SampleStrategy } from './sample.js';
 export type { BatchSampleStrategy } from './sample.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/sequence/sequence.d.ts

@@ -4,6 +4,21 @@ import type { DurationInput } from '../core/duration.js';
 import type { TemporalLike, TimestampInput } from '../core/temporal.js';
 export type { DurationInput };
 export type SequenceSample = 'begin' | 'center' | 'end';
+/**
+ * How `bounded(...)` decides which buckets a range selects.
+ *
+ * - `'sample'` (default) — by the bucket's **sample point**: a bucket is
+ *   selected when the instant picked by `sample` falls in the range. This is
+ *   what alignment wants, where the sample point becomes the output key.
+ * - `'overlap'` — by the bucket's **extent**: a bucket is selected when any
+ *   part of it overlaps the range, so the bucket *containing* `range.begin()`
+ *   is included even though it starts before it. This is what bucketing wants,
+ *   where every event in the range must land in some emitted bucket.
+ *
+ * `'overlap'` selects on extent alone, so `sample` does not affect which
+ * buckets it returns.
+ */
+export type SequenceCoverage = 'sample' | 'overlap';
 type FixedSequenceInput = {
     every: DurationInput;
     anchor?: TimestampInput;
@@ -69,7 +84,31 @@ export declare class Sequence {
      * Example: `sequence.bounded(new TimeRange({ start, end }))`.
      * Realizes a finite `BoundedSequence` over the supplied range.
      *
-     * Sample position controls which intervals are selected:
+     * `coverage` chooses what "over the range" means, and is the more
+     * consequential of the two options:
+     *
+     * - `'sample'` (default) — select by sample point, per the table below. The
+     *   bucket containing `range.begin()` is **excluded** when it starts before
+     *   it, because its sample point sits outside the range.
+     * - `'overlap'` — select every bucket whose extent overlaps the range,
+     *   including the one containing `range.begin()`. `sample` is then ignored:
+     *   selection is on extent, not on a point. Use this whenever the buckets
+     *   are containers that must account for every instant in the range —
+     *   `aggregate` realizes its grid this way.
+     *
+     * At the default `sample: 'begin'` only the leading edge differs between the
+     * two: both keep a trailing bucket that starts inside the range and runs
+     * past its end. Against a non-default `sample` the trailing edge moves too,
+     * because `'overlap'` drops the sample offset that `'sample'` shifts both
+     * edges by — another reason to read `'overlap'` as ignoring `sample`
+     * outright rather than as a modifier on it.
+     *
+     * A single-instant range under `'overlap'` is the flooring primitive:
+     * `sequence.bounded({ start: t, end: t }, { coverage: 'overlap' })` returns
+     * exactly the bucket containing `t`.
+     *
+     * Sample position controls which intervals are selected under
+     * `coverage: 'sample'`:
      *
      * - `'begin'` (default) — sample point is the interval's start.
      *   Includes buckets where `sample ∈ [range.begin, range.end]`.
@@ -84,6 +123,7 @@ export declare class Sequence {
      */
     bounded(range: TemporalLike, options?: {
         sample?: SequenceSample;
+        coverage?: SequenceCoverage;
     }): BoundedSequence;
 }
 //# sourceMappingURL=sequence.d.ts.map

package/dist/sequence/sequence.js

@@ -99,7 +99,31 @@ export class Sequence {
      * Example: `sequence.bounded(new TimeRange({ start, end }))`.
      * Realizes a finite `BoundedSequence` over the supplied range.
      *
-     * Sample position controls which intervals are selected:
+     * `coverage` chooses what "over the range" means, and is the more
+     * consequential of the two options:
+     *
+     * - `'sample'` (default) — select by sample point, per the table below. The
+     *   bucket containing `range.begin()` is **excluded** when it starts before
+     *   it, because its sample point sits outside the range.
+     * - `'overlap'` — select every bucket whose extent overlaps the range,
+     *   including the one containing `range.begin()`. `sample` is then ignored:
+     *   selection is on extent, not on a point. Use this whenever the buckets
+     *   are containers that must account for every instant in the range —
+     *   `aggregate` realizes its grid this way.
+     *
+     * At the default `sample: 'begin'` only the leading edge differs between the
+     * two: both keep a trailing bucket that starts inside the range and runs
+     * past its end. Against a non-default `sample` the trailing edge moves too,
+     * because `'overlap'` drops the sample offset that `'sample'` shifts both
+     * edges by — another reason to read `'overlap'` as ignoring `sample`
+     * outright rather than as a modifier on it.
+     *
+     * A single-instant range under `'overlap'` is the flooring primitive:
+     * `sequence.bounded({ start: t, end: t }, { coverage: 'overlap' })` returns
+     * exactly the bucket containing `t`.
+     *
+     * Sample position controls which intervals are selected under
+     * `coverage: 'sample'`:
      *
      * - `'begin'` (default) — sample point is the interval's start.
      *   Includes buckets where `sample ∈ [range.begin, range.end]`.
@@ -114,6 +138,7 @@ export class Sequence {
      */
     bounded(range, options = {}) {
         const sample = options.sample ?? 'begin';
+        const coverage = options.coverage ?? 'sample';
         const requested = toTimeRange(range);
         const intervals = [];
         if (this.#kind === 'fixed') {
@@ -129,11 +154,26 @@ export class Sequence {
             // boundary case symmetric: begin-sampling at range.end() and
             // end-sampling at range.begin() would otherwise BOTH include
             // intervals whose extent sits entirely outside the range.
-            const sampleOffset = sample === 'center' ? stepMs / 2 : sample === 'end' ? stepMs : 0;
-            const firstIndex = sample === 'end'
-                ? Math.floor((requested.begin() - sampleOffset - anchorMs) / stepMs) +
-                    1
-                : Math.ceil((requested.begin() - sampleOffset - anchorMs) / stepMs);
+            //
+            // Under `coverage: 'overlap'` selection is on extent instead, so the
+            // sample point plays no part: a bucket is in when its extent overlaps
+            // the range. `end > requested.begin()` reduces to `floor` on the same
+            // quotient `ceil` is taken of above — the one index of difference is
+            // the bucket containing `requested.begin()`. The trailing test is
+            // `begin <= requested.end()`, which is what `lastIndex` already
+            // computes at a zero offset, so only the leading edge moves.
+            const sampleOffset = coverage === 'overlap'
+                ? 0
+                : sample === 'center'
+                    ? stepMs / 2
+                    : sample === 'end'
+                        ? stepMs
+                        : 0;
+            const firstIndex = coverage === 'overlap'
+                ? Math.floor((requested.begin() - anchorMs) / stepMs)
+                : sample === 'end'
+                    ? Math.floor((requested.begin() - sampleOffset - anchorMs) / stepMs) + 1
+                    : Math.ceil((requested.begin() - sampleOffset - anchorMs) / stepMs);
             const lastIndex = Math.floor((requested.end() - sampleOffset - anchorMs) / stepMs);
             for (let index = firstIndex; index <= lastIndex; index += 1) {
                 const start = anchorMs + index * stepMs;
@@ -156,14 +196,25 @@ export class Sequence {
                 : sample === 'center'
                     ? start + (end - start) / 2
                     : start;
-            if (sampleTime > requested.end()) {
+            // Under `coverage: 'overlap'` selection is on extent, so both tests
+            // read the bucket's own start rather than its sample point.
+            const selector = coverage === 'overlap' ? start : sampleTime;
+            if (selector > requested.end()) {
                 break;
             }
             // 'begin' and 'center': sample ∈ [requested.begin, requested.end]
             // 'end':                 sample ∈ (requested.begin, requested.end]
-            const include = sample === 'end'
-                ? sampleTime > requested.begin()
-                : sampleTime >= requested.begin();
+            //
+            // Under 'overlap' every candidate is in: the walk starts at the bucket
+            // containing `requested.begin()` (`toPlainDateStart` floors to it), and
+            // every later bucket starts after that, so the leading test can only
+            // ever pass. This is the one line the leading-bucket drop turned on —
+            // the containing bucket was computed above and then discarded here.
+            const include = coverage === 'overlap'
+                ? true
+                : sample === 'end'
+                    ? sampleTime > requested.begin()
+                    : sampleTime >= requested.begin();
             if (include) {
                 intervals.push(new Interval({ value: start, start, end }));
             }

package/package.json

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