@grundyjs/algiviz 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.4.0 — 2026-10-09
+
+- Verify the packed npm archive in an isolated TypeScript consumer before publishing.
+
+- Add `/scene` with typed user-defined object data and visualization handlers,
+  identity matching, enter/update/exit transitions, layers and reference lookup.
+- Render array bars through the scene dispatcher and expose `arrayScene`.
+- Add an external tree traversal demo defining its own nodes, edges and pointer.
+
+- Add algorithm-free `/array` and `/playback` entry points: user-defined generators,
+  validated array operations, generic states/events and optional rendering callbacks.
+- Add `highlight` events and `createArrayRenderer`; existing rendering names remain available.
+- Move demo algorithms into application-owned examples using only the public API.
+  Old `/core` algorithm exports remain deprecated compatibility adapters.
+- Preserve all original insertion/bubble traces; premature exhaustion now reports
+  a missing terminal step rather than a missing done event.
+
 ## 0.3.0 — 2026-10-09
 
 - Extend `SortEvent` with `swap` and `pass`, and `SortSnapshot` with optional

package/README.md

@@ -1,6 +1,221 @@
 # AlgiViz
 
-A TypeScript library for educational algorithm visualization: stable insertion and bubble sort traces, a seekable timeline and a canvas renderer. No runtime dependencies. The core works without DOM, React or Next.js. ESM only, with TypeScript declarations.
+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.
+
+## 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.
+- `@grundyjs/algiviz/playback`: generic playback of any immutable states and events.
+- `@grundyjs/algiviz/scene`: typed objects and user-provided visualizations.
+- `@grundyjs/algiviz/canvas`: the ready-made array renderer.
+
+You own the loops, conditions and operation order. No library registration or
+changes to AlgiViz are required. For example, reversing an array:
+
+```js
+import { defineArrayAlgorithm, createArrayPlayer, createArrayTimeline } from "@grundyjs/algiviz/array";
+import { createArrayRenderer } from "@grundyjs/algiviz/canvas";
+
+const reverse = defineArrayAlgorithm(function* (array) {
+    yield array.start();
+    for (let i = 0; i < Math.floor(array.length / 2); i++) {
+        yield array.highlight([i, array.length - 1 - i]);
+        yield array.swap(i, array.length - 1 - i);
+    }
+    yield array.done();
+});
+
+const options = { stepDurationMs: 350, finalHoldMs: 1000 };
+const ctx = canvas.getContext("2d");
+const renderer = createArrayRenderer({ theme: "dark" });
+const player = createArrayPlayer(reverse.iterate([1, 2, 3, 4]), {
+    ...options,
+    render: frame => renderer.render(ctx, frame)
+});
+// Your animation loop calls player.advance(deltaMs * speed).
+// No calls while paused; advance(0) redraws after resizing.
+// On teardown: cancel your animation loop and call player.dispose().
+
+// Alternatively, retain history and seek:
+const timeline = createArrayTimeline(reverse.steps([1, 2, 3, 4]), options);
+renderer.render(ctx, timeline.sample(500));
+```
+
+`defineArrayAlgorithm` returns `iterate(values)` and `steps(values)`. Each
+iterator owns a separate workspace and copies/validates input on the first
+`next()`. `steps` collects the iterator into a frozen array. Yield every
+operation immediately, begin with `start`, and end with `done`. Each operation
+updates the workspace and returns an immutable snapshot; it does not draw.
+The player invokes the supplied `render` initially and on every `advance`.
+Rendering errors close the iterator and propagate to the caller.
+
+### Array operations
+
+| Operation | Effect |
+| --- | --- |
+| `at(index)`, `held`, `length` | Read a frozen item, the held item or array length |
+| `start(regions?)` | Emit initial state; call once |
+| `compare(left, right)` | Highlight two positions and count one comparison; either position can be `"held"` |
+| `highlight(positions)` | Highlight items for this step without changing counters |
+| `swap(left, right, regions?)` | Exchange occupied positions; count two writes (non-adjacent swaps are supported) |
+| `select(from, regions?)` | Hold an item and leave a hole; no counted writes |
+| `shift(from, to, regions?)` | Move an item into the hole; count one write |
+| `insert(to, regions?)` | Fill the hole with the held item; count one write |
+| `pass(end, regions?)` | Describe a completed pass without changing items or counters |
+| `done(regions?)` | Finish; requires no held item; does not sort or infer sorted regions |
+
+`regions` can contain `sortedPrefixLength` and `sortedSuffixLength`.
+Omitted markers retain their previous values. The author decides when regions
+are sorted; AlgiViz validates their bounds but does not prove that claim. Positions
+are zero-based; invalid positions, occupied destinations and invalid operation
+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.
+
+### Custom structures and renderers
+
+`/playback` does not know arrays, sorting, Canvas, or event names. A source yields
+`Step<State, Event>` objects with contiguous zero-based `index`, immutable
+`state` and `event`. Supply `isTerminal` to identify the final step and
+`render` to draw each interpolated frame using any rendering technology:
+
+```js
+import { createPlayer, createTimeline } from "@grundyjs/algiviz/playback";
+
+const player = createPlayer(myTraversal(), {
+    stepDurationMs: 300,
+    finalHoldMs: 1000,
+    isTerminal: step => step.event.kind === "finished",
+    render: frame => drawGraph(frame.previous, frame.current, frame.progress, frame.event)
+});
+```
+
+The render callback is optional. Without it, read `player.frame` and render
+manually. `createTimeline(steps, timing)` supports seeking with the same generic
+frame shape; call your renderer with its `sample(timeMs)` result. The generic
+engine does not clone or freeze user states; that is the source's responsibility.
+It retains adjacent snapshots only; the timeline retains the supplied history.
+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.
+
+### User-defined objects and visualizations
+
+The `/scene` API is introduced in 0.4.0. 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.
+
+```ts
+import { createSceneRenderer, type Scene } from "@grundyjs/algiviz/scene";
+
+interface MyObjects {
+    badge: { x: number; y: number; label: string };
+}
+
+const renderer = createSceneRenderer<MyObjects, CanvasRenderingContext2D>({
+    badge(ctx, object) {
+        const from = (object.previous ?? object.current)!.data;
+        const to = (object.current ?? object.previous)!.data;
+        const x = from.x + (to.x - from.x) * object.progress;
+        const y = from.y + (to.y - from.y) * object.progress;
+        ctx.save();
+        try {
+            ctx.globalAlpha = object.presence;
+            ctx.fillText(to.label, x, y);
+        } finally { ctx.restore(); }
+    }
+});
+
+const before: Scene<MyObjects> = {
+    objects: [{ id: "first", type: "badge", data: { x: 20, y: 30, label: "A" } }]
+};
+const after: Scene<MyObjects> = {
+    objects: [{ id: "first", type: "badge", data: { x: 120, y: 30, label: "A" } }]
+};
+// Keep these states immutable. A generic timeline/player can provide this frame.
+renderer.render(ctx, {
+    previous: before, current: after, progress: 0.5, stepIndex: 1, event: "move"
+});
+```
+
+- An object has a non-empty stable `id`, a `type`, user-defined `data` and an
+  optional finite `zIndex` (default zero). IDs are unique within a snapshot. A
+  retained ID cannot change type; use a new ID to replace an object of another type.
+- Handlers receive `previous` and `current` objects, with `null` for a missing
+  endpoint. `phase` is `enter`, `update` or `exit`. `progress` is the raw 0–1 frame
+  progress. `presence` is progress on entry, 1 on update and 1−progress on exit;
+  handlers may use it for opacity or scale. It is not applied automatically.
+- Lower `zIndex` draws first. Ties follow the current snapshot's object order;
+  removed objects follow in their previous order. The current layer wins when it
+  changes. There is no implicit layout or coordinate system.
+- The third handler argument exposes `scene.get(id)` for links, pointers and other
+  references. It returns the referenced object's full transition, including both
+  endpoints; missing references return `undefined`. The application decides how to
+  handle them and how to interpolate positions or changing targets.
+- `createSceneFrame(frame)` exposes the same resolved transitions without drawing.
+  The registry is captured at renderer construction. Missing handlers, duplicate
+  IDs, invalid progress/layers and changed types fail before any handler is called.
+- Scene processing is stateless, so arbitrary seeking is supported. Handlers may
+  see zero-presence objects. They are frame draws, **not guaranteed lifecycle
+  callbacks**: skipping steps can skip appearances/exits entirely. Clear Canvas
+  each frame; a retained SVG/DOM backend must reconcile its elements against the
+  current frame, removing stale IDs itself. Save/restore Canvas state inside each
+  handler. Exceptions propagate; there is no rollback of drawing already performed.
+- Snapshots and user data are not cloned or deep-frozen. The author owns their
+  immutability, as with generic playback. Scene indexing uses O(n) additional
+  memory and layer ordering O(n log n) time per frame.
+
+`arrayScene(snapshot)` from `/canvas` adapts an array to a `Scene<ArrayObjects>`
+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
 
@@ -189,53 +404,29 @@ catch-up work to keep controls responsive.
 
 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.
 
-## Adding an algorithm to this repository
-
-Implement a generator in `src/core/` using the internal `createSortTrace` helper
-from `./sort-trace.js`. Call it **inside** the generator body to preserve lazy
-validation. It provides a mutable `state` workspace and `emit(event)`; emitting
-copies and freezes the snapshot, assigns its step index, and updates counters.
-It retains no history. The helper is internal, not a public package export.
-
-The algorithm owns its loop, array changes and sorted-region markers. Always
-change the workspace before yielding the event that describes that change:
-
-```ts
-// Inside a generator, after checking that adjacent items need exchanging:
-const a = state.slots[left]!;
-const b = state.slots[right]!;
-state.slots[left] = b;
-state.slots[right] = a;
-yield emit({ type: "swap", leftId: a.id, rightId: b.id, left, right });
-```
-
-Yield `start` before sorting and `done` after updating the final sorted region.
-Do not increment counters manually: `compare` adds one comparison, `shift` and
-`insert` add one write, and `swap` adds two writes. Reuse the frozen items created
-by the helper and preserve each item's identity across moves.
-
-Add a history wrapper with `Object.freeze([...iterateYourSortSteps(values)])`,
-export both functions from `src/core/index.ts`, and register the algorithm in
-`examples/demo.mjs` plus its select option in `examples/index.html`. The timeline
-and sequential player need no algorithm-specific changes. A new operation also
-requires updating `SortEvent`, its counter semantics and canvas highlighting or
-movement; existing operations can reuse the renderer.
+## Adding an algorithm
 
-Use the bubble-sort tests as a guide: independently replay events, verify stable
-ordering and item conservation, check frozen snapshots and lazy validation, and
-compare sequential frames with the timeline. This helper reduces snapshot
-boilerplate; it does not validate that an algorithm's events match its mutations.
+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.
 
 ## Release
 
-Run `npm test`, `npm pack --dry-run` and test the resulting tarball in a separate consumer project. Source and issues: [urffin/algiviz](https://github.com/urffin/algiviz). Publishing is a separate maintainer action.
+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.3.0`).
+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).
 

package/dist/array/index.d.ts

@@ -0,0 +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";

package/dist/array/index.js

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

package/dist/array/trace.d.ts

@@ -0,0 +1,27 @@
+import type { Item, SortStep } from "./types.js";
+export interface SortedRegions {
+    readonly sortedPrefixLength?: number;
+    readonly sortedSuffixLength?: number;
+}
+export interface ArrayTrace {
+    readonly length: number;
+    readonly held: Item | null;
+    at(index: number): Item | null;
+    start(regions?: SortedRegions): SortStep;
+    compare(left: number | "held", right: number | "held"): SortStep;
+    highlight(positions: readonly (number | "held")[]): SortStep;
+    swap(left: number, right: number, regions?: SortedRegions): SortStep;
+    select(from: number, regions?: SortedRegions): SortStep;
+    shift(from: number, to: number, regions?: SortedRegions): SortStep;
+    insert(to: number, regions?: SortedRegions): SortStep;
+    pass(end: number, regions?: SortedRegions): SortStep;
+    done(regions?: SortedRegions): SortStep;
+}
+/** Operations own mutations, counters and immutable snapshots, but no algorithm. */
+export declare function createArrayTrace(values: readonly number[]): ArrayTrace;
+export interface ArrayAlgorithm {
+    iterate(values: readonly number[]): Generator<SortStep, void, unknown>;
+    steps(values: readonly number[]): readonly SortStep[];
+}
+/** Each iterator owns its workspace; input is read on its first next(). */
+export declare function defineArrayAlgorithm(algorithm: (array: ArrayTrace) => Generator<SortStep, void, unknown>): ArrayAlgorithm;

package/dist/array/trace.js

@@ -0,0 +1,119 @@
+import { createSortTrace } from "./snapshot-builder.js";
+/** Operations own mutations, counters and immutable snapshots, but no algorithm. */
+export function createArrayTrace(values) {
+    const { state, emit } = createSortTrace(values);
+    const { slots } = state;
+    let phase = "new";
+    function index(value) {
+        if (!Number.isInteger(value) || value < 0 || value >= slots.length)
+            throw new RangeError(`Invalid array index: ${value}`);
+    }
+    function active() {
+        if (phase !== "running")
+            throw new Error("Call start before operations; no operations are allowed after done");
+    }
+    function item(position) {
+        if (position !== "held")
+            index(position);
+        const value = position === "held" ? state.held : slots[position];
+        if (!value)
+            throw new Error(`No item at ${position}`);
+        return value;
+    }
+    function regions(update = {}) {
+        for (const value of [update.sortedPrefixLength, update.sortedSuffixLength]) {
+            if (value !== undefined && (!Number.isInteger(value) || value < 0 || value > slots.length)) {
+                throw new RangeError("Sorted region length must be between zero and array length");
+            }
+        }
+        if (update.sortedPrefixLength !== undefined)
+            state.sortedPrefixLength = update.sortedPrefixLength;
+        if (update.sortedSuffixLength !== undefined)
+            state.sortedSuffixLength = update.sortedSuffixLength;
+    }
+    return Object.freeze({
+        get length() { return slots.length; },
+        get held() { return state.held; },
+        at(position) { index(position); return slots[position]; },
+        start(update) {
+            if (phase !== "new")
+                throw new Error("Trace has already started");
+            regions(update);
+            phase = "running";
+            return emit({ type: "start" });
+        },
+        compare(left, right) {
+            active();
+            const a = item(left), b = item(right);
+            return emit({ type: "compare", leftId: a.id, rightId: b.id });
+        },
+        highlight(positions) {
+            active();
+            const itemIds = Object.freeze(positions.map(position => item(position).id));
+            return emit({ type: "highlight", itemIds });
+        },
+        swap(left, right, update) {
+            active();
+            const a = item(left), b = item(right);
+            if (left === right)
+                throw new RangeError("Swap requires distinct positions");
+            regions(update);
+            slots[left] = b;
+            slots[right] = a;
+            return emit({ type: "swap", leftId: a.id, rightId: b.id, left, right });
+        },
+        select(from, update) {
+            active();
+            if (state.held)
+                throw new Error("An item is already held");
+            const selected = item(from);
+            regions(update);
+            state.held = selected;
+            slots[from] = null;
+            return emit({ type: "select", itemId: selected.id, from });
+        },
+        shift(from, to, update) {
+            active();
+            const moved = item(from);
+            index(to);
+            if (slots[to] !== null)
+                throw new Error("Shift destination must be empty");
+            regions(update);
+            slots[to] = moved;
+            slots[from] = null;
+            return emit({ type: "shift", itemId: moved.id, from, to });
+        },
+        insert(to, update) {
+            active();
+            const inserted = item("held");
+            index(to);
+            if (slots[to] !== null)
+                throw new Error("Insert destination must be empty");
+            regions(update);
+            slots[to] = inserted;
+            state.held = null;
+            return emit({ type: "insert", itemId: inserted.id, to });
+        },
+        pass(end, update) {
+            active();
+            index(end);
+            regions(update);
+            return emit({ type: "pass", end });
+        },
+        done(update) {
+            active();
+            if (state.held)
+                throw new Error("Insert the held item before completing the trace");
+            regions(update);
+            phase = "done";
+            return emit({ type: "done" });
+        }
+    });
+}
+/** Each iterator owns its workspace; input is read on its first next(). */
+export function defineArrayAlgorithm(algorithm) {
+    function* iterate(values) {
+        yield* algorithm(createArrayTrace(values));
+    }
+    return Object.freeze({ iterate, steps: (values) => Object.freeze([...iterate(values)]) });
+}

package/dist/array/types.d.ts

@@ -0,0 +1,55 @@
+export type Item = Readonly<{
+    id: string;
+    value: number;
+}>;
+export type SortEvent = Readonly<{
+    type: "start";
+} | {
+    type: "select";
+    itemId: string;
+    from: number;
+} | {
+    type: "compare";
+    leftId: string;
+    rightId: string;
+} | {
+    type: "shift";
+    itemId: string;
+    from: number;
+    to: number;
+} | {
+    type: "insert";
+    itemId: string;
+    to: number;
+} | {
+    type: "swap";
+    leftId: string;
+    rightId: string;
+    left: number;
+    right: number;
+} | {
+    type: "pass";
+    end: number;
+} | {
+    type: "highlight";
+    itemIds: readonly string[];
+} | {
+    type: "done";
+}>;
+export interface SortSnapshot {
+    readonly slots: readonly (Item | null)[];
+    readonly held: Item | null;
+    /** Sorted leading occupied slots; during insertion it ends at the hole. */
+    readonly sortedPrefixLength: number;
+    /** Final sorted trailing slots. Omitted by older traces and insertion sort. */
+    readonly sortedSuffixLength?: number;
+    readonly comparisons: number;
+    /** Writes into array slots; selecting a key does not count as a write. */
+    readonly writes: number;
+}
+export interface SortStep {
+    readonly index: number;
+    readonly event: SortEvent;
+    /** Complete immutable state immediately after the event. */
+    readonly state: SortSnapshot;
+}

package/dist/array/types.js

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

package/dist/canvas/index.d.ts

@@ -1,4 +1,16 @@
+import type { Item, SortSnapshot } from "../core/types.js";
 import type { SortFrame } from "../core/timeline.js";
+import { type Scene } from "../scene/index.js";
+export type ArrayObjects = {
+    bar: {
+        item: Item;
+        index: number;
+        held: boolean;
+    };
+};
+/** Adapts array identities to the same public scene contract used by custom objects. */
+export declare function arrayScene(state: SortSnapshot): Scene<ArrayObjects>;
+export { createSortRenderer as createArrayRenderer };
 /** Stateless full-frame renderer. Bitmap dimensions determine layout and video size. */
 export declare function createSortRenderer(options: {
     theme: "light" | "dark";