@grundyjs/algiviz 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # 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.

package/README.md

@@ -183,7 +183,49 @@ 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.
+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
 
@@ -229,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
@@ -448,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/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.0",
   "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",