@zakkster/lite-canvas-graph 1.0.0

package/CanvasGraph.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @zakkster/lite-canvas-graph
+ * Zero-GC canvas rendering for time-series telemetry.
+ */
+
+import { RingBuffer } from '@zakkster/lite-ring-buffer';
+
+/** Constructor options for {@link CanvasGraph}. */
+export interface CanvasGraphOptions {
+    /**
+     * Override `globalThis.devicePixelRatio`.
+     * Required in OffscreenCanvas / Worker contexts where DPR is undefined.
+     * @default globalThis.devicePixelRatio || 1
+     */
+    dpr?: number;
+    /**
+     * Background fill (rendered with `alpha: false`, so this is opaque).
+     * @default '#111'
+     */
+    background?: string;
+    /**
+     * Trace stroke style.
+     * @default '#00ffcc'
+     */
+    stroke?: string;
+    /**
+     * Trace stroke width in CSS pixels.
+     * @default 1
+     */
+    lineWidth?: number;
+}
+
+/** Per-call options for {@link CanvasGraph.render}. */
+export interface RenderOptions {
+    /**
+     * When `true` and `ringBuffer.count > width`, render a per-column
+     * min/max envelope (oscilloscope/audio-waveform style). When `false`,
+     * always render a polyline regardless of sample count.
+     * @default true
+     */
+    decimate?: boolean;
+    /**
+     * Lower bound of the value range. Anything below is clamped to this.
+     * @default 0
+     */
+    minValue?: number;
+}
+
+/**
+ * Optional post-render hook signature. Anything drawn here lands ON TOP of
+ * the trace — useful for axis labels, units, peak markers, etc.
+ */
+export type LabelBitmapHook = (
+    ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+    maxValue: number,
+    width: number,
+    height: number,
+) => void;
+
+/**
+ * Zero-GC canvas renderer for time-series ring buffers.
+ *
+ * One scratch allocation per resize, nothing per-frame. Reads samples
+ * directly from a {@link RingBuffer} via `copyTo` — no array conversion,
+ * no `Array.from`, no `[].slice()`.
+ *
+ * Time flows LEFT → RIGHT: oldest sample on the left edge, newest on the right.
+ *
+ * @example
+ * ```ts
+ * import { RingBuffer }  from '@zakkster/lite-ring-buffer';
+ * import { CanvasGraph } from '@zakkster/lite-canvas-graph';
+ *
+ * const ring  = new RingBuffer(1024);
+ * const graph = new CanvasGraph(canvas, 400, 120, { stroke: '#0ff' });
+ *
+ * function frame(t: number) {
+ *   ring.push(Math.sin(t / 200));
+ *   graph.render(ring, 1, { minValue: -1 });
+ *   requestAnimationFrame(frame);
+ * }
+ * requestAnimationFrame(frame);
+ * ```
+ */
+export class CanvasGraph {
+    /** The bound canvas (HTMLCanvasElement in the main thread, OffscreenCanvas in workers). */
+    canvas: HTMLCanvasElement | OffscreenCanvas | null;
+    /** Live 2D context. Becomes `null` after {@link destroy}. */
+    ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null;
+    /** Logical (CSS) width in pixels. */
+    width: number;
+    /** Logical (CSS) height in pixels. */
+    height: number;
+    /** Background fill colour. Mutate freely between frames. */
+    background: string;
+    /** Trace stroke style. Mutate freely between frames. */
+    stroke: string;
+    /** Trace stroke width in CSS pixels. Mutate freely between frames. */
+    lineWidth: number;
+    /**
+     * Optional post-render hook. Draws ON TOP of the trace.
+     * Set to `null` (default) to skip. Mutate freely between frames.
+     */
+    labelBitmapHook: LabelBitmapHook | null;
+
+    /**
+     * @param canvas  Render target.
+     * @param width   Logical (CSS) width in pixels, >= 1.
+     * @param height  Logical (CSS) height in pixels, >= 1.
+     * @param options See {@link CanvasGraphOptions}.
+     * @throws {TypeError}  if `canvas` is missing.
+     * @throws {RangeError} if `width` or `height` is < 1 or non-finite.
+     */
+    constructor(
+        canvas: HTMLCanvasElement | OffscreenCanvas,
+        width: number,
+        height: number,
+        options?: CanvasGraphOptions,
+    );
+
+    /**
+     * Resize logical drawing area. Forces backing-store reconfig and pixel
+     * scratchpad reallocation on the next {@link render} call.
+     * No-op if dimensions are unchanged.
+     */
+    resize(width: number, height: number): void;
+
+    /**
+     * Draw the current contents of `ringBuffer` to the canvas.
+     * Allocation-free in the steady state.
+     */
+    render(ringBuffer: RingBuffer, maxValue: number, options?: RenderOptions): void;
+
+    /** Release internal scratchpads and the canvas reference. Idempotent. */
+    destroy(): void;
+}

package/CanvasGraph.js

@@ -0,0 +1,273 @@
+/**
+ * @zakkster/lite-canvas-graph
+ *
+ * Zero-GC canvas rendering for time-series telemetry.
+ *
+ * Time flows LEFT → RIGHT: oldest sample on the left edge, newest on the right.
+ * One scratchpad allocation per resize (or capacity change), nothing in the
+ * hot path. Renders directly from a `RingBuffer` via `copyTo` — no array
+ * conversion, no per-frame `[].slice()`, no `Array.from`.
+ *
+ * Decimation strategy (when sample count exceeds pixel width):
+ *   Each pixel column collects min/max of all samples that map to it, and the
+ *   renderer draws a single vertical line per column from min to max. No
+ *   diagonals between columns — the output reads as a clean envelope/barcode,
+ *   which is the standard convention for oscilloscopes and audio waveform
+ *   views. Empty columns leave a gap rather than fake-filling with neighbours.
+ *
+ * Worker-friendly:
+ *   `window` is not referenced. Pass `options.dpr` in OffscreenCanvas/Worker
+ *   contexts where `globalThis.devicePixelRatio` is undefined.
+ */
+export class CanvasGraph {
+    /**
+     * @param {HTMLCanvasElement|OffscreenCanvas} canvas
+     * @param {number} width   logical (CSS) width in pixels, >= 1
+     * @param {number} height  logical (CSS) height in pixels, >= 1
+     * @param {object} [options]
+     * @param {number} [options.dpr]              override devicePixelRatio (required in Workers)
+     * @param {string} [options.background='#111']
+     * @param {string} [options.stroke='#00ffcc']
+     * @param {number} [options.lineWidth=1]
+     */
+    constructor(canvas, width, height, options = {}) {
+        if (!canvas) throw new TypeError('LiteCanvasGraph: canvas is required');
+        if (!Number.isFinite(width) || width < 1) {
+            throw new RangeError(`LiteCanvasGraph: width must be >= 1 (got ${width})`);
+        }
+        if (!Number.isFinite(height) || height < 1) {
+            throw new RangeError(`LiteCanvasGraph: height must be >= 1 (got ${height})`);
+        }
+
+        this.canvas = canvas;
+        this.ctx = canvas.getContext('2d', {alpha: false});
+        if (!this.ctx) throw new Error('LiteCanvasGraph: failed to get 2d context');
+
+        this.width = Math.floor(width);
+        this.height = Math.floor(height);
+
+        this._dprOverride = options.dpr;
+        this._dpr = 0; // sentinel: forces backing-store reconfig on first render
+        this.background = options.background ?? '#111';
+        this.stroke = options.stroke ?? '#00ffcc';
+        this.lineWidth = options.lineWidth ?? 1;
+
+        /** @type {Float32Array|null} sample copy scratchpad */
+        this._scratch = null;
+        /** @type {Float32Array|null} per-column [min, max] pairs (length = width * 2) */
+        this._pixelScratch = null;
+
+        /**
+         * Optional hook called at the end of each `render()`. Useful for
+         * overlaying axis labels, units, or peak markers without forcing them
+         * into the core renderer. Called with the live 2D context — anything
+         * you draw will appear ON TOP of the trace.
+         *
+         * @type {((ctx: CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D, maxValue: number, width: number, height: number) => void) | null}
+         */
+        this.labelBitmapHook = null;
+    }
+
+    /**
+     * Resize logical drawing area. Forces backing-store reconfig and pixel
+     * scratchpad reallocation on the next `render()` call. Cheap to call when
+     * dimensions are unchanged — DPR sentinel only resets if values shifted.
+     *
+     * @param {number} width  >= 1
+     * @param {number} height >= 1
+     */
+    resize(width, height) {
+        if (!Number.isFinite(width) || width < 1) {
+            throw new RangeError(`LiteCanvasGraph.resize: width must be >= 1 (got ${width})`);
+        }
+        if (!Number.isFinite(height) || height < 1) {
+            throw new RangeError(`LiteCanvasGraph.resize: height must be >= 1 (got ${height})`);
+        }
+        const w = Math.floor(width);
+        const h = Math.floor(height);
+        if (w === this.width && h === this.height) return;
+
+        this.width = w;
+        this.height = h;
+        this._dpr = 0;            // force backing-store reconfig
+        this._pixelScratch = null; // force decimation scratch reallocation
+    }
+
+    _resolveDpr() {
+        if (this._dprOverride !== undefined) return this._dprOverride;
+        if (typeof globalThis !== 'undefined' && globalThis.devicePixelRatio) {
+            return globalThis.devicePixelRatio;
+        }
+        return 1;
+    }
+
+    /**
+     * Draw the current contents of `ringBuffer` to the canvas.
+     *
+     * Hot path is allocation-free after the first call: the sample scratch
+     * grows once to `ringBuffer.capacity`, the pixel scratch grows once to
+     * `width * 2`, and both are reused forever.
+     *
+     * @param {import('@zakkster/lite-ring-buffer').RingBuffer} ringBuffer
+     * @param {number} maxValue   upper bound of the value range
+     * @param {object} [options]
+     * @param {boolean} [options.decimate=true]   aggregate to per-column min/max when n > width
+     * @param {number}  [options.minValue=0]      lower bound of the value range
+     */
+    render(ringBuffer, maxValue, options) {
+        // Property access (no destructuring default) keeps this allocation-free
+        // when `options` is omitted.
+        const decimate = options ? options.decimate !== false : true;
+        const minValue = options && options.minValue !== undefined ? options.minValue : 0;
+
+        // Reconfigure backing store on DPR change (or first render).
+        const dpr = this._resolveDpr();
+        if (this._dpr !== dpr) {
+            this._dpr = dpr;
+            this.canvas.width = Math.floor(this.width * dpr);
+            this.canvas.height = Math.floor(this.height * dpr);
+            if (this.canvas.style) {
+                this.canvas.style.width = `${this.width}px`;
+                this.canvas.style.height = `${this.height}px`;
+            }
+            this.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        }
+
+        // Clear with solid background (alpha: false context, so this is opaque).
+        this.ctx.fillStyle = this.background;
+        this.ctx.fillRect(0, 0, this.width, this.height);
+
+        const count = ringBuffer.count;
+        if (count === 0) {
+            if (this.labelBitmapHook) this.labelBitmapHook(this.ctx, maxValue, this.width, this.height);
+            return;
+        }
+
+        const range = maxValue - minValue;
+        if (!(range > 0)) {
+            // Degenerate range: cannot map values to pixels. Bail honestly.
+            if (this.labelBitmapHook) this.labelBitmapHook(this.ctx, maxValue, this.width, this.height);
+            return;
+        }
+
+        // Lazy / grow scratch. Grow-only — never shrinks across frames.
+        if (!this._scratch || this._scratch.length < ringBuffer.capacity) {
+            this._scratch = new Float32Array(ringBuffer.capacity);
+        }
+        const n = ringBuffer.copyTo(this._scratch, 0); // oldest-first
+
+        this.ctx.strokeStyle = this.stroke;
+        this.ctx.lineWidth = this.lineWidth;
+        this.ctx.lineCap = 'square'; // ensures single-sample columns render visibly
+
+        const usableX = this.width - 1; // last drawable pixel column
+        const yScale = this.height / range;
+
+        if (decimate && n > this.width) {
+            this._renderDecimated(this._scratch, n, minValue, maxValue, yScale);
+        } else {
+            this._renderDirect(this._scratch, n, minValue, maxValue, yScale, usableX);
+        }
+
+        if (this.labelBitmapHook) {
+            this.labelBitmapHook(this.ctx, maxValue, this.width, this.height);
+        }
+    }
+
+    _renderDirect(samples, n, minValue, maxValue, yScale, usableX) {
+        const ctx = this.ctx;
+        const h = this.height;
+        const stepX = n > 1 ? usableX / (n - 1) : 0;
+
+        ctx.beginPath();
+        let started = false;
+        let lastX = 0, lastY = 0;
+        for (let i = 0; i < n; i++) {
+            const raw = samples[i];
+            if (raw !== raw) {
+                started = false;
+                continue;
+            } // NaN → break the line
+
+            const v = raw < minValue ? minValue : (raw > maxValue ? maxValue : raw);
+            const x = i * stepX;                       // index 0 → x=0 (oldest, left)
+            const y = h - (v - minValue) * yScale;     // (newest is at x=usableX, right)
+
+            if (!started) {
+                ctx.moveTo(x, y);
+                started = true;
+                lastX = x;
+                lastY = y;
+            } else {
+                ctx.lineTo(x, y);
+                lastX = x;
+                lastY = y;
+            }
+        }
+
+        // Single-sample edge case: a lone moveTo() draws nothing. Emit a
+        // tiny lineTo so lineCap='square' produces a visible dot at lineWidth.
+        if (started && n === 1) {
+            ctx.lineTo(lastX, lastY);
+        }
+        ctx.stroke();
+    }
+
+    _renderDecimated(samples, n, minValue, maxValue, yScale) {
+        const ctx = this.ctx;
+        const h = this.height;
+        const w = this.width;
+
+        if (!this._pixelScratch || this._pixelScratch.length !== w * 2) {
+            this._pixelScratch = new Float32Array(w * 2);
+        }
+        const px = this._pixelScratch;
+        for (let i = 0; i < w; i++) {
+            px[i * 2] = Infinity;
+            px[i * 2 + 1] = -Infinity;
+        }
+
+        // Map sample index i ∈ [0, n-1] → bucket bi ∈ [0, w-1].
+        // Endpoints land exactly on the first/last column.
+        const denom = n - 1;
+        for (let i = 0; i < n; i++) {
+            const sample = samples[i];
+            if (sample !== sample) continue; // NaN
+            const bi = denom > 0 ? Math.floor((i * (w - 1)) / denom) : 0;
+            const mi = bi * 2;
+            if (sample < px[mi]) px[mi] = sample;
+            if (sample > px[mi + 1]) px[mi + 1] = sample;
+        }
+
+        // One vertical span per column. Each column is a discrete subpath
+        // (moveTo + lineTo); empty columns leave a gap rather than fake-filling.
+        ctx.beginPath();
+        for (let bi = 0; bi < w; bi++) {
+            const mn = px[bi * 2];
+            const mx = px[bi * 2 + 1];
+            if (mn === Infinity) continue; // no samples in this column
+
+            const lo = mn < minValue ? minValue : (mn > maxValue ? maxValue : mn);
+            const hi = mx < minValue ? minValue : (mx > maxValue ? maxValue : mx);
+
+            const yLo = h - (lo - minValue) * yScale;
+            const yHi = h - (hi - minValue) * yScale;
+            const xPx = bi + 0.5; // crisp 1px-aligned vertical
+
+            ctx.moveTo(xPx, yHi);
+            // For a single-sample bucket (yLo === yHi) the line is degenerate;
+            // lineCap='square' guarantees a visible mark at lineWidth pixels.
+            ctx.lineTo(xPx, yLo);
+        }
+        ctx.stroke();
+    }
+
+    /** Release internal scratchpads and the canvas reference. Idempotent. */
+    destroy() {
+        this.ctx = null;
+        this.canvas = null;
+        this._scratch = null;
+        this._pixelScratch = null;
+        this.labelBitmapHook = null;
+    }
+}

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# @zakkster/lite-canvas-graph
+
+[![npm version](https://img.shields.io/npm/v/@zakkster/lite-canvas-graph.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-canvas-graph)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-canvas-graph?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-canvas-graph)
+[![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-canvas-graph?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-canvas-graph)
+[![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-canvas-graph?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-canvas-graph)
+![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+
+**Zero-GC canvas renderer for time-series telemetry.**
+
+One scratchpad allocation per resize. Nothing in the hot path. Renders straight from a `RingBuffer` via `copyTo` — no array conversion, no `Array.from`, no `[].slice()`. Decimates to a per-column min/max envelope when sample count exceeds pixel width, the way oscilloscopes and audio waveform views have always done it.
+
+```js
+import { RingBuffer } from '@zakkster/lite-ring-buffer';
+import { CanvasGraph } from '@zakkster/lite-canvas-graph';
+
+const canvas = document.getElementById('telemetry-canvas');
+const ring = new RingBuffer(1024);
+const graph = new CanvasGraph(canvas, 400, 120, { stroke: '#0ff' });
+
+let lastTime = performance.now();
+
+function renderLoop(currentTime) {
+    const delta = currentTime - lastTime;
+    lastTime = currentTime;
+
+    ring.push(delta);
+    graph.render(ring, 16, { minValue: 0 }); // 0..16ms frame budget baseline
+
+    requestAnimationFrame(renderLoop);
+}
+
+requestAnimationFrame(renderLoop);
+```
+
+---
+
+## Contents
+
+- [Why](#why) · [Install](#install) · [Quick start](#quick-start)
+- [How it works](#how-it-works)
+- [API reference](#api-reference)
+- [Edge cases & guarantees](#edge-cases--guarantees)
+- [FAQ](#faq)
+- [License](#license)
+
+---
+
+## Why
+
+A "live graph" component looks innocent until you profile it.
+
+The naive approach — copy samples into an array, map over them, call `lineTo` — allocates a fresh array and a fresh path object every single frame. At 60Hz with a 1024-sample window that's **60,000 allocations per second** before you've drawn a pixel. The GC will eventually pause your render loop to clean it up, and your "smooth" graph stutters at exactly the wrong moment.
+
+```mermaid
+flowchart LR
+    subgraph Naive["Naive approach (per frame)"]
+        A1[ring → Array.from] --> A2[points = data.map]
+        A2 --> A3[ctx.beginPath]
+        A3 --> A4[for .. lineTo]
+        A4 --> A5[stroke]
+        A5 --> GC[GC pause]
+    end
+    subgraph Lite["lite-canvas-graph (per frame)"]
+        B1[ring.copyTo(scratch)] --> B2[ctx.beginPath]
+        B2 --> B3[lineTo loop]
+        B3 --> B4[stroke]
+    end
+```
+
+`lite-canvas-graph` allocates once — a `Float32Array` sized to the ring's capacity, plus a per-column min/max scratchpad sized to the canvas width. After that the render path is a tight numeric loop and direct canvas calls. No object graphs, no arrays, no GC churn.
+
+For windows larger than the canvas width (the common case — you have 4096 telemetry samples but only 400 horizontal pixels), the renderer **decimates**: each column collects min/max of all samples that map to it and draws a single vertical line from min to max. This is the correct convention for oscilloscope and audio-waveform displays. It preserves spike visibility — a single outlier in a column still pushes the envelope to the edge — where naive subsampling would silently drop it.
+
+---
+
+## Install
+
+```bash
+npm i @zakkster/lite-canvas-graph @zakkster/lite-ring-buffer
+```
+
+ESM only. Zero runtime dependencies (the ring buffer is a peer dep — bring your own).
+
+---
+
+## Quick start
+
+```js
+import { RingBuffer }  from '@zakkster/lite-ring-buffer';
+import { CanvasGraph } from '@zakkster/lite-canvas-graph';
+
+const canvas = document.getElementById('chart');
+const ring   = new RingBuffer(1024);                   // power-of-2-rounded
+const graph  = new CanvasGraph(canvas, 400, 120, {
+  background: '#111',
+  stroke:     '#00ffcc',
+  lineWidth:  1,
+});
+
+// Push samples from anywhere — performance observer, websocket, RAF, ...
+performance.mark && setInterval(() => {
+  ring.push(performance.now() % 1000);                 // toy data
+}, 16);
+
+// Draw at your preferred cadence.
+function frame() {
+  graph.render(ring, 1000, { minValue: 0 });
+  requestAnimationFrame(frame);
+}
+requestAnimationFrame(frame);
+```
+
+### Worker / OffscreenCanvas
+
+`window` is never referenced. In a worker, pass `dpr` explicitly:
+
+```js
+const off   = canvas.transferControlToOffscreen();
+// inside the worker:
+const graph = new CanvasGraph(off, 400, 120, { dpr: 2 });
+```
+
+### Overlaying labels
+
+Use `labelBitmapHook` to draw axis labels, units, or peak markers on top of the trace without forcing them into the core renderer:
+
+```js
+graph.labelBitmapHook = (ctx, maxValue, w, h) => {
+  ctx.fillStyle = '#888';
+  ctx.font = '10px monospace';
+  ctx.fillText(`${maxValue.toFixed(1)} ms`, 4, 12);
+};
+```
+
+---
+
+## How it works
+
+### Layout
+
+```mermaid
+flowchart TB
+    subgraph Canvas["400 × 120 logical px (e.g. 800 × 240 backing at DPR=2)"]
+        oldest[oldest sample<br/>x = 0]
+        middle[...]
+        newest[newest sample<br/>x = width − 1]
+        oldest -.-> middle -.-> newest
+    end
+```
+
+Time flows left → right. Index `0` of the ring (oldest) lands at `x = 0`, index `count - 1` (newest) at `x = width - 1`. Standard direction for telemetry; the most-recent reading is always at the right edge where your eye expects it.
+
+### Direct vs decimated
+
+The renderer picks one of two modes per frame:
+
+```mermaid
+flowchart LR
+    Start[render&#40;&#41;] --> Q{n &gt; width?}
+    Q -- yes --> Dec[Decimated<br/>per-column min/max envelope]
+    Q -- no  --> Dir[Direct<br/>polyline moveTo + lineTo]
+```
+
+**Direct** mode is the obvious one: one `moveTo` for the first sample, `lineTo` for every subsequent sample. Used when you have at most one sample per pixel column. NaN samples break the path (no fake connecting lines).
+
+**Decimated** mode is what makes the renderer correct at scale. For each pixel column it walks every sample whose index maps to that column, tracks `min` and `max`, and draws a single vertical line from `min` to `max`. Empty columns leave a gap rather than fake-filling with neighbours — if your data has a hole, the graph shows a hole.
+
+### Allocations
+
+| Where        | What                                  | When                       |
+|--------------|---------------------------------------|----------------------------|
+| Constructor  | nothing                               | —                          |
+| First render | `Float32Array(ring.capacity)`         | once, grown on capacity ↑  |
+| First render | `Float32Array(width * 2)` (decimated) | once, grown on width ↑     |
+| Resize       | re-grow pixel scratch on next render  | per resize                 |
+| Per frame    | **0**                                 | always                     |
+
+The `options` object literal in `render(ring, max, { decimate: false })` is the only thing the V8 inliner has to deal with — the renderer itself reads `options.decimate` directly without destructuring, so passing or omitting it changes nothing in the steady state.
+
+---
+
+## API reference
+
+### `new CanvasGraph(canvas, width, height, options?)`
+
+| Param  | Type                                       | Notes                                  |
+|--------|--------------------------------------------|----------------------------------------|
+| canvas | `HTMLCanvasElement \| OffscreenCanvas`     | required                               |
+| width  | `number`                                   | logical CSS pixels, ≥ 1                |
+| height | `number`                                   | logical CSS pixels, ≥ 1                |
+| options.dpr        | `number?`                        | overrides `globalThis.devicePixelRatio` |
+| options.background | `string?`                        | default `'#111'`                       |
+| options.stroke     | `string?`                        | default `'#00ffcc'`                    |
+| options.lineWidth  | `number?`                        | default `1`                            |
+
+Throws `TypeError` on missing canvas, `RangeError` on bad dimensions.
+
+### `.render(ringBuffer, maxValue, options?)`
+
+The hot path. Allocation-free in the steady state.
+
+| Param               | Type           | Notes                                    |
+|---------------------|----------------|------------------------------------------|
+| ringBuffer          | `RingBuffer`   | from `@zakkster/lite-ring-buffer`        |
+| maxValue            | `number`       | upper bound of the value range           |
+| options.decimate    | `boolean?`     | default `true` (envelope when n > width) |
+| options.minValue    | `number?`      | default `0`                              |
+
+Values outside `[minValue, maxValue]` are clamped to the visible range. NaN samples break the polyline (direct mode) and are skipped (decimated mode). A degenerate range (`maxValue <= minValue`) clears the canvas and bails — labels still run.
+
+### `.resize(width, height)`
+
+Updates the logical drawing area. Forces backing-store reconfig and pixel-scratch reallocation on the next `render()`. No-op when dimensions are unchanged.
+
+### `.labelBitmapHook`
+
+`(ctx, maxValue, width, height) => void` — runs at the end of each `render()`, drawing on top of the trace. Set to `null` (default) to skip.
+
+### `.destroy()`
+
+Releases scratchpads and references. Idempotent. Calling any other method afterwards is undefined behaviour.
+
+---
+
+## Edge cases & guarantees
+
+- **Single sample (`n === 1`).** Direct mode emits a degenerate `lineTo` so `lineCap='square'` produces a visible dot at `lineWidth` pixels. Without this, a lone `moveTo` would render nothing.
+- **NaN samples.** Direct: break the path (no fake interpolation). Decimated: skipped during column accumulation; columns with only NaN samples remain empty (gap).
+- **Out-of-range values.** Clamped to `[minValue, maxValue]`. The trace pins to the top or bottom edge instead of overshooting; this is what you want for "value capped" indicators.
+- **`maxValue <= minValue`.** Renderer clears the canvas, runs `labelBitmapHook` if set, returns. No throw — invalid axes happen during init/resize race conditions and shouldn't crash your loop.
+- **DPR changes mid-session.** Detected at the start of each `render()`. Triggers a one-time backing-store reconfig + transform reset. Cheap.
+- **Capacity growth.** If you push to a ring buffer whose capacity grew (you replaced it with a bigger one), the sample scratch is re-grown on next render. `_pixelScratch` only re-grows on resize.
+- **`alpha: false` context.** The renderer requests an opaque context, which is faster on most GPUs. `background` colour is therefore guaranteed visible — there is no transparency to bleed through to the page beneath.
+
+---
+
+## FAQ
+
+**Why not just use Chart.js / uPlot / d3?**
+
+Those are general-purpose charting libraries with axes, tooltips, animations, legends, themes — and per-frame allocation. This package is one thing: a zero-GC trace renderer for live telemetry. It composes nicely with axes drawn in `labelBitmapHook` if you need them, but it doesn't ship them.
+
+**Can I render multiple traces?**
+
+Construct multiple `CanvasGraph` instances over different canvases, or layer them — the cheapest way is one canvas per trace stacked in CSS, since each one keeps its own scratchpads and DPR state.
+
+**Does it support log scale?**
+
+Not directly. Pre-transform your samples before pushing them: `ring.push(Math.log10(rawValue))`. Set `minValue` / `maxValue` in log space.
+
+**Can I scroll the view backwards in time?**
+
+This renderer always shows "the current contents of the ring buffer." If you want a scrubbing/scrollback view, you want a different component — one that buffers historical data outside the live ring.
+
+**Why `Float32` and not `Float64`?**
+
+Halves memory bandwidth, doubles the cache density of the scratchpad, and 7 significant decimal digits is more than your screen can show. If you need 64-bit precision for sample storage, `lite-canvas-graph` is the wrong layer.
+
+---
+
+## License
+
+MIT © Zahary Shinikchiev

package/llms.txt

@@ -0,0 +1,51 @@
+# @zakkster/lite-canvas-graph
+
+> Zero-GC canvas renderer for time-series telemetry. Decimates to per-column min/max envelope when sample count exceeds pixel width.
+
+## Summary
+
+`@zakkster/lite-canvas-graph` draws a live trace from a `RingBuffer` to a `<canvas>` (or `OffscreenCanvas` in a Worker) without per-frame allocation. One `Float32Array` scratch grows once to the ring's capacity; one `Float32Array(width * 2)` holds per-column min/max for decimation. After warmup, every render is a fixed-size numeric loop and a sequence of direct canvas calls.
+
+Time flows left → right: the oldest sample renders at `x = 0`, the newest at `x = width - 1`. Out-of-range samples are clamped. NaN samples break the polyline in direct mode and are skipped in decimated mode (their columns stay empty).
+
+## Core API
+
+```ts
+new CanvasGraph(canvas, width, height, options?)
+  options: { dpr?, background?='#111', stroke?='#00ffcc', lineWidth?=1 }
+
+graph.render(ringBuffer, maxValue, options?)
+  options: { decimate?=true, minValue?=0 }
+
+graph.resize(width, height)
+graph.labelBitmapHook = (ctx, maxValue, width, height) => void
+graph.destroy()
+```
+
+`render` is the only hot-path method. Allocation-free in the steady state.
+
+## Concepts
+
+- **Direct vs decimated.** When `ringBuffer.count <= width`, renders a polyline (`moveTo` + `lineTo` per sample). When `ringBuffer.count > width` and `decimate !== false`, renders a per-column min/max envelope — one vertical line per pixel column. Convention from oscilloscope and audio-waveform displays; preserves spike visibility that naive subsampling would lose.
+- **Scratchpads grow once.** Sample scratch sized to `ringBuffer.capacity`, pixel scratch to `width * 2`. Both re-grow only on capacity / width increase. Resize triggers a one-time backing-store reconfig on next render.
+- **DPR detection.** Reads `globalThis.devicePixelRatio` (or `options.dpr` override — required in Workers). Detected per render; reconfigures backing store + transform when DPR shifts.
+- **`alpha: false` context.** Opaque, faster on most GPUs. `background` is always visible.
+
+## Constraints
+
+- Single trace per instance. Use multiple instances for multi-trace charts (one canvas per trace stacked in CSS is the cheapest pattern).
+- Linear scale only. Pre-transform samples (e.g. `Math.log10`) for log axes.
+- Float32 internal storage. 7 significant digits of precision.
+- Renders the *current* ring contents only — no scrollback.
+- Methods are NOT safe to call after `destroy()`.
+
+## Performance
+
+- Per-frame allocations: **0** (after warmup).
+- Per-frame canvas calls in direct mode: 1 `fillRect` + 1 `beginPath` + n `moveTo/lineTo` + 1 `stroke`.
+- Per-frame canvas calls in decimated mode: 1 `fillRect` + 1 `beginPath` + 2 × occupied-column-count + 1 `stroke`.
+- DPR handling reconfigures the backing store at most once per actual DPR change.
+
+## License
+
+MIT © Zahary Shinikchiev

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@zakkster/lite-canvas-graph",
+  "version": "1.0.0",
+  "description": "Zero-GC canvas renderer for time-series telemetry. Decimates to per-column min/max envelope when sample count exceeds pixel width.",
+  "type": "module",
+  "main": "CanvasGraph.js",
+  "module": "CanvasGraph.js",
+  "types": "CanvasGraph.d.ts",
+  "exports": {
+    ".": {
+      "types": "CanvasGraph.d.ts",
+      "import": "CanvasGraph.js",
+      "default": "CanvasGraph.js"
+    }
+  },
+  "files": [
+    "CanvasGraph.js",
+    "CanvasGraph.d.ts",
+    "README.md",
+    "llms.txt",
+    "LICENSE.txt"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "keywords": [
+    "canvas",
+    "graph",
+    "chart",
+    "telemetry",
+    "time-series",
+    "oscilloscope",
+    "waveform",
+    "zero-gc",
+    "lite",
+    "no-allocation",
+    "performance",
+    "offscreen-canvas"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@zakkster/lite-ring-buffer": "^1.0.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.0.0",
+    "@zakkster/lite-ring-buffer": "^1.0.0"
+  },
+  "license": "MIT",
+  "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
+  "homepage": "https://github.com/PeshoVurtoleta/lite-canvas-graph#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeshoVurtoleta/lite-canvas-graph.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PeshoVurtoleta/lite-canvas-graph/issues",
+    "email": "shinikchiev@yahoo.com"
+  },
+  "sideEffects": false
+}