@grundyjs/algiviz 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.8.2 — 2026-10-27
+
+- Add a self-contained minimal usage example to both English and Russian READMEs.
+- Link an interactive walkthrough of generator states, playback and custom drawing.
+- Add repository examples with sequential code highlighting and explicit startup.
+- No runtime API or behavior changes; examples remain outside the npm package.
+
 ## 0.8.1 — 2026-10-26
 
 - Use Array-prefixed internal types in public declarations and make

package/README.md

@@ -30,26 +30,61 @@ renderer help you get started.
 
 Use it for educational demos, interactive articles and algorithm walkthroughs.
 Algorithms and layouts belong to your application; AlgiViz provides the playback
-and rendering API. This README describes version 0.8.1.
+and rendering API. This README describes version 0.8.2.
 
 ## Start with one custom object
 
-The [standalone page](https://github.com/urffin/algiviz/blob/master/examples/minimal.html)
-moves one token with a generator and a custom Canvas handler. It uses only public
-package imports, without the shared demo controller. Copy its
-[complete module](https://github.com/urffin/algiviz/blob/master/examples/minimal.mjs)
-into your application and connect a canvas:
+Four states of one circle: `40 → 200 → 360 → 560`. The generator supplies
+coordinates, the `dot` handler draws the circle, and the player requests the next
+state. Add a canvas and button to your HTML, then load the JavaScript below as a
+module through a bundler that resolves imports from the installed npm package.
 
-```js
-import { createTokenPlayer } from './minimal.mjs';
+```html
+<canvas width="600" height="160"></canvas>
+<button id="next">Next state</button>
+```
 
-const canvas = document.querySelector('canvas');
-const player = createTokenPlayer(canvas.getContext('2d'));
-player.advance(100); // Advance playback by 100 ms.
-// Call advance(deltaMs) from your controls or animation loop.
-// Call player.dispose() when removing the visualization.
+```js
+import { createPlayer } 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()) {
+        const state = { objects: [{ id: 'circle', type: 'dot', data: { x } }] };
+        yield { index, state, event: index === 3 ? 'done' : 'position' };
+    }
+}
+const renderer = createSceneRenderer({
+    dot(ctx, { current }) {
+        ctx.beginPath();
+        ctx.arc(current.data.x, 80, 18, 0, Math.PI * 2);
+        ctx.fillStyle = '#b39bff';
+        ctx.fill();
+    },
+});
+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);
 ```
 
+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
+`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.
+
+[Interactive walkthrough with sequential code highlighting](https://github.com/urffin/algiviz/blob/master/examples/visualization-pipeline.html)
+shows initial rendering behind a Start button and the subsequent loop iterations
+(Russian UI). This is an example page in the repository; run it locally using
+the setup instructions below.
+
 [Follow the walkthrough](https://github.com/urffin/algiviz/blob/master/docs/minimal-example.md)
 for local setup, snapshot ownership and lifecycle. For a larger custom-object
 example, see the [graph BFS walkthrough](https://github.com/urffin/algiviz/blob/master/docs/custom-graph-example.md).
@@ -425,6 +460,7 @@ included in the npm archive.
 
 | Example | What it demonstrates |
 | --- | --- |
+| [How a frame is made](https://github.com/urffin/algiviz/blob/master/examples/visualization-pipeline.html) | AlgiViz visualizes its own generator → player → scene → renderer pipeline (Russian walkthrough) |
 | [Sorting lab](examples/index.html) | Insertion and bubble sort using the array operations and renderer |
 | [Merge sort](examples/merge.html) | Custom state and a two-row scene for the main array and buffer |
 | [Quick sort partitions](examples/quick.html) | Lomuto and three-way partitioning with custom state and scene |

package/package.json

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

package/ru/README.md

@@ -30,26 +30,60 @@ AlgiViz управляет воспроизведением и сопостав
 
 Используйте библиотеку для учебных примеров, интерактивных статей и пошаговых разборов.
 Алгоритмы и расположение объектов остаются в приложении; AlgiViz предоставляет API
-воспроизведения и отрисовки. Этот README описывает версию 0.8.1.
+воспроизведения и отрисовки. Этот README описывает версию 0.8.2.
 
 ## Начните с одного собственного объекта
 
-[Отдельная страница](https://github.com/urffin/algiviz/blob/master/examples/minimal.html)
-перемещает один объект с помощью генератора и собственного Canvas-обработчика.
-Она использует только публичные импорты пакета, без общего контроллера демонстраций.
-Скопируйте [полный модуль](https://github.com/urffin/algiviz/blob/master/examples/minimal.mjs)
-в приложение и подключите canvas:
+Четыре состояния одного круга: `40 → 200 → 360 → 560`. Генератор задаёт
+координаты, обработчик `dot` рисует круг, а плеер запрашивает следующее состояние.
+Добавьте Canvas и кнопку в HTML, а JavaScript ниже подключите как модуль через
+сборщик, разрешающий импорты установленного npm-пакета.
 
-```js
-import { createTokenPlayer } from './minimal.mjs';
+```html
+<canvas width="600" height="160"></canvas>
+<button id="next">Следующее состояние</button>
+```
 
-const canvas = document.querySelector('canvas');
-const player = createTokenPlayer(canvas.getContext('2d'));
-player.advance(100); // Advance playback by 100 ms.
-// Call advance(deltaMs) from your controls or animation loop.
-// Call player.dispose() when removing the visualization.
+```js
+import { createPlayer } 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()) {
+        const state = { objects: [{ id: 'circle', type: 'dot', data: { x } }] };
+        yield { index, state, event: index === 3 ? 'done' : 'position' };
+    }
+}
+const renderer = createSceneRenderer({
+    dot(ctx, { current }) {
+        ctx.beginPath();
+        ctx.arc(current.data.x, 80, 18, 0, Math.PI * 2);
+        ctx.fillStyle = '#b39bff';
+        ctx.fill();
+    },
+});
+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);
 ```
 
+Первый кадр (`x = 40`) рисуется сразу внутри `createPlayer(...)`. Каждый клик
+проходит один шаг длительностью 1000 мс: плеер возобновляет цикл до следующего
+`yield`, затем вызывает отрисовку. Здесь нет плавного перехода: обработчик рисует
+только `current`. Каждый снимок создаётся заново и больше не изменяется. При
+удалении визуализации вызовите `player.dispose()`.
+
+[Интерактивный разбор с последовательной подсветкой кода](https://github.com/urffin/algiviz/blob/master/examples/visualization-pipeline.html)
+показывает создание первого кадра по кнопке «Начать» и последующие итерации цикла.
+Это страница примера в репозитории; запускайте её локально по инструкции ниже.
+
 [Пошаговое руководство](https://github.com/urffin/algiviz/blob/master/docs/minimal-example.md)
 объясняет локальный запуск, владение снимками состояния и жизненный цикл.
 Более крупный пример с собственными объектами описан в
@@ -435,6 +469,7 @@ Canvas, передаваемые без CSS-проверки. Для пропу
 
 | Пример | Что демонстрирует |
 | --- | --- |
+| [Как рождается кадр](https://github.com/urffin/algiviz/blob/master/examples/visualization-pipeline.html) | Путь от генератора через плеер и сцену к отрисовке, показанный средствами AlgiViz |
 | [Лаборатория сортировок](../examples/index.html) | Сортировки вставками и пузырьком с операциями массива и готовым рендерером |
 | [Сортировка слиянием](../examples/merge.html) | Собственное состояние и сцена из двух строк для основного массива и буфера |
 | [Разбиения быстрой сортировки](../examples/quick.html) | Разбиения Ломуто и трёхстороннее с собственными состоянием и сценой |