@pond-ts/react 0.67.0 → 0.68.0

package/AGENTS.md

@@ -0,0 +1,244 @@
+# Using pond from a coding agent
+
+You are reading this because a project depends on `pond-ts` or one of the
+`@pond-ts/*` packages, or because you are deciding whether it should. This
+file is the shortest route to correct code. It ships inside every pond
+tarball as `AGENTS.md`, next to `API.md` (every public export, one line
+each, with its source file) and `CHANGELOG.md`.
+
+Docs: <https://pond-ts.org> · index for agents: <https://pond-ts.org/llms.txt>
+· source: <https://github.com/pond-ts/pond>.
+
+## What pond is, in three lines
+
+- A **typed, immutable time series** (`TimeSeries`) whose schema is declared
+  once `as const` and narrows every downstream transform — no casts.
+- The **same operator vocabulary on a streaming buffer** (`LiveSeries`):
+  push events in, subscribe to incremental `rolling` / `aggregate` views,
+  bounded by retention.
+- **Domain packages on top**: React hooks, canvas charts that read a series
+  directly, financial studies + trading calendars, fitness analytics, and an
+  experimental processing-graph runtime.
+
+## Which package
+
+| You need to…                                                            | Install                              | Import from                                           |
+| ----------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------- |
+| Load timestamped rows; bucket, regrid, roll, fill, join, partition them | `pond-ts`                            | `'pond-ts'`                                           |
+| Ingest a live feed and keep rolling stats over the last N minutes       | `pond-ts`                            | `'pond-ts'` (`LiveSeries`)                            |
+| Share a series' type across a wire boundary with zero runtime           | `pond-ts`                            | `'pond-ts/types'`                                     |
+| Own / subscribe to a series inside React                                | `@pond-ts/react`                     | `'@pond-ts/react'`                                    |
+| Draw it (line, area, band, bar, scatter, box, candlestick, heat map)    | `@pond-ts/charts` (+ react, pond-ts) | `'@pond-ts/charts'`                                   |
+| OHLCV bars, SMA/EMA/RSI/MACD/Bollinger/ATR/VWAP…, market-hours calendar | `@pond-ts/financial`                 | `'@pond-ts/financial'`, `'@pond-ts/financial/fluent'` |
+| GPS / power / heart-rate activity analytics                             | `@pond-ts/fit`                       | `'@pond-ts/fit'`                                      |
+| Computations as JSON plans with caching + provenance (experimental)     | `@pond-ts/process`                   | `'@pond-ts/process'`                                  |
+
+All six release together under one version and release often. Install with
+`@latest` rather than a version written from memory (a cold-start agent once
+wrote `^0.3.0` and spent turns on a 2024 API); keep their ranges in step — a
+pre-1.0 caret (`^0.67.0`) does **not** span minors.
+
+## The idioms that cover most jobs
+
+### 1. Declare the schema, build the series
+
+```ts
+import { TimeSeries, Sequence } from 'pond-ts';
+
+const schema = [
+  { name: 'time', kind: 'time' },
+  { name: 'host', kind: 'string' },
+  { name: 'latencyMs', kind: 'number' },
+] as const; // ← load-bearing. Without it every column widens to string.
+
+const s = TimeSeries.fromJSON({
+  name: 'latency',
+  schema,
+  rows, // positional tuples [time, host, latencyMs] or objects { time, host, latencyMs }
+  sort: true, // input not already time-ordered? sort on construction (stable)
+});
+```
+
+Time cells accept ms-since-epoch numbers, `Date`s, or ISO strings **with an
+offset** (`…Z`, `…+01:00`). A wall-clock string with no offset throws unless
+you pass `parse: { timeZone: 'America/New_York' }`.
+
+Other doors: `TimeSeries.fromPoints(points)` for wide `{ ts, a, b }` rows,
+`fromColumns` for struct-of-arrays / `Float64Array`, `fromArrow` for an Arrow
+table, `fromEvents`. `toJSON()` round-trips.
+
+### 2. Downsample, regrid, slide — three different verbs
+
+```ts
+// Fewer rows out than in: one row per bucket.
+const perMin = s.aggregate(Sequence.every('1m'), {
+  latencyMs: 'avg', // reducer by column …
+  p95: { from: 'latencyMs', using: 'p95' }, // … or a named output; reducers: sum avg min max count first last median stdev pNN
+  host: 'last',
+});
+
+// Same information, on a regular grid (hold / interpolate). No reduction.
+const gridded = s.align(Sequence.every('10s'), { method: 'hold' });
+
+// One output per input event, looking back over a window.
+const rolled = s.rolling('5m', {
+  latencyMs: 'avg',
+  sd: { from: 'latencyMs', using: 'stdev' },
+});
+```
+
+`Sequence.every()` takes fixed durations only (`'10s'`, `'5m'`, `'1h'`,
+`'1d'`). Months, weeks-in-a-zone, calendar days: `Sequence.calendar('month',
+{ timeZone })`. Common shortcuts: `s.baseline('latencyMs', { window: '1h',
+sigma: 2 })` appends avg / sd / upper / lower in one pass;
+`s.outliers(col, { window, sigma })` keeps only the rows outside the band.
+
+### 3. Per-entity, then flatten
+
+```ts
+const perHost = s
+  .partitionBy('host') // every stateful operator below runs per host
+  .rolling('5m', { latencyMs: 'avg' })
+  .collect(); // one flat TimeSeries, `host` carried through (type and runtime)
+// or .toMap() → Map<host, TimeSeries>
+```
+
+`aggregate` and `rolling` under `partitionBy` carry the partition column
+through in both the runtime **and** the static type (since 0.68), so
+`e.get('host')` works on the collected result without naming it. On 0.67 or
+older, name it in the mapping — `{ host: 'first', … }`.
+
+### 4. Clean, fill, join, read out
+
+```ts
+const clean = s.dedupe().fill({ latencyMs: 'hold' }); // also 'linear', 'zero', gap caps
+const joined = a.join(b); // on the time key; see API.md for options
+clean.toPoints(); // [{ ts, host, latencyMs }, …] — chart-library friendly
+clean.toRows(); // positional tuples
+clean.column('latencyMs').mean(); // typed column: min/max/sum/mean/stdev/median/percentile
+clean.column('latencyMs').toFloat64Array(); // zero-copy for canvas / WebGL loops
+```
+
+Everything returns a **new** series. There is no `push` on a `TimeSeries`;
+if you are appending, you want a `LiveSeries`.
+
+### 5. Streaming
+
+```ts
+import { LiveSeries, Sequence } from 'pond-ts';
+
+const live = new LiveSeries({
+  name: 'latency',
+  schema,
+  retention: { maxAge: '15m' }, // or { maxEvents: 10_000 }
+  ordering: 'reorder', // tolerate late rows …
+  graceWindow: '5s', // … up to this late
+});
+
+const view = live.partitionBy('host').rolling('5m', { latencyMs: 'avg' });
+const stop = view.on('event', (e) => render(e.get('host'), e.get('latencyMs')));
+
+live.push([Date.now(), 'api-1', 42]); // validated against the schema
+live.pushMany(batch);
+const snapshot = live.toTimeSeries(); // immutable batch copy for analytics
+```
+
+`live.aggregate(Sequence.every('1m'), …)` emits `'bucket'` (partial) and
+`'close'` (final) events. Retention bounds memory; `sample({ stride })`
+between `partitionBy` and a long `rolling` bounds it further at firehose
+rates.
+
+### React and charts
+
+```tsx
+import { useLiveSeries } from '@pond-ts/react';
+import {
+  ChartContainer,
+  ChartRow,
+  Layers,
+  LineChart,
+  YAxis,
+} from '@pond-ts/charts';
+
+const [live, snap] = useLiveSeries({
+  name: 'latency',
+  schema,
+  retention: { maxAge: '10m' },
+});
+
+<ChartContainer width={800} cursor="crosshair" panZoom>
+  <ChartRow height={240}>
+    <YAxis id="ms" />
+    <Layers>
+      {snap && <LineChart series={snap} column="latencyMs" axis="ms" />}
+    </Layers>
+  </ChartRow>
+</ChartContainer>;
+```
+
+Charts read a pond series directly — do the maths in pond (`rolling`,
+`aggregate`, `align`) and hand the result to a layer. `useLiveSeries`'s snapshot is `null` before the first
+push, hence the guard. `width` is a pixel
+number or `'auto'` (the parent then needs a definite width, or nothing draws).
+Hooks: `useTimeSeries`, `useLiveSeries`, `useSnapshot`, `useLiveQuery`,
+`useDerived`, `useWindow`, `useCurrent`, `useLatest`.
+
+### Financial
+
+```ts
+import '@pond-ts/financial/fluent'; // once, anywhere: adds studies to TimeSeries
+import { TradingCalendar } from '@pond-ts/financial';
+
+const studied = bars
+  .sma({ period: 20 })
+  .rsi({ period: 14 })
+  .bollinger({ period: 20 });
+// or, function form: sma(bars, { period: 20 })
+const cal = TradingCalendar.fromRules(
+  { timeZone: 'America/New_York', open: '09:30', close: '16:00' },
+  { from: '2026-01-05', to: '2026-02-13' },
+);
+```
+
+Studies read `'close'` by default, take **bar-count** periods, append
+columns, preserve row count (warm-up rows are `undefined`). Sixty-plus of
+them; `import { STUDIES } from '@pond-ts/financial/catalog'` lists them at runtime. Session-aligned bars: `ticks.aggregate(cal.barSequence('5m'), {...})`.
+
+## Mistakes agents actually make
+
+1. **Dropping `as const` on the schema.** Everything compiles and every
+   column is `string`. If `.get('x')` is not `number | undefined`, this is
+   why.
+2. **`aggregate` when you meant `rolling`, or vice versa.** `aggregate`
+   changes the row count (one per bucket); `rolling` keeps it (one per
+   event); `align` puts rows on a grid without reducing.
+3. **`Sequence.every('1M')` for months.** Not fixed-length → use
+   `Sequence.calendar('month', { timeZone })`.
+4. **Wall-clock strings without a zone.** `'2025-01-01T09:00'` throws; add
+   `parse: { timeZone }` or use offset strings / ms numbers.
+5. **Unsorted rows.** The constructor throws and names the row; pass
+   `sort: true` rather than sorting by hand.
+6. **Mutating.** Nothing mutates. Capture the return value.
+7. **Iterating events in a hot loop for a chart.** Use `column(name)` /
+   `toFloat64Array()` or hand the series to `@pond-ts/charts` — do not
+   rebuild point arrays per frame.
+8. **Mismatched package versions.** All `pond-ts` / `@pond-ts/*` at the same
+   version, always.
+9. **Reaching for a chart-library adapter first.** If the project uses React,
+   `@pond-ts/charts` consumes the series with no adapter; `toPoints()` is the
+   bridge for other libraries.
+
+## Where to read next
+
+- `API.md` (this folder) — find any export and its source file.
+- <https://pond-ts.org/llms.txt> — every docs page with a one-line
+  description; `https://pond-ts.org/llms-<area>.txt` for a single-fetch dump
+  of one area (`pond-ts`, `charts`, `financial`, …).
+- <https://pond-ts.org/docs/pond-ts/mental-model> — one picture, and the
+  pandas / pondjs translation tables.
+- <https://pond-ts.org/docs/how-to-guides> — end-to-end builds with the
+  friction already ironed out (dashboard, messy CSV ingest, histograms,
+  large series).
+- Claude Code users: `/plugin marketplace add pond-ts/pond` then
+  `/plugin install pond-ts@pond-ts` installs skills for core, charts and
+  financial.

package/API.md

@@ -40,13 +40,13 @@ next door is the point.
 
 ### Series classes & construction
 
-| Export                  | Purpose                                                | Source                                               |
-| ----------------------- | ------------------------------------------------------ | ---------------------------------------------------- |
-| `TimeSeries`            | Immutable time-indexed collection, columnar storage    | `packages/core/src/batch/time-series.ts`             |
-| `ValueSeries`           | Series keyed by a monotonic non-time value axis        | `packages/core/src/batch/value-series.ts`            |
-| `PartitionedTimeSeries` | Scoped view for per-partition stateful transforms      | `packages/core/src/batch/partitioned-time-series.ts` |
-| `Sequence`              | Infinite grid of time buckets (daily, hourly, every N) | `packages/core/src/sequence/sequence.ts`             |
-| `BoundedSequence`       | Finite ordered list of explicit interval buckets       | `packages/core/src/sequence/bounded-sequence.ts`     |
+| Export                  | Purpose                                                                                                                                                 | Source                                               |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `TimeSeries`            | Immutable time-indexed collection, columnar storage                                                                                                     | `packages/core/src/batch/time-series.ts`             |
+| `ValueSeries`           | Series keyed by a monotonic non-time value axis                                                                                                         | `packages/core/src/batch/value-series.ts`            |
+| `PartitionedTimeSeries` | Scoped view for per-partition stateful transforms; `<S, K, By>` — `By` is the partition column names, carried into `aggregate` / `rolling` result types | `packages/core/src/batch/partitioned-time-series.ts` |
+| `Sequence`              | Infinite grid of time buckets (daily, hourly, every N)                                                                                                  | `packages/core/src/sequence/sequence.ts`             |
+| `BoundedSequence`       | Finite ordered list of explicit interval buckets                                                                                                        | `packages/core/src/sequence/bounded-sequence.ts`     |
 
 Static constructors on `TimeSeries`: `fromJSON()` (row tuples/objects),
 `fromColumns()` (struct-of-arrays; `number` + `string` value columns),
@@ -125,10 +125,11 @@ Value-axis wire types
   `arrayContainsAny()`, `arrayAggregate()`, `arrayExplode()`
 - **Gap fill / dedupe**: `fill()`, `materialize()`, `dedupe()`
 - **Aggregate/group**: `aggregate(sequence, spec)`, `reduce()`, `groupBy()`,
-  `partitionBy()`, `byColumn()` (order-free, by column value),
+  `partitionBy()`, `byColumn(col, bins, mapping)` (numeric binning of a column into
+  fixed-`width` or explicit-`edges` bins, then reduce per bin — histograms),
   `rollingByColumn()`, `byValue(axis)` (project onto a `ValueSeries`)
 - **Windowing/smoothing**: `rolling(window, spec, opts)`, `smooth(column,
-method)` (EMA / Butterworth / Savitzky-Golay), `align(method, opts)`
+method, opts)` (`'ema'` / `'movingAverage'` / `'loess'`), `align(method, opts)`
 - **Differential/statistical**: `diff()`, `rate()`, `pctChange()`,
   `cumulative()`, `scan()` (custom stateful reducer), `shift()`, `baseline()`
   (rolling avg/sd/bands), `outliers()` (deviation from baseline)

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.67.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.68.0...HEAD
+[0.68.0]: https://github.com/pond-ts/pond/compare/v0.67.0...v0.68.0
 [0.67.0]: https://github.com/pond-ts/pond/compare/v0.66.0...v0.67.0
 [0.66.0]: https://github.com/pond-ts/pond/compare/v0.65.0...v0.66.0
 [0.65.0]: https://github.com/pond-ts/pond/compare/v0.64.0...v0.65.0
@@ -70,6 +71,33 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.68.0] — 2026-09-13
+
+### Added
+
+- **Agent adoption tranche ([PND-ADOPTMETA] / [PND-ADOPTLINKS] /
+  [PND-LLMSTXT] / [PND-AGENTGUIDE] / [PND-SKILL] / [PND-CONTEXT7]).** Every
+  package now declares `keywords`, `homepage` and `bugs` (there were none —
+  `pond-ts` ranked last in `npm search "time series"`). Every tarball ships an
+  `AGENTS.md` (source `docs/agents/USING_POND.md`): which package for which
+  task, the core idioms, the mistakes agents make. `pond-ts.org/llms.txt` is
+  now llmstxt.org-shaped (titles + descriptions per page, one section per
+  docs area, `Optional` links to `API.md` / the agent guide) with per-area
+  `llms-<area>.txt` dumps so a single fetch stays small. A Claude Code plugin
+  marketplace lives in the repo (`/plugin marketplace add pond-ts/pond`) with
+  `pond-ts`, `pond-charts` and `pond-financial` skills. `context7.json`
+  configures docs-MCP indexing. Plan and baseline:
+  `docs/plans/PND_ADOPTION_PLAN.md`.
+
+- **Agent guide + skill hardened by the first cold-start run** (`docs/agents/USING_POND.md`, shipped as `AGENTS.md`; `plugins/pond-ts/skills/pond-ts`): install with `@latest` and the `.d.ts` paths that carry signatures. Cold-start harness committed at `docs/adoption/cold-start/`.
+
+### Fixed
+
+- **`pond-ts`: the partition column is now in the static type after a partitioned `aggregate` / `rolling` ([PND-PARTCOL]).** `series.partitionBy('host').aggregate(seq, { p95: { from: 'ms', using: 'p95' } }).collect()` always carried `host` at runtime (auto-injected as `'first'`) but the result type omitted it, so `e.get('host')` failed to compile — every fresh agent in the cold-start experiment hit or pre-empted it. `PartitionedTimeSeries` gains a third type parameter `By` (the partition column names, captured by `partitionBy`, default `never`), and the two schema-replacing operators are typed over `WithPartitionColumns<Mapping, By>` — the user's keys win, kind and all; missing partition columns are added as `'first'`. Composite partitions and typed `groups` carry through; `smooth` / `baseline` under `partitionBy` now also keep `K`. Additive: untyped views are unchanged.
+- `@pond-ts/charts` and `@pond-ts/fit` READMEs (rendered on npm) and eight
+  docs pages pointed at the retired `pjm17971.github.io/pond-ts` site /
+  `pjm17971/pond-ts` repo; now `pond-ts.org` / `pond-ts/pond`.
+
 ## [0.67.0] — 2026-09-11
 
 ### Added

package/README.md

@@ -202,6 +202,26 @@ The full guide is at **<https://pond-ts.org/>**.
   — TypeDoc output, every public class and method.
 - **[CHANGELOG](./CHANGELOG.md)** — what shipped in each release.
 
+## For coding agents
+
+pond is built by agents and expects to be used by them. Three things exist so
+an agent can go from "never heard of pond" to working code without a human in
+the loop:
+
+- **`AGENTS.md` + `API.md` ship inside every npm tarball** —
+  `node_modules/pond-ts/AGENTS.md` is a one-read guide (which package for
+  which task, the idioms, the mistakes agents make); `API.md` maps every
+  public export to its source file. Source:
+  [docs/agents/USING_POND.md](docs/agents/USING_POND.md), [API.md](API.md).
+- **<https://pond-ts.org/llms.txt>** — every docs page with a one-line
+  description, plus `llms-<area>.txt` single-fetch dumps per package.
+- **Claude Code plugin** — skills for core, charts and financial, versioned
+  with the library:
+  ```
+  /plugin marketplace add pond-ts/pond
+  /plugin install pond-ts@pond-ts
+  ```
+
 ## Examples
 
 - **[pond-ts-dashboard](https://github.com/pjm17971/pond-ts-dashboard)**

package/package.json

@@ -1,7 +1,24 @@
 {
   "name": "@pond-ts/react",
-  "version": "0.67.0",
-  "description": "React hooks for pond-ts live time series",
+  "version": "0.68.0",
+  "description": "React hooks for pond-ts: subscribe to LiveSeries and derived views with throttled snapshots",
+  "keywords": [
+    "time-series",
+    "timeseries",
+    "typescript",
+    "streaming",
+    "analytics",
+    "react",
+    "hooks",
+    "live",
+    "realtime",
+    "dashboard",
+    "pond-ts"
+  ],
+  "homepage": "https://pond-ts.org/docs/react/",
+  "bugs": {
+    "url": "https://github.com/pond-ts/pond/issues"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -24,17 +41,18 @@
   "files": [
     "dist",
     "CHANGELOG.md",
-    "API.md"
+    "API.md",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "prepack": "cp ../../README.md ./README.md && cp ../../LICENSE ./LICENSE && cp ../../CHANGELOG.md ./CHANGELOG.md && cp ../../API.md ./API.md && npm run build && cp cjs-fallback.cjs dist/cjs-fallback.cjs && find dist -name '*.map' -delete",
+    "prepack": "cp ../../README.md ./README.md && cp ../../LICENSE ./LICENSE && cp ../../CHANGELOG.md ./CHANGELOG.md && cp ../../API.md ./API.md && cp ../../docs/agents/USING_POND.md ./AGENTS.md && npm run build && cp cjs-fallback.cjs dist/cjs-fallback.cjs && find dist -name '*.map' -delete",
     "test": "npm run test:type && npm run test:runtime",
     "test:type": "tsc -p tsconfig.types.json",
     "test:runtime": "vitest run"
   },
   "peerDependencies": {
-    "pond-ts": "^0.67.0",
+    "pond-ts": "^0.68.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {