@grundyjs/algiviz 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 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.
+- Stateless light and dark canvas rendering.
+- ESM and TypeScript declarations; no runtime dependencies.

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -1,4 +1,186 @@
-# Temporary Holding Version
+# AlgiViz
+
+A TypeScript library for educational algorithm visualization: stable insertion sort traces, a seekable timeline and a canvas renderer. No runtime dependencies. The core works without DOM, React or Next.js. ESM only, with TypeScript declarations.
+
+## Install
+
+```sh
+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.x is an initial API and may change in later minor releases.
+
+## Development
+
+Requires Node.js 22 or later and npm.
+
+```sh
+npm install
+npm test
+npm pack
+```
+
+Build output includes ESM and TypeScript declarations. `npm pack` rebuilds automatically; `npm publish` runs the tests before packing. The archive includes only dist, README, LICENSE, CHANGELOG and package metadata. Licensed under MIT.
+
+```js
+import { insertionSortSteps } from "@grundyjs/algiviz/core";
+
+const steps = insertionSortSteps([5, 2, 4, 2, 1]);
+console.log(steps.at(-1).state.slots.map(item => item.value));
+// [1, 2, 2, 4, 5]
+```
+
+Each step contains a typed event and the complete state **after** it. `start` preserves the input; `done` has no held item and a fully sorted array. Original-index ids (`item-0`, etc.) distinguish equal values and are deterministic within one trace. The input is never modified. Invalid values, including NaN, Infinity and sparse holes, throw TypeError.
+
+`select` moves the key into `held` and leaves one null slot. `compare` compares the neighbor with the key. `shift` moves the neighbor into the hole. `insert` puts the key back. All original items occur exactly once across `slots` and `held` in every snapshot. Equal values are never shifted past each other.
+
+`sortedPrefixLength` counts the leading occupied slots known to be sorted: initially min(1, n), during insertion it ends at the hole, after insertion it extends through the processed region. `comparisons` counts compare events. `writes` counts shift and insert events, including reinserting an unchanged key; extracting a key and clearing the hole are visualization bookkeeping, not counted writes.
+
+The result, steps, events, snapshots, slot arrays and items are frozen at runtime. Items may be shared between snapshots because they are immutable.
+
+The underlying sort uses O(n²) comparisons in the worst case and O(n) on already sorted input. This API stores full history, so its worst-case time and memory are O(n³), unlike ordinary in-place insertion sort. Intended for small educational inputs; the demo site limits inputs to 24 items. This core imposes no UI limit.
+
+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`.
+Step i completes at i * stepDurationMs; finalHoldMs extends the final frame. sample clamps finite times to the timeline range and rejects non-finite times. Frames include the current event for explanations and highlights.
+The renderer draws a full frame using the canvas bitmap dimensions and restores context state. Signed values use magnitude for bar height and retain their sign in labels. Use small inputs for readable labels.
+
+```js
+import { createSortTimeline } from "@grundyjs/algiviz/core";
+import { createSortRenderer } from "@grundyjs/algiviz/canvas";
+
+const timeline = createSortTimeline(steps, { stepDurationMs: 650, finalHoldMs: 2000 });
+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.
+
+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
+
+- `insertionSortSteps(values)` returns immutable `SortStep[]` snapshots. Empty arrays are valid.
+- `createSortTimeline(steps, { stepDurationMs, finalHoldMs })` returns `durationMs` and `sample(timeMs)`. Frames expose `previous`, `current`, `progress`, `stepIndex` and `event`.
+- `createSortRenderer({ theme: "dark" | "light" }).render(ctx, frame)` draws into a browser 2D canvas context. Drawing and animation scheduling remain separate.
+
+For playback, call `timeline.sample(elapsedMs)` in your own requestAnimationFrame loop. For recording, use a fixed-size export canvas. Negative values are shown by magnitude with signed labels; the chart is not a signed-axis plot.
+
+## 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.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.

package/dist/canvas/index.d.ts

@@ -0,0 +1,7 @@
+import type { SortFrame } from "../core/timeline.js";
+/** Stateless full-frame renderer. Bitmap dimensions determine layout and video size. */
+export declare function createSortRenderer(options: {
+    theme: "light" | "dark";
+}): Readonly<{
+    render(ctx: CanvasRenderingContext2D, frame: SortFrame): void;
+}>;

package/dist/canvas/index.js

@@ -0,0 +1,76 @@
+const palettes = {
+    dark: { background: "#101827", text: "#f1f5f9", bar: "#94a3b8", sorted: "#34d399", active: "#fbbf24", held: "#c4b5fd" },
+    light: { background: "#f8fafc", text: "#0f172a", bar: "#475569", sorted: "#047857", active: "#b45309", held: "#7c3aed" }
+};
+function positions(state) {
+    const result = new Map();
+    state.slots.forEach((item, index) => { if (item)
+        result.set(item.id, { item, index, held: false }); });
+    if (state.held)
+        result.set(state.held.id, { item: state.held,
+            index: state.slots.indexOf(null), held: true });
+    return result;
+}
+/** Stateless full-frame renderer. Bitmap dimensions determine layout and video size. */
+export function createSortRenderer(options) {
+    const colors = palettes[options.theme];
+    return Object.freeze({
+        render(ctx, frame) {
+            const { width, height } = ctx.canvas;
+            if (width <= 0 || height <= 0)
+                return;
+            const before = positions(frame.previous);
+            const after = positions(frame.current);
+            const items = [...after.values()];
+            const count = frame.current.slots.length;
+            const margin = Math.min(32, width * 0.05);
+            const cell = (width - 2 * margin) / Math.max(count, 1);
+            const barWidth = cell * 0.7;
+            const available = height * 0.48;
+            const maxMagnitude = Math.max(1, ...items.map(({ item }) => Math.abs(item.value)));
+            const baseline = height * 0.69;
+            const fontSize = Math.max(9, Math.min(20, cell * 0.45, width * 0.035));
+            const progress = frame.progress;
+            const p = progress * progress * (3 - 2 * progress);
+            const event = frame.event;
+            ctx.save();
+            try {
+                ctx.setTransform(1, 0, 0, 1, 0, 0);
+                ctx.globalAlpha = 1;
+                ctx.fillStyle = colors.background;
+                ctx.fillRect(0, 0, width, height);
+                ctx.font = `${Math.max(12, Math.min(24, width * 0.045))}px sans-serif`;
+                ctx.textAlign = "left";
+                ctx.textBaseline = "middle";
+                ctx.fillStyle = colors.text;
+                ctx.fillText(`AlgiViz · ${event.type} · ${frame.stepIndex}`, margin, height * 0.07);
+                if (!count)
+                    ctx.fillText("Empty array", margin, baseline);
+                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 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, 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 - fontSize, cell * 0.95);
+                    ctx.fillText(String(next.index), margin + (next.index + 0.5) * cell, baseline + height * 0.06);
+                }
+                ctx.textAlign = "left";
+                ctx.font = `${Math.max(11, Math.min(18, width * 0.03))}px sans-serif`;
+                ctx.fillStyle = colors.text;
+                ctx.fillText(`Comparisons: ${frame.current.comparisons} · Writes: ${frame.current.writes}`, margin, height * 0.9, width - margin * 2);
+            }
+            finally {
+                ctx.restore();
+            }
+        }
+    });
+}

package/dist/core/index.d.ts

@@ -0,0 +1,6 @@
+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

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

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

@@ -0,0 +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

@@ -0,0 +1,65 @@
+/** 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++) {
+        if (typeof input[i] !== "number" || !Number.isFinite(input[i])) {
+            throw new TypeError(`Expected a finite number at index ${i}`);
+        }
+    }
+    const slots = input.map((value, index) => Object.freeze({ id: `item-${index}`, value }));
+    let index = 0;
+    let held = null;
+    let sortedPrefixLength = Math.min(1, slots.length);
+    let comparisons = 0;
+    let writes = 0;
+    const emit = (event) => {
+        return Object.freeze({
+            index: index++,
+            event: Object.freeze(event),
+            state: Object.freeze({
+                slots: Object.freeze(slots.slice()),
+                held,
+                sortedPrefixLength,
+                comparisons,
+                writes
+            })
+        });
+    };
+    yield emit({ type: "start" });
+    for (let i = 1; i < slots.length; i++) {
+        const key = slots[i];
+        held = key;
+        slots[i] = null;
+        sortedPrefixLength = i;
+        yield emit({ type: "select", itemId: key.id, from: i });
+        let hole = i;
+        while (hole > 0) {
+            const left = slots[hole - 1];
+            comparisons++;
+            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;
+            yield emit({ type: "shift", itemId: left.id, from: hole - 1, to: hole });
+            hole--;
+        }
+        slots[hole] = key;
+        held = null;
+        writes++;
+        sortedPrefixLength = i + 1;
+        yield emit({ type: "insert", itemId: key.id, to: hole });
+    }
+    sortedPrefixLength = slots.length;
+    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/dist/core/timeline.d.ts

@@ -0,0 +1,17 @@
+import type { SortEvent, SortSnapshot, SortStep } from "./types.js";
+export interface SortFrame {
+    readonly previous: SortSnapshot;
+    readonly current: SortSnapshot;
+    readonly progress: number;
+    readonly stepIndex: number;
+    readonly event: SortEvent;
+}
+export interface SortTimeline {
+    readonly durationMs: number;
+    sample(timeMs: number): SortFrame;
+}
+/** Step i is complete at i * stepDurationMs; the final state is held afterwards. */
+export declare function createSortTimeline(steps: readonly SortStep[], options: {
+    stepDurationMs: number;
+    finalHoldMs: number;
+}): SortTimeline;

package/dist/core/timeline.js

@@ -0,0 +1,30 @@
+/** Step i is complete at i * stepDurationMs; the final state is held afterwards. */
+export function createSortTimeline(steps, options) {
+    if (!steps.length)
+        throw new RangeError("Timeline requires at least one step");
+    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 history = steps.slice();
+    const end = (history.length - 1) * stepDurationMs;
+    const durationMs = end + finalHoldMs;
+    if (!Number.isFinite(durationMs))
+        throw new RangeError("Timeline duration is too large");
+    return Object.freeze({
+        durationMs,
+        sample(timeMs) {
+            if (!Number.isFinite(timeMs))
+                throw new TypeError("Time must be finite");
+            const time = Math.max(0, Math.min(timeMs, durationMs));
+            const index = Math.min(history.length - 1, Math.ceil(time / stepDurationMs));
+            const step = history[index];
+            const previous = time >= end || index === 0 ? step : history[index - 1];
+            const progress = previous === step ? 1 :
+                Math.min(1, (time - (index - 1) * stepDurationMs) / stepDurationMs);
+            return Object.freeze({ previous: previous.state, current: step.state,
+                progress, stepIndex: index, event: step.event });
+        }
+    });
+}

package/dist/core/types.d.ts

@@ -0,0 +1,41 @@
+export type Item = Readonly<{
+    id: string;
+    value: number;
+}>;
+export type SortEvent = Readonly<{
+    type: "start";
+} | {
+    type: "select";
+    itemId: string;
+    from: number;
+} | {
+    type: "compare";
+    leftId: string;
+    rightId: string;
+} | {
+    type: "shift";
+    itemId: string;
+    from: number;
+    to: number;
+} | {
+    type: "insert";
+    itemId: string;
+    to: number;
+} | {
+    type: "done";
+}>;
+export interface SortSnapshot {
+    readonly slots: readonly (Item | null)[];
+    readonly held: Item | null;
+    /** Sorted leading occupied slots; during insertion it ends at the hole. */
+    readonly sortedPrefixLength: number;
+    readonly comparisons: number;
+    /** Writes into array slots; selecting a key does not count as a write. */
+    readonly writes: number;
+}
+export interface SortStep {
+    readonly index: number;
+    readonly event: SortEvent;
+    /** Complete immutable state immediately after the event. */
+    readonly state: SortSnapshot;
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@grundyjs/algiviz",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Deterministic algorithm steps for educational visualizations",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "default": "./dist/core/index.js"
+    },
+    "./canvas": {
+      "types": "./dist/canvas/index.d.ts",
+      "import": "./dist/canvas/index.js",
+      "default": "./dist/canvas/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Grundy",
+    "url": "https://grundyjs.ru/"
+  },
+  "homepage": "https://grundyjs.ru/algorithms/insertion-sort/",
+  "keywords": [
+    "algorithms",
+    "visualization",
+    "insertion-sort",
+    "canvas",
+    "typescript"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/urffin/algiviz.git"
+  },
+  "bugs": {
+    "url": "https://github.com/urffin/algiviz/issues"
+  }
+}