goro-charts 1.0.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,119 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] — 2026-07-06
+
+### Behavior fixes
+
+- **Data ownership contract (`copy`/`borrowed`).**
+  `setData` now **copies** the arrays by default (`'copy'`), making the chart
+  immune to external mutation. The `'borrowed'` (zero-copy) mode is available
+  as an opt-in but requires the caller to treat the arrays as immutable.
+  _(minor, behavior fix — the default semantics changed from borrowed to copy)_
+- **Numeric input validation.**
+  Length mismatches, non-monotonic X, non-finite X (`Infinity`, `-Infinity`,
+  `NaN`), and non-finite Y (`±Infinity`) are now rejected with a descriptive
+  error naming the series and position — the same contract applies both in
+  snapshot mode (`setData`) and in streaming mode (`append`/`appendBatch`).
+  `NaN` in Y is the only accepted exception (see below). Inputs previously
+  accepted silently (or only with a `console.warn`) now throw.
+  _(minor, behavior fix)_
+- **Non-monotonic append now throws.**
+  The previous `console.warn` was promoted to a thrown error to fail fast.
+  `appendBatch` validates the entire batch before pushing any sample — partial
+  batches never corrupt the ring state. _(minor, behavior fix)_
+- **NaN in Y accepted and documented.**
+  `NaN` in Y is accepted, excluded from the extent computation, and reserved
+  for gap rendering in v1.6.0. Arrays where every Y is `NaN` produce a safe
+  degenerate range. _(minor, behavior fix)_
+
+### Added
+
+- `DataOwnership = 'copy' | 'borrowed'` type and the optional `ownership`
+  parameter on `setData(index, x, y, ownership?)`.
+- `npm run check:readme` script — extracts every `ts` block from the README
+  and typechecks it against the real exported types. Wired into CI.
+- New `Check README examples` CI step (before Typecheck).
+- Reserved (commented-out TODO) slot for `docs/assets/streaming.gif` in the
+  README's first fold — the `![…]` stays commented until the asset exists, so
+  a broken image is never published.
+
+### Changed
+
+- `setData(index, x, y)` now takes an optional fourth argument `ownership`
+  (default `'copy'`).
+- README signature-reference blocks (e.g. `new LineChart(canvas, opts?:
+ChartOpts)`) are marked with `// signature` and skipped by `check:readme`,
+  keeping the readable form without breaking the semantic checking of the
+  runnable examples.
+
+## [1.2.0] — 2026-07-06
+
+### Behavior fixes
+
+- **Crosshair sync by X value, not by pixel.**
+  Charts with different sizes, margins, and domains now sync correctly: the
+  data value is converted from pixel at the origin and back to pixel at the
+  target via pxToX/xToPx. A value outside the domain hides the crosshair on
+  the target. _(minor, behavior fix)_
+- **Stacking separates positives and negatives.**
+  Positives accumulate on an ascending track, negatives on a descending track,
+  without cancelling each other out. In development, series in the same `stack`
+  with divergent axes or lengths emit a descriptive warning.
+  _(minor, behavior fix)_
+- **`renderedPointCount` renamed to `windowPointCount`.**
+  The old metric lied: it returned the total points in the window, not those
+  actually drawn (the renderer decimates to ~2·plotW columns in the dense
+  regime). There are now two honest metrics: `windowPointCount` (data volume)
+  and `drawnPointCount` (post-decimation estimate). Anyone using
+  `renderedPointCount` should migrate to `windowPointCount`.
+  _(minor, behavior fix)_
+
+### Added
+
+- `unsync(other)` — removes bidirectional crosshair synchronization.
+- `drawnPointCount` — estimate of segments actually drawn after decimation
+  (useful to verify that decimation is active).
+- Stacking: alignment validation between series in the same group (axis and
+  length) in development.
+
+### Changed
+
+- `injectCursor` (private) now receives an X value instead of a pixel —
+  aligned with value-based sync. `notifySyncCrosshair` sends a value instead
+  of a screen coordinate.
+- `destroy` now removes the chart from all synced peers before clearing the
+  stores.
+- `accumulateStackGroup` returns separate `{ posCum, negCum }` instead of a
+  single net accumulation.
+
+## [1.1.0] — 2026-07-06
+
+### Behavior fixes
+
+- **`yMin`/`yMax` sentinel: `0` is now a legitimate bound.**
+  Previously `yMin: 0` and `yMax: 0` were treated as "auto" (discarded). They
+  now fall back to an automatic domain only when `undefined`. An anchored
+  `yMin: 0` is the most common case and finally works. _(minor, behavior fix)_
+- **Keyboard: navigation by data point, not by pixel.**
+  The arrow keys move the crosshair point by point (logical) across the first
+  non-empty series. `Shift+arrow` advances 10 points. It previously navigated
+  by pixel, without anchoring to real data. _(minor, behavior fix)_
+- **`prefers-reduced-motion` no longer stops streaming.**
+  It previously turned off `autoDraw`, interrupting the coalesced repaint of
+  live data. It now only sets a flag to suppress visual animations (when
+  present) without affecting the chart's continuous updates.
+  _(minor, behavior fix)_
+
+### Changed
+
+- `ResolvedOpts.yMin` / `ResolvedOpts.yMax` are now `number | undefined`.
+  The "auto" sentinel changed from `0` to `undefined`. Code that relied on the
+  old behavior (e.g. `yMin !== 0` checks) should use `yMin !== undefined`.
+- `prefers-reduced-motion` adds a runtime `change` listener to re-evaluate the
+  preference without recreating the chart. The listener is removed in
+  `destroy()`.
+
 ## [1.0.0]
 
 Initial stable release.

package/README.md

@@ -7,6 +7,10 @@
 
 **[Live demo →](https://stefanelloisaac.github.io/goro-charts/)**
 
+<!-- TODO: gravar e adicionar docs/assets/streaming.gif, depois descomentar:
+![Live streaming demo](docs/assets/streaming.gif)
+-->
+
 Minimal high-performance chart engine. **Canvas 2D only. Zero runtime dependencies. Framework-agnostic.** Inspired by [uPlot](https://github.com/leeoniya/uPlot) — small, fast, and covers only what you need.
 
 - **LineChart** — batched polyline with per-pixel-column min/max decimation
@@ -59,6 +63,7 @@ chart.appendBatch(1, [1, 2, 3], [39, 40, 39]);
 Every chart holds one or more series. Each series owns its visual identity:
 
 ```ts
+// signature
 import type { SeriesConfig } from 'goro-charts';
 
 interface SeriesConfig {
@@ -94,6 +99,7 @@ When `series` is omitted from `ChartOpts` a single default series is created aut
 ### `LineChart`
 
 ```ts
+// signature
 new LineChart(canvas, opts?: ChartOpts)
 ```
 
@@ -102,6 +108,7 @@ Each series is drawn as a single batched polyline. When the dataset is dense (mo
 ### `AreaChart`
 
 ```ts
+// signature
 new AreaChart(canvas, opts?: ChartOpts)
 ```
 
@@ -123,6 +130,7 @@ const chart = new AreaChart(canvas, {
 ### `ScatterChart`
 
 ```ts
+// signature
 new ScatterChart(canvas, opts?: ChartOpts)
 ```
 
@@ -131,9 +139,10 @@ Each series is drawn as filled circles, one per sampled point. When the dataset
 ```ts
 const chart = new ScatterChart(canvas, {
   series: [
-    { name: 'Packets', color: '#f07167', pointRadius: 3.5 },
+    { name: 'Packets', color: '#f07167' },
     { name: 'Errors', color: '#ffb454', dash: [6, 3] },
   ],
+  pointRadius: 3.5,
   maxPoints: 5000,
   autoDraw: true,
 });
@@ -145,18 +154,33 @@ const chart = new ScatterChart(canvas, {
 
 Every data method takes a **series index** as the first argument. `setMaxPoints()`, `clear()`, and `draw()` operate on all series.
 
-| Method         | Signature                                                     | Description                                                        |
-| -------------- | ------------------------------------------------------------- | ------------------------------------------------------------------ |
-| `setData`      | `(seriesIndex, x: Float64Array, y: Float64Array)`             | Snapshot: replace a series. O(n) extent.                           |
-| `append`       | `(seriesIndex, x: number, y: number)`                         | Ring: append one point. O(1) amortized.                            |
-| `appendBatch`  | `(seriesIndex, xs: ArrayLike<number>, ys: ArrayLike<number>)` | Ring: append a batch. O(k).                                        |
-| `setMaxPoints` | `(maxPoints: number)`                                         | Resize the streaming window for all series.                        |
-| `clear`        | `()`                                                          | Empty all series and reset the grid domain.                        |
-| `draw`         | `()`                                                          | Manual paint. No-op when clean and no crosshair.                   |
-| `suspendDraw`  | `()`                                                          | Pause rAF-coalesced drawing. Nestable — pair with `resumeDraw()`.  |
-| `resumeDraw`   | `()`                                                          | Resume after matching `suspendDraw()`. Draws immediately if dirty. |
-| `toImage`      | `()`                                                          | Export the canvas as a PNG data URL.                               |
-| `destroy`      | `()`                                                          | Detach observers, release buffers.                                 |
+| Method         | Signature                                                                           | Description                                                                                                                                                       |
+| -------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `setData`      | `(seriesIndex, x: Float64Array, y: Float64Array, ownership?: 'copy' \| 'borrowed')` | Snapshot: replace a series. O(n) extent. Ownership: `'copy'` (default, safe) copies arrays; `'borrowed'` keeps caller's reference (must be treated as immutable). |
+| `append`       | `(seriesIndex, x: number, y: number)`                                               | Ring: append one point. O(1) amortized.                                                                                                                           |
+| `appendBatch`  | `(seriesIndex, xs: ArrayLike<number>, ys: ArrayLike<number>)`                       | Ring: append a batch. O(k).                                                                                                                                       |
+| `setMaxPoints` | `(maxPoints: number)`                                                               | Resize the streaming window for all series.                                                                                                                       |
+| `clear`        | `()`                                                                                | Empty all series and reset the grid domain.                                                                                                                       |
+| `draw`         | `()`                                                                                | Manual paint. No-op when clean and no crosshair.                                                                                                                  |
+| `suspendDraw`  | `()`                                                                                | Pause rAF-coalesced drawing. Nestable — pair with `resumeDraw()`.                                                                                                 |
+| `resumeDraw`   | `()`                                                                                | Resume after matching `suspendDraw()`. Draws immediately if dirty.                                                                                                |
+| `toImage`      | `()`                                                                                | Export the canvas as a PNG data URL.                                                                                                                              |
+| `destroy`      | `()`                                                                                | Detach observers, release buffers.                                                                                                                                |
+
+### Ownership (`copy` vs `borrowed`)
+
+`setData` accepts an optional fourth argument to control data ownership:
+
+- **`'copy'`** (default) — the chart copies your arrays into fresh buffers. You may reuse or mutate the originals freely after the call. This is the safe default.
+- **`'borrowed'`** — the chart keeps your arrays by reference to avoid allocation. The caller **must** treat the arrays as immutable for as long as the chart holds them; mutating them externally leads to undefined behaviour.
+
+```ts
+// Safe default — caller can mutate the originals later
+chart.setData(0, x, y);
+
+// Zero-copy — caller must not mutate x or y after this call
+chart.setData(0, x, y, 'borrowed');
+```
 
 ### Read-only properties
 
@@ -335,13 +359,13 @@ flat regardless of window size.
 Pre-built `DARK` and `LIGHT` colour presets ready to spread over constructor options.
 
 ```ts
-import { LineChart, DARK, LIGHT } from 'goro-charts'
+import { LineChart, DARK, LIGHT } from 'goro-charts';
 
 // Dark (default) — explicit
-new LineChart(canvas, { ...DARK, series: [...] })
+new LineChart(canvas, { ...DARK, series: [/* ... */] });
 
 // Light theme
-new LineChart(canvas, { ...LIGHT, series: [...] })
+new LineChart(canvas, { ...LIGHT, series: [/* ... */] });
 ```
 
 ---
@@ -402,9 +426,7 @@ tooltips, update framework state, or pipe values into external widgets.
 
 ```ts
 chart.onHover = (hits) => {
-  myTooltipEl.innerHTML = hits
-    .map((h) => `${h.label}: ${h.yVal.toFixed(1)}`)
-    .join('<br>');
+  myTooltipEl.innerHTML = hits.map((h) => `${h.label}: ${h.yVal.toFixed(1)}`).join('<br>');
 };
 ```
 
@@ -454,6 +476,7 @@ outside the canvas.
 ## Troubleshooting
 
 ### Canvas is blank / black
+
 - Ensure the canvas element has non-zero CSS width and height.
 - Check that `chart.draw()` is being called after `setData()` (or enable
   `autoDraw` for streaming mode).
@@ -462,23 +485,27 @@ outside the canvas.
   visible.
 
 ### "Canvas 2D context not available"
+
 - This error means `canvas.getContext('2d')` returned `null`. Common causes:
   - The canvas element does not exist in the DOM at construction time.
   - The canvas was already claimed by a WebGL context.
   - You are running in a server-side environment (Node.js without `node-canvas`).
 
 ### "append() requires the chart to be created with { maxPoints }"
+
 - Streaming methods (`append`, `appendBatch`) require ring mode, which is
   activated by passing `maxPoints` (a positive number) to the constructor.
 - Use `setData()` for snapshot mode (full replacement).
 
 ### Crosshair does not appear
+
 - The crosshair only shows when the mouse is inside the plot area (the inner
   rectangle after padding is applied).
 - Check that `onHover` or mouse events are not being consumed by an overlay
   element above the canvas.
 
 ### Performance is slow with many points
+
 - Verify that decimation is working: the line/area renderers auto-switch to
   per-pixel-column decimation when `count > 2 × plotWidth`.
 - For scatter charts, reduce `maxDots` (default 2000) or set it to a lower

package/dist/charts/chart-base.d.ts

@@ -20,7 +20,7 @@
  */
 import { SeriesStore } from '../data/series-store.js';
 import { Surface } from '../render/surface.js';
-import type { ChartOpts, ResolvedOpts, SeriesConfig, SeriesView, PlotRect } from '../types.js';
+import type { ChartOpts, ResolvedOpts, SeriesConfig, SeriesView, PlotRect, DataOwnership } from '../types.js';
 import type { SeriesHit } from '../render/crosshair.js';
 /** Abstract base for all chart types. */
 export declare abstract class ChartBase {
@@ -39,10 +39,17 @@ export declare abstract class ChartBase {
      */
     private stackGroupsAll;
     private stackGroupsByAxis;
+    /**
+     * Tracks stack-misalignment warnings already emitted, so a misaligned group
+     * warns once instead of on every frame (accumulateStackGroup runs per draw).
+     */
+    private stackWarned;
     private dirty;
     private cursorX;
     private cursorY;
     private showCrosshair;
+    /** Logical index of the keyboard-cursor point in the reference series. */
+    private cursorLogical;
     private autoDraw;
     private rafScheduled;
     private suspendCount;
@@ -50,6 +57,13 @@ export declare abstract class ChartBase {
     private resizeObserver;
     protected destroyed: boolean;
     private liveRegion;
+    /**
+     * Reference to the `prefers-reduced-motion` MQL plus its change listener.
+     * Check `reducedMotionMql.matches` to test the preference; the listener
+     * triggers a re-draw when the preference changes at runtime.
+     */
+    private reducedMotionMql;
+    private readonly handleReducedMotionChange;
     private readonly handleResize;
     private readonly handleMouseMove;
     private readonly handleMouseLeave;
@@ -62,9 +76,15 @@ export declare abstract class ChartBase {
     private validateOpts;
     /**
      * Detect system accessibility preferences and adjust visual styles.
-     * - prefers-reduced-motion → disable rAF coalescing (synchronous draws)
+     * - prefers-reduced-motion → tracked via `reducedMotionMql.matches`
+     *   (streaming/rAF continue normally; read the flag to suppress future
+     *   transitions/animations)
      * - prefers-contrast: more → increase colour opacity
      * - forced-colors: active → use system CSS system colours
+     *
+     * Also registers a `change` listener on the reduced-motion MQL so the
+     * preference is re-evaluated at runtime. The listener is removed in
+     * {@link destroy}.
      */
     private applySystemTheme;
     /**
@@ -77,10 +97,21 @@ export declare abstract class ChartBase {
      * Called once per static redraw.
      */
     private updateAriaLabel;
+    /**
+     * Return the first non-empty series index, or -1 when all stores are empty.
+     * Used as the reference for keyboard navigation — the cursor advances by
+     * logical point indices of this series and the crosshair position is derived
+     * from its X value at the current logical index.
+     */
+    private referenceSeriesIndex;
     /**
      * Handle keyboard navigation for the crosshair.
      * - ArrowLeft / ArrowRight: move crosshair by 1 point (Shift: 10 points)
      * - Escape: hide crosshair
+     *
+     * Navigation is anchored to the logical index of the first non-empty series
+     * (see {@link referenceSeriesIndex}). The pixel position is derived from the
+     * point's X value via the grid domain so the cursor tracks data, not pixels.
      */
     private onKeyDown;
     /** Reusable crosshair-sync helpers used by both mouse and keyboard handlers. */
@@ -91,27 +122,28 @@ export declare abstract class ChartBase {
     /**
      * Snapshot mode: replace the series at `index` (O(n) extent).
      * @param index - Series index (0-based)
-     * @param x - X values, must be monotonically increasing
-     * @param y - Y values, must have the same length as x
-     * @throws {Error} if `index` is out of range, or x/y length mismatch
+     * @param x - X values, must be finite and monotonically increasing
+     * @param y - Y values, may contain NaN (reserved for gaps v1.6.0); non-finite other than NaN is rejected
+     * @param ownership - `'copy'` (default): store copies the arrays; `'borrowed'`: store keeps caller's arrays by reference (must be treated as immutable)
+     * @throws {Error} if `index` is out of range, length mismatch, empty, non-finite X, or non-monotonic X
      */
-    setData(index: number, x: Float64Array<ArrayBufferLike>, y: Float64Array<ArrayBufferLike>): void;
+    setData(index: number, x: Float64Array<ArrayBufferLike>, y: Float64Array<ArrayBufferLike>, ownership?: DataOwnership): void;
     /**
      * Ring mode: append one sample to series `index`.
      * @param index - Series index (0-based)
-     * @param x - X value (must be monotonically increasing)
-     * @param y - Y value
+     * @param x - X value (must be finite and monotonically increasing)
+     * @param y - Y value (NaN is allowed — reserved for gaps v1.6.0)
      * @throws {Error} if ring mode is not active (maxPoints not set)
-     * @throws {Error} if `index` is out of range
+     * @throws {Error} if `index` is out of range, x is not finite, x is non-monotonic, or y is non-finite (NaN allowed)
      */
     append(index: number, x: number, y: number): void;
     /**
      * Ring mode: append a batch of samples to series `index`.
      * @param index - Series index (0-based)
-     * @param xs - X values (must be monotonically increasing)
-     * @param ys - Y values, must have the same length as xs
+     * @param xs - X values (must be finite and monotonically increasing)
+     * @param ys - Y values (NaN is allowed — reserved for gaps v1.6.0)
      * @throws {Error} if ring mode is not active
-     * @throws {Error} if `index` is out of range or xs/ys length mismatch
+     * @throws {Error} if `index` is out of range, length mismatch, non-finite X, non-monotonic X, or non-finite Y (NaN allowed)
      */
     appendBatch(index: number, xs: ArrayLike<number>, ys: ArrayLike<number>): void;
     /**
@@ -125,10 +157,20 @@ export declare abstract class ChartBase {
     /** Number of series configured. */
     get seriesCount(): number;
     /**
-     * Total points rendered across all series in the last draw.
-     * Useful for debug/performance monitoring (e.g. to verify decimation is active).
+     * Total points currently in the window across all series (before decimation).
+     * Useful as a high-level data-volume indicator.
      */
-    get renderedPointCount(): number;
+    get windowPointCount(): number;
+    /**
+     * Estimated number of line segments actually drawn in the last render.
+     * When a series has more than 2×plotW points, the renderer decimates to
+     * ~2·plotW per-pixel-column segments (the `dense` regime). This property
+     * mirrors that rule so you can verify decimation is active.
+     *
+     * Returns an upper bound (the real hardware draw count may be slightly
+     * lower due to degenerate columns) — sufficient for debug/monitoring.
+     */
+    get drawnPointCount(): number;
     /**
      * Number of points currently in the window for series `index`.
      * @param index - Series index (0-based)
@@ -169,6 +211,12 @@ export declare abstract class ChartBase {
      * @param other - Another chart instance to sync with
      */
     sync(other: ChartBase): void;
+    /**
+     * Remove bidirectional crosshair sync previously established with `other`.
+     * No-op if the two charts were not synced.
+     * @param other - Another chart instance to unsync from
+     */
+    unsync(other: ChartBase): void;
     /**
      * External callback for hover events. Called on `mousemove` with the
      * interpolated data for every visible series. Use to build custom DOM
@@ -200,8 +248,23 @@ export declare abstract class ChartBase {
      */
     private computeAllStackGroups;
     /**
-     * Compute accumulated Y values across a stack group.
-     * Returns the cumulative Y array (length = n), or null if all stores are empty.
+     * Validate that all series within each stack group share the same axis.
+     * Runs once in the constructor — axis assignment is immutable after that.
+     * Data-length alignment is validated separately at draw time in
+     * {@link accumulateStackGroup}, since counts change as data arrives.
+     * Warns in development — mixed-axis stacking produces incorrect output.
+     */
+    private validateStackGroups;
+    /**
+     * Compute accumulated Y values across a stack group, separating positive
+     * and negative contributions.
+     *
+     * Positive values accumulate upward from 0 (`posCum`); negative values
+     * accumulate downward from 0 (`negCum`). This prevents positive and negative
+     * series from cancelling each other in the same accumulation track.
+     *
+     * Returns `{ posCum, negCum }` where each is `null` when no value of that
+     * sign exists, or the cumulative `Float64Array` (length = n).
      */
     private accumulateStackGroup;
     /**

package/dist/data/series-store.d.ts

@@ -9,7 +9,7 @@
  *
  * The store is purely about data: it never touches the canvas or scheduling.
  */
-import type { SeriesView } from '../types.js';
+import type { SeriesView, DataOwnership } from '../types.js';
 /** Owns the series data and computes/caches its extents. */
 export declare class SeriesStore implements SeriesView {
     xArr: Float64Array<ArrayBufferLike>;
@@ -32,19 +32,36 @@ export declare class SeriesStore implements SeriesView {
     /**
      * Snapshot mode: replace the whole series. Extents computed once in O(n).
      * Disables any active ring mode.
+     *
+     * By default (`ownership: 'copy'`) the store copies the caller's arrays into
+     * fresh buffers — the caller may mutate the originals freely after the call.
+     * Pass `'borrowed'` to keep the caller's arrays by reference (must be treated
+     * as immutable for as long as the chart holds them).
+     *
      * @throws {Error} if x and y have different lengths
      * @throws {Error} if x is empty
+     * @throws {Error} if any x value is not finite, or x is not monotonically increasing
+     * @throws {Error} if any y value is not finite (NaN in Y is allowed — reserved for gaps v1.6.0)
      */
-    setData(x: Float64Array<ArrayBufferLike>, y: Float64Array<ArrayBufferLike>): void;
+    setData(x: Float64Array<ArrayBufferLike>, y: Float64Array<ArrayBufferLike>, ownership?: DataOwnership): void;
     /**
      * Ring mode: append one sample (x must be monotonically increasing).
      * @throws {Error} if ring mode is not active (maxPoints not set)
+     * @throws {Error} if x is not finite
+     * @throws {Error} if x is < last x (not monotonically increasing)
+     * @throws {Error} if y is not finite (NaN in Y is allowed — reserved for gaps v1.6.0)
      */
     append(x: number, y: number): void;
     /**
      * Ring mode: append a batch of parallel samples. O(k).
+     *
+     * The entire batch is validated before any sample is pushed, so a partial
+     * batch never corrupts the ring.
+     *
      * @throws {Error} if ring mode is not active
      * @throws {Error} if xs and ys have different lengths
+     * @throws {Error} if any x is not finite, or xs are not monotonically increasing
+     * @throws {Error} if any y is not finite (NaN in Y is allowed — reserved for gaps v1.6.0)
      */
     appendBatch(xs: ArrayLike<number>, ys: ArrayLike<number>): void;
     /** Resize the streaming window, keeping the most recent samples. */
@@ -55,6 +72,12 @@ export declare class SeriesStore implements SeriesView {
     get lastValue(): number;
     physOf(logical: number): number;
     bracketLogical(target: number): number;
+    /**
+     * Validate snapshot data before accepting it into the store.
+     * Checks length, non-empty, finite + monotonic X, and finite Y.
+     * @throws {Error} with position-aware message on any violation.
+     */
+    private validateSnapshot;
     private requireRing;
     /** Point the store's logical window at the ring's physical storage. */
     private bindRing;

package/dist/defaults.d.ts

@@ -6,8 +6,8 @@
  * is a sentinel meaning "snapshot mode" (no ring); the constructor activates
  * ring mode only when the user passes a positive value.
  *
- * `yMin: 0 / yMax: 0` are sentinels meaning "auto" — the grid domain
- * expands from data unless the user sets non-zero values.
+ * `yMin: undefined / yMax: undefined` — the grid domain expands from data
+ * automatically. Set a number to pin the bound; `0` is a legitimate bound.
  */
 import type { ResolvedOpts } from './types.js';
 export declare const CHART_DEFAULTS: ResolvedOpts;