goro-charts 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -5,69 +5,118 @@ 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 por valor X, não por pixel.**
-  Gráficos com tamanhos, margens e domínios diferentes agora sincronizam
-  corretamente: o valor de dado é convertido de pixel na origem e de volta
-  a pixel no target via pxToX/xToPx. Valor fora do domínio oculta o
-  crosshair no target. _(minor, behavior fix)_
-- **Stacking separa positivos e negativos.**
-  Positivos acumulam num track ascendente, negativos num track descendente,
-  sem se cancelarem. Em desenvolvimento, séries do mesmo `stack` com eixos
-  ou comprimentos divergentes geram aviso descritivo. _(minor, behavior fix)_
-- **`renderedPointCount` renomeado para `windowPointCount`.**
-  A métrica antiga mentia: retornava o total de pontos na janela, não os
-  efetivamente desenhados (o renderer decima para ~2·plotW colunas no
-  regime denso). Agora há duas métricas honestas: `windowPointCount`
-  (volume de dados) e `drawnPointCount` (estimativa pós-decimação).
-  Quem usava `renderedPointCount` deve migrar para `windowPointCount`.
+- **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)` — remove sincronização bidirecional de crosshair.
-- `drawnPointCount` — estimativa de segmentos realmente desenhados após
-  decimação (útil para verificar que a decimação está ativa).
-- Stacking: validação de alinhamento entre séries do mesmo grupo (eixo e
-  comprimento) em desenvolvimento.
+- `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` (privado) agora recebe valor X em vez de pixel — alinhado
-  com a sincronização por valor. `notifySyncCrosshair` envia valor em vez
-  de coordenada de tela.
-- `destroy` agora remove o chart de todos os peers sincronizados antes de
-  limpar as stores.
-- `accumulateStackGroup` retorna `{ posCum, negCum }` separados em vez de
-  uma única acumulação líquida.
+- `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` agora é um bound legítimo.**
-  Antes `yMin: 0` e `yMax: 0` eram tratados como "auto" (descartados). Agora só
-  caem em domínio automático quando `undefined`. `yMin: 0` ancorado é o caso mais
-  comum e finalmente funciona. _(minor, behavior fix)_
-- **Teclado: navegação por ponto de dado, não por pixel.**
-  As setas movem o crosshair de ponto em ponto (lógico) da primeira série
-  não-vazia. `Shift+seta` avança 10 pontos. Antes navegava por pixel, sem
-  ancorar em dados reais. _(minor, behavior fix)_
-- **`prefers-reduced-motion` não para mais o streaming.**
-  Antes desligava `autoDraw`, interrompendo o repaint coalescido de dados ao
-  vivo. Agora só sinaliza uma flag para suprimir animações visuais (quando
-  houverem) sem afetar a atualização contínua do gráfico. _(minor, behavior fix)_
+- **`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` agora são `number | undefined`.
-  O sentinela "auto" mudou de `0` para `undefined`. Código que dependia do
-  comportamento antigo (ex.: checagens `yMin !== 0`) deve usar `yMin !== undefined`.
-- `prefers-reduced-motion` adiciona listener `change` em runtime para reavaliar
-  a preferência sem recriar o gráfico. O listener é removido em `destroy()`.
+- `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]
 

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: [/* ... */] });
 ```
 
 ---

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 {
@@ -122,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;
     /**

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;