@pond-ts/react 0.64.0 → 0.65.0

package/API.md

@@ -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,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.64.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
@@ -67,6 +68,166 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/react",
-  "version": "0.64.0",
+  "version": "0.65.0",
   "description": "React hooks for pond-ts live time series",
   "license": "MIT",
   "repository": {
@@ -34,7 +34,7 @@
     "test:runtime": "vitest run"
   },
   "peerDependencies": {
-    "pond-ts": "^0.64.0",
+    "pond-ts": "^0.65.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {