@grundyjs/algiviz 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Changelog
 
-## 0.1.0 — unreleased
+## 0.2.0 — 2026-10-09
+
+- Move the held key horizontally along the baseline without lifting it above the array;
+  remove the redundant key label while retaining its color highlight.
+
+- Expand the demo with history/generator playback, array input, generation and speed
+  controls; hide individual bar labels on dense charts.
+
+- Add `createSortPlayer` for forward-only playback with bounded snapshot storage,
+  interpolated canvas-compatible frames, final hold and iterator cleanup.
+
+- Add `iterateInsertionSortSteps` for lazy immutable snapshots without retaining history.
+- Keep `insertionSortSteps` compatible by collecting the shared generator implementation.
+
+## 0.1.0
 
 - Stable, immutable insertion sort traces with item identities and operation counters.
 - A seekable timeline with interpolated frames and final hold.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Grundy
-
-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.
+MIT License
+
+Copyright (c) 2026 Grundy
+
+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

@@ -8,7 +8,7 @@ A TypeScript library for educational algorithm visualization: stable insertion s
 npm install @grundyjs/algiviz
 ```
 
-Try the [interactive insertion sort demo](https://grundyjs.ru/algorithms/insertion-sort/). Import the core from `@grundyjs/algiviz/core` and the browser renderer from `@grundyjs/algiviz/canvas`; there is no root entry point or CommonJS build. Version 0.1 is an initial API and may change in later minor releases.
+Try the [interactive insertion sort demo](https://grundyjs.ru/algorithms/insertion-sort/). Import the core from `@grundyjs/algiviz/core` and the browser renderer from `@grundyjs/algiviz/canvas`; there is no root entry point or CommonJS build. Version 0.x is an initial API and may change in later minor releases.
 
 ## Development
 
@@ -42,6 +42,84 @@ The underlying sort uses O(n²) comparisons in the worst case and O(n) on alread
 
 Tests replay every event independently, check item conservation, stability, prefix ordering, counters, frozen snapshots and 1,093 exhaustive inputs with values -1, 0 and 1 of lengths 0–6.
 
+## Lazy steps
+
+Use `iterateInsertionSortSteps` to consume steps on demand without retaining the
+entire history. It yields the same immutable `SortStep` snapshots as
+`insertionSortSteps`, which collects this iterator into a frozen array.
+
+```js
+import { iterateInsertionSortSteps } from "@grundyjs/algiviz/core";
+
+const iterator = iterateInsertionSortSteps([5, 2, 4, 2, 1]);
+const start = iterator.next().value;
+const selected = iterator.next().value;
+iterator.return(); // Stop early when no more steps are needed.
+```
+
+Creating the generator does not read the input or run the algorithm. The first
+`next()` copies and validates the input; invalid values throw at that point.
+Changes to the input before the first `next()` are observed; later changes do not
+affect the iterator. Each subsequent `next()` runs only to the next step. An
+iterator is single-use; create a new one to restart. A `for...of` loop can also
+consume it, and `break` closes it early.
+
+When the consumer retains only a fixed number of snapshots, memory is O(n).
+Every snapshot still copies n slots, so consuming the complete worst-case trace
+still takes O(n³) time. Collecting the iterator into an array restores the full
+history memory cost. Iteration is synchronous; a long loop can block the UI.
+
+The existing `createSortTimeline` still requires an array of steps for seeking.
+It does not accept this iterator directly. Use `createSortPlayer` for forward-only
+playback; the generator itself provides no timing or backward seeking.
+
+## Sequential playback
+
+`createSortPlayer` consumes an iterable of steps and retains only the two adjacent
+snapshots needed for rendering. With the lazy generator, playback uses O(n)
+memory as long as the caller does not retain old frames.
+
+```js
+import { createSortPlayer, iterateInsertionSortSteps } from "@grundyjs/algiviz/core";
+import { createSortRenderer } from "@grundyjs/algiviz/canvas";
+
+const player = createSortPlayer(iterateInsertionSortSteps([5, 2, 4, 1]), {
+    stepDurationMs: 650, finalHoldMs: 2000
+});
+const renderer = createSortRenderer({ theme: "dark" });
+const ctx = canvas.getContext("2d");
+let paused = false;
+let speed = 1;
+let last;
+let requestId;
+function tick(now) {
+    const delta = last === undefined ? 0 : now - last;
+    last = now;
+    if (!paused) player.advance(delta * speed);
+    renderer.render(ctx, player.frame);
+    if (!player.finished) requestId = requestAnimationFrame(tick);
+}
+requestId = requestAnimationFrame(tick);
+// Set paused = true/false or speed = 2 from your controls.
+// On teardown: cancelAnimationFrame(requestId); player.dispose();
+```
+
+- Construction reads the first step immediately, including input validation by
+  the generator. The initial `frame` is fully rendered at progress 1.
+- `advance(deltaMs)` accepts finite, non-negative elapsed playback time and
+  returns a `SortFrame` compatible with the existing canvas renderer. Zero does
+  not consume steps. Pause by not advancing; multiply delta by a non-negative
+  speed factor to change speed.
+- `finished` becomes true after the final transition and `finalHoldMs`. Further
+  advances return the final frame. There is no known total duration or seeking.
+- The source must end with a `done` event. The player closes the iterator when
+  that transition completes; unexpected exhaustion or source errors throw and
+  close playback. `dispose()` closes early and is safe to repeat; afterward the
+  frame remains readable but `advance()` throws.
+- Restart by disposing the old player and creating a new player and generator.
+  Large deltas synchronously consume all intervening steps, so limit the elapsed
+  delta in the UI if resuming from a background tab should not cause a long catch-up.
+
 ## Timeline and canvas
 
 Import `createSortTimeline` from `@grundyjs/algiviz/core` and `createSortRenderer` from `@grundyjs/algiviz/canvas`.
@@ -57,7 +135,15 @@ const renderer = createSortRenderer({ theme: "dark" });
 renderer.render(canvas.getContext("2d"), timeline.sample(3250));
 ```
 
-Build, serve this project root using any static HTTP server, and open examples/index.html for play, pause, restart and seeking. The example changes bitmap size to fit its container; for video use a separate canvas with fixed export dimensions. Canvas rendering does not start any animation loop. There are no video recording dependencies.
+Build, serve this project root using any static HTTP server, and open examples/index.html for play, pause, restart and seeking. The example changes bitmap size to fit its container; for video use a separate canvas with fixed export dimensions. Canvas rendering does not start any animation loop. There are no video recording dependencies.
+
+The demo supports history (up to 64 items) and generator playback (up to 2,000).
+Enter values or generate random, sorted or reversed arrays. Both modes support
+pause, restart and speed changes; seeking is available only with full history.
+Mode changes restart the loaded array. These limits apply only to the demo.
+Dense charts hide bar labels. Hidden tabs pause playback, and delayed frames cap
+catch-up work to keep controls responsive.
+
 
 ## API at a glance
 
@@ -70,4 +156,31 @@ For playback, call `timeline.sample(elapsedMs)` in your own requestAnimationFram
 ## Release
 
 Run `npm test`, `npm pack --dry-run` and test the resulting tarball in a separate consumer project. Source and issues: [urffin/algiviz](https://github.com/urffin/algiviz). Publishing is a separate maintainer action.
-
+
+### Publishing from GitHub Releases
+
+The `.github/workflows/npm-publish.yml` workflow publishes to npm when a stable
+GitHub Release is published (`release: published`). Drafts, prereleases and tag
+pushes alone do not publish a package. The release tag must be `v` followed by
+the exact version in `package.json` and `package-lock.json` (for example `v0.2.0`).
+The workflow uses Node.js 24 and npm 11. The publish lifecycle runs the tests and
+build before publishing with provenance, using npm trusted publishing (OIDC).
+
+One-time setup in the npm package settings, under **Trusted Publisher**:
+
+- Provider: GitHub Actions.
+- Organization or user: `urffin`.
+- Repository: `algiviz`.
+- Workflow filename: `npm-publish.yml` (without the directory).
+- Environment: leave empty; this workflow does not use a GitHub environment.
+- Allow direct publishing with `npm publish` if the settings show this option.
+
+No `NPM_TOKEN` secret is required. Keep account 2FA enabled.
+See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+For each release, update the version and changelog, commit and push the changes
+(including the workflow), then publish a GitHub Release for the matching tag at
+that commit. Check the Actions run and the npm package version afterward. Do not
+reuse an already published npm version; if setup failed before publication,
+correct the settings and rerun the failed workflow.
+

package/dist/canvas/index.js

@@ -49,20 +49,19 @@ export function createSortRenderer(options) {
                 for (const [id, next] of after) {
                     const old = before.get(id) ?? next;
                     const x = margin + ((old.index + (next.index - old.index) * p) + 0.5) * cell;
-                    const lift = ((old.held ? 1 : 0) + ((next.held ? 1 : 0) - (old.held ? 1 : 0)) * p) * height * 0.13;
                     const size = Math.max(4, Math.abs(next.item.value) / maxMagnitude * available);
                     const active = event.type === "compare" ? id === event.leftId || id === event.rightId :
                         "itemId" in event && event.itemId === id;
                     ctx.fillStyle = next.held ? colors.held : active ? colors.active :
                         next.index < frame.current.sortedPrefixLength ? colors.sorted : colors.bar;
-                    ctx.fillRect(x - barWidth / 2, baseline - size - lift, barWidth, size);
+                    ctx.fillRect(x - barWidth / 2, baseline - size, barWidth, size);
+                    if (cell < 24)
+                        continue;
                     ctx.fillStyle = colors.text;
                     ctx.font = `${fontSize}px sans-serif`;
                     ctx.textAlign = "center";
-                    ctx.fillText(String(next.item.value), x, baseline - size - lift - fontSize, cell * 0.95);
+                    ctx.fillText(String(next.item.value), x, baseline - size - fontSize, cell * 0.95);
                     ctx.fillText(String(next.index), margin + (next.index + 0.5) * cell, baseline + height * 0.06);
-                    if (next.held)
-                        ctx.fillText("key", x, baseline - lift + fontSize, cell * 0.95);
                 }
                 ctx.textAlign = "left";
                 ctx.font = `${Math.max(11, Math.min(18, width * 0.03))}px sans-serif`;

package/dist/core/index.d.ts

@@ -1,4 +1,6 @@
-export { insertionSortSteps } from "./insertion-sort.js";
+export { insertionSortSteps, iterateInsertionSortSteps } from "./insertion-sort.js";
 export type { Item, SortEvent, SortSnapshot, SortStep } from "./types.js";
 export { createSortTimeline } from "./timeline.js";
 export type { SortFrame, SortTimeline } from "./timeline.js";
+export { createSortPlayer } from "./player.js";
+export type { SortPlayer } from "./player.js";

package/dist/core/index.js

@@ -1,2 +1,3 @@
-export { insertionSortSteps } from "./insertion-sort.js";
+export { insertionSortSteps, iterateInsertionSortSteps } from "./insertion-sort.js";
 export { createSortTimeline } from "./timeline.js";
+export { createSortPlayer } from "./player.js";

package/dist/core/insertion-sort.d.ts

@@ -1,3 +1,8 @@
 import type { SortStep } from "./types.js";
 /** Creates a stable ascending insertion-sort trace without modifying the input. */
 export declare function insertionSortSteps(values: readonly number[]): readonly SortStep[];
+/**
+ * Yields immutable snapshots without retaining history.
+ * Input is copied and validated on the first next(), not when creating the iterator.
+ */
+export declare function iterateInsertionSortSteps(values: readonly number[]): Generator<SortStep, void, unknown>;

package/dist/core/insertion-sort.js

@@ -1,5 +1,12 @@
 /** Creates a stable ascending insertion-sort trace without modifying the input. */
 export function insertionSortSteps(values) {
+    return Object.freeze([...iterateInsertionSortSteps(values)]);
+}
+/**
+ * Yields immutable snapshots without retaining history.
+ * Input is copied and validated on the first next(), not when creating the iterator.
+ */
+export function* iterateInsertionSortSteps(values) {
     // Array.from also exposes sparse holes as undefined for validation.
     const input = Array.from(values);
     for (let i = 0; i < input.length; i++) {
@@ -8,14 +15,14 @@ export function insertionSortSteps(values) {
         }
     }
     const slots = input.map((value, index) => Object.freeze({ id: `item-${index}`, value }));
-    const steps = [];
+    let index = 0;
     let held = null;
     let sortedPrefixLength = Math.min(1, slots.length);
     let comparisons = 0;
     let writes = 0;
     const emit = (event) => {
-        steps.push(Object.freeze({
-            index: steps.length,
+        return Object.freeze({
+            index: index++,
             event: Object.freeze(event),
             state: Object.freeze({
                 slots: Object.freeze(slots.slice()),
@@ -24,36 +31,35 @@ export function insertionSortSteps(values) {
                 comparisons,
                 writes
             })
-        }));
+        });
     };
-    emit({ type: "start" });
+    yield emit({ type: "start" });
     for (let i = 1; i < slots.length; i++) {
         const key = slots[i];
         held = key;
         slots[i] = null;
         sortedPrefixLength = i;
-        emit({ type: "select", itemId: key.id, from: i });
+        yield emit({ type: "select", itemId: key.id, from: i });
         let hole = i;
         while (hole > 0) {
             const left = slots[hole - 1];
             comparisons++;
-            emit({ type: "compare", leftId: left.id, rightId: key.id });
+            yield emit({ type: "compare", leftId: left.id, rightId: key.id });
             if (left.value <= key.value)
                 break;
             slots[hole] = left;
             slots[hole - 1] = null;
             writes++;
             sortedPrefixLength = hole - 1;
-            emit({ type: "shift", itemId: left.id, from: hole - 1, to: hole });
+            yield emit({ type: "shift", itemId: left.id, from: hole - 1, to: hole });
             hole--;
         }
         slots[hole] = key;
         held = null;
         writes++;
         sortedPrefixLength = i + 1;
-        emit({ type: "insert", itemId: key.id, to: hole });
+        yield emit({ type: "insert", itemId: key.id, to: hole });
     }
     sortedPrefixLength = slots.length;
-    emit({ type: "done" });
-    return Object.freeze(steps);
+    yield emit({ type: "done" });
 }

package/dist/core/player.d.ts

@@ -0,0 +1,15 @@
+import type { SortStep } from "./types.js";
+import type { SortFrame } from "./timeline.js";
+export interface SortPlayer {
+    readonly frame: SortFrame;
+    readonly finished: boolean;
+    /** Advance by playback time; pass zero to redraw without consuming steps. */
+    advance(deltaMs: number): SortFrame;
+    /** Close the source early. The last frame remains readable. */
+    dispose(): void;
+}
+/** Forward-only playback. The source must end with a `done` event. */
+export declare function createSortPlayer(steps: Iterable<SortStep>, options: {
+    stepDurationMs: number;
+    finalHoldMs: number;
+}): SortPlayer;

package/dist/core/player.js

@@ -0,0 +1,88 @@
+/** Forward-only playback. The source must end with a `done` event. */
+export function createSortPlayer(steps, options) {
+    const { stepDurationMs, finalHoldMs } = options;
+    if (!Number.isFinite(stepDurationMs) || stepDurationMs <= 0 ||
+        !Number.isFinite(finalHoldMs) || finalHoldMs < 0) {
+        throw new RangeError("Expected positive step duration and non-negative final hold");
+    }
+    const iterator = steps[Symbol.iterator]();
+    let closed = false;
+    const close = () => {
+        if (!closed) {
+            closed = true;
+            iterator.return?.();
+        }
+    };
+    let current;
+    try {
+        const first = iterator.next();
+        if (first.done)
+            throw new RangeError("Player requires at least one step");
+        current = first.value;
+    }
+    catch (error) {
+        close();
+        throw error;
+    }
+    let previous = current;
+    let elapsed = stepDurationMs;
+    let hold = 0;
+    let disposed = false;
+    let finished = false;
+    const complete = () => {
+        if (current.event.type === "done" && elapsed === stepDurationMs) {
+            previous = current;
+            close();
+            finished = hold >= finalHoldMs;
+        }
+    };
+    complete();
+    const frame = () => Object.freeze({
+        previous: previous.state, current: current.state,
+        progress: elapsed / stepDurationMs,
+        stepIndex: current.index, event: current.event
+    });
+    return Object.freeze({
+        get frame() { return frame(); },
+        get finished() { return finished; },
+        advance(deltaMs) {
+            if (disposed)
+                throw new Error("Player has been disposed");
+            if (!Number.isFinite(deltaMs) || deltaMs < 0) {
+                throw new RangeError("Expected finite non-negative playback time");
+            }
+            try {
+                let remaining = deltaMs;
+                while (remaining > 0 && !finished) {
+                    if (elapsed === stepDurationMs) {
+                        if (current.event.type === "done") {
+                            hold += Math.min(remaining, finalHoldMs - hold);
+                            complete();
+                            break;
+                        }
+                        const next = iterator.next();
+                        if (next.done)
+                            throw new RangeError("Step source ended without a done event");
+                        previous = current;
+                        current = next.value;
+                        elapsed = 0;
+                    }
+                    const amount = Math.min(remaining, stepDurationMs - elapsed);
+                    elapsed += amount;
+                    remaining -= amount;
+                    complete();
+                }
+                return frame();
+            }
+            catch (error) {
+                disposed = true;
+                close();
+                throw error;
+            }
+        },
+        dispose() {
+            disposed = true;
+            close();
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grundyjs/algiviz",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Deterministic algorithm steps for educational visualizations",
   "type": "module",
   "files": [