@grundyjs/algiviz 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.4.0 — 2026-10-09
+
+- Verify the packed npm archive in an isolated TypeScript consumer before publishing.
+
+- Add `/scene` with typed user-defined object data and visualization handlers,
+  identity matching, enter/update/exit transitions, layers and reference lookup.
+- Render array bars through the scene dispatcher and expose `arrayScene`.
+- Add an external tree traversal demo defining its own nodes, edges and pointer.
+
+- Add algorithm-free `/array` and `/playback` entry points: user-defined generators,
+  validated array operations, generic states/events and optional rendering callbacks.
+- Add `highlight` events and `createArrayRenderer`; existing rendering names remain available.
+- Move demo algorithms into application-owned examples using only the public API.
+  Old `/core` algorithm exports remain deprecated compatibility adapters.
+- Preserve all original insertion/bubble traces; premature exhaustion now reports
+  a missing terminal step rather than a missing done event.
+
+## 0.3.0 — 2026-10-09
+
+- Extend `SortEvent` with `swap` and `pass`, and `SortSnapshot` with optional
+  `sortedSuffixLength`. Consumers with exhaustive event switches must handle
+  the new event types. Existing insertion-sort traces remain unchanged.
+
+- Share input validation, item identities, immutable snapshots and operation
+  counters between sorting algorithms; document adding an algorithm internally.
+
+- Add stable bubble sort with `bubbleSortSteps` and `iterateBubbleSortSteps`,
+  adjacent swaps, sorted suffix tracking and early exit after a pass without swaps.
+- Render both swapped items and the sorted suffix; select either algorithm in
+  the demo with history or generator playback.
+
 ## 0.2.0 — 2026-10-09
 
 - Move the held key horizontally along the baseline without lifting it above the array;

package/README.md

@@ -1,6 +1,221 @@
 # 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.
+A TypeScript toolkit for user-defined algorithm visualizations. You write the algorithm; AlgiViz provides array operations, immutable steps, playback and canvas rendering. No runtime dependencies. Playback works without DOM, React or Next.js. ESM only, with TypeScript declarations.
+
+## User-defined algorithms
+
+The following API is introduced in 0.4.0.
+New applications use these entry points, which do not import bundled algorithms:
+
+- `@grundyjs/algiviz/array`: array operations and generator definitions.
+- `@grundyjs/algiviz/playback`: generic playback of any immutable states and events.
+- `@grundyjs/algiviz/scene`: typed objects and user-provided visualizations.
+- `@grundyjs/algiviz/canvas`: the ready-made array renderer.
+
+You own the loops, conditions and operation order. No library registration or
+changes to AlgiViz are required. For example, reversing an array:
+
+```js
+import { defineArrayAlgorithm, createArrayPlayer, createArrayTimeline } from "@grundyjs/algiviz/array";
+import { createArrayRenderer } from "@grundyjs/algiviz/canvas";
+
+const reverse = defineArrayAlgorithm(function* (array) {
+    yield array.start();
+    for (let i = 0; i < Math.floor(array.length / 2); i++) {
+        yield array.highlight([i, array.length - 1 - i]);
+        yield array.swap(i, array.length - 1 - i);
+    }
+    yield array.done();
+});
+
+const options = { stepDurationMs: 350, finalHoldMs: 1000 };
+const ctx = canvas.getContext("2d");
+const renderer = createArrayRenderer({ theme: "dark" });
+const player = createArrayPlayer(reverse.iterate([1, 2, 3, 4]), {
+    ...options,
+    render: frame => renderer.render(ctx, frame)
+});
+// Your animation loop calls player.advance(deltaMs * speed).
+// No calls while paused; advance(0) redraws after resizing.
+// On teardown: cancel your animation loop and call player.dispose().
+
+// Alternatively, retain history and seek:
+const timeline = createArrayTimeline(reverse.steps([1, 2, 3, 4]), options);
+renderer.render(ctx, timeline.sample(500));
+```
+
+`defineArrayAlgorithm` returns `iterate(values)` and `steps(values)`. Each
+iterator owns a separate workspace and copies/validates input on the first
+`next()`. `steps` collects the iterator into a frozen array. Yield every
+operation immediately, begin with `start`, and end with `done`. Each operation
+updates the workspace and returns an immutable snapshot; it does not draw.
+The player invokes the supplied `render` initially and on every `advance`.
+Rendering errors close the iterator and propagate to the caller.
+
+### Array operations
+
+| Operation | Effect |
+| --- | --- |
+| `at(index)`, `held`, `length` | Read a frozen item, the held item or array length |
+| `start(regions?)` | Emit initial state; call once |
+| `compare(left, right)` | Highlight two positions and count one comparison; either position can be `"held"` |
+| `highlight(positions)` | Highlight items for this step without changing counters |
+| `swap(left, right, regions?)` | Exchange occupied positions; count two writes (non-adjacent swaps are supported) |
+| `select(from, regions?)` | Hold an item and leave a hole; no counted writes |
+| `shift(from, to, regions?)` | Move an item into the hole; count one write |
+| `insert(to, regions?)` | Fill the hole with the held item; count one write |
+| `pass(end, regions?)` | Describe a completed pass without changing items or counters |
+| `done(regions?)` | Finish; requires no held item; does not sort or infer sorted regions |
+
+`regions` can contain `sortedPrefixLength` and `sortedSuffixLength`.
+Omitted markers retain their previous values. The author decides when regions
+are sorted; AlgiViz validates their bounds but does not prove that claim. Positions
+are zero-based; invalid positions, occupied destinations and invalid operation
+order throw before mutating the workspace. Read snapshots rather than modifying
+items yourself. `createArrayTrace(values)` exposes the same operations directly,
+with immediate input validation, for authors writing their own generator wrapper.
+
+Full insertion/bubble implementations live in [examples/algorithms.mjs](examples/algorithms.mjs).
+The browser demo imports those external algorithms. Deprecated `/core` exports
+remain available through isolated compatibility implementations using the same
+operations; they are retained in the package until a breaking release removes them.
+Existing insertion/bubble traces remain unchanged. `ArrayEvent` also includes the
+new `highlight` event, so exhaustive event switches must handle it.
+
+### Custom structures and renderers
+
+`/playback` does not know arrays, sorting, Canvas, or event names. A source yields
+`Step<State, Event>` objects with contiguous zero-based `index`, immutable
+`state` and `event`. Supply `isTerminal` to identify the final step and
+`render` to draw each interpolated frame using any rendering technology:
+
+```js
+import { createPlayer, createTimeline } from "@grundyjs/algiviz/playback";
+
+const player = createPlayer(myTraversal(), {
+    stepDurationMs: 300,
+    finalHoldMs: 1000,
+    isTerminal: step => step.event.kind === "finished",
+    render: frame => drawGraph(frame.previous, frame.current, frame.progress, frame.event)
+});
+```
+
+The render callback is optional. Without it, read `player.frame` and render
+manually. `createTimeline(steps, timing)` supports seeking with the same generic
+frame shape; call your renderer with its `sample(timeMs)` result. The generic
+engine does not clone or freeze user states; that is the source's responsibility.
+It retains adjacent snapshots only; the timeline retains the supplied history.
+Custom array events or tree/graph operations can use this contract and a custom
+renderer. The scene API below dispatches individual objects; there is no built-in
+graph/tree algorithm or operation set.
+
+### User-defined objects and visualizations
+
+The `/scene` API is introduced in 0.4.0. Define a type map with your own data, then
+provide a visualization for every type. AlgiViz matches identities and dispatches
+objects; your handlers decide how data becomes geometry and how it interpolates.
+
+```ts
+import { createSceneRenderer, type Scene } from "@grundyjs/algiviz/scene";
+
+interface MyObjects {
+    badge: { x: number; y: number; label: string };
+}
+
+const renderer = createSceneRenderer<MyObjects, CanvasRenderingContext2D>({
+    badge(ctx, object) {
+        const from = (object.previous ?? object.current)!.data;
+        const to = (object.current ?? object.previous)!.data;
+        const x = from.x + (to.x - from.x) * object.progress;
+        const y = from.y + (to.y - from.y) * object.progress;
+        ctx.save();
+        try {
+            ctx.globalAlpha = object.presence;
+            ctx.fillText(to.label, x, y);
+        } finally { ctx.restore(); }
+    }
+});
+
+const before: Scene<MyObjects> = {
+    objects: [{ id: "first", type: "badge", data: { x: 20, y: 30, label: "A" } }]
+};
+const after: Scene<MyObjects> = {
+    objects: [{ id: "first", type: "badge", data: { x: 120, y: 30, label: "A" } }]
+};
+// Keep these states immutable. A generic timeline/player can provide this frame.
+renderer.render(ctx, {
+    previous: before, current: after, progress: 0.5, stepIndex: 1, event: "move"
+});
+```
+
+- An object has a non-empty stable `id`, a `type`, user-defined `data` and an
+  optional finite `zIndex` (default zero). IDs are unique within a snapshot. A
+  retained ID cannot change type; use a new ID to replace an object of another type.
+- Handlers receive `previous` and `current` objects, with `null` for a missing
+  endpoint. `phase` is `enter`, `update` or `exit`. `progress` is the raw 0–1 frame
+  progress. `presence` is progress on entry, 1 on update and 1−progress on exit;
+  handlers may use it for opacity or scale. It is not applied automatically.
+- Lower `zIndex` draws first. Ties follow the current snapshot's object order;
+  removed objects follow in their previous order. The current layer wins when it
+  changes. There is no implicit layout or coordinate system.
+- The third handler argument exposes `scene.get(id)` for links, pointers and other
+  references. It returns the referenced object's full transition, including both
+  endpoints; missing references return `undefined`. The application decides how to
+  handle them and how to interpolate positions or changing targets.
+- `createSceneFrame(frame)` exposes the same resolved transitions without drawing.
+  The registry is captured at renderer construction. Missing handlers, duplicate
+  IDs, invalid progress/layers and changed types fail before any handler is called.
+- Scene processing is stateless, so arbitrary seeking is supported. Handlers may
+  see zero-presence objects. They are frame draws, **not guaranteed lifecycle
+  callbacks**: skipping steps can skip appearances/exits entirely. Clear Canvas
+  each frame; a retained SVG/DOM backend must reconcile its elements against the
+  current frame, removing stale IDs itself. Save/restore Canvas state inside each
+  handler. Exceptions propagate; there is no rollback of drawing already performed.
+- Snapshots and user data are not cloned or deep-frozen. The author owns their
+  immutability, as with generic playback. Scene indexing uses O(n) additional
+  memory and layer ordering O(n log n) time per frame.
+
+`arrayScene(snapshot)` from `/canvas` adapts an array to a `Scene<ArrayObjects>`
+with `bar` objects whose data contains `item`, `index` and `held`. The built-in
+array renderer uses this same dispatcher. You can provide a different `bar`
+visualization using `createSceneRenderer<ArrayObjects, YourContext>`.
+
+See [examples/tree-scene.mjs](examples/tree-scene.mjs) and open
+`examples/tree.html` after building and serving the repository. The application
+defines its own tree traversal, `node`, `edge` and `pointer` types, appearance,
+pointer movement and removal. No tree-specific code is added to AlgiViz.
+
+## Migrating from 0.3.x
+
+Existing `/core` imports continue to work in 0.4.0. Built-in insertion and bubble
+sort exports are deprecated, but their traces remain unchanged. Migrate each
+algorithm into your application using `defineArrayAlgorithm`; complete examples
+are in [examples/algorithms.mjs](https://github.com/urffin/algiviz/blob/v0.4.0/examples/algorithms.mjs).
+
+| Previous API | Application-owned API |
+| --- | --- |
+| `insertionSortSteps(values)` | `insertion.steps(values)` on your algorithm definition |
+| `iterateInsertionSortSteps(values)` | `insertion.iterate(values)` |
+| `bubbleSortSteps(values)` / `iterateBubbleSortSteps(values)` | `bubble.steps(values)` / `bubble.iterate(values)` |
+| `/core` `createSortTimeline` / `createSortPlayer` | `/array` `createArrayTimeline` / `createArrayPlayer` |
+| `/canvas` `createSortRenderer` | `/canvas` `createArrayRenderer` |
+| `/core` `SortEvent`, `SortSnapshot`, `SortStep`, `SortFrame` | `/array` `ArrayEvent`, `ArraySnapshot`, `ArrayStep`, `ArrayFrame` |
+
+Timing options and array frames remain compatible. Exhaustive event switches
+must handle the new `highlight` event, even though the legacy algorithms do not
+emit it. An incomplete player source now reports a missing terminal step; avoid
+depending on the old error text. Generic `/playback` requires an explicit
+`isTerminal` predicate; `/array` players still recognize the `done` event.
+
+Use `/scene` when you need your own object types and visualization handlers.
+This is optional for array users: `createArrayRenderer` already uses scenes.
+Generic states and custom scene data must remain immutable; unlike array
+operations, the generic engine does not clone or deep-freeze them.
+
+## Legacy sorting API
+
+The following `/core` examples remain supported for compatibility. Prefer the
+user-defined algorithm API above for new integrations.
 
 ## Install
 
@@ -42,6 +257,38 @@ 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.
 
+## Bubble sort
+
+`bubbleSortSteps(values)` collects a frozen history; `iterateBubbleSortSteps(values)`
+yields the same snapshots on demand. Both work with the existing timeline, player
+and canvas renderer. Available since version 0.3.0.
+
+```js
+import { bubbleSortSteps, iterateBubbleSortSteps, createSortPlayer } from "@grundyjs/algiviz/core";
+
+const steps = bubbleSortSteps([5, 2, 4, 2, 1]);
+const player = createSortPlayer(iterateBubbleSortSteps([5, 2, 4, 2, 1]), {
+    stepDurationMs: 350, finalHoldMs: 1000
+});
+```
+
+Each left-to-right pass compares adjacent items. `compare` identifies both items;
+`swap` contains their pre-swap `leftId`, `rightId`, `left` and `right` positions,
+and its snapshot is after the exchange. Each swap counts as two array writes.
+Equal items are never swapped, so the sort is stable. `held` remains null and
+`sortedPrefixLength` is zero.
+
+`pass` marks a completed pass, with `end` identifying its last compared position.
+The optional `sortedSuffixLength` snapshot field counts trailing items in their
+final positions; renderers treat an omitted value as zero for older traces.
+A pass with no swaps ends the sort early and marks the entire array sorted.
+`done` always has `sortedSuffixLength` equal to the array length.
+
+Validation, lazy input copying, freezing and memory costs match insertion sort.
+The underlying algorithm performs O(n²) comparisons in the worst case and O(n)
+on sorted input; full snapshots still make worst-case trace generation O(n³).
+Consumers switching on `SortEvent.type` should handle the new `swap` and `pass` events.
+
 ## Lazy steps
 
 Use `iterateInsertionSortSteps` to consume steps on demand without retaining the
@@ -140,7 +387,8 @@ Build, serve this project root using any static HTTP server, and open examples/i
 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.
+Algorithm and mode changes restart the loaded array. Choose insertion or bubble
+sort; both support both playback modes. 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.
 
@@ -148,21 +396,37 @@ catch-up work to keep controls responsive.
 ## API at a glance
 
 - `insertionSortSteps(values)` returns immutable `SortStep[]` snapshots. Empty arrays are valid.
+- `bubbleSortSteps(values)` returns the same snapshot format for stable bubble sort.
+- `iterateInsertionSortSteps(values)` and `iterateBubbleSortSteps(values)` yield snapshots lazily.
+- `createSortPlayer(iterable, { stepDurationMs, finalHoldMs })` provides forward-only playback with `frame`, `advance(deltaMs)`, `finished` and `dispose()`.
 - `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.
 
+## Adding an algorithm
+
+Create an application-owned generator with `defineArrayAlgorithm`, as shown
+above. Add it to your application's controls or the demo registry. AlgiViz needs
+no change when the existing operations are sufficient. For a new kind of state
+or event, implement the generic playback contract and its renderer.
+
 ## 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.
+Run `npm test` and `npm run test:package`. The package check builds a real tarball,
+installs it offline in a separate temporary consumer, compiles TypeScript against
+the installed declarations and runs an external algorithm and custom scene with
+both playback modes. It also checks the array adapter and legacy compatibility.
+The temporary consumer is removed afterward. The release workflow runs this check
+before publishing. 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 exact version in `package.json` and `package-lock.json` (for example `v0.4.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).
 

package/dist/array/index.d.ts

@@ -0,0 +1,7 @@
+export { createArrayTrace, defineArrayAlgorithm } from "./trace.js";
+export type { ArrayTrace, ArrayAlgorithm, SortedRegions } from "./trace.js";
+export type { Item, SortEvent as ArrayEvent, SortSnapshot as ArraySnapshot, SortStep as ArrayStep } from "./types.js";
+export { createSortPlayer as createArrayPlayer } from "../core/player.js";
+export { createSortTimeline as createArrayTimeline } from "../core/timeline.js";
+export type { SortPlayer as ArrayPlayer } from "../core/player.js";
+export type { SortFrame as ArrayFrame, SortTimeline as ArrayTimeline } from "../core/timeline.js";

package/dist/array/index.js

@@ -0,0 +1,3 @@
+export { createArrayTrace, defineArrayAlgorithm } from "./trace.js";
+export { createSortPlayer as createArrayPlayer } from "../core/player.js";
+export { createSortTimeline as createArrayTimeline } from "../core/timeline.js";

package/dist/array/snapshot-builder.d.ts

@@ -0,0 +1,11 @@
+import type { Item, SortEvent, SortStep } from "./types.js";
+/** Internal mutable workspace; only emit() exposes immutable snapshots. */
+export declare function createSortTrace(values: readonly number[]): {
+    state: {
+        slots: (Item | null)[];
+        held: Item | null;
+        sortedPrefixLength: number;
+        sortedSuffixLength?: number;
+    };
+    emit: (event: SortEvent) => SortStep;
+};

package/dist/array/snapshot-builder.js

@@ -0,0 +1,34 @@
+/** Internal mutable workspace; only emit() exposes immutable snapshots. */
+export function createSortTrace(values) {
+    // Array.from exposes sparse holes as undefined so they fail validation too.
+    const input = Array.from(values);
+    const slots = input.map((value, index) => {
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+            throw new TypeError(`Expected a finite number at index ${index}`);
+        }
+        return Object.freeze({ id: `item-${index}`, value });
+    });
+    const state = { slots, held: null, sortedPrefixLength: 0 };
+    let index = 0;
+    let comparisons = 0;
+    let writes = 0;
+    function emit(event) {
+        if (event.type === "compare")
+            comparisons++;
+        if (event.type === "shift" || event.type === "insert")
+            writes++;
+        if (event.type === "swap")
+            writes += 2;
+        return Object.freeze({
+            index: index++,
+            event: Object.freeze(event),
+            state: Object.freeze({
+                ...state,
+                slots: Object.freeze(state.slots.slice()),
+                comparisons,
+                writes
+            })
+        });
+    }
+    return { state, emit };
+}

package/dist/array/trace.d.ts

@@ -0,0 +1,27 @@
+import type { Item, SortStep } from "./types.js";
+export interface SortedRegions {
+    readonly sortedPrefixLength?: number;
+    readonly sortedSuffixLength?: number;
+}
+export interface ArrayTrace {
+    readonly length: number;
+    readonly held: Item | null;
+    at(index: number): Item | null;
+    start(regions?: SortedRegions): SortStep;
+    compare(left: number | "held", right: number | "held"): SortStep;
+    highlight(positions: readonly (number | "held")[]): SortStep;
+    swap(left: number, right: number, regions?: SortedRegions): SortStep;
+    select(from: number, regions?: SortedRegions): SortStep;
+    shift(from: number, to: number, regions?: SortedRegions): SortStep;
+    insert(to: number, regions?: SortedRegions): SortStep;
+    pass(end: number, regions?: SortedRegions): SortStep;
+    done(regions?: SortedRegions): SortStep;
+}
+/** Operations own mutations, counters and immutable snapshots, but no algorithm. */
+export declare function createArrayTrace(values: readonly number[]): ArrayTrace;
+export interface ArrayAlgorithm {
+    iterate(values: readonly number[]): Generator<SortStep, void, unknown>;
+    steps(values: readonly number[]): readonly SortStep[];
+}
+/** Each iterator owns its workspace; input is read on its first next(). */
+export declare function defineArrayAlgorithm(algorithm: (array: ArrayTrace) => Generator<SortStep, void, unknown>): ArrayAlgorithm;

package/dist/array/trace.js

@@ -0,0 +1,119 @@
+import { createSortTrace } from "./snapshot-builder.js";
+/** Operations own mutations, counters and immutable snapshots, but no algorithm. */
+export function createArrayTrace(values) {
+    const { state, emit } = createSortTrace(values);
+    const { slots } = state;
+    let phase = "new";
+    function index(value) {
+        if (!Number.isInteger(value) || value < 0 || value >= slots.length)
+            throw new RangeError(`Invalid array index: ${value}`);
+    }
+    function active() {
+        if (phase !== "running")
+            throw new Error("Call start before operations; no operations are allowed after done");
+    }
+    function item(position) {
+        if (position !== "held")
+            index(position);
+        const value = position === "held" ? state.held : slots[position];
+        if (!value)
+            throw new Error(`No item at ${position}`);
+        return value;
+    }
+    function regions(update = {}) {
+        for (const value of [update.sortedPrefixLength, update.sortedSuffixLength]) {
+            if (value !== undefined && (!Number.isInteger(value) || value < 0 || value > slots.length)) {
+                throw new RangeError("Sorted region length must be between zero and array length");
+            }
+        }
+        if (update.sortedPrefixLength !== undefined)
+            state.sortedPrefixLength = update.sortedPrefixLength;
+        if (update.sortedSuffixLength !== undefined)
+            state.sortedSuffixLength = update.sortedSuffixLength;
+    }
+    return Object.freeze({
+        get length() { return slots.length; },
+        get held() { return state.held; },
+        at(position) { index(position); return slots[position]; },
+        start(update) {
+            if (phase !== "new")
+                throw new Error("Trace has already started");
+            regions(update);
+            phase = "running";
+            return emit({ type: "start" });
+        },
+        compare(left, right) {
+            active();
+            const a = item(left), b = item(right);
+            return emit({ type: "compare", leftId: a.id, rightId: b.id });
+        },
+        highlight(positions) {
+            active();
+            const itemIds = Object.freeze(positions.map(position => item(position).id));
+            return emit({ type: "highlight", itemIds });
+        },
+        swap(left, right, update) {
+            active();
+            const a = item(left), b = item(right);
+            if (left === right)
+                throw new RangeError("Swap requires distinct positions");
+            regions(update);
+            slots[left] = b;
+            slots[right] = a;
+            return emit({ type: "swap", leftId: a.id, rightId: b.id, left, right });
+        },
+        select(from, update) {
+            active();
+            if (state.held)
+                throw new Error("An item is already held");
+            const selected = item(from);
+            regions(update);
+            state.held = selected;
+            slots[from] = null;
+            return emit({ type: "select", itemId: selected.id, from });
+        },
+        shift(from, to, update) {
+            active();
+            const moved = item(from);
+            index(to);
+            if (slots[to] !== null)
+                throw new Error("Shift destination must be empty");
+            regions(update);
+            slots[to] = moved;
+            slots[from] = null;
+            return emit({ type: "shift", itemId: moved.id, from, to });
+        },
+        insert(to, update) {
+            active();
+            const inserted = item("held");
+            index(to);
+            if (slots[to] !== null)
+                throw new Error("Insert destination must be empty");
+            regions(update);
+            slots[to] = inserted;
+            state.held = null;
+            return emit({ type: "insert", itemId: inserted.id, to });
+        },
+        pass(end, update) {
+            active();
+            index(end);
+            regions(update);
+            return emit({ type: "pass", end });
+        },
+        done(update) {
+            active();
+            if (state.held)
+                throw new Error("Insert the held item before completing the trace");
+            regions(update);
+            phase = "done";
+            return emit({ type: "done" });
+        }
+    });
+}
+/** Each iterator owns its workspace; input is read on its first next(). */
+export function defineArrayAlgorithm(algorithm) {
+    function* iterate(values) {
+        yield* algorithm(createArrayTrace(values));
+    }
+    return Object.freeze({ iterate, steps: (values) => Object.freeze([...iterate(values)]) });
+}

package/dist/array/types.d.ts

@@ -0,0 +1,55 @@
+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: "swap";
+    leftId: string;
+    rightId: string;
+    left: number;
+    right: number;
+} | {
+    type: "pass";
+    end: number;
+} | {
+    type: "highlight";
+    itemIds: readonly string[];
+} | {
+    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;
+    /** Final sorted trailing slots. Omitted by older traces and insertion sort. */
+    readonly sortedSuffixLength?: 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/array/types.js

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

package/dist/canvas/index.d.ts

@@ -1,4 +1,16 @@
+import type { Item, SortSnapshot } from "../core/types.js";
 import type { SortFrame } from "../core/timeline.js";
+import { type Scene } from "../scene/index.js";
+export type ArrayObjects = {
+    bar: {
+        item: Item;
+        index: number;
+        held: boolean;
+    };
+};
+/** Adapts array identities to the same public scene contract used by custom objects. */
+export declare function arrayScene(state: SortSnapshot): Scene<ArrayObjects>;
+export { createSortRenderer as createArrayRenderer };
 /** Stateless full-frame renderer. Bitmap dimensions determine layout and video size. */
 export declare function createSortRenderer(options: {
     theme: "light" | "dark";