@grundyjs/algiviz 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.5.0 — 2026-10-14
+
+- Cache immutable array and quick-sort scene projections and avoid repeated scale/layout
+  calculations and hidden text styling on dense charts; add a reproducible CPU/heap benchmark.
+- Add application-owned Lomuto and three-way quick-sort demos with shared playback
+  controls and limits (64 history values or 2,000 generator values).
+- Move the tree cursor along edges through shared ancestors in Canvas and SVG.
+
+- Add a retained SVG tree renderer alongside Canvas, with layer ordering and seek-safe element cleanup.
+
+- Add createSceneProjector to adapt immutable state frames with a two-endpoint cache; use it in the merge example.
+
+- Run tests and isolated package-consumer checks on pushes and pull requests,
+  using Node.js 22/24 on Linux and Windows.
+
+- Share array generation controls and validation across insertion, bubble and merge demos.
+
+- Support forward-only generator playback in the merge sort example without retaining history.
+
+- Add an application-owned merge sort example using scene/playback, with a main
+  array and buffer, stable identity labels, seeking and accessible playback controls.
+
+## 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

package/README.md

@@ -1,6 +1,263 @@
 # AlgiViz
 
-A TypeScript library for educational algorithm visualization: stable insertion and bubble 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. The Renderer selector switches between Canvas and SVG without restarting playback. The SVG example retains elements by ID, restores layer order and removes stale elements on every frame, including after a seek that skips exit transitions. See [examples/tree-svg.mjs](examples/tree-svg.mjs).
+
+For a second custom scene, open `examples/merge.html`. Its application-owned
+[merge algorithm](examples/merge-algorithm.mjs) and
+[renderer](examples/merge-scene.mjs) use `/playback` and `/scene` to show the main
+array and a reusable buffer. Equal values have letter suffixes to demonstrate
+stability. Cells use row/position IDs because copy-back temporarily duplicates
+item identities. Play/pause, step controls, speed and seeking support up to 64
+input values; text status, reduced motion and hidden-tab pausing are included.
+Select Generator for forward-only playback with O(n) retained snapshot memory;
+steps are produced on demand, and restarting creates a fresh iterator. History
+mode enables backward stepping and seeking with up to 64 values. Generator mode
+accepts up to 2,000 values; dense charts hide labels and text status previews the
+first 24 cells. Switching to history requires loading an array within its limit.
+The example stores full history, costing O(n² log n) space in the worst case;
+the underlying algorithm uses O(n) auxiliary memory. No merge-sort package
+export or new library API is needed.
+
+### State-to-scene projection (since 0.5.0)
+
+`createSceneProjector` was added in 0.5.0. It adapts
+playback frames from your state model to scenes without changing the algorithm:
+
+```js
+import { createSceneProjector } from '@grundyjs/algiviz/scene';
+const projectFrame = createSceneProjector(state => ({
+    objects: state.items.map(item => ({ id: item.id, type: 'node', data: item }))
+}));
+// Reuse the projector across renders, with either history or generator playback.
+renderer.render(ctx, projectFrame(frame));
+```
+
+The projection receives only a state, not an event or progress. Use a pure
+function and immutable states/scenes. Endpoints are compared with `Object.is`;
+mutating a retained state or changing captured projection settings will not
+invalidate the cache. Create a new projector when those settings change.
+At most two endpoint projections are retained; seeking to older states may
+recompute them. Events, step indices and progress are preserved. Viewport layout
+and animation belong in render handlers, not in this cached projection.
+The returned frame is frozen; user states and projected scenes are not cloned
+or deep-frozen. Scene validation still happens in the scene renderer.
+The merge example uses this adapter to avoid rebuilding two cell scenes on every
+animation frame. The algorithm, object types and visual behavior remain external.
+
+## 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
 
@@ -14,6 +271,10 @@ Try the [interactive insertion sort demo](https://grundyjs.ru/algorithms/inserti
 
 Requires Node.js 22 or later and npm.
 
+GitHub Actions runs `npm test` and `npm run test:package` on pushes to `master`
+and pull requests, using Node.js 22 and 24 on Linux and Windows. CI checks do not
+publish packages; publishing remains tied to a GitHub Release.
+
 ```sh
 npm install
 npm test
@@ -189,53 +450,29 @@ catch-up work to keep controls responsive.
 
 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 to this repository
+## Adding an algorithm
 
-Implement a generator in `src/core/` using the internal `createSortTrace` helper
-from `./sort-trace.js`. Call it **inside** the generator body to preserve lazy
-validation. It provides a mutable `state` workspace and `emit(event)`; emitting
-copies and freezes the snapshot, assigns its step index, and updates counters.
-It retains no history. The helper is internal, not a public package export.
-
-The algorithm owns its loop, array changes and sorted-region markers. Always
-change the workspace before yielding the event that describes that change:
-
-```ts
-// Inside a generator, after checking that adjacent items need exchanging:
-const a = state.slots[left]!;
-const b = state.slots[right]!;
-state.slots[left] = b;
-state.slots[right] = a;
-yield emit({ type: "swap", leftId: a.id, rightId: b.id, left, right });
-```
-
-Yield `start` before sorting and `done` after updating the final sorted region.
-Do not increment counters manually: `compare` adds one comparison, `shift` and
-`insert` add one write, and `swap` adds two writes. Reuse the frozen items created
-by the helper and preserve each item's identity across moves.
-
-Add a history wrapper with `Object.freeze([...iterateYourSortSteps(values)])`,
-export both functions from `src/core/index.ts`, and register the algorithm in
-`examples/demo.mjs` plus its select option in `examples/index.html`. The timeline
-and sequential player need no algorithm-specific changes. A new operation also
-requires updating `SortEvent`, its counter semantics and canvas highlighting or
-movement; existing operations can reuse the renderer.
-
-Use the bubble-sort tests as a guide: independently replay events, verify stable
-ordering and item conservation, check frozen snapshots and lazy validation, and
-compare sequential frames with the timeline. This helper reduces snapshot
-boilerplate; it does not validate that an algorithm's events match its mutations.
+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.3.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).
 
@@ -257,3 +494,42 @@ 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.
 
+
+All browser examples share playback defaults from examples/player-settings.mjs:
+The browser controller in `examples/demo-player.mjs` also owns animation scheduling,
+mode changes, stepping, seeking, restart, reduced motion and generator cleanup.
+650 ms per step, 1,000 ms final hold, speeds 0.25× through 32×, history/generator
+modes and forward/backward step controls. Backward stepping and seeking are
+disabled in generator mode. Array input limits are 64 for history and 2,000
+for generators. Reduced motion disables interpolation; hidden tabs pause.
+All sorting demos also share array generation: choose the element count and
+Random, Sorted or Reverse order, then Generate & load. The generated values
+appear in the input field and obey the selected playback mode's limit.
+
+## Quick sort partitions example
+
+Build and serve the repository root, then open [examples/quick.html](examples/quick.html).
+Choose Lomuto or three-way partitioning, preserving loaded values when switching.
+Both use the shared demo player: history supports seeking; generator mode retains
+adjacent snapshots and supports forward stepping. Speed, restart, reduced motion
+and hidden-tab pausing follow the other examples. Both modes are capped at 64
+finite values here because direct recursion and worst-case traces are expensive.
+This is a demo limit, not a library restriction.
+
+The example owns its algorithm and scene and uses the public /scene and /playback
+APIs. Three-way recursion skips the equal band: n >= 2 equal items take 2n scalar
+checks and zero swaps, versus n(n-1)/2 checks with this Lomuto variant. Both may
+be unstable and take quadratic worst-case time. The recursion stack can reach
+O(n); stored history has a separate O(n³) memory upper bound. This adds no new
+package exports and does not require a package release.
+
+### Performance checks
+
+Run `npm run benchmark` for 2,000-element insertion, bubble, merge and both quick-sort
+variants. It reports generation of 1,000 steps, median rendering CPU time over five
+100-frame samples, and retained Node heap after each 5,000 playback steps (up to
+25,000). Drawing uses a mock Canvas: these are CPU comparisons, not browser FPS or
+GPU measurements. Heap samples use explicit GC and include the Node process; they
+are diagnostics, not portable pass/fail thresholds. Generator playback and scene
+projection retain adjacent endpoints, but snapshot size still grows with input size.
+Array rendering expects immutable snapshots, as produced by the array workspace.

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/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";