@grundyjs/algiviz 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.7.0 — 2026-10-15
+
+- Breaking: remove the deprecated /core entry point and bundled insertion/bubble
+  algorithms. Application-owned examples use /array; playback adapters now live there.
+
+- Preserve source step indices in generic timeline frames, matching generator playback.
+- Preserve primary playback errors when iterator cleanup also fails; standalone
+  cleanup failures still propagate.
+
+## 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,15 @@ 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.7.0.
+
+## Minimal custom object
+
+Start with [the standalone example](examples/minimal.html) and its
+[complete module](examples/minimal.mjs). It defines a custom token, emits immutable
+steps and draws interpolated positions using only public package imports.
+No shared demo controller is needed. See [the walkthrough](docs/minimal-example.md)
+for running it in your own application.
 
 ## Install
 
@@ -16,7 +24,7 @@ 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.
+Algorithms live in application code and examples.
 For new integrations, use the APIs below. Version 0.x may introduce breaking changes
 in minor releases; consult [CHANGELOG.md](CHANGELOG.md) when updating.
 
@@ -123,6 +131,42 @@ 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.
 
+### Playback contracts
+
+Playback retains application snapshots without cloning them; keep steps, state and
+events immutable while they are in use. A timeline copies the input array only.
+Timeline timing follows array position, and finite sample times are clamped to its
+range. Generator playback requires an explicit terminal step; an early end throws.
+`dispose()` closes the source at most once, keeps the last frame readable and
+prevents further advancement. Restart uses a fresh source.
+
+Version 0.7.0 makes timeline `stepIndex` preserve the source `step.index`,
+matching the player. If source consumption, a terminal predicate or rendering
+throws, cleanup is attempted without replacing that primary error. A standalone
+cleanup error from disposal or normal completion still propagates.
+
+### 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 +355,8 @@ 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 |
+| [Heap sort](examples/heap.html) | Max-heap construction and extraction with synchronized tree and array identities |
+| [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
@@ -344,6 +390,18 @@ 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.
 
+### Heap sort
+
+The [algorithm](examples/heap-algorithm.mjs) owns immutable states and events.
+The [scene](examples/heap-scene.mjs) assigns separate tree/array visual IDs to each
+element and uses the public scene projector with viewport-independent endpoints.
+Tree positions stay fixed as the heap shrinks. At most 15 array cells wrap on narrow
+screens; larger arrays use a dense row and hide unreadable labels.
+Bottom-up construction is O(n), worst-case sorting O(n log n), and the iterative
+in-place algorithm uses O(1) auxiliary space. This demo copies input and retains
+O(n) adjacent snapshot data in generator mode; full history can use O(n² log n).
+It is not stable: [2a, 2b, 1] becomes [1, 2b, 2a].
+
 ### Tree traversal
 
 The example defines its own `node`, `edge` and `pointer` types. The pointer follows
@@ -353,6 +411,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.
@@ -366,7 +436,7 @@ 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.
+including rejection of the removed `/core` export. 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.
@@ -392,7 +462,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.7.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/array/index.d.ts

@@ -1,7 +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";
+export { createArrayPlayer } from "./player.js";
+export { createArrayTimeline } from "./timeline.js";
+export type { ArrayPlayer } from "./player.js";
+export type { ArrayFrame, ArrayTimeline } from "./timeline.js";

package/dist/array/index.js

@@ -1,3 +1,3 @@
 export { createArrayTrace, defineArrayAlgorithm } from "./trace.js";
-export { createSortPlayer as createArrayPlayer } from "../core/player.js";
-export { createSortTimeline as createArrayTimeline } from "../core/timeline.js";
+export { createArrayPlayer } from "./player.js";
+export { createArrayTimeline } from "./timeline.js";

package/dist/array/player.d.ts

@@ -0,0 +1,10 @@
+import { type Player } from "../playback/index.js";
+import type { SortStep, SortSnapshot, SortEvent } from "./types.js";
+import type { ArrayFrame } from "./timeline.js";
+export type ArrayPlayer = Player<SortSnapshot, SortEvent>;
+/** Array playback adapter for array steps ending in done. */
+export declare function createArrayPlayer(steps: Iterable<SortStep>, options: {
+    stepDurationMs: number;
+    finalHoldMs: number;
+    render?: (frame: ArrayFrame) => void;
+}): ArrayPlayer;

package/dist/{core → array}/player.js

@@ -1,5 +1,5 @@
 import { createPlayer } from "../playback/index.js";
-/** Compatibility adapter for array steps ending in done. */
-export function createSortPlayer(steps, options) {
+/** Array playback adapter for array steps ending in done. */
+export function createArrayPlayer(steps, options) {
     return createPlayer(steps, { ...options, isTerminal: step => step.event.type === "done" });
 }

package/dist/array/timeline.d.ts

@@ -0,0 +1,8 @@
+import { type Frame, type Timeline } from "../playback/index.js";
+import type { SortEvent, SortSnapshot, SortStep } from "./types.js";
+export type ArrayFrame = Frame<SortSnapshot, SortEvent>;
+export type ArrayTimeline = Timeline<SortSnapshot, SortEvent>;
+export declare function createArrayTimeline(steps: readonly SortStep[], options: {
+    stepDurationMs: number;
+    finalHoldMs: number;
+}): ArrayTimeline;

package/dist/{core → array}/timeline.js

@@ -1,4 +1,4 @@
 import { createTimeline } from "../playback/index.js";
-export function createSortTimeline(steps, options) {
+export function createArrayTimeline(steps, options) {
     return createTimeline(steps, options);
 }

package/dist/canvas/index.d.ts

@@ -1,5 +1,5 @@
-import type { Item, SortSnapshot } from "../core/types.js";
-import type { SortFrame } from "../core/timeline.js";
+import type { Item, SortSnapshot } from "../array/types.js";
+import type { ArrayFrame as SortFrame } from "../array/timeline.js";
 import { type Scene } from "../scene/index.js";
 export type ArrayObjects = {
     bar: {

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/player.js

@@ -13,6 +13,13 @@ export function createPlayer(steps, options) {
             iterator.return?.();
         }
     };
+    // A cleanup failure must not replace the source, predicate or render error.
+    const closeAfterFailure = () => {
+        try {
+            close();
+        }
+        catch { /* Preserve the error already being handled. */ }
+    };
     let current;
     try {
         const first = iterator.next();
@@ -21,7 +28,7 @@ export function createPlayer(steps, options) {
         current = first.value;
     }
     catch (error) {
-        close();
+        closeAfterFailure();
         throw error;
     }
     let previous = current;
@@ -46,7 +53,7 @@ export function createPlayer(steps, options) {
         options.render?.(frame());
     }
     catch (error) {
-        close();
+        closeAfterFailure();
         throw error;
     }
     return Object.freeze({
@@ -85,7 +92,7 @@ export function createPlayer(steps, options) {
             }
             catch (error) {
                 disposed = true;
-                close();
+                closeAfterFailure();
                 throw error;
             }
         },

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/dist/playback/timeline.d.ts

@@ -1,5 +1,5 @@
 import type { Step, Timeline } from "./types.js";
-/** Step i is complete at i * stepDurationMs; the final state is held afterwards. */
+/** The step at array position i is complete at i * stepDurationMs; the final state is held afterwards. */
 export declare function createTimeline<S, E>(steps: readonly Step<S, E>[], options: {
     stepDurationMs: number;
     finalHoldMs: number;

package/dist/playback/timeline.js

@@ -1,4 +1,4 @@
-/** Step i is complete at i * stepDurationMs; the final state is held afterwards. */
+/** The step at array position i is complete at i * stepDurationMs; the final state is held afterwards. */
 export function createTimeline(steps, options) {
     if (!steps.length)
         throw new RangeError("Timeline requires at least one step");
@@ -24,7 +24,7 @@ export function createTimeline(steps, options) {
             const progress = previous === step ? 1 :
                 Math.min(1, (time - (index - 1) * stepDurationMs) / stepDurationMs);
             return Object.freeze({ previous: previous.state, current: step.state,
-                progress, stepIndex: index, event: step.event });
+                progress, stepIndex: step.index, event: step.event });
         }
     });
 }

package/dist/playback/types.d.ts

@@ -8,6 +8,7 @@ export interface Frame<S, E> {
     readonly previous: S;
     readonly current: S;
     readonly progress: number;
+    /** Source step.index; timing is based on sequence position, not this value. */
     readonly stepIndex: number;
     readonly event: E;
 }

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@grundyjs/algiviz",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Deterministic algorithm steps for educational visualizations",
   "type": "module",
   "files": [
-    "dist",
+    "dist/array",
+    "dist/playback",
+    "dist/scene",
+    "dist/canvas",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -25,11 +28,6 @@
       "import": "./dist/playback/index.js",
       "default": "./dist/playback/index.js"
     },
-    "./core": {
-      "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.js",
-      "default": "./dist/core/index.js"
-    },
     "./canvas": {
       "types": "./dist/canvas/index.d.ts",
       "import": "./dist/canvas/index.js",

package/dist/compat/algorithms.d.ts

@@ -1,2 +0,0 @@
-export declare const insertion: import("../array/trace.js").ArrayAlgorithm;
-export declare const bubble: import("../array/trace.js").ArrayAlgorithm;

package/dist/compat/algorithms.js

@@ -1,36 +0,0 @@
-import { defineArrayAlgorithm } from "../array/trace.js";
-// Legacy core exports only. New consumers provide algorithms like examples/algorithms.mjs.
-export const insertion = defineArrayAlgorithm(function* (array) {
-    yield array.start({ sortedPrefixLength: Math.min(1, array.length) });
-    for (let i = 1; i < array.length; i++) {
-        const key = array.at(i);
-        yield array.select(i, { sortedPrefixLength: i });
-        let hole = i;
-        while (hole > 0) {
-            yield array.compare(hole - 1, 'held');
-            if (array.at(hole - 1).value <= key.value)
-                break;
-            yield array.shift(hole - 1, hole, { sortedPrefixLength: hole - 1 });
-            hole--;
-        }
-        yield array.insert(hole, { sortedPrefixLength: i + 1 });
-    }
-    yield array.done({ sortedPrefixLength: array.length });
-});
-export const bubble = defineArrayAlgorithm(function* (array) {
-    yield array.start({ sortedSuffixLength: array.length < 2 ? array.length : 0 });
-    for (let end = array.length - 1; end > 0; end--) {
-        let swapped = false;
-        for (let left = 0; left < end; left++) {
-            yield array.compare(left, left + 1);
-            if (array.at(left).value <= array.at(left + 1).value)
-                continue;
-            yield array.swap(left, left + 1);
-            swapped = true;
-        }
-        yield array.pass(end, { sortedSuffixLength: swapped ? array.length - end : array.length });
-        if (!swapped)
-            break;
-    }
-    yield array.done({ sortedSuffixLength: array.length });
-});

package/dist/core/bubble-sort.d.ts

@@ -1,4 +0,0 @@
-/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
-export declare const bubbleSortSteps: (values: readonly number[]) => readonly import("./types.js").SortStep[];
-/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
-export declare const iterateBubbleSortSteps: (values: readonly number[]) => Generator<import("./types.js").SortStep, void, unknown>;

package/dist/core/bubble-sort.js

@@ -1,5 +0,0 @@
-import { bubble } from "../compat/algorithms.js";
-/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
-export const bubbleSortSteps = bubble.steps;
-/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
-export const iterateBubbleSortSteps = bubble.iterate;

package/dist/core/index.d.ts

@@ -1,7 +0,0 @@
-export { insertionSortSteps, iterateInsertionSortSteps } from "./insertion-sort.js";
-export { bubbleSortSteps, iterateBubbleSortSteps } from "./bubble-sort.js";
-export type { Item, SortEvent, SortSnapshot, SortStep } from "./types.js";
-export { createSortTimeline } from "./timeline.js";
-export type { SortFrame, SortTimeline } from "./timeline.js";
-export { createSortPlayer } from "./player.js";
-export type { SortPlayer } from "./player.js";

package/dist/core/index.js

@@ -1,4 +0,0 @@
-export { insertionSortSteps, iterateInsertionSortSteps } from "./insertion-sort.js";
-export { bubbleSortSteps, iterateBubbleSortSteps } from "./bubble-sort.js";
-export { createSortTimeline } from "./timeline.js";
-export { createSortPlayer } from "./player.js";

package/dist/core/insertion-sort.d.ts

@@ -1,4 +0,0 @@
-/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
-export declare const insertionSortSteps: (values: readonly number[]) => readonly import("./types.js").SortStep[];
-/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
-export declare const iterateInsertionSortSteps: (values: readonly number[]) => Generator<import("./types.js").SortStep, void, unknown>;

package/dist/core/insertion-sort.js

@@ -1,5 +0,0 @@
-import { insertion } from "../compat/algorithms.js";
-/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
-export const insertionSortSteps = insertion.steps;
-/** @deprecated Define your algorithm with @grundyjs/algiviz/array. */
-export const iterateInsertionSortSteps = insertion.iterate;

package/dist/core/player.d.ts

@@ -1,10 +0,0 @@
-import { type Player } from "../playback/index.js";
-import type { SortStep, SortSnapshot, SortEvent } from "./types.js";
-import type { SortFrame } from "./timeline.js";
-export type SortPlayer = Player<SortSnapshot, SortEvent>;
-/** Compatibility adapter for array steps ending in done. */
-export declare function createSortPlayer(steps: Iterable<SortStep>, options: {
-    stepDurationMs: number;
-    finalHoldMs: number;
-    render?: (frame: SortFrame) => void;
-}): SortPlayer;

package/dist/core/timeline.d.ts

@@ -1,8 +0,0 @@
-import { type Frame, type Timeline } from "../playback/index.js";
-import type { SortEvent, SortSnapshot, SortStep } from "./types.js";
-export type SortFrame = Frame<SortSnapshot, SortEvent>;
-export type SortTimeline = Timeline<SortSnapshot, SortEvent>;
-export declare function createSortTimeline(steps: readonly SortStep[], options: {
-    stepDurationMs: number;
-    finalHoldMs: number;
-}): SortTimeline;

package/dist/core/types.d.ts

@@ -1 +0,0 @@
-export type { Item, SortEvent, SortSnapshot, SortStep } from "../array/types.js";

package/dist/core/types.js

@@ -1 +0,0 @@
-export {};