@grundyjs/algiviz 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.11.1 — 2026-11-05
+
+- Validate both numeric positions in array swap/shift before reading or mutating
+  the trace, rejecting invalid JavaScript arguments without losing item identities
+  or changing snapshots, counters, markers or the next step index.
+- Allow explicitly undefined sorted-region inputs with exactOptionalPropertyTypes,
+  matching the existing runtime behavior of preserving the current marker.
+- Document array guarantees in English and Russian: fixed length, one held item,
+  trace-local IDs, immutable snapshots, counters and author-supplied sorted markers.
+- Add an application-owned object lifecycle example and expand playback completion,
+  strict type and installed-package consumer checks. No new public exports.
+
+## 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.

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,8 +73,7 @@ const renderer = createSceneRenderer({
         ctx.fill();
     },
 });
-const player = createPlayer(steps(), {
-    isTerminal: step => step.event === 'done',
+const player = createStatePlayer(states(), {
     render(frame) {
         ctx.clearRect(0, 0, 600, 160);
         renderer.render(ctx, frame);
@@ -83,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
@@ -101,13 +102,13 @@ the [local setup instructions](https://github.com/urffin/algiviz/blob/master/doc
 - **Scene:** describes objects with stable IDs, types and application-owned data.
 - **Handler:** chooses geometry and drawing behavior, including interpolation.
 
-Do not mutate emitted states. Players require an explicit terminal step;
-call `dispose()` when removing a visualization. Algorithms, layouts and animation
+Do not mutate emitted states. `createStatePlayer` completes on source exhaustion;
+`createPlayer` requires an explicit terminal step. Call `dispose()` when removing a visualization. Algorithms, layouts and animation
 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 |
@@ -141,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/trace.d.ts

@@ -1,7 +1,8 @@
 import type { Item, ArrayStep } from "./types.js";
+/** Omitted or undefined markers preserve their current values. */
 export interface SortedRegions {
-    readonly sortedPrefixLength?: number;
-    readonly sortedSuffixLength?: number;
+    readonly sortedPrefixLength?: number | undefined;
+    readonly sortedSuffixLength?: number | undefined;
 }
 export interface ArrayTrace {
     readonly length: number;

package/dist/array/trace.js

@@ -54,6 +54,8 @@ export function createArrayTrace(values) {
         },
         swap(left, right, update) {
             active();
+            index(left);
+            index(right);
             const a = item(left), b = item(right);
             if (left === right)
                 throw new RangeError("Swap requires distinct positions");
@@ -74,8 +76,9 @@ export function createArrayTrace(values) {
         },
         shift(from, to, update) {
             active();
-            const moved = item(from);
+            index(from);
             index(to);
+            const moved = item(from);
             if (slots[to] !== null)
                 throw new Error("Shift destination must be empty");
             regions(update);

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

@@ -21,3 +21,5 @@ export declare function createPlayer<S, E>(steps: Iterable<Step<S, E>>, options:
     /** 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,5 +1,9 @@
 /** Forward-only playback. The source must reach a step accepted by isTerminal. */
 export function createPlayer(steps, 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;
@@ -38,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;
@@ -67,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
@@ -106,14 +117,19 @@ export function createPlayer(steps, options) {
                 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.10.0",
+  "version": "0.11.1",
   "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,8 +72,7 @@ const renderer = createSceneRenderer({
         ctx.fill();
     },
 });
-const player = createPlayer(steps(), {
-    isTerminal: step => step.event === 'done',
+const player = createStatePlayer(states(), {
     render(frame) {
         ctx.clearRect(0, 0, 600, 160);
         renderer.render(ctx, frame);
@@ -82,7 +81,9 @@ const player = createPlayer(steps(), {
 document.querySelector('#next').onclick = () => player.nextStep();
 ```
 
-Первый кадр (`x = 40`) рисуется сразу внутри `createPlayer(...)`. Каждый клик
+После последнего состояния ещё один клик обнаруживает конец генератора и сохраняет позицию круга. Чтения вперёд нет.
+
+Первый кадр (`x = 40`) рисуется сразу внутри `createStatePlayer(...)`. Каждый клик
 запрашивает следующее состояние: плеер возобновляет цикл до следующего
 `yield`, затем вызывает отрисовку. Здесь нет плавного перехода: обработчик рисует
 только `current`. Каждый снимок создаётся заново и больше не изменяется. При
@@ -99,13 +100,14 @@ document.querySelector('#next').onclick = () => player.nextStep();
 - **Сцена** описывает объекты: стабильный `id`, тип и собственные данные.
 - **Обработчик** выбирает геометрию и способ рисования. Плавность — его решение.
 
-Состояния после выдачи нельзя изменять. Плееру нужен явный завершающий шаг;
+Состояния после выдачи нельзя изменять. `createStatePlayer` завершается при исчерпании
+источника; `createPlayer` требует явного завершающего шага;
 при удалении визуализации вызовите `dispose()`. Алгоритмы, раскладка и цикл
 анимации принадлежат приложению.
 
 ## Режимы воспроизведения
 
-| | Генератор: `createPlayer` | История: `createTimeline` |
+| | Генератор: `createPlayer` / `createStatePlayer` | История: `createTimeline` |
 | --- | --- | --- |
 | Получение шагов | По мере продвижения | Все шаги заранее |
 | Хранение | Соседние снимки | Вся история |
@@ -139,6 +141,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).