@grundyjs/algiviz 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.5.1 — 2026-10-14
+
+- Update the README around the current public API and examples; remove migration
+  instructions and detailed legacy API documentation.
+- Correct demo input limits and clarify playback, snapshot memory and rendering.
+- No runtime API or behavior changes.
+
+## 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.

package/README.md

@@ -1,10 +1,28 @@
 # AlgiViz
 
-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.
+A TypeScript toolkit for user-defined algorithm visualizations. You write the
+algorithm and define your objects; AlgiViz provides array operations, playback,
+typed scene dispatch and a ready-made Canvas array renderer. No runtime dependencies.
+Playback works without DOM, React or Next.js. ESM only, with TypeScript declarations.
+
+This README describes version 0.5.1.
+
+## Install
+
+```sh
+npm install @grundyjs/algiviz
+```
+
+There is no root entry point or CommonJS build. Import the modules you need:
+`/array`, `/playback`, `/scene` and `/canvas`.
+
+The deprecated `/core` sorting API remains available for compatibility.
+For new integrations, use the APIs below. Version 0.x may introduce breaking changes
+in minor releases; consult [CHANGELOG.md](CHANGELOG.md) when updating.
 
 ## 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.
@@ -75,12 +93,8 @@ 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.
+Insertion and bubble sort implementations live in [examples/algorithms.mjs](examples/algorithms.mjs).
+The algorithms belong to the application; they require no changes to the library.
 
 ### Custom structures and renderers
 
@@ -111,7 +125,7 @@ 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
+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.
 
@@ -180,271 +194,214 @@ 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
-
-```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.
+### State-to-scene projection
 
-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
-entire history. It yields the same immutable `SortStep` snapshots as
-`insertionSortSteps`, which collects this iterator into a frozen array.
+`createSceneProjector` adapts
+playback frames from your state model to scenes without changing the algorithm:
 
 ```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.
+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));
 ```
 
-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.
+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.
+
+## Playback and rendering
+
+Array players and timelines use the same frame shape as generic playback:
+`previous`, `current`, `progress`, `stepIndex` and `event`.
+A frame describes the transition into the current step; that step's state is the
+state after its operation.
+
+| API | Behavior |
+| --- | --- |
+| `createArrayPlayer(iterable, options)` | Array playback; recognizes the `done` event |
+| `createPlayer(iterable, options)` | Generic playback; requires `isTerminal(step)` |
+| `createArrayTimeline(steps, timing)` / `createTimeline(steps, timing)` | Retained history with `durationMs` and `sample(timeMs)` |
+| `createArrayRenderer({ theme: "dark" \| "light" })` | Full-frame Canvas array rendering |
+| `createSceneRenderer(handlers)` | Dispatches custom objects to your visualization handlers |
+| `createSceneProjector(project)` | Adapts immutable state endpoints to scenes with a bounded cache |
+
+Players read the first step at construction and expose `frame`, `advance(deltaMs)`,
+`finished` and `dispose()`. The initial frame has progress 1.
+`advance` accepts finite, non-negative elapsed playback time; zero consumes no steps.
+Pause by not advancing. Apply speed by multiplying elapsed time.
+The optional render callback runs initially and on every advance.
+
+The source must reach a terminal step. The player closes the iterator after its
+final transition and becomes finished after `finalHoldMs`. Premature exhaustion,
+source errors and render errors propagate and close the iterator.
+`dispose()` closes early and can be repeated; the frame remains readable, but
+advancing a disposed player throws. Restart with a new iterator and player.
+
+Timelines require an array of steps. Step i completes at `i * stepDurationMs`;
+`finalHoldMs` extends the last frame. Sampling clamps finite times to the timeline
+range and rejects non-finite times. There is no seeking or known total duration
+in generator playback.
+
+Animation scheduling belongs to your application. For example:
 
 ```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;
+const player = createArrayPlayer(reverse.iterate([1, 2, 3, 4]), options);
 let last;
 let requestId;
+let paused = false;
+let speed = 1;
+
 function tick(now) {
-    const delta = last === undefined ? 0 : now - last;
+    const delta = last === undefined ? 0 : Math.min(100, 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();
+// To replay after finishing, create a new player and schedule a new loop.
 ```
 
-- 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.
+This is an alternative to the player setup in the earlier array example, reusing
+its `reverse`, `options`, `ctx` and `renderer`. Large deltas consume intervening steps
+synchronously, so cap elapsed time or pause on hidden tabs to avoid a long catch-up.
 
-```js
-import { createSortTimeline } from "@grundyjs/algiviz/core";
-import { createSortRenderer } from "@grundyjs/algiviz/canvas";
+The array renderer expects immutable snapshots. It uses Canvas bitmap dimensions
+for layout, draws a full frame and restores context state. Negative values use
+magnitude for bar height and retain their sign in labels; this is not a signed-axis
+plot. Dense charts hide labels. For recording, use a canvas with fixed export
+dimensions. Rendering does not start an animation loop or record video.
 
-const timeline = createSortTimeline(steps, { stepDurationMs: 650, finalHoldMs: 2000 });
-const renderer = createSortRenderer({ theme: "dark" });
-renderer.render(canvas.getContext("2d"), timeline.sample(3250));
-```
+### Memory and generation cost
 
-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.
+Array operations copy the input, validate finite numbers and reject sparse inputs.
+`defineArrayAlgorithm` performs this work on the first iterator `next()`;
+`createArrayTrace` validates immediately. Each iterator owns its workspace.
+Array steps, events, snapshots and items are frozen; immutable items can be shared
+between snapshots.
 
-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.
-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.
+Generator playback retains adjacent snapshots, not the entire history. Array
+playback therefore uses O(n) snapshot memory if the caller does not retain old
+frames. Generic states and algorithm-specific storage may have different costs.
+Each full array snapshot still copies n slots: laziness reduces retained history,
+not the cost of producing every step. Collecting steps restores the history cost.
+For example, a quadratic sorting trace with O(n)-sized snapshots can take O(n³)
+time and history space. Iteration is synchronous and can block the UI.
 
+## Browser examples
 
-## API at a glance
+Build the project, serve the repository root with a static HTTP server and open
+one of these pages. Examples are application code in the repository and are not
+included in the npm archive.
 
-- `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.
+| Example | What it demonstrates |
+| --- | --- |
+| [Sorting lab](examples/index.html) | Insertion and bubble sort using the array operations and renderer |
+| [Merge sort](examples/merge.html) | Custom state and a two-row scene for the main array and buffer |
+| [Quick sort partitions](examples/quick.html) | Lomuto and three-way partitioning with custom state and scene |
+| [Tree traversal](examples/tree.html) | Custom nodes, edges and pointer with Canvas and retained SVG backends |
+
+All examples reuse [demo-player.mjs](examples/demo-player.mjs) and
+[player-settings.mjs](examples/player-settings.mjs): 650 ms per step, 1,000 ms final
+hold, speeds 0.25× through 32×, play/pause, restart and step controls.
+History enables backward stepping and seeking; generator mode disables both.
+Reduced motion disables interpolation, and hidden tabs pause playback.
+
+All sorting examples accept up to **64 finite values with history** or **2,000 in
+generator mode**. Enter values or generate an array by count with Random, Sorted or
+Reverse order. These are demo limits, not library restrictions. Switching a large
+array to history requires first loading an array within the history limit.
+Dense charts hide labels; custom sorting examples preview the first 24 cells in
+their text status.
+
+### Merge sort
+
+The [algorithm](examples/merge-algorithm.mjs) and
+[renderer](examples/merge-scene.mjs) use `/playback` and `/scene`.
+Equal values have letter suffixes to demonstrate stability. Cells use row/position
+IDs because copy-back temporarily duplicates item identities. Left wins ties.
+The algorithm uses O(n) auxiliary memory; full snapshot history has an
+O(n² log n) space upper bound.
+
+### Quick sort
+
+Choose Lomuto or three-way partitioning while preserving loaded values.
+Both algorithms and their scene belong to the example. 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. Neither variant guarantees stability.
+Worst-case algorithm time is quadratic; recursion can use O(n) stack space.
+Full snapshot history has a separate O(n³) space upper bound.
+
+### Tree traversal
+
+The example defines its own `node`, `edge` and `pointer` types. The pointer follows
+tree edges through shared ancestors between visited nodes. The Renderer selector
+switches between Canvas and SVG without restarting playback.
+[tree-svg.mjs](examples/tree-svg.mjs) retains elements by ID, restores layer order
+and removes stale elements even after seeking skips exit transitions.
+No tree-specific algorithm or renderer is added to the package.
 
-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.
+## Development
 
-## Adding an algorithm
+Requires Node.js 22 or later and npm.
 
-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.
+```sh
+npm ci
+npm test
+npm run test:package
+```
+
+`npm test` builds the library, checks TypeScript fixtures and runs the tests.
+`npm run test:package` builds a tarball, installs it offline in an isolated temporary
+consumer, compiles against the installed declarations and exercises public APIs,
+including compatibility exports. The temporary consumer is removed afterward.
+
+GitHub Actions runs both checks on pushes to `master` and pull requests, using
+Node.js 22 and 24 on Linux and Windows. CI checks do not publish packages.
+
+`npm pack` rebuilds automatically. The archive includes dist, README, LICENSE,
+CHANGELOG and package metadata. Source and issues:
+[urffin/algiviz](https://github.com/urffin/algiviz). Licensed under MIT.
+
+### 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.
 
 ## Release
 
-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.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).
-
-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/).
+Publishing is a maintainer action. Update the package version, lockfile and changelog;
+run `npm test` and `npm run test:package`, commit and push, and check CI on the
+candidate commit.
+
+The [publish workflow](.github/workflows/npm-publish.yml) runs when a stable GitHub
+Release is published. Drafts, prereleases and tag pushes alone do not publish.
+Use `v` followed by the exact package version, such as `v0.5.1`, at the tested commit.
 
-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.
+The workflow uses Node.js 24 and npm 11, checks the version and packed consumer,
+then publishes with provenance through npm trusted publishing (OIDC).
+The publish lifecycle also runs tests and rebuilds. No `NPM_TOKEN` secret is required.
+
+The npm trusted publisher must match GitHub owner `urffin`, repository `algiviz`
+and workflow `npm-publish.yml`. The workflow does not use a GitHub environment.
+See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
 
+After publication, verify the Actions run and the exact version in npm.
+Never reuse an already published npm version. If a workflow fails, check whether
+publication occurred before deciding whether to rerun it.

package/dist/canvas/index.js

@@ -1,4 +1,4 @@
-import { createSceneRenderer } from "../scene/index.js";
+import { createSceneRenderer, createSceneProjector } from "../scene/index.js";
 /** Adapts array identities to the same public scene contract used by custom objects. */
 export function arrayScene(state) {
     return Object.freeze({
@@ -37,19 +37,20 @@ function positions(state) {
 /** Stateless full-frame renderer. Bitmap dimensions determine layout and video size. */
 export function createSortRenderer(options) {
     const colors = palettes[options.theme];
+    const projectFrame = createSceneProjector(arrayScene);
     return Object.freeze({
         render(ctx, frame) {
             const { width, height } = ctx.canvas;
             if (width <= 0 || height <= 0)
                 return;
-            const after = positions(frame.current);
-            const items = [...after.values()];
+            const projected = projectFrame(frame);
+            const items = projected.current.objects;
             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 maxMagnitude = Math.max(1, ...items.map(({ data }) => Math.abs(data.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;
@@ -99,11 +100,7 @@ export function createSortRenderer(options) {
                         ctx.fillText(String(next.index), margin + (next.index + 0.5) * cell, baseline + height * 0.06);
                     }
                 });
-                sceneRenderer.render(ctx, {
-                    ...frame,
-                    previous: arrayScene(frame.previous),
-                    current: arrayScene(frame.current)
-                });
+                sceneRenderer.render(ctx, projected);
                 ctx.textAlign = "left";
                 ctx.font = `${Math.max(11, Math.min(18, width * 0.03))}px sans-serif`;
                 ctx.fillStyle = colors.text;

package/dist/scene/index.d.ts

@@ -40,3 +40,5 @@ export declare function createSceneFrame<Types extends object, Event>(frame: Fra
 export declare function createSceneRenderer<Types extends object, Context, Event = unknown>(visualizations: SceneVisualizations<Types, Context, Event>): Readonly<{
     render(context: Context, frame: Frame<Scene<Types>, Event>): void;
 }>;
+/** Projects immutable state endpoints, retaining at most two scenes. */
+export declare function createSceneProjector<State, Types extends object>(project: (state: State) => Scene<Types>): <Event>(frame: Frame<State, Event>) => Frame<Scene<Types>, Event>;

package/dist/scene/index.js

@@ -63,3 +63,22 @@ export function createSceneRenderer(visualizations) {
         }
     });
 }
+/** Projects immutable state endpoints, retaining at most two scenes. */
+export function createSceneProjector(project) {
+    let cache = [];
+    return (frame) => {
+        const next = [];
+        function endpoint(state) {
+            const found = [...next, ...cache].find(entry => Object.is(entry.state, state));
+            const entry = found ?? { state, scene: project(state) };
+            if (!next.includes(entry))
+                next.push(entry);
+            return entry.scene;
+        }
+        const previous = endpoint(frame.previous);
+        const current = endpoint(frame.current);
+        // Failed projections do not replace the previously successful cache.
+        cache = next;
+        return Object.freeze({ previous, current, progress: frame.progress, stepIndex: frame.stepIndex, event: frame.event });
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grundyjs/algiviz",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Deterministic algorithm steps for educational visualizations",
   "type": "module",
   "files": [
@@ -38,6 +38,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "benchmark": "npm run build && node --expose-gc scripts/benchmark.mjs",
     "test": "npm run build && tsc -p test/tsconfig.json && node --test test/*.test.mjs",
     "test:package": "node scripts/test-package.mjs",
     "prepack": "npm run build",