@grundyjs/algiviz 0.8.3 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 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,
+  consume one next snapshot. Complete terminal holds without extra source reads.
+- Preserve rendering, disposal and error handling contracts; avoid rounding errors
+  when mixing timed advancement with manual steps.
+- Update the minimal example, English/Russian READMEs and highlighted GIF to use nextStep().
+
 ## 0.8.3 — 2026-10-27
 
 - Streamline English and Russian READMEs around installation and a minimal example.

package/README.md

@@ -74,18 +74,17 @@ const renderer = createSceneRenderer({
     },
 });
 const player = createPlayer(steps(), {
-    stepDurationMs: 1000, finalHoldMs: 0,
     isTerminal: step => step.event === 'done',
     render(frame) {
         ctx.clearRect(0, 0, 600, 160);
         renderer.render(ctx, frame);
     },
 });
-document.querySelector('#next').onclick = () => player.advance(1000);
+document.querySelector('#next').onclick = () => player.nextStep();
 ```
 
 The first frame (`x = 40`) is drawn immediately inside `createPlayer(...)`. Each
-click advances one 1000 ms step: the player resumes the loop until the next
+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
 `player.dispose()` when removing the visualization.

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/player.d.ts

@@ -5,14 +5,19 @@ export interface Player<S, E> {
     readonly finished: boolean;
     /** Advance by playback time; pass zero to redraw without consuming steps. */
     advance(deltaMs: number): Frame<S, E>;
+    /** Finish the current transition, or consume one next step at a boundary.
+     * At the terminal boundary, finish the hold. Renders once, even if finished. */
+    nextStep(): Frame<S, E>;
     /** Close the source early. The last frame remains readable. */
     dispose(): void;
 }
 /** 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, including advance(0). */
+    /** Called initially and on each advance or nextStep, including after completion. */
     render?: (frame: Frame<S, E>) => void;
 }): Player<S, E>;

package/dist/playback/player.js

@@ -1,6 +1,8 @@
 /** Forward-only playback. The source must reach a step accepted by isTerminal. */
 export function createPlayer(steps, options) {
-    const { stepDurationMs, finalHoldMs } = options;
+    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");
@@ -59,12 +61,47 @@ export function createPlayer(steps, options) {
     return Object.freeze({
         get frame() { return frame(); },
         get finished() { return finished; },
+        nextStep() {
+            if (disposed)
+                throw new Error("Player has been disposed");
+            try {
+                if (!finished) {
+                    if (elapsed === stepDurationMs) {
+                        if (options.isTerminal(current)) {
+                            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;
+                        }
+                    }
+                    // Assign the endpoint directly: time arithmetic can undershoot or
+                    // spill a rounding remainder into an unwanted additional step.
+                    elapsed = stepDurationMs;
+                    complete();
+                }
+                const result = frame();
+                options.render?.(result);
+                return result;
+            }
+            catch (error) {
+                disposed = true;
+                closeAfterFailure();
+                throw error;
+            }
+        },
         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");
             }
+            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) {

package/package.json

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

package/ru/README.md

@@ -73,18 +73,17 @@ const renderer = createSceneRenderer({
     },
 });
 const player = createPlayer(steps(), {
-    stepDurationMs: 1000, finalHoldMs: 0,
     isTerminal: step => step.event === 'done',
     render(frame) {
         ctx.clearRect(0, 0, 600, 160);
         renderer.render(ctx, frame);
     },
 });
-document.querySelector('#next').onclick = () => player.advance(1000);
+document.querySelector('#next').onclick = () => player.nextStep();
 ```
 
 Первый кадр (`x = 40`) рисуется сразу внутри `createPlayer(...)`. Каждый клик
-проходит один шаг длительностью 1000 мс: плеер возобновляет цикл до следующего
+запрашивает следующее состояние: плеер возобновляет цикл до следующего
 `yield`, затем вызывает отрисовку. Здесь нет плавного перехода: обработчик рисует
 только `current`. Каждый снимок создаётся заново и больше не изменяется. При
 удалении визуализации вызовите `player.dispose()`.