@grundyjs/algiviz 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.6.0 — 2026-10-14
+
+- Add an application-owned graph BFS example with custom vertices, edges and queue
+  entries, shortest distances, disconnected components and both playback modes.
+- Add createStepEmitter to /playback for per-iterator step numbering and frozen
+  wrappers; snapshot copying and state/event immutability remain author-owned.
+- Use the helper in graph and merge examples, and document custom graph integration.
+
+## 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

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.6.0.
+
+## 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
 
@@ -109,9 +123,31 @@ 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.
 
+### Step emission helper (since 0.6.0)
+
+Version 0.6.0 adds `createStepEmitter` from `/playback`. It removes manual step numbering and freezes the step wrapper:
+
+```js
+import { createStepEmitter } from '@grundyjs/algiviz/playback';
+
+function* counter() {
+    let count = 0;
+    const emit = createStepEmitter(() => Object.freeze({ count }));
+    yield emit('start');
+    count++;
+    yield emit('done');
+}
+```
+
+Create the emitter inside each iterator. Its callback runs once per emission;
+indices start at zero and failed captures do not consume an index. The helper
+does not clone or freeze state/event data, infer terminal events or store history.
+The callback must produce isolated immutable snapshots; immutable shared structures
+can be reused. Returning a mutable workspace directly does not make it a snapshot.
+
 ### 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,30 +216,9 @@ 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
+### State-to-scene projection
+
+`createSceneProjector` adapts
 playback frames from your state model to scenes without changing the algorithm:
 
 ```js
@@ -227,309 +242,201 @@ 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
+## Playback and rendering
 
-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).
+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.
 
-| Previous API | Application-owned API |
+| API | Behavior |
 | --- | --- |
-| `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.
-
-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
-npm pack
-```
-
-Build output includes ESM and TypeScript declarations. `npm pack` rebuilds automatically; `npm publish` runs the tests before packing. The archive includes only dist, README, LICENSE, CHANGELOG and package metadata. Licensed under MIT.
-
-```js
-import { insertionSortSteps } from "@grundyjs/algiviz/core";
-
-const steps = insertionSortSteps([5, 2, 4, 2, 1]);
-console.log(steps.at(-1).state.slots.map(item => item.value));
-// [1, 2, 2, 4, 5]
-```
-
-Each step contains a typed event and the complete state **after** it. `start` preserves the input; `done` has no held item and a fully sorted array. Original-index ids (`item-0`, etc.) distinguish equal values and are deterministic within one trace. The input is never modified. Invalid values, including NaN, Infinity and sparse holes, throw TypeError.
-
-`select` moves the key into `held` and leaves one null slot. `compare` compares the neighbor with the key. `shift` moves the neighbor into the hole. `insert` puts the key back. All original items occur exactly once across `slots` and `held` in every snapshot. Equal values are never shifted past each other.
-
-`sortedPrefixLength` counts the leading occupied slots known to be sorted: initially min(1, n), during insertion it ends at the hole, after insertion it extends through the processed region. `comparisons` counts compare events. `writes` counts shift and insert events, including reinserting an unchanged key; extracting a key and clearing the hole are visualization bookkeeping, not counted writes.
-
-The result, steps, events, snapshots, slot arrays and items are frozen at runtime. Items may be shared between snapshots because they are immutable.
-
-The underlying sort uses O(n²) comparisons in the worst case and O(n) on already sorted input. This API stores full history, so its worst-case time and memory are O(n³), unlike ordinary in-place insertion sort. Intended for small educational inputs; the demo site limits inputs to 24 items. This core imposes no UI limit.
-
-Tests replay every event independently, check item conservation, stability, prefix ordering, counters, frozen snapshots and 1,093 exhaustive inputs with values -1, 0 and 1 of lengths 0–6.
-
-## 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.
-
-```js
-import { iterateInsertionSortSteps } from "@grundyjs/algiviz/core";
-
-const iterator = iterateInsertionSortSteps([5, 2, 4, 2, 1]);
-const start = iterator.next().value;
-const selected = iterator.next().value;
-iterator.return(); // Stop early when no more steps are needed.
-```
-
-Creating the generator does not read the input or run the algorithm. The first
-`next()` copies and validates the input; invalid values throw at that point.
-Changes to the input before the first `next()` are observed; later changes do not
-affect the iterator. Each subsequent `next()` runs only to the next step. An
-iterator is single-use; create a new one to restart. A `for...of` loop can also
-consume it, and `break` closes it early.
-
-When the consumer retains only a fixed number of snapshots, memory is O(n).
-Every snapshot still copies n slots, so consuming the complete worst-case trace
-still takes O(n³) time. Collecting the iterator into an array restores the full
-history memory cost. Iteration is synchronous; a long loop can block the UI.
-
-The existing `createSortTimeline` still requires an array of steps for seeking.
-It does not accept this iterator directly. Use `createSortPlayer` for forward-only
-playback; the generator itself provides no timing or backward seeking.
-
-## Sequential playback
-
-`createSortPlayer` consumes an iterable of steps and retains only the two adjacent
-snapshots needed for rendering. With the lazy generator, playback uses O(n)
-memory as long as the caller does not retain old frames.
+| `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 |
+| [Graph BFS](examples/graph.html) | Cycles, disconnected components, shortest distances and an animated queue |
+| [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.
+
+### Graph breadth-first search
+
+Open [examples/graph.html](examples/graph.html) and choose a start vertex.
+The example explores only its connected component, marks vertices when enqueued
+and shows shortest unweighted distances. Its custom vertex, connection and queue
+entry types are projected from immutable algorithm state. Both playback modes use
+the same generator; changing the start creates a new traversal.
+
+See [Building a custom graph example](docs/custom-graph-example.md) for the
+algorithm, projection and renderer boundaries. This example uses the existing
+public APIs and adds no graph-specific package exports.
 
-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
+```
 
-## Release
+`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.
 
-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/).
+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.
 
-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.
-
-
-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.
+`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. 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.
+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
+
+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.6.0`, at the tested commit.
+
+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/playback/index.d.ts

@@ -2,3 +2,4 @@ export { createPlayer } from "./player.js";
 export type { Player } from "./player.js";
 export { createTimeline } from "./timeline.js";
 export type { Step, Frame, Timeline } from "./types.js";
+export { createStepEmitter } from "./step-emitter.js";

package/dist/playback/index.js

@@ -1,2 +1,3 @@
 export { createPlayer } from "./player.js";
 export { createTimeline } from "./timeline.js";
+export { createStepEmitter } from "./step-emitter.js";

package/dist/playback/step-emitter.d.ts

@@ -0,0 +1,6 @@
+import type { Step } from "./types.js";
+/**
+ * Capture state in a frozen, consecutively indexed step. Use one emitter per iterator.
+ * The callback owns snapshot isolation; state and event are not cloned or frozen.
+ */
+export declare function createStepEmitter<State>(snapshot: () => State): <Event>(event: Event) => Step<State, Event>;

package/dist/playback/step-emitter.js

@@ -0,0 +1,13 @@
+/**
+ * Capture state in a frozen, consecutively indexed step. Use one emitter per iterator.
+ * The callback owns snapshot isolation; state and event are not cloned or frozen.
+ */
+export function createStepEmitter(snapshot) {
+    let index = 0;
+    return (event) => {
+        const state = snapshot();
+        const step = Object.freeze({ index, state, event });
+        index++;
+        return step;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grundyjs/algiviz",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Deterministic algorithm steps for educational visualizations",
   "type": "module",
   "files": [