@grundyjs/algiviz 0.5.1 → 0.6.0

package/CHANGELOG.md

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

package/README.md

@@ -5,7 +5,7 @@ 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.
+This README describes version 0.6.0.
 
 ## Install
 
@@ -123,6 +123,28 @@ 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
 
 Define a type map with your own data, then
@@ -311,6 +333,7 @@ included in the npm archive.
 | [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
@@ -353,6 +376,18 @@ switches between Canvas and SVG without restarting playback.
 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.
+
 ## Development
 
 Requires Node.js 22 or later and npm.
@@ -392,7 +427,7 @@ 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.
+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).

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.1",
+  "version": "0.6.0",
   "description": "Deterministic algorithm steps for educational visualizations",
   "type": "module",
   "files": [