@grundyjs/algiviz 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,6 +1,26 @@
 # Changelog
 
-## 0.9.0 � 2026-10-27
+## 0.11.0 — 2026-11-02
+
+- Add createStatePlayer() for lazy playback of plain immutable states without
+  step wrappers, event fields or an isTerminal predicate.
+- Consume one state per request without lookahead. A request after the final
+  state detects exhaustion, preserves the last frame and index, and completes
+  playback or starts an explicitly configured final hold.
+- Support manual and timed playback, infinite sources, disposal and source errors.
+- Simplify the interactive minimal example and English/Russian READMEs; update
+  the highlighted GIF to show the extra completion request.
+
+## 0.10.0 — 2026-10-27
+
+- Default finalHoldMs to zero for generic and array players.
+- Make stepDurationMs optional for manual nextStep playback; advance(0) redraws,
+  while positive timed advancement requires an explicit duration.
+- Allow array players to omit the options object entirely.
+- Simplify the minimal example and both READMEs; refresh the highlighted GIF.
+- Preserve explicit timing behavior and timeline requirements.
+
+## 0.9.0 — 2026-10-27
 
 - Add player.nextStep() for exact manual stepping in generic and array players.
 - Finish an in-progress transition without reading another snapshot; at a boundary,

package/README.md

@@ -55,14 +55,14 @@ module through a bundler that resolves imports from the installed npm package.
 ```
 
 ```js
-import { createPlayer } from '@grundyjs/algiviz/playback';
+import { createStatePlayer } from '@grundyjs/algiviz/playback';
 import { createSceneRenderer } from '@grundyjs/algiviz/scene';
 
 const ctx = document.querySelector('canvas').getContext('2d');
-function* steps() {
-    for (const [index, x] of [40, 200, 360, 560].entries()) {
+function* states() {
+    for (const x of [40, 200, 360, 560]) {
         const state = { objects: [{ id: 'circle', type: 'dot', data: { x } }] };
-        yield { index, state, event: index === 3 ? 'done' : 'position' };
+        yield state;
     }
 }
 const renderer = createSceneRenderer({
@@ -73,9 +73,7 @@ const renderer = createSceneRenderer({
         ctx.fill();
     },
 });
-const player = createPlayer(steps(), {
-    stepDurationMs: 1000, finalHoldMs: 0,
-    isTerminal: step => step.event === 'done',
+const player = createStatePlayer(states(), {
     render(frame) {
         ctx.clearRect(0, 0, 600, 160);
         renderer.render(ctx, frame);
@@ -84,7 +82,9 @@ const player = createPlayer(steps(), {
 document.querySelector('#next').onclick = () => player.nextStep();
 ```
 
-The first frame (`x = 40`) is drawn immediately inside `createPlayer(...)`. Each
+After the last state, one more click detects generator exhaustion and keeps the final position. No lookahead is performed.
+
+The first frame (`x = 40`) is drawn immediately inside `createStatePlayer(...)`. Each
 click requests the next state: the player resumes the loop until the next
 `yield`, then renders. There is no interpolation here: the handler draws only
 `current`. Each snapshot is created afresh and never mutated. Call
@@ -108,7 +108,7 @@ scheduling belong to the application.
 
 ## Playback modes
 
-| | Generator: `createPlayer` | History: `createTimeline` |
+| | Generator: `createPlayer` / `createStatePlayer` | History: `createTimeline` |
 | --- | --- | --- |
 | Steps | Consumed on demand | Collected up front |
 | Retention | Adjacent snapshots | Complete history |
@@ -142,6 +142,7 @@ Generators reduce retained history, not the cost of producing each snapshot.
 | [Binary search](https://github.com/urffin/algiviz/blob/master/examples/binary-search.html) | First occurrence in sorted input, closed search intervals and lazy playback |
 | [Graph BFS](https://github.com/urffin/algiviz/blob/master/examples/graph.html) | Queue, layers, shortest paths, unreachable targets and history/generator playback |
 | [Graph DFS](https://github.com/urffin/algiviz/blob/master/examples/dfs.html) | Recursive call frames, backtracking, tree depth and paths; history/generator playback |
+| [Maze](https://github.com/urffin/algiviz/blob/master/examples/maze.html) | Randomized DFS generation, BFS wave, DFS backtracking, cycles and unreachable exits; history/generator playback |
 | [Tree traversal](https://github.com/urffin/algiviz/blob/master/examples/tree.html) | Custom nodes, edges and pointer with Canvas and retained SVG backends |
 
 [Full catalog, local setup and algorithm details](https://github.com/urffin/algiviz/blob/master/docs/examples.md).

package/dist/array/player.d.ts

@@ -3,8 +3,8 @@ import type { ArrayStep, ArraySnapshot, ArrayEvent } from "./types.js";
 import type { ArrayFrame } from "./timeline.js";
 export type ArrayPlayer = Player<ArraySnapshot, ArrayEvent>;
 /** Array playback adapter for array steps ending in done. */
-export declare function createArrayPlayer(steps: Iterable<ArrayStep>, options: {
-    stepDurationMs: number;
-    finalHoldMs: number;
+export declare function createArrayPlayer(steps: Iterable<ArrayStep>, options?: {
+    stepDurationMs?: number | undefined;
+    finalHoldMs?: number | undefined;
     render?: (frame: ArrayFrame) => void;
 }): ArrayPlayer;

package/dist/array/player.js

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

package/dist/playback/index.d.ts

@@ -1,4 +1,5 @@
 export { createPlayer } from "./player.js";
+export { createStatePlayer } from "./state-player.js";
 export type { Player } from "./player.js";
 export { createTimeline } from "./timeline.js";
 export type { Step, Frame, Timeline } from "./types.js";

package/dist/playback/index.js

@@ -1,3 +1,4 @@
 export { createPlayer } from "./player.js";
+export { createStatePlayer } from "./state-player.js";
 export { createTimeline } from "./timeline.js";
 export { createStepEmitter } from "./step-emitter.js";

package/dist/playback/player.d.ts

@@ -13,9 +13,13 @@ export interface Player<S, E> {
 }
 /** Forward-only playback. The source must reach a step accepted by isTerminal. */
 export declare function createPlayer<S, E>(steps: Iterable<Step<S, E>>, options: {
-    stepDurationMs: number;
-    finalHoldMs: number;
+    /** Omit for manual playback; positive advance requires a duration. */
+    stepDurationMs?: number | undefined;
+    /** Final hold duration, default 0. */
+    finalHoldMs?: number | undefined;
     isTerminal: (step: Step<S, E>) => boolean;
     /** Called initially and on each advance or nextStep, including after completion. */
     render?: (frame: Frame<S, E>) => void;
 }): Player<S, E>;
+/** Internal engine shared by explicit-step and exhaustion-based sources. */
+export declare function createPlayback<S, E>(steps: Iterable<Step<S, E>>, options: Parameters<typeof createPlayer<S, E>>[1], finishOnExhaustion?: boolean): Player<S, E>;

package/dist/playback/player.js

@@ -1,6 +1,12 @@
 /** Forward-only playback. The source must reach a step accepted by isTerminal. */
 export function createPlayer(steps, options) {
-    const { stepDurationMs, finalHoldMs } = options;
+    return createPlayback(steps, options);
+}
+/** Internal engine shared by explicit-step and exhaustion-based sources. */
+export function createPlayback(steps, options, finishOnExhaustion = false) {
+    const manual = options.stepDurationMs === undefined;
+    // Unit endpoint for manual steps; positive timed advancement is disallowed.
+    const { stepDurationMs = 1, finalHoldMs = 0 } = options;
     if (!Number.isFinite(stepDurationMs) || stepDurationMs <= 0 ||
         !Number.isFinite(finalHoldMs) || finalHoldMs < 0) {
         throw new RangeError("Expected positive step duration and non-negative final hold");
@@ -36,8 +42,10 @@ export function createPlayer(steps, options) {
     let hold = 0;
     let disposed = false;
     let finished = false;
+    let exhausted = false;
+    const terminal = () => exhausted || options.isTerminal(current);
     const complete = () => {
-        if (options.isTerminal(current) && elapsed === stepDurationMs) {
+        if (terminal() && elapsed === stepDurationMs) {
             previous = current;
             close();
             finished = hold >= finalHoldMs;
@@ -65,15 +73,20 @@ export function createPlayer(steps, options) {
             try {
                 if (!finished) {
                     if (elapsed === stepDurationMs) {
-                        if (options.isTerminal(current)) {
+                        if (terminal()) {
                             hold = finalHoldMs;
                         }
                         else {
                             const next = iterator.next();
-                            if (next.done)
-                                throw new RangeError("Step source ended without a terminal step");
-                            previous = current;
-                            current = next.value;
+                            if (next.done) {
+                                if (!finishOnExhaustion)
+                                    throw new RangeError("Step source ended without a terminal step");
+                                exhausted = true;
+                            }
+                            else {
+                                previous = current;
+                                current = next.value;
+                            }
                         }
                     }
                     // Assign the endpoint directly: time arithmetic can undershoot or
@@ -97,18 +110,26 @@ export function createPlayer(steps, options) {
             if (!Number.isFinite(deltaMs) || deltaMs < 0) {
                 throw new RangeError("Expected finite non-negative playback time");
             }
+            if (manual && deltaMs > 0) {
+                throw new Error("Set stepDurationMs to use advance with positive time; use nextStep for manual playback");
+            }
             try {
                 let remaining = deltaMs;
                 while (remaining > 0 && !finished) {
                     if (elapsed === stepDurationMs) {
-                        if (options.isTerminal(current)) {
+                        if (terminal()) {
                             hold += Math.min(remaining, finalHoldMs - hold);
                             complete();
                             break;
                         }
                         const next = iterator.next();
-                        if (next.done)
-                            throw new RangeError("Step source ended without a terminal step");
+                        if (next.done) {
+                            if (!finishOnExhaustion)
+                                throw new RangeError("Step source ended without a terminal step");
+                            exhausted = true;
+                            complete();
+                            continue;
+                        }
                         previous = current;
                         current = next.value;
                         elapsed = 0;

package/dist/playback/state-player.d.ts

@@ -0,0 +1,9 @@
+import { type Player } from './player.js';
+import type { Frame } from './types.js';
+/** Lazy state playback. Exhaustion is detected on the request after the last state.
+ * States must be immutable snapshots. Generator return values are ignored. */
+export declare function createStatePlayer<S>(states: Iterable<S>, options?: {
+    stepDurationMs?: number | undefined;
+    finalHoldMs?: number | undefined;
+    render?: (frame: Frame<S, undefined>) => void;
+}): Player<S, undefined>;

package/dist/playback/state-player.js

@@ -0,0 +1,36 @@
+import { createPlayback } from './player.js';
+/** Lazy state playback. Exhaustion is detected on the request after the last state.
+ * States must be immutable snapshots. Generator return values are ignored. */
+export function createStatePlayer(states, options = {}) {
+    function* steps() {
+        const iterator = states[Symbol.iterator]();
+        let index = 0, exhausted = false, failed = false;
+        try {
+            while (true) {
+                const item = iterator.next();
+                if (item.done) {
+                    exhausted = true;
+                    return;
+                }
+                yield { index: index++, state: item.value, event: undefined };
+            }
+        }
+        catch (error) {
+            failed = true;
+            throw error;
+        }
+        finally {
+            if (!exhausted) {
+                if (failed) {
+                    try {
+                        iterator.return?.();
+                    }
+                    catch { /* Preserve source failure. */ }
+                }
+                else
+                    iterator.return?.();
+            }
+        }
+    }
+    return createPlayback(steps(), { ...options, isTerminal: () => false }, true);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grundyjs/algiviz",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "TypeScript toolkit for custom algorithm visualizations with step-by-step playback and extensible rendering",
   "type": "module",
   "files": [

package/ru/README.md

@@ -54,14 +54,14 @@ npm install @grundyjs/algiviz
 ```
 
 ```js
-import { createPlayer } from '@grundyjs/algiviz/playback';
+import { createStatePlayer } from '@grundyjs/algiviz/playback';
 import { createSceneRenderer } from '@grundyjs/algiviz/scene';
 
 const ctx = document.querySelector('canvas').getContext('2d');
-function* steps() {
-    for (const [index, x] of [40, 200, 360, 560].entries()) {
+function* states() {
+    for (const x of [40, 200, 360, 560]) {
         const state = { objects: [{ id: 'circle', type: 'dot', data: { x } }] };
-        yield { index, state, event: index === 3 ? 'done' : 'position' };
+        yield state;
     }
 }
 const renderer = createSceneRenderer({
@@ -72,9 +72,7 @@ const renderer = createSceneRenderer({
         ctx.fill();
     },
 });
-const player = createPlayer(steps(), {
-    stepDurationMs: 1000, finalHoldMs: 0,
-    isTerminal: step => step.event === 'done',
+const player = createStatePlayer(states(), {
     render(frame) {
         ctx.clearRect(0, 0, 600, 160);
         renderer.render(ctx, frame);
@@ -83,7 +81,9 @@ const player = createPlayer(steps(), {
 document.querySelector('#next').onclick = () => player.nextStep();
 ```
 
-Первый кадр (`x = 40`) рисуется сразу внутри `createPlayer(...)`. Каждый клик
+После последнего состояния ещё один клик обнаруживает конец генератора и сохраняет позицию круга. Чтения вперёд нет.
+
+Первый кадр (`x = 40`) рисуется сразу внутри `createStatePlayer(...)`. Каждый клик
 запрашивает следующее состояние: плеер возобновляет цикл до следующего
 `yield`, затем вызывает отрисовку. Здесь нет плавного перехода: обработчик рисует
 только `current`. Каждый снимок создаётся заново и больше не изменяется. При
@@ -106,7 +106,7 @@ document.querySelector('#next').onclick = () => player.nextStep();
 
 ## Режимы воспроизведения
 
-| | Генератор: `createPlayer` | История: `createTimeline` |
+| | Генератор: `createPlayer` / `createStatePlayer` | История: `createTimeline` |
 | --- | --- | --- |
 | Получение шагов | По мере продвижения | Все шаги заранее |
 | Хранение | Соседние снимки | Вся история |
@@ -140,6 +140,7 @@ document.querySelector('#next').onclick = () => player.nextStep();
 | [Бинарный поиск](https://github.com/urffin/algiviz/blob/master/examples/binary-search.html) | Первое вхождение в отсортированном массиве, замкнутый интервал поиска и ленивое воспроизведение |
 | [BFS графа](https://github.com/urffin/algiviz/blob/master/examples/graph.html) | Очередь, слои, кратчайшие пути, недостижимая цель и история/генератор |
 | [DFS графа](https://github.com/urffin/algiviz/blob/master/examples/dfs.html) | Стек вызовов, возвраты, глубина и путь дерева; история/генератор |
+| [Лабиринт](https://github.com/urffin/algiviz/blob/master/examples/maze.html) | Генерация рандомизированным DFS, волна BFS, поиск DFS, циклы и недостижимый выход; история/генератор |
 | [Обход дерева](https://github.com/urffin/algiviz/blob/master/examples/tree.html) | Собственные узлы, рёбра и указатель с Canvas и SVG с сохранением элементов |
 
 [Полный каталог, локальный запуск и особенности алгоритмов](https://github.com/urffin/algiviz/blob/master/docs/ru/examples.md).