@grundyjs/algiviz 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,34 @@
 # Changelog
 
-## 0.1.0 — unreleased
+## 0.3.0 — 2026-10-09
+
+- Extend `SortEvent` with `swap` and `pass`, and `SortSnapshot` with optional
+  `sortedSuffixLength`. Consumers with exhaustive event switches must handle
+  the new event types. Existing insertion-sort traces remain unchanged.
+
+- Share input validation, item identities, immutable snapshots and operation
+  counters between sorting algorithms; document adding an algorithm internally.
+
+- Add stable bubble sort with `bubbleSortSteps` and `iterateBubbleSortSteps`,
+  adjacent swaps, sorted suffix tracking and early exit after a pass without swaps.
+- Render both swapped items and the sorted suffix; select either algorithm in
+  the demo with history or generator playback.
+
+## 0.2.0 — 2026-10-09
+
+- Move the held key horizontally along the baseline without lifting it above the array;
+  remove the redundant key label while retaining its color highlight.
+
+- Expand the demo with history/generator playback, array input, generation and speed
+  controls; hide individual bar labels on dense charts.
+
+- Add `createSortPlayer` for forward-only playback with bounded snapshot storage,
+  interpolated canvas-compatible frames, final hold and iterator cleanup.
+
+- Add `iterateInsertionSortSteps` for lazy immutable snapshots without retaining history.
+- Keep `insertionSortSteps` compatible by collecting the shared generator implementation.
+
+## 0.1.0
 
 - Stable, immutable insertion sort traces with item identities and operation counters.
 - A seekable timeline with interpolated frames and final hold.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Grundy
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Grundy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # AlgiViz
 
-A TypeScript library for educational algorithm visualization: stable insertion 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 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.
 
 ## Install
 
@@ -8,7 +8,7 @@ A TypeScript library for educational algorithm visualization: stable insertion s
 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.1 is an initial API and may change in later minor releases.
+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
 
@@ -42,6 +42,116 @@ The underlying sort uses O(n²) comparisons in the worst case and O(n) on alread
 
 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.
+
+```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;
+let last;
+let requestId;
+function tick(now) {
+    const delta = last === undefined ? 0 : 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();
+```
+
+- 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`.
@@ -57,17 +167,93 @@ const renderer = createSortRenderer({ theme: "dark" });
 renderer.render(canvas.getContext("2d"), timeline.sample(3250));
 ```
 
-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.
+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.
+
+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.
+
 
 ## API at a glance
 
 - `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.
 
 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.
+
+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.
+
 ## 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.
-
+
+### 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 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/).
+
+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.
+

package/dist/canvas/index.js

@@ -49,20 +49,20 @@ export function createSortRenderer(options) {
                 for (const [id, next] of after) {
                     const old = before.get(id) ?? next;
                     const x = margin + ((old.index + (next.index - old.index) * p) + 0.5) * cell;
-                    const lift = ((old.held ? 1 : 0) + ((next.held ? 1 : 0) - (old.held ? 1 : 0)) * p) * height * 0.13;
                     const size = Math.max(4, Math.abs(next.item.value) / maxMagnitude * available);
-                    const active = event.type === "compare" ? id === event.leftId || id === event.rightId :
+                    const active = event.type === "compare" || event.type === "swap" ? id === event.leftId || id === event.rightId :
                         "itemId" in event && event.itemId === id;
                     ctx.fillStyle = next.held ? colors.held : active ? colors.active :
-                        next.index < frame.current.sortedPrefixLength ? colors.sorted : colors.bar;
-                    ctx.fillRect(x - barWidth / 2, baseline - size - lift, barWidth, size);
+                        next.index < frame.current.sortedPrefixLength ||
+                            next.index >= count - (frame.current.sortedSuffixLength ?? 0) ? colors.sorted : colors.bar;
+                    ctx.fillRect(x - barWidth / 2, baseline - size, barWidth, size);
+                    if (cell < 24)
+                        continue;
                     ctx.fillStyle = colors.text;
                     ctx.font = `${fontSize}px sans-serif`;
                     ctx.textAlign = "center";
-                    ctx.fillText(String(next.item.value), x, baseline - size - lift - fontSize, cell * 0.95);
+                    ctx.fillText(String(next.item.value), x, baseline - size - fontSize, cell * 0.95);
                     ctx.fillText(String(next.index), margin + (next.index + 0.5) * cell, baseline + height * 0.06);
-                    if (next.held)
-                        ctx.fillText("key", x, baseline - lift + fontSize, cell * 0.95);
                 }
                 ctx.textAlign = "left";
                 ctx.font = `${Math.max(11, Math.min(18, width * 0.03))}px sans-serif`;

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

@@ -0,0 +1,5 @@
+import type { SortStep } from "./types.js";
+/** Creates a stable ascending bubble-sort trace without modifying the input. */
+export declare function bubbleSortSteps(values: readonly number[]): readonly SortStep[];
+/** Yields immutable snapshots lazily, retaining no history. */
+export declare function iterateBubbleSortSteps(values: readonly number[]): Generator<SortStep, void, unknown>;

package/dist/core/bubble-sort.js

@@ -0,0 +1,33 @@
+import { createSortTrace } from "./sort-trace.js";
+/** Creates a stable ascending bubble-sort trace without modifying the input. */
+export function bubbleSortSteps(values) {
+    return Object.freeze([...iterateBubbleSortSteps(values)]);
+}
+/** Yields immutable snapshots lazily, retaining no history. */
+export function* iterateBubbleSortSteps(values) {
+    const { state, emit } = createSortTrace(values);
+    const { slots } = state;
+    state.sortedSuffixLength = slots.length < 2 ? slots.length : 0;
+    yield emit({ type: "start" });
+    for (let end = slots.length - 1; end > 0; end--) {
+        let swapped = false;
+        for (let left = 0; left < end; left++) {
+            const right = left + 1;
+            const a = slots[left];
+            const b = slots[right];
+            yield emit({ type: "compare", leftId: a.id, rightId: b.id });
+            if (a.value <= b.value)
+                continue;
+            slots[left] = b;
+            slots[right] = a;
+            swapped = true;
+            yield emit({ type: "swap", leftId: a.id, rightId: b.id, left, right });
+        }
+        state.sortedSuffixLength = swapped ? slots.length - end : slots.length;
+        yield emit({ type: "pass", end });
+        if (!swapped)
+            break;
+    }
+    state.sortedSuffixLength = slots.length;
+    yield emit({ type: "done" });
+}

package/dist/core/index.d.ts

@@ -1,4 +1,7 @@
-export { insertionSortSteps } from "./insertion-sort.js";
+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,2 +1,4 @@
-export { insertionSortSteps } from "./insertion-sort.js";
+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,3 +1,8 @@
 import type { SortStep } from "./types.js";
 /** Creates a stable ascending insertion-sort trace without modifying the input. */
 export declare function insertionSortSteps(values: readonly number[]): readonly SortStep[];
+/**
+ * Yields immutable snapshots without retaining history.
+ * Input is copied and validated on the first next(), not when creating the iterator.
+ */
+export declare function iterateInsertionSortSteps(values: readonly number[]): Generator<SortStep, void, unknown>;

package/dist/core/insertion-sort.js

@@ -1,59 +1,40 @@
+import { createSortTrace } from "./sort-trace.js";
 /** Creates a stable ascending insertion-sort trace without modifying the input. */
 export function insertionSortSteps(values) {
-    // Array.from also exposes sparse holes as undefined for validation.
-    const input = Array.from(values);
-    for (let i = 0; i < input.length; i++) {
-        if (typeof input[i] !== "number" || !Number.isFinite(input[i])) {
-            throw new TypeError(`Expected a finite number at index ${i}`);
-        }
-    }
-    const slots = input.map((value, index) => Object.freeze({ id: `item-${index}`, value }));
-    const steps = [];
-    let held = null;
-    let sortedPrefixLength = Math.min(1, slots.length);
-    let comparisons = 0;
-    let writes = 0;
-    const emit = (event) => {
-        steps.push(Object.freeze({
-            index: steps.length,
-            event: Object.freeze(event),
-            state: Object.freeze({
-                slots: Object.freeze(slots.slice()),
-                held,
-                sortedPrefixLength,
-                comparisons,
-                writes
-            })
-        }));
-    };
-    emit({ type: "start" });
+    return Object.freeze([...iterateInsertionSortSteps(values)]);
+}
+/**
+ * Yields immutable snapshots without retaining history.
+ * Input is copied and validated on the first next(), not when creating the iterator.
+ */
+export function* iterateInsertionSortSteps(values) {
+    const { state, emit } = createSortTrace(values);
+    const { slots } = state;
+    state.sortedPrefixLength = Math.min(1, slots.length);
+    yield emit({ type: "start" });
     for (let i = 1; i < slots.length; i++) {
         const key = slots[i];
-        held = key;
+        state.held = key;
         slots[i] = null;
-        sortedPrefixLength = i;
-        emit({ type: "select", itemId: key.id, from: i });
+        state.sortedPrefixLength = i;
+        yield emit({ type: "select", itemId: key.id, from: i });
         let hole = i;
         while (hole > 0) {
             const left = slots[hole - 1];
-            comparisons++;
-            emit({ type: "compare", leftId: left.id, rightId: key.id });
+            yield emit({ type: "compare", leftId: left.id, rightId: key.id });
             if (left.value <= key.value)
                 break;
             slots[hole] = left;
             slots[hole - 1] = null;
-            writes++;
-            sortedPrefixLength = hole - 1;
-            emit({ type: "shift", itemId: left.id, from: hole - 1, to: hole });
+            state.sortedPrefixLength = hole - 1;
+            yield emit({ type: "shift", itemId: left.id, from: hole - 1, to: hole });
             hole--;
         }
         slots[hole] = key;
-        held = null;
-        writes++;
-        sortedPrefixLength = i + 1;
-        emit({ type: "insert", itemId: key.id, to: hole });
+        state.held = null;
+        state.sortedPrefixLength = i + 1;
+        yield emit({ type: "insert", itemId: key.id, to: hole });
     }
-    sortedPrefixLength = slots.length;
-    emit({ type: "done" });
-    return Object.freeze(steps);
+    state.sortedPrefixLength = slots.length;
+    yield emit({ type: "done" });
 }

package/dist/core/player.d.ts

@@ -0,0 +1,15 @@
+import type { SortStep } from "./types.js";
+import type { SortFrame } from "./timeline.js";
+export interface SortPlayer {
+    readonly frame: SortFrame;
+    readonly finished: boolean;
+    /** Advance by playback time; pass zero to redraw without consuming steps. */
+    advance(deltaMs: number): SortFrame;
+    /** Close the source early. The last frame remains readable. */
+    dispose(): void;
+}
+/** Forward-only playback. The source must end with a `done` event. */
+export declare function createSortPlayer(steps: Iterable<SortStep>, options: {
+    stepDurationMs: number;
+    finalHoldMs: number;
+}): SortPlayer;

package/dist/core/player.js

@@ -0,0 +1,88 @@
+/** Forward-only playback. The source must end with a `done` event. */
+export function createSortPlayer(steps, options) {
+    const { stepDurationMs, finalHoldMs } = options;
+    if (!Number.isFinite(stepDurationMs) || stepDurationMs <= 0 ||
+        !Number.isFinite(finalHoldMs) || finalHoldMs < 0) {
+        throw new RangeError("Expected positive step duration and non-negative final hold");
+    }
+    const iterator = steps[Symbol.iterator]();
+    let closed = false;
+    const close = () => {
+        if (!closed) {
+            closed = true;
+            iterator.return?.();
+        }
+    };
+    let current;
+    try {
+        const first = iterator.next();
+        if (first.done)
+            throw new RangeError("Player requires at least one step");
+        current = first.value;
+    }
+    catch (error) {
+        close();
+        throw error;
+    }
+    let previous = current;
+    let elapsed = stepDurationMs;
+    let hold = 0;
+    let disposed = false;
+    let finished = false;
+    const complete = () => {
+        if (current.event.type === "done" && elapsed === stepDurationMs) {
+            previous = current;
+            close();
+            finished = hold >= finalHoldMs;
+        }
+    };
+    complete();
+    const frame = () => Object.freeze({
+        previous: previous.state, current: current.state,
+        progress: elapsed / stepDurationMs,
+        stepIndex: current.index, event: current.event
+    });
+    return Object.freeze({
+        get frame() { return frame(); },
+        get finished() { return finished; },
+        advance(deltaMs) {
+            if (disposed)
+                throw new Error("Player has been disposed");
+            if (!Number.isFinite(deltaMs) || deltaMs < 0) {
+                throw new RangeError("Expected finite non-negative playback time");
+            }
+            try {
+                let remaining = deltaMs;
+                while (remaining > 0 && !finished) {
+                    if (elapsed === stepDurationMs) {
+                        if (current.event.type === "done") {
+                            hold += Math.min(remaining, finalHoldMs - hold);
+                            complete();
+                            break;
+                        }
+                        const next = iterator.next();
+                        if (next.done)
+                            throw new RangeError("Step source ended without a done event");
+                        previous = current;
+                        current = next.value;
+                        elapsed = 0;
+                    }
+                    const amount = Math.min(remaining, stepDurationMs - elapsed);
+                    elapsed += amount;
+                    remaining -= amount;
+                    complete();
+                }
+                return frame();
+            }
+            catch (error) {
+                disposed = true;
+                close();
+                throw error;
+            }
+        },
+        dispose() {
+            disposed = true;
+            close();
+        }
+    });
+}

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

@@ -0,0 +1,11 @@
+import type { Item, SortEvent, SortStep } from "./types.js";
+/** Internal mutable workspace; only emit() exposes immutable snapshots. */
+export declare function createSortTrace(values: readonly number[]): {
+    state: {
+        slots: (Item | null)[];
+        held: Item | null;
+        sortedPrefixLength: number;
+        sortedSuffixLength?: number;
+    };
+    emit: (event: SortEvent) => SortStep;
+};

package/dist/core/sort-trace.js

@@ -0,0 +1,34 @@
+/** Internal mutable workspace; only emit() exposes immutable snapshots. */
+export function createSortTrace(values) {
+    // Array.from exposes sparse holes as undefined so they fail validation too.
+    const input = Array.from(values);
+    const slots = input.map((value, index) => {
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+            throw new TypeError(`Expected a finite number at index ${index}`);
+        }
+        return Object.freeze({ id: `item-${index}`, value });
+    });
+    const state = { slots, held: null, sortedPrefixLength: 0 };
+    let index = 0;
+    let comparisons = 0;
+    let writes = 0;
+    function emit(event) {
+        if (event.type === "compare")
+            comparisons++;
+        if (event.type === "shift" || event.type === "insert")
+            writes++;
+        if (event.type === "swap")
+            writes += 2;
+        return Object.freeze({
+            index: index++,
+            event: Object.freeze(event),
+            state: Object.freeze({
+                ...state,
+                slots: Object.freeze(state.slots.slice()),
+                comparisons,
+                writes
+            })
+        });
+    }
+    return { state, emit };
+}

package/dist/core/types.d.ts

@@ -21,6 +21,15 @@ export type SortEvent = Readonly<{
     type: "insert";
     itemId: string;
     to: number;
+} | {
+    type: "swap";
+    leftId: string;
+    rightId: string;
+    left: number;
+    right: number;
+} | {
+    type: "pass";
+    end: number;
 } | {
     type: "done";
 }>;
@@ -29,6 +38,8 @@ export interface SortSnapshot {
     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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grundyjs/algiviz",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Deterministic algorithm steps for educational visualizations",
   "type": "module",
   "files": [
@@ -35,11 +35,12 @@
     "name": "Grundy",
     "url": "https://grundyjs.ru/"
   },
-  "homepage": "https://grundyjs.ru/algorithms/insertion-sort/",
+  "homepage": "https://grundyjs.ru/algiviz/",
   "keywords": [
     "algorithms",
     "visualization",
     "insertion-sort",
+    "bubble-sort",
     "canvas",
     "typescript"
   ],