@grundyjs/algiviz 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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;

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
 
@@ -42,6 +42,38 @@ 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
@@ -140,7 +172,8 @@ Build, serve this project root using any static HTTP server, and open examples/i
 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.
-Mode changes restart the loaded array. These limits apply only to the demo.
+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.
 
@@ -148,11 +181,51 @@ 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.
@@ -162,7 +235,7 @@ Run `npm test`, `npm pack --dry-run` and test the resulting tarball in a separat
 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.2.0`).
+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).
 

package/dist/canvas/index.js

@@ -50,10 +50,11 @@ export function createSortRenderer(options) {
                     const old = before.get(id) ?? next;
                     const x = margin + ((old.index + (next.index - old.index) * p) + 0.5) * cell;
                     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;
+                        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;

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

package/dist/core/index.js

@@ -1,3 +1,4 @@
 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.js

@@ -1,3 +1,4 @@
+import { createSortTrace } from "./sort-trace.js";
 /** Creates a stable ascending insertion-sort trace without modifying the input. */
 export function insertionSortSteps(values) {
     return Object.freeze([...iterateInsertionSortSteps(values)]);
@@ -7,59 +8,33 @@ export function insertionSortSteps(values) {
  * Input is copied and validated on the first next(), not when creating the iterator.
  */
 export function* iterateInsertionSortSteps(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 }));
-    let index = 0;
-    let held = null;
-    let sortedPrefixLength = Math.min(1, slots.length);
-    let comparisons = 0;
-    let writes = 0;
-    const emit = (event) => {
-        return Object.freeze({
-            index: index++,
-            event: Object.freeze(event),
-            state: Object.freeze({
-                slots: Object.freeze(slots.slice()),
-                held,
-                sortedPrefixLength,
-                comparisons,
-                writes
-            })
-        });
-    };
+    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;
+        state.sortedPrefixLength = i;
         yield emit({ type: "select", itemId: key.id, from: i });
         let hole = i;
         while (hole > 0) {
             const left = slots[hole - 1];
-            comparisons++;
             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;
+            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;
+        state.held = null;
+        state.sortedPrefixLength = i + 1;
         yield emit({ type: "insert", itemId: key.id, to: hole });
     }
-    sortedPrefixLength = slots.length;
+    state.sortedPrefixLength = slots.length;
     yield emit({ type: "done" });
 }

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.2.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"
   ],