@grundyjs/algiviz 0.8.3 → 0.9.0

package/CHANGELOG.md

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

@@ -81,11 +81,11 @@ const player = createPlayer(steps(), {
         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/playback/player.d.ts

@@ -5,6 +5,9 @@ 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;
 }
@@ -13,6 +16,6 @@ export declare function createPlayer<S, E>(steps: Iterable<Step<S, E>>, options:
     stepDurationMs: number;
     finalHoldMs: number;
     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

@@ -59,6 +59,38 @@ 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");

package/package.json

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

package/ru/README.md

@@ -80,11 +80,11 @@ const player = createPlayer(steps(), {
         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()`.