pond-ts 0.63.0 → 0.65.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`).
@@ -432,19 +432,32 @@ Series shapes (same file): `ChartSeries`, `BandSeries`, `BoxSeries`,
 
 All are pure `(series, options) → TimeSeries` appending output columns;
 `column` defaults to `'close'`; periods are bar counts; warm-up is
-length-preserving (`undefined` head rows).
-
-| Study                       | Output column(s)                    | Options gist                                        | Source                                             |
-| --------------------------- | ----------------------------------- | --------------------------------------------------- | -------------------------------------------------- |
-| `sma`                       | `sma`                               | `{ period, column?, output? }`                      | `packages/financial/src/studies/moving-average.ts` |
-| `ema`                       | `ema`                               | `{ period, column?, output? }` (α = 2/(period+1))   | `packages/financial/src/studies/moving-average.ts` |
-| `bollinger`                 | `bbMiddle`, `bbUpper`, `bbLower`    | `{ period, stdDev?, column?, prefix? }`             | `packages/financial/src/studies/bollinger.ts`      |
-| `envelope`                  | `envMiddle`, `envUpper`, `envLower` | `{ period, percent?, maType?, column?, prefix? }`   | `packages/financial/src/studies/envelope.ts`       |
-| `rollingStdev`              | `stdev`                             | `{ period, column?, output? }` (population, ddof=0) | `packages/financial/src/studies/rolling-stat.ts`   |
-| `rollingMin` / `rollingMax` | `min` / `max`                       | `{ period, column?, output? }` (Donchian edges)     | `packages/financial/src/studies/rolling-stat.ts`   |
-| `rollingPercentile`         | `p{q}` (e.g. `p90`)                 | `{ period, q, column?, output? }`                   | `packages/financial/src/studies/rolling-stat.ts`   |
-| `zScore`                    | `zscore`                            | `{ period, column?, output? }`                      | `packages/financial/src/studies/z-score.ts`        |
-| `percentChange`             | `pctChange`                         | `{ periods?, column?, output? }`                    | `packages/financial/src/studies/percent-change.ts` |
+length-preserving (`undefined` head rows). A **multi-input** study (`atr`)
+names each input instead of taking one `column`, each defaulting to its
+`DEFAULT_OHLCV` name — the same "never hard-code a column" rule applied
+per input.
+
+| Study                       | Output column(s)                     | Options gist                                                                                   | Source                                             |
+| --------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `sma`                       | `sma`                                | `{ period, column?, output? }`                                                                 | `packages/financial/src/studies/moving-average.ts` |
+| `ema`                       | `ema`                                | `{ period, column?, output? }` (α = 2/(period+1))                                              | `packages/financial/src/studies/moving-average.ts` |
+| `bollinger`                 | `bbMiddle`, `bbUpper`, `bbLower`     | `{ period, stdDev?, column?, prefix? }`                                                        | `packages/financial/src/studies/bollinger.ts`      |
+| `envelope`                  | `envMiddle`, `envUpper`, `envLower`  | `{ period, percent?, maType?, column?, prefix? }`                                              | `packages/financial/src/studies/envelope.ts`       |
+| `rollingStdev`              | `stdev`                              | `{ period, column?, output? }` (population, ddof=0)                                            | `packages/financial/src/studies/rolling-stat.ts`   |
+| `rollingMin` / `rollingMax` | `min` / `max`                        | `{ period, column?, output? }` (one edge; `donchian` gives the channel)                        | `packages/financial/src/studies/rolling-stat.ts`   |
+| `rollingPercentile`         | `p{q}` (e.g. `p90`)                  | `{ period, q, column?, output? }`                                                              | `packages/financial/src/studies/rolling-stat.ts`   |
+| `zScore`                    | `zscore`                             | `{ period, column?, output? }`                                                                 | `packages/financial/src/studies/z-score.ts`        |
+| `percentChange`             | `pctChange`                          | `{ periods?, column?, output? }` (= ROC; TA-Lib-verified)                                      | `packages/financial/src/studies/percent-change.ts` |
+| `rsi`                       | `rsi`                                | `{ period?, column?, output? }` (Wilder, default 14)                                           | `packages/financial/src/studies/rsi.ts`            |
+| `macd`                      | `macdLine`, `macdSignal`, `macdHist` | `{ fastPeriod?, slowPeriod?, signalPeriod?, column?, prefix? }` (12/26/9)                      | `packages/financial/src/studies/macd.ts`           |
+| `atr`                       | `atr`                                | `{ period?, high?, low?, close?, output? }` (Wilder, default 14)                               | `packages/financial/src/studies/atr.ts`            |
+| `momentum`                  | `momentum`                           | `{ period?, column?, output? }` (`v − v[−period]`, default 10)                                 | `packages/financial/src/studies/momentum.ts`       |
+| `historicalVolatility`      | `hv`                                 | `{ period?, annualize?, column?, output? }` (σ of log returns, ×√252)                          | `packages/financial/src/studies/volatility.ts`     |
+| `stochastic`                | `stochK`, `stochD`                   | `{ kPeriod?, slowing?, dPeriod?, high?, low?, close?, prefix? }` (14/3/3; `slowing: 1` = fast) | `packages/financial/src/studies/stochastic.ts`     |
+| `williamsR`                 | `williamsR`                          | `{ period?, high?, low?, close?, output? }` (default 14, bounded −100..0)                      | `packages/financial/src/studies/williams-r.ts`     |
+| `donchian`                  | `dcUpper`, `dcLower`, `dcMiddle`     | `{ period?, high?, low?, prefix? }` (default 20)                                               | `packages/financial/src/studies/donchian.ts`       |
+| `obv`                       | `obv`                                | `{ close?, volume?, output? }` (no period; TA-Lib seed `volume[0]`)                            | `packages/financial/src/studies/obv.ts`            |
+| `vwap`                      | `vwap`                               | `{ period, high?, low?, close?, volume?, output? }` (rolling, typical px)                      | `packages/financial/src/studies/vwap.ts`           |
 
 Adding a study? Follow `packages/financial/src/studies/README.md` (uniform
 shape + pandas oracle case + fluent method are all REQUIRED).

package/CHANGELOG.md

@@ -8,7 +8,9 @@ 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.65.0...HEAD
+[0.65.0]: https://github.com/pond-ts/pond/compare/v0.64.0...v0.65.0
+[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 +68,287 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.65.0] — 2026-09-06
+
+### Added
+
+- `@pond-ts/financial`: **`stochastic(...)`**, **`williamsR(...)`** and
+  **`donchian(...)`** — the three range-position studies, built on one new
+  kernel (`highestLowestValues`: the trailing highest high / lowest low in a
+  single `rolling` scan) plus fluent `.stochastic()` / `.williamsR()` /
+  `.donchian()`. All name their bar inputs per column (`high` / `low` /
+  `close`, defaulting to `DEFAULT_OHLCV`), the `atr` shape.
+
+  **`stochastic`** — `{ kPeriod = 14, slowing = 3, dPeriod = 3, prefix =
+'stoch' }` appending `stochK` / `stochD`: the slow stochastic, with
+  `slowing: 1` giving the fast one (TA-Lib's `STOCHF`) from the same
+  function. Values match TA-Lib's `STOCH`/`STOCHF` to `5.7e-14` on every bar
+  TA-Lib emits, `%D` with an identical warm-up. Two deliberate deltas,
+  both documented on the study: **`%K` starts when it can** (bar 15 at the
+  defaults) where TA-Lib masks it back to `%D`'s first bar (17), discarding
+  `dPeriod − 1` real values — the `macd` precedent; and **a flat window
+  (`HH === LL`) is `undefined`** where TA-Lib reports `0`, which is also its
+  value for "close at the very bottom of a real range" — the `rsi` precedent.
+  The smoothing uses a new raw-array kernel, `rollingMeanValues`, that waits
+  for `slowing` _values_ rather than rows: a scratch-column SMA would have
+  put a "3-bar" `%K` on bar 13 with one value in it.
+
+  **`williamsR`** — `{ period = 14, output = 'williamsR' }`, bounded
+  `−100..0`. Matches TA-Lib's `WILLR` bar-for-bar to `1.4e-14` with an
+  identical warm-up; the only delta is the same flat-window `undefined`.
+  It is fast `%K − 100`, computed on the same kernel, and a test pins that
+  identity against `stochastic({ slowing: 1 })`.
+
+  **`donchian`** — `{ period = 20, prefix = 'dc' }` appending `dcUpper` /
+  `dcLower` / `dcMiddle`. `upper` is exactly `rollingMax(high)` and `lower`
+  exactly `rollingMin(low)` (pinned), in one scan plus the midpoint; pandas
+  oracle only (TA-Lib has no Donchian). Scales linearly with price, like
+  `atr`; a missing `high`/`low` is skipped (core's reducer policy), not
+  propagated.
+
+- `@pond-ts/financial`: **`obv(...)`** and **`vwap(...)`** — the first two
+  **volume** studies, plus fluent `.obv()` / `.vwap()`. Both name their inputs
+  per column (`close` / `volume`, and `high` / `low` for VWAP), each
+  defaulting to its `DEFAULT_OHLCV` name, the rule `atr` established.
+
+  **`obv`** is Granville's On-Balance Volume — the running total of each bar's
+  volume signed by its close change — and is the first study with **no
+  `period`**: it is read for its shape, not its level, so there is nothing to
+  size a window over. It is **TA-Lib's OBV exactly**, including the seed
+  (`OBV[0] = volume[0]`) and an unchanged close adding nothing; the oracle
+  asserts equality, with an identical (empty) warm-up mask. On **interior
+  gaps** it deliberately departs from TA-Lib: a running sum has no local
+  answer for a missing term, so a missing close or volume leaves the level
+  `undefined` from that bar on (the same asymmetry the Wilder recursion has —
+  a leading gap shifts the seed, an interior one propagates). TA-Lib has no
+  gap semantics; measured on a seven-bar series it is 400 out of level at
+  the gap bar and 100 out from then on, presented as a value.
+
+  **`vwap`** is a **rolling** Volume-Weighted Average Price:
+  `Σ typicalPrice · volume / Σ volume` over `period` bars, typical price
+  `(high + low + close) / 3`. There is no TA-Lib VWAP and no single
+  definition, so this is a documented design choice: the rolling form fits
+  the package's count-window shape, and the intraday desk's _anchored_ VWAP
+  is not a special case of it (a count window emits only once it spans
+  `period` rows) — that one needs a session reset and is deferred to the
+  session-anchored phase. `period` is **required** (no conventional length to
+  default to). A window with no volume is `undefined`; a bar missing any
+  input is dropped from **both** sums so the ratio is never biased. Verified
+  against a pandas replication on a fixture whose volume spikes make a
+  dropped weighting visible (≥ 1.24 price units from the plain mean).
+
+  The oracle fixture gains a `volumes` input, and four kernels land under
+  them for the studies that follow: `cumulativeValues` (A/D line, PVT),
+  `signedVolumeValues`, `typicalPriceValues` (CCI, MFI, Keltner) and
+  `rollingWeightedMeanValues` (VWMA).
+
+- `@pond-ts/financial`: **`atr(...)`** — Wilder's Average True Range, the third
+  [PND-STUDY] named indicator, plus a fluent `.atr()`. `{ period = 14,
+high = 'high', low = 'low', close = 'close', output = 'atr' }`. Verified
+  against **TA-Lib** bar-for-bar in the oracle — exact agreement at both
+  periods tested, with identical warm-up.
+
+  **The first multi-input study.** Where every study so far took a single
+  `column`, ATR names each of its three inputs, each defaulting to its
+  `DEFAULT_OHLCV` name — the same "never hard-code a column" rule applied per
+  input rather than a new mechanism. Because the inputs are columns of one
+  series they are aligned by construction, so the mismatched-length error
+  array-based libraries must check for at every call is unrepresentable here.
+
+  Warm-up is `period` rows, not `period − 1`: true range needs a previous
+  close, so bar 0 has none.
+
+- `@pond-ts/financial`: **`macd(...)`** — Moving Average Convergence/Divergence,
+  the second [PND-STUDY] named indicator. `{ fastPeriod = 12, slowPeriod = 26,
+signalPeriod = 9, column = 'close', prefix = 'macd' }`, appending
+  `macdLine` / `macdSignal` / `macdHist`, plus a fluent `.macd()`.
+
+  Two deliberate deltas from TA-Lib, both documented on the study:
+  **each column warms up when it can** (the line at bar 25, signal and
+  histogram at 33) where TA-Lib masks all three back to 33, keeping eight real
+  values it discards; and the EMAs are **pond's own** (`α = 2/(span+1)` seeded
+  on the first sample — what `ema()` already ships) rather than TA-Lib's
+  SMA-seeded ones. The second is a _seed_ difference, so it decays: measured
+  at 3.8% of the line's magnitude at the first shared bar, 0.089% by bar 79.
+  Seeding TA-Lib's way would make `macd()` disagree with
+  `ema(fast) − ema(slow)` inside this package, which is the worse surprise —
+  and is pinned by a test.
+
+- `@pond-ts/financial`: **`rsi(...)`** — Wilder's Relative Strength Index, the
+  first of the [PND-STUDY] named indicators. `{ period = 14, column = 'close',
+output = 'rsi' }`, length-preserving warm-up (`period` rows, not `period − 1`
+  — RSI averages _differences_, so it needs one extra bar), and a fluent
+  `.rsi()`. Verified against **TA-Lib** bar-for-bar in the oracle fixture,
+  agreeing to `1.4e-14`.
+
+  Worth knowing which RSI this is: the gain/loss averages are seeded on the
+  arithmetic mean of the first `period` differences, then carried by Wilder's
+  recursion — TA-Lib's definition and Wilder's original. Implementations that
+  instead smooth with a plain first-sample-seeded EMA of the same `α = 1/period`
+  produce a **materially different** series: on this package's own oracle input
+  the two sit up to **7.03 RSI points** apart, and are still `0.15` apart 65
+  bars later. That is enough to move a reading across the conventional 70/30
+  thresholds, so it is a definition choice rather than a rounding detail.
+
+- `@pond-ts/financial`: **`momentum(...)`** — the absolute `period`-bar
+  difference, `value − value[i − period]`. `{ period = 10, column = 'close',
+output = 'momentum' }`, warm-up `period` rows, plus a fluent `.momentum()`.
+  Verified against **TA-Lib's `MOM`** bar-for-bar in the oracle: exact
+  agreement with identical warm-up masks. The additive companion to
+  `percentChange`'s ratio; it is in the price's units and scales with them
+  (pinned by a property test).
+
+- `@pond-ts/financial`: **`historicalVolatility(...)`** — the standard
+  deviation of log returns over `period` bars, annualised.
+  `{ period = 20, annualize = 252, column = 'close', output = 'hv' }`, plus a
+  fluent `.historicalVolatility()`. Warm-up is `period` rows, not
+  `period − 1` — `period` returns need `period + 1` prices, the same
+  off-by-one RSI and ATR have.
+
+  TA-Lib has no HV to arbitrate the conventions, so they are pinned on the
+  study and in the pandas oracle (`np.log(s).diff().rolling(n).std(ddof=0)
+· √annualize`): **population σ** (`ddof = 0`, the package convention shared
+  with Bollinger / `rollingStdev` / `zScore`; a sample σ is
+  `√(n/(n−1))` larger — 2.6% at 20); **log returns**, not simple; annualised
+  by `√annualize` with `252` the default for daily bars and an **option**
+  rather than a hidden constant (`1` for per-bar σ, `252·390` for one-minute
+  bars); and a **decimal** (`0.18` = 18%), the form volatility is consumed
+  in. Scale-invariant, pinned by a property test. A non-positive price has
+  no log return: both returns touching it are missing (explicitly, since
+  `ln(−4/−5)` is a finite non-answer). A leading gap shifts the start so the
+  first window still covers `period` real returns, matching pandas'
+  `min_periods` and the Wilder-family studies — the σ is computed by calling
+  the range-exact kernel on the returns array directly, because a scratch
+  column through `rollingValues` counts rows and would emit one bar early
+  over one return too few.
+
+- `@pond-ts/financial`: **`percentChange` is ROC** — TA-Lib's `ROC` is the same
+  `(price / prevPrice − 1) × 100`, and the oracle now cross-checks the study
+  against it: exact agreement (`0.0`) with identical warm-up masks at both
+  periods. Documented on the study and in API.md; there is deliberately no
+  separate `roc` study.
+
+## [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.65.0",
   "description": "TypeScript-first time series primitives",
   "license": "MIT",
   "repository": {