@invinite-org/chartlang-runtime 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,312 @@
 # @invinite-org/chartlang-runtime
 
+## 1.3.0
+
+### Minor Changes
+
+- e620ba8: Add `bgcolor(color, opts?)` and `barcolor(color, opts?)` — Pine-ergonomic
+  top-level aliases for the `bg-color` / `bar-color` plot styles. One call
+  (`bgcolor(close > open ? "#16a34a" : "#dc2626", { transp: 80 })`) replaces
+  the verbose `plot(NaN, { style: { kind: "bg-color", … } })`. Surfaced in the
+  generated primitive reference and taught in the chartlang-coding skill.
+
+  Deliverable 2 (per-bar dynamic color): `PlotEmission` gains an optional
+  `colorValue: Color | null` channel; the runtime resolves the `bgcolor` /
+  `barcolor` per-bar color into it (omitted on the static `plot` path → wire
+  byte-identical, every pinned `plot-hash` untouched), validates it
+  (non-empty color string or `null`), and dedups it last-write-wins per
+  `(slotId, bar)` like `value`. Adapters prefer `colorValue` over the static
+  `style.color` at render time — this precedence is now the normative
+  adapter-kit contract (`PlotEmission.colorValue` JSDoc) and is implemented in
+  the canvas2d reference renderer (`null` ⇒ paint-nothing gap; omitted ⇒ static
+  fallback). The Pine converter emits the real per-bar dynamic color
+  (`bgcolor(close > open ? "#16a34a" : "#dc2626")`) instead of a static
+  `plot(NaN, …)`, so `bgcolor`/`barcolor` round-trip with per-bar semantics
+  intact.
+
+- 08cba38: Add `time.*` calendar accessors (`time.year/month/dayofmonth/dayofweek/hour/
+minute/second/timestamp`), a `time.timeClose(t, tz?)` bar-close accessor
+  (Pine's `time_close()` = bar start + interval), a `session.isOpen(t, spec, tz?)`
+  helper, and an `input.session` kind. Calendar fields are derived from a `Time`
+  epoch via the host (authors stay sandboxed — `Date`/`Intl` remain banned). v1
+  is UTC + fixed-offset only; exchange-tz/DST is a scoped follow-up. The Pine
+  converter lowers `dayofweek` / `time()` / `time_close()` / `input.session`.
+- 1efb49c: Add multi-symbol support to `request.security`. `request.security({ symbol,
+interval })` now reads a **different instrument** (not just a higher
+  timeframe), e.g. `request.security({ symbol: "AMEX:SPY", interval: "1D" })`.
+  `symbol` is optional (defaults to the chart symbol) and must be a compile-time
+  literal (`input.symbol` / `input.enum` resolved). A new `multiSymbol` adapter
+  capability gates non-chart-symbol requests: a different-symbol request against
+  an adapter declaring `multiSymbol: false` degrades to an all-NaN
+  bar/series with a single deduped `multi-symbol-not-supported` diagnostic,
+  mirroring `multi-timeframe-not-supported` (the symbol gate precedes the
+  timeframe gate, so a both-different request emits only the symbol diagnostic).
+  The Pine converter now lowers `request.security("OTHER", tf, expr)`, and the
+  `chartlang scaffold-adapter` template advertises `multiSymbol`.
+- 1efb49c: Add `state.array<T>(capacity)` — a persistent, bounded FIFO collection. Push
+  many values across bars (`a.push(v)`) into a fixed-capacity ring and read
+  them back by element (`a.get(0)` = newest, `a.last()`, `a.size`,
+  `a.capacity`, `a.clear()`). Bounded literal capacity keeps it
+  serialization-clean. The Pine converter lowers a bounded numeric
+  `var array<…>` Camp B ring to it.
+
+  The compiler guards the capacity: it must be a compile-time numeric literal
+  (a `const` numeric binding is accepted) that is a positive integer within
+  `MAX_STATE_ARRAY_CAPACITY` (100_000). A non-literal capacity errors
+  `state-array-capacity-not-literal`; an out-of-range / non-integer literal
+  errors `state-array-capacity-exceeds-max`.
+
+### Patch Changes
+
+- Updated dependencies [189493a]
+- Updated dependencies [8bc628e]
+- Updated dependencies [ab8b218]
+- Updated dependencies [8bc628e]
+- Updated dependencies [ab8b218]
+- Updated dependencies [189493a]
+- Updated dependencies [e620ba8]
+- Updated dependencies [08cba38]
+- Updated dependencies [1efb49c]
+- Updated dependencies [1efb49c]
+  - @invinite-org/chartlang-adapter-kit@1.6.0
+  - @invinite-org/chartlang-core@1.3.0
+
+## 1.2.0
+
+### Minor Changes
+
+- 850ae21: Add `bar.point(offset, price)` — index authoring sugar for anchoring drawings
+  by bar offset instead of an absolute timestamp.
+
+  `bar.point` resolves the offset to the existing time-based `WorldPoint`
+  (`{ time, price }`) at compute time, so it composes directly with every
+  `draw.*` anchor argument and introduces no new wire format or anchor union:
+
+  - `bar.point(0, price)` — the current bar.
+  - `bar.point(-n, price)` — `n` bars back, using the real historical timestamp
+    from the runtime's time ring buffer (`NaN` time past retained history; never
+    throws).
+  - `bar.point(n, price)` — a future bar, with the time extrapolated from the
+    median recent bar spacing (falling back to the parsed bar interval when
+    fewer than two bars are retained).
+
+  The compiler's max-lookback analysis now counts a negative integer-literal
+  `bar.point(-n, …)` offset toward `maxLookback` exactly like a `series[n]`
+  lookback, so the runtime sizes the time buffer deeply enough; positive (future)
+  offsets and dynamic offsets contribute no extra depth. The recogniser peels
+  parentheses, so the converter's emitted form `bar.point(-(n), …)` is sized
+  identically to a hand-written `bar.point(-n, …)` (without it, a converted
+  historical tracking line sized its buffer to 0 and resolved to a NaN anchor).
+
+  The Pine v6 converter now lowers `bar_index` drawing anchors to
+  `bar.point(<signed offset>, <price>)` and drops the dead `__BAR_INTERVAL_MS`
+  sentinel and its `bar.time ± (N * __BAR_INTERVAL_MS)` arithmetic — future
+  anchors resolve at runtime instead of needing a host-supplied bar interval.
+
+- ca19e20: Bidirectional plot `offset` — negative offsets shift a plotted series left.
+
+  `offset` becomes a presentation-only **display shift** in bars with the
+  fixed sign convention `+n` = right (future), `−n` = left (past); the
+  numeric series value is unshifted. This replaces the old value-read model
+  (where a positive offset made `series.current` read the value N bars ago
+  and a negative offset resolved to `NaN`). The `*Opts` `offset` JSDoc (and
+  ALMA's `barShift`) now describe both directions and drop the old
+  "negative ⇒ NaN" wording (`AlmaOpts.offset`, the Gaussian-centre
+  position, is unchanged).
+
+  `PlotEmission` gains an optional presentation field `xShift?: number`
+  (signed integer bars; omitted/`0` ≡ no shift, so a no-shift emission is
+  byte-identical to today). `validateEmission` rejects a non-integer
+  `xShift`. The compiler no longer counts `offset` toward `maxLookback`
+  (the value is no longer read from a deeper slot). The runtime threads the
+  declared offset onto the emission as `xShift` (reading a
+  `WeakMap<Series, number>` offset tag set by `makeShiftedSeriesView`; ALMA
+  tags `opts.barShift`) and stops the old value-read shift so
+  `series.current` is unshifted; the reference adapter renders it by
+  projecting `xShift` onto the x-axis (extending the viewport for
+  future-shifted points).
+
+  The Pine converter now maps `plot(<ta.* call>, offset=N)` onto the
+  emitted `ta.*` call's `offset` opt (signed, both directions); a plot
+  whose value is not a direct `ta.*` call drops the offset and emits the
+  new `plot-offset-needs-ta-call` warning, and a plot-level offset
+  replacing the ta call's own `offset=` emits `plot-offset-overrides-ta-offset`.
+
+  The conformance harness's `plot-field` assertion gains an `xShift` field,
+  and a new scenario pins both shift directions plus the unshifted value
+  series.
+
+- 6235ad7: Make the compute bar's OHLCV + derived fields directly indexable as a series.
+
+  `bar.close`, `bar.open`, `bar.high`, `bar.low`, `bar.volume`, and the derived
+  `bar.hl2` / `bar.hlc3` / `bar.ohlc4` / `bar.hlcc4` are now `PriceSeries` /
+  `VolumeSeries` (`number & Series<number>`) on the bar passed to `compute`
+  (`ComputeContext.bar`, typed as the new `BarSeries`). Each field is **both** a
+  scalar — `bar.close * 2`, `plot(bar.close)`, `ta.ema(bar.close, 20)` keep
+  working unchanged — **and** an indexable series, so a script can read prior
+  bars directly:
+
+  ```ts
+  const sma5 =
+    (bar.close[0] + bar.close[1] + bar.close[2] + bar.close[3] + bar.close[4]) /
+    5;
+  ```
+
+  This removes the `ta.ema(bar.close, 1)` identity-trick that scripts previously
+  needed to "republish" a scalar price as an indexable `Series`.
+
+  The adapter-supplied candle type `Bar` (and `request.lowerTf` intrabar bars) is
+  unchanged — it stays scalar OHLCV; only the streaming `compute` bar gains the
+  series shape. `request.security`'s higher-timeframe bar remains the separate
+  `SecurityBar`.
+
+  Migration note: because the field is now an object, `Number.isFinite(bar.close)`
+  is always `false` (it does not coerce) and `bar.close === 42` is `false` (object
+  vs number). Use `bar.close.current` or `+bar.close` in those raw-number
+  contexts. `bar.point(0, bar.close)` continues to work — the runtime coerces the
+  anchor price to a scalar.
+
+- 3bf391a: Add the `draw.fillBetween(edgeA, edgeB, opts?)` drawing primitive — a
+  native filled ribbon between two edges (the closed polygon `edgeA`
+  forward then `edgeB` reversed). It is the chartlang equivalent of Pine's
+  `linefill.new(line1, line2, color)` / `fill(plot1, plot2)`. The
+  pine-converter now lowers static two-line `linefill.new` to it instead of
+  approximating with `draw.rotatedRectangle`, retiring the
+  `linefill-rotatedrect-approximated` diagnostic.
+- 8086003: Add an optional presentation-only `z` (render-order / z-index) option to
+  `plot()` and every `draw.*` primitive. Default `0`; higher renders on
+  top, ties fall back to the existing group + declaration order. Finite
+  numbers only. Affects stacking only — values, alerts, and `state.*` are
+  unchanged.
+
+  Adapter kit: `PlotEmission` and `DrawingEmission` gain the matching
+  presentation-only `z?: number` wire field, validated by
+  `validateEmission` as a finite number (NaN / ±Infinity rejected;
+  fractional and negative allowed). Omitted/`0` stays byte-identical to a
+  pre-feature emission, so existing goldens and conformance hashes are
+  untouched.
+
+  Runtime: `plotImpl` reads `opts.z`, and the drawing-emit path
+  (`createDrawingHandle`) lifts `z` out of `state.style` — into a shallow
+  clone with `z` removed, where the per-kind `draw.*` impls fold the opts
+  bag — and threads it onto the top-level `PlotEmission.z` /
+  `DrawingEmission.z` with the same omit-when-`0` conditional spread used
+  for `xShift`. `z` is persisted **beside** the drawing slot's `state`
+  (never inside `DrawingState`), so an `update` retains the last value. A
+  no-`z` plot or drawing emits no `z` key — byte-identical to the
+  pre-feature baseline. `draw.table` / `draw.group` do not carry `z` in
+  v1.
+
+  Pine converter: `explicit_plot_zorder` is now a recognized no-op instead
+  of an unmapped warning. chartlang already layers marks by declaration
+  order within their group (the normative ordering contract), which is
+  exactly what Pine's `explicit_plot_zorder=true` makes authoritative — so
+  the flag is satisfied by default and needs no chartlang option.
+  `mapDeclarationArgs` no longer raises `indicator-arg-not-mapped` for it;
+  instead it emits a single `explicit-plot-zorder-default` info note
+  (covering both `explicit_plot_zorder=true` and the Pine-default
+  `=false`). The converter still never _emits_ a numeric `z` — Pine has no
+  per-element z source construct. Other unmapped `indicator(...)` args
+  (`timeframe`, etc.) keep warning.
+
+  Compiler: the ambient `@invinite-org/chartlang-core` `.d.ts` shim gains a
+  `ZOrdered { z?: number }` mixin intersected into `PlotOpts` and every
+  `draw.*` option type (mirroring core's `drawingStyle.ts`), so a compiled
+  script's `plot(value, { z })` **and** `draw.*(…, { z })` type-check (the
+  shim stays in lockstep with core).
+
+  Conformance: a new `z-order` scenario pins the plot `z` →
+  `PlotEmission.z` wire contract — a `plot(value, { z: -1 })` emits
+  `z: -1`, a no-`z` plot omits the field (omit-when-`0` byte-identity), and
+  a value-hash proves `z` never transforms the series. The `plot-field`
+  assertion's `field` union widens to also accept `"z"`.
+
+- 073f41b: Add the higher-timeframe expression/callback overload to `request.security`.
+  Alongside the existing data form `request.security({ interval })` →
+  `SecurityBar`, scripts can now write `request.security({ interval }, (bar) =>
+…)` → `Series<number>`, where the callback runs on the **higher-timeframe
+  clock** — `request.security({ interval: "1W" }, (bar) => ta.ema(bar.close, 20))`
+  is a true weekly EMA(20) (20 weekly bars), not 20 main bars of a weekly-stepped
+  series. The result is aligned no-lookahead down to the main timeline.
+
+  - **core** — the `SecurityExpr` callback type (re-exported from the package
+    root), the second `security` overload, and the shared `statefulPrimitives`
+    entry annotated as covering both arities.
+  - **compiler** — records one `SecurityExpressionDescriptor { slotId, interval,
+paramName }` per expression callsite in `manifest.securityExpressions`
+    (sorted by `slotId`, omitted for the data-only form), and validates each
+    callback against the allowed subset — its `bar` parameter and body locals,
+    the ambient `ta` / `inputs`, safe `Math.*` globals, and literals — rejecting
+    any captured outer binding with the new
+    `request-security-expr-captures-local` diagnostic.
+  - **runtime** — mounts one `SecurityExprRunner` per manifest entry: the
+    callback is captured lazily on the first main compute, driven once per HTF bar
+    close through a dedicated fold `StreamState` so `ta.*` accumulate on the HTF
+    clock, and one sampled value per HTF bar feeds a per-slot output buffer that
+    `request.security(opts, expr)` returns aligned no-lookahead to the main
+    timeline. Capability / interval / stream fallbacks return an all-NaN series
+    with a deduped diagnostic.
+  - **host-worker / host-quickjs** — boot the expression form unchanged; the
+    `__manifest` sidecar already carries `securityExpressions`.
+  - **pine-converter** — Pine's `request.security(sym, "D", ta.ema(close, 9))`
+    now lowers to the chartlang callback form
+    `request.security({ interval: "1d" }, (bar) => ta.ema(bar.close, 9))` (a bare
+    OHLCV third arg keeps lowering to the data form).
+  - **conformance** — new scenarios prove the weekly expression value differs
+    from a same-length main-timeframe EMA, plus the `multiTimeframe: false` NaN
+    fallback.
+
+- 5a9c24d: Add `state.series(init)` — a writable, indexable user series. Store an
+  arbitrary value each bar (`s.value = expr`) and read its history N bars
+  back (`s[1]`). Number-coercible (`+s`, `s.current`) and usable as a `ta.*`
+  source. The Pine converter lowers a history-indexed `var` to it.
+- 08c536c: Add the `ta.highestbars` / `ta.lowestbars` primitives plus the cross-package
+  wiring that makes them usable as drawing anchors and Pine-converter targets.
+
+  - **core / runtime:** `ta.highestbars(source, length, opts?)` and
+    `ta.lowestbars(source, length, opts?)` return the bar OFFSET (≤ 0) to the
+    highest / lowest `source` value over the trailing `length` bars (window
+    INCLUDES the current bar). `0` → current bar is the extreme; `-k` → the
+    extreme occurred `k` bars ago. Ties resolve to the most recent bar; NaN
+    inputs are skipped; warmup is `length − 1` bars; tick-mode replays the
+    in-progress head as the offset-0 candidate. Registered in
+    `STATEFUL_PRIMITIVES` (now 174 entries) and `TA_REGISTRY` (now 96 entries).
+  - **compiler:** a literal-length `ta.highestbars` / `ta.lowestbars` call
+    contributes `length − 1` toward `maxLookback`, so the runtime sizes the time
+    ring buffer deep enough for a `bar.point(<that offset>, …)` anchor to resolve.
+    A non-literal length contributes 0.
+  - **pine-converter:** `ta.highestbars` / `ta.lowestbars` now map to the real
+    chartlang primitives (previously lossy passthroughs to `ta.highest` /
+    `ta.lowest`). **Behavior change:** a DYNAMIC `bar_index + <non-literal>`
+    drawing-x anchor no longer raises the hard `requires-bar-interval` error —
+    the offset is resolved by `bar.point` at runtime sign-agnostically (a
+    negative runtime offset, e.g. what `ta.highestbars` returns, resolves to the
+    historical timestamp via the time buffer). Only the literal `bar_index + N`
+    future case still requires a bar interval.
+  - **conformance:** new `TA_HIGHEST_LOWEST_BARS_SCENARIO` export pins both
+    primitives end-to-end through the compiler + runtime over the bundled
+    `goldenBars.json` fixture, and is added to `ALL_SCENARIOS`.
+
+### Patch Changes
+
+- 850ae21: Promote every remaining `@experimental` symbol to `@stable`. The entire
+  `pine-converter` public surface, the three `pineConverterRoundTrip*` conformance
+  scenarios, and `runtime/barPoint.ts` now carry the stable maturity marker.
+  Annotation-only — no behavior, API, or output changes; goldens and conformance
+  reports are byte-identical. The hand-authored `docs/converter/index.md`
+  stability line is updated to match.
+- Updated dependencies [850ae21]
+- Updated dependencies [ca19e20]
+- Updated dependencies [6235ad7]
+- Updated dependencies [3bf391a]
+- Updated dependencies [8086003]
+- Updated dependencies [850ae21]
+- Updated dependencies [073f41b]
+- Updated dependencies [5a9c24d]
+- Updated dependencies [08c536c]
+  - @invinite-org/chartlang-core@1.2.0
+  - @invinite-org/chartlang-adapter-kit@1.3.0
+
 ## 1.1.1
 
 ### Patch Changes

package/dist/barPoint.d.ts

@@ -0,0 +1,20 @@
+import type { Price, WorldPoint } from "@invinite-org/chartlang-core";
+import type { Float64RingBuffer } from "./ringBuffer.js";
+/**
+ * Resolve a `bar.point(offset, price)` call to the time-based
+ * {@link WorldPoint} the rest of the drawing pipeline already speaks.
+ *
+ * `offset === 0` reads the live `bar.time`; `offset < 0` reads the real
+ * historical timestamp `|offset|` bars back from the time ring buffer
+ * (`NaN` past retention); `offset > 0` extrapolates `lastTime + offset *
+ * spacing`, where `spacing` is the median retained-bar delta and falls back
+ * to the parsed bar interval when fewer than two bars are retained. `price`
+ * passes through unchanged. Never throws.
+ *
+ * @since 0.9
+ * @stable
+ * @example
+ *     // const wp = resolveBarPoint(stream.ohlcv.time, "1D", currentTime, -10, 42);
+ */
+export declare function resolveBarPoint(time: Float64RingBuffer, interval: string, currentTime: number, offset: number, price: Price): WorldPoint;
+//# sourceMappingURL=barPoint.d.ts.map

package/dist/barPoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"barPoint.d.ts","sourceRoot":"","sources":["../src/barPoint.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAGtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAoCzD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC3B,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,GACb,UAAU,CAaZ"}

package/dist/barPoint.js

@@ -0,0 +1,72 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// See the LICENSE file in the repo root for full license text.
+import { intervalToSeconds } from "@invinite-org/chartlang-core";
+/**
+ * Parse a bar-interval string to its spacing in milliseconds, or `NaN` when
+ * the string is not a parseable interval. `intervalToSeconds` throws on an
+ * unparseable descriptor; this wrapper swallows that so `bar.point` stays a
+ * non-throwing, graceful-degradation helper.
+ */
+function intervalSpacingMs(interval) {
+    try {
+        return intervalToSeconds({ value: interval, label: interval, group: "" }) * 1000;
+    }
+    catch {
+        return Number.NaN;
+    }
+}
+/**
+ * The median delta between the most recent retained bar times, used to
+ * extrapolate future-bar timestamps. Walks the newest `min(length - 1, cap)`
+ * deltas (cap keeps the scan O(1) on long histories) and returns the median;
+ * `NaN` when fewer than two bars are retained or every delta is non-finite.
+ */
+function medianSpacingMs(time) {
+    const pairs = Math.min(time.length - 1, 100);
+    if (pairs < 1)
+        return Number.NaN;
+    const deltas = [];
+    for (let i = 0; i < pairs; i += 1) {
+        const delta = time.at(i) - time.at(i + 1);
+        if (Number.isFinite(delta))
+            deltas.push(delta);
+    }
+    if (deltas.length === 0)
+        return Number.NaN;
+    deltas.sort((a, b) => a - b);
+    const mid = deltas.length >> 1;
+    return deltas.length % 2 === 1 ? deltas[mid] : (deltas[mid - 1] + deltas[mid]) / 2;
+}
+/**
+ * Resolve a `bar.point(offset, price)` call to the time-based
+ * {@link WorldPoint} the rest of the drawing pipeline already speaks.
+ *
+ * `offset === 0` reads the live `bar.time`; `offset < 0` reads the real
+ * historical timestamp `|offset|` bars back from the time ring buffer
+ * (`NaN` past retention); `offset > 0` extrapolates `lastTime + offset *
+ * spacing`, where `spacing` is the median retained-bar delta and falls back
+ * to the parsed bar interval when fewer than two bars are retained. `price`
+ * passes through unchanged. Never throws.
+ *
+ * @since 0.9
+ * @stable
+ * @example
+ *     // const wp = resolveBarPoint(stream.ohlcv.time, "1D", currentTime, -10, 42);
+ */
+export function resolveBarPoint(time, interval, currentTime, offset, price) {
+    // `price` is a `Price` (number) by contract, but a script may pass a bar
+    // price field (`bar.point(0, bar.close)`) which is now a number-coercible
+    // series view. Coerce to the scalar so the persisted `WorldPoint.price`
+    // is always a number, never the view object. `Number(NaN)` stays NaN.
+    const p = Number(price);
+    if (offset === 0)
+        return { time: currentTime, price: p };
+    if (offset < 0)
+        return { time: time.at(-offset), price: p };
+    const spacing = (() => {
+        const median = medianSpacingMs(time);
+        return Number.isFinite(median) ? median : intervalSpacingMs(interval);
+    })();
+    return { time: currentTime + offset * spacing, price: p };
+}
+//# sourceMappingURL=barPoint.js.map

package/dist/barPoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"barPoint.js","sourceRoot":"","sources":["../src/barPoint.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAG/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAIjE;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,QAAgB;IACvC,IAAI,CAAC;QACD,OAAO,iBAAiB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC;IACrF,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,MAAM,CAAC,GAAG,CAAC;IACtB,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,IAAuB;IAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;IAC7C,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC;IACjC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnD,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC;IAC3C,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;IAC/B,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;AACvF,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAC3B,IAAuB,EACvB,QAAgB,EAChB,WAAmB,EACnB,MAAc,EACd,KAAY;IAEZ,yEAAyE;IACzE,0EAA0E;IAC1E,wEAAwE;IACxE,sEAAsE;IACtE,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACxB,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IACzD,IAAI,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC5D,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE;QAClB,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QACrC,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC1E,CAAC,CAAC,EAAE,CAAC;IACL,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AAC9D,CAAC","sourcesContent":["// Copyright (c) 2026 Invinite. Licensed under the MIT License.\n// See the LICENSE file in the repo root for full license text.\n\nimport type { Price, WorldPoint } from \"@invinite-org/chartlang-core\";\nimport { intervalToSeconds } from \"@invinite-org/chartlang-core\";\n\nimport type { Float64RingBuffer } from \"./ringBuffer.js\";\n\n/**\n * Parse a bar-interval string to its spacing in milliseconds, or `NaN` when\n * the string is not a parseable interval. `intervalToSeconds` throws on an\n * unparseable descriptor; this wrapper swallows that so `bar.point` stays a\n * non-throwing, graceful-degradation helper.\n */\nfunction intervalSpacingMs(interval: string): number {\n    try {\n        return intervalToSeconds({ value: interval, label: interval, group: \"\" }) * 1000;\n    } catch {\n        return Number.NaN;\n    }\n}\n\n/**\n * The median delta between the most recent retained bar times, used to\n * extrapolate future-bar timestamps. Walks the newest `min(length - 1, cap)`\n * deltas (cap keeps the scan O(1) on long histories) and returns the median;\n * `NaN` when fewer than two bars are retained or every delta is non-finite.\n */\nfunction medianSpacingMs(time: Float64RingBuffer): number {\n    const pairs = Math.min(time.length - 1, 100);\n    if (pairs < 1) return Number.NaN;\n    const deltas: number[] = [];\n    for (let i = 0; i < pairs; i += 1) {\n        const delta = time.at(i) - time.at(i + 1);\n        if (Number.isFinite(delta)) deltas.push(delta);\n    }\n    if (deltas.length === 0) return Number.NaN;\n    deltas.sort((a, b) => a - b);\n    const mid = deltas.length >> 1;\n    return deltas.length % 2 === 1 ? deltas[mid] : (deltas[mid - 1] + deltas[mid]) / 2;\n}\n\n/**\n * Resolve a `bar.point(offset, price)` call to the time-based\n * {@link WorldPoint} the rest of the drawing pipeline already speaks.\n *\n * `offset === 0` reads the live `bar.time`; `offset < 0` reads the real\n * historical timestamp `|offset|` bars back from the time ring buffer\n * (`NaN` past retention); `offset > 0` extrapolates `lastTime + offset *\n * spacing`, where `spacing` is the median retained-bar delta and falls back\n * to the parsed bar interval when fewer than two bars are retained. `price`\n * passes through unchanged. Never throws.\n *\n * @since 0.9\n * @stable\n * @example\n *     // const wp = resolveBarPoint(stream.ohlcv.time, \"1D\", currentTime, -10, 42);\n */\nexport function resolveBarPoint(\n    time: Float64RingBuffer,\n    interval: string,\n    currentTime: number,\n    offset: number,\n    price: Price,\n): WorldPoint {\n    // `price` is a `Price` (number) by contract, but a script may pass a bar\n    // price field (`bar.point(0, bar.close)`) which is now a number-coercible\n    // series view. Coerce to the scalar so the persisted `WorldPoint.price`\n    // is always a number, never the view object. `Number(NaN)` stays NaN.\n    const p = Number(price);\n    if (offset === 0) return { time: currentTime, price: p };\n    if (offset < 0) return { time: time.at(-offset), price: p };\n    const spacing = (() => {\n        const median = medianSpacingMs(time);\n        return Number.isFinite(median) ? median : intervalSpacingMs(interval);\n    })();\n    return { time: currentTime + offset * spacing, price: p };\n}\n"]}

package/dist/bufferSnapshot.d.ts

@@ -0,0 +1,102 @@
+import type { JsonValue } from "@invinite-org/chartlang-core";
+import { Float64RingBuffer } from "./ringBuffer.js";
+/**
+ * JSON-clean snapshot shape of a {@link Float64RingBuffer} — the head
+ * index, the filled count, and the raw cell values with non-finite cells
+ * persisted as `null` (the snapshot validator rejects `NaN`). Shared by the
+ * `ta.*` and `state.series` slot persistence paths.
+ *
+ * @since 0.5
+ * @internal
+ * @stable
+ * @example
+ *     // const snap: BufferSnapshot = { headIndex: 0, filled: 1, values: [1] };
+ */
+export type BufferSnapshot = Readonly<{
+    headIndex: number;
+    filled: number;
+    values: ReadonlyArray<number | null>;
+}>;
+/**
+ * Narrow an `unknown` to a plain (non-array) object record. The first guard
+ * every snapshot restore runs before reading named fields.
+ *
+ * @since 0.5
+ * @internal
+ * @stable
+ * @example
+ *     isRecord({ a: 1 }); // true
+ */
+export declare function isRecord(value: unknown): value is Readonly<Record<string, unknown>>;
+/**
+ * Narrow an `unknown` to a finite integer (used for `headIndex` / `filled`
+ * snapshot fields).
+ *
+ * @since 0.5
+ * @internal
+ * @stable
+ * @example
+ *     isInteger(3); // true
+ */
+export declare function isInteger(value: unknown): value is number;
+/**
+ * Map a runtime number to its JSON-clean form: a finite number rides
+ * through, any non-finite value (`NaN`, `±Infinity`) becomes `null` so the
+ * snapshot validator accepts it.
+ *
+ * @since 0.5
+ * @internal
+ * @stable
+ * @example
+ *     finiteOrNull(Number.NaN); // null
+ */
+export declare function finiteOrNull(value: number): number | null;
+/**
+ * Inverse of {@link finiteOrNull} for restore: a persisted `null` rehydrates
+ * to `NaN`, a finite number rides through, and anything else (a string, an
+ * `Infinity` that slipped past serialise) fails to `null` so the caller can
+ * reject the whole slot.
+ *
+ * @since 0.5
+ * @internal
+ * @stable
+ * @example
+ *     restoreNumber(null); // NaN
+ */
+export declare function restoreNumber(value: unknown): number | null;
+/**
+ * Validate that an `unknown` is a well-formed {@link BufferSnapshot}: integer
+ * `headIndex` + `filled`, and a `values` array whose every cell is `null` or
+ * a finite number.
+ *
+ * @since 0.5
+ * @internal
+ * @stable
+ * @example
+ *     isBufferSnapshot({ headIndex: 0, filled: 0, values: [] }); // true
+ */
+export declare function isBufferSnapshot(value: unknown): value is BufferSnapshot;
+/**
+ * Serialise a {@link Float64RingBuffer} into its JSON-clean
+ * {@link BufferSnapshot} record.
+ *
+ * @since 0.5
+ * @internal
+ * @stable
+ * @example
+ *     // const snap = serialiseBuffer(new Float64RingBuffer(8));
+ */
+export declare function serialiseBuffer(buffer: Float64RingBuffer): JsonValue;
+/**
+ * Rebuild a {@link Float64RingBuffer} of the given `capacity` from a
+ * {@link BufferSnapshot}, returning `null` when the snapshot is incompatible
+ * with the capacity (the underlying restore throws and is caught).
+ *
+ * @since 0.5
+ * @internal
+ * @stable
+ * @example
+ *     // const buf = restoreBuffer(snap, 8); // null on capacity mismatch
+ */
+export declare function restoreBuffer(snapshot: BufferSnapshot, capacity: number): Float64RingBuffer | null;
+//# sourceMappingURL=bufferSnapshot.d.ts.map

package/dist/bufferSnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bufferSnapshot.d.ts","sourceRoot":"","sources":["../src/bufferSnapshot.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,aAAa,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACxC,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEzD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAG3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CASxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAOpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CACzB,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,MAAM,GACjB,iBAAiB,GAAG,IAAI,CAQ1B"}

package/dist/bufferSnapshot.js

@@ -0,0 +1,119 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// See the LICENSE file in the repo root for full license text.
+import { Float64RingBuffer } from "./ringBuffer.js";
+/**
+ * Narrow an `unknown` to a plain (non-array) object record. The first guard
+ * every snapshot restore runs before reading named fields.
+ *
+ * @since 0.5
+ * @internal
+ * @stable
+ * @example
+ *     isRecord({ a: 1 }); // true
+ */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Narrow an `unknown` to a finite integer (used for `headIndex` / `filled`
+ * snapshot fields).
+ *
+ * @since 0.5
+ * @internal
+ * @stable
+ * @example
+ *     isInteger(3); // true
+ */
+export function isInteger(value) {
+    return typeof value === "number" && Number.isInteger(value);
+}
+/**
+ * Map a runtime number to its JSON-clean form: a finite number rides
+ * through, any non-finite value (`NaN`, `±Infinity`) becomes `null` so the
+ * snapshot validator accepts it.
+ *
+ * @since 0.5
+ * @internal
+ * @stable
+ * @example
+ *     finiteOrNull(Number.NaN); // null
+ */
+export function finiteOrNull(value) {
+    return Number.isFinite(value) ? value : null;
+}
+/**
+ * Inverse of {@link finiteOrNull} for restore: a persisted `null` rehydrates
+ * to `NaN`, a finite number rides through, and anything else (a string, an
+ * `Infinity` that slipped past serialise) fails to `null` so the caller can
+ * reject the whole slot.
+ *
+ * @since 0.5
+ * @internal
+ * @stable
+ * @example
+ *     restoreNumber(null); // NaN
+ */
+export function restoreNumber(value) {
+    if (value === null)
+        return Number.NaN;
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Validate that an `unknown` is a well-formed {@link BufferSnapshot}: integer
+ * `headIndex` + `filled`, and a `values` array whose every cell is `null` or
+ * a finite number.
+ *
+ * @since 0.5
+ * @internal
+ * @stable
+ * @example
+ *     isBufferSnapshot({ headIndex: 0, filled: 0, values: [] }); // true
+ */
+export function isBufferSnapshot(value) {
+    if (!isRecord(value))
+        return false;
+    if (!isInteger(value.headIndex) || !isInteger(value.filled))
+        return false;
+    return (Array.isArray(value.values) &&
+        value.values.every((entry) => entry === null || (typeof entry === "number" && Number.isFinite(entry))));
+}
+/**
+ * Serialise a {@link Float64RingBuffer} into its JSON-clean
+ * {@link BufferSnapshot} record.
+ *
+ * @since 0.5
+ * @internal
+ * @stable
+ * @example
+ *     // const snap = serialiseBuffer(new Float64RingBuffer(8));
+ */
+export function serialiseBuffer(buffer) {
+    const snapshot = buffer.serialiseSnapshotBuffer();
+    return {
+        headIndex: snapshot.headIndex,
+        filled: snapshot.filled,
+        values: snapshot.values,
+    };
+}
+/**
+ * Rebuild a {@link Float64RingBuffer} of the given `capacity` from a
+ * {@link BufferSnapshot}, returning `null` when the snapshot is incompatible
+ * with the capacity (the underlying restore throws and is caught).
+ *
+ * @since 0.5
+ * @internal
+ * @stable
+ * @example
+ *     // const buf = restoreBuffer(snap, 8); // null on capacity mismatch
+ */
+export function restoreBuffer(snapshot, capacity) {
+    const buffer = new Float64RingBuffer(capacity);
+    try {
+        buffer.restoreFromSnapshotBuffer(snapshot);
+        return buffer;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=bufferSnapshot.js.map

package/dist/bufferSnapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bufferSnapshot.js","sourceRoot":"","sources":["../src/bufferSnapshot.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAI/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAoBpD;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc;IACpC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACtC,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IACxC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC3C,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1E,OAAO,CACH,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;QAC3B,KAAK,CAAC,MAAM,CAAC,KAAK,CACd,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CACrF,CACJ,CAAC;AACN,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,MAAyB;IACrD,MAAM,QAAQ,GAAG,MAAM,CAAC,uBAAuB,EAAE,CAAC;IAClD,OAAO;QACH,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,MAAM,EAAE,QAAQ,CAAC,MAAM;KAC1B,CAAC;AACN,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CACzB,QAAwB,EACxB,QAAgB;IAEhB,MAAM,MAAM,GAAG,IAAI,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC/C,IAAI,CAAC;QACD,MAAM,CAAC,yBAAyB,CAAC,QAAQ,CAAC,CAAC;QAC3C,OAAO,MAAM,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,IAAI,CAAC;IAChB,CAAC;AACL,CAAC","sourcesContent":["// Copyright (c) 2026 Invinite. Licensed under the MIT License.\n// See the LICENSE file in the repo root for full license text.\n\nimport type { JsonValue } from \"@invinite-org/chartlang-core\";\n\nimport { Float64RingBuffer } from \"./ringBuffer.js\";\n\n/**\n * JSON-clean snapshot shape of a {@link Float64RingBuffer} — the head\n * index, the filled count, and the raw cell values with non-finite cells\n * persisted as `null` (the snapshot validator rejects `NaN`). Shared by the\n * `ta.*` and `state.series` slot persistence paths.\n *\n * @since 0.5\n * @internal\n * @stable\n * @example\n *     // const snap: BufferSnapshot = { headIndex: 0, filled: 1, values: [1] };\n */\nexport type BufferSnapshot = Readonly<{\n    headIndex: number;\n    filled: number;\n    values: ReadonlyArray<number | null>;\n}>;\n\n/**\n * Narrow an `unknown` to a plain (non-array) object record. The first guard\n * every snapshot restore runs before reading named fields.\n *\n * @since 0.5\n * @internal\n * @stable\n * @example\n *     isRecord({ a: 1 }); // true\n */\nexport function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {\n    return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * Narrow an `unknown` to a finite integer (used for `headIndex` / `filled`\n * snapshot fields).\n *\n * @since 0.5\n * @internal\n * @stable\n * @example\n *     isInteger(3); // true\n */\nexport function isInteger(value: unknown): value is number {\n    return typeof value === \"number\" && Number.isInteger(value);\n}\n\n/**\n * Map a runtime number to its JSON-clean form: a finite number rides\n * through, any non-finite value (`NaN`, `±Infinity`) becomes `null` so the\n * snapshot validator accepts it.\n *\n * @since 0.5\n * @internal\n * @stable\n * @example\n *     finiteOrNull(Number.NaN); // null\n */\nexport function finiteOrNull(value: number): number | null {\n    return Number.isFinite(value) ? value : null;\n}\n\n/**\n * Inverse of {@link finiteOrNull} for restore: a persisted `null` rehydrates\n * to `NaN`, a finite number rides through, and anything else (a string, an\n * `Infinity` that slipped past serialise) fails to `null` so the caller can\n * reject the whole slot.\n *\n * @since 0.5\n * @internal\n * @stable\n * @example\n *     restoreNumber(null); // NaN\n */\nexport function restoreNumber(value: unknown): number | null {\n    if (value === null) return Number.NaN;\n    return typeof value === \"number\" && Number.isFinite(value) ? value : null;\n}\n\n/**\n * Validate that an `unknown` is a well-formed {@link BufferSnapshot}: integer\n * `headIndex` + `filled`, and a `values` array whose every cell is `null` or\n * a finite number.\n *\n * @since 0.5\n * @internal\n * @stable\n * @example\n *     isBufferSnapshot({ headIndex: 0, filled: 0, values: [] }); // true\n */\nexport function isBufferSnapshot(value: unknown): value is BufferSnapshot {\n    if (!isRecord(value)) return false;\n    if (!isInteger(value.headIndex) || !isInteger(value.filled)) return false;\n    return (\n        Array.isArray(value.values) &&\n        value.values.every(\n            (entry) => entry === null || (typeof entry === \"number\" && Number.isFinite(entry)),\n        )\n    );\n}\n\n/**\n * Serialise a {@link Float64RingBuffer} into its JSON-clean\n * {@link BufferSnapshot} record.\n *\n * @since 0.5\n * @internal\n * @stable\n * @example\n *     // const snap = serialiseBuffer(new Float64RingBuffer(8));\n */\nexport function serialiseBuffer(buffer: Float64RingBuffer): JsonValue {\n    const snapshot = buffer.serialiseSnapshotBuffer();\n    return {\n        headIndex: snapshot.headIndex,\n        filled: snapshot.filled,\n        values: snapshot.values,\n    };\n}\n\n/**\n * Rebuild a {@link Float64RingBuffer} of the given `capacity` from a\n * {@link BufferSnapshot}, returning `null` when the snapshot is incompatible\n * with the capacity (the underlying restore throws and is caught).\n *\n * @since 0.5\n * @internal\n * @stable\n * @example\n *     // const buf = restoreBuffer(snap, 8); // null on capacity mismatch\n */\nexport function restoreBuffer(\n    snapshot: BufferSnapshot,\n    capacity: number,\n): Float64RingBuffer | null {\n    const buffer = new Float64RingBuffer(capacity);\n    try {\n        buffer.restoreFromSnapshotBuffer(snapshot);\n        return buffer;\n    } catch {\n        return null;\n    }\n}\n"]}