@grundyjs/algiviz 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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
+  createArrayRenderer the canonical function name, retaining createSortRenderer
+  as the identical compatibility alias.
+- Allow explicit undefined palette roles with exactOptionalPropertyTypes,
+  matching the existing runtime fallback to theme defaults.
+- Verify the full runtime export inventory, private-path rejection, all public
+  types and headless compilation against the installed package.
+- Add a strictly typed custom-object starter and optimize merge example drawing.
+- Expand application-owned BFS examples and add DFS with a call stack and
+  backtracking. Algorithms remain outside the npm package.
+
 ## 0.8.0 — 2026-10-19
 
 - Add partial custom colors to the Canvas array renderer and its compatible alias,

package/README.md

@@ -1,5 +1,7 @@
 # AlgiViz
 
+[Русский](ru/README.md)
+
 **Your algorithms and objects. Step-by-step playback and custom rendering.**
 
 ![BFS from A: custom graph vertices, edges and queue animated with AlgiViz](https://raw.githubusercontent.com/urffin/algiviz/master/docs/assets/bfs.gif)
@@ -28,30 +30,69 @@ 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.0.
+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).
 
+For a complete TypeScript integration with two object types and Play/Pause/Restart,
+see [custom-objects.ts](examples/custom-objects.ts) and the
+[setup instructions](docs/minimal-example.md#a-complete-typescript-integration).
+
 ## Install
 
 ```sh
@@ -144,7 +185,7 @@ The algorithms belong to the application; they require no changes to the library
 ### Custom structures and renderers
 
 `/playback` does not know arrays, sorting, Canvas, or event names. A source yields
-`Step<State, Event>` objects with contiguous zero-based `index`, immutable
+`Step<State, Event>` objects with a numeric `index`, immutable
 `state` and `event`. Supply `isTerminal` to identify the final step and
 `render` to draw each interpolated frame using any rendering technology:
 
@@ -159,6 +200,10 @@ const player = createPlayer(myTraversal(), {
 });
 ```
 
+Both engines preserve the supplied index; it need not start at zero or be
+contiguous. Timing follows source order. `createStepEmitter` provides consecutive
+zero-based numbering for convenience.
+
 The render callback is optional. Without it, read `player.frame` and render
 manually. `createTimeline(steps, timing)` supports seeking with the same generic
 frame shape; call your renderer with its `sample(timeMs)` result. The generic
@@ -415,11 +460,14 @@ 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 |
 | [Heap sort](examples/heap.html) | Max-heap construction and extraction with synchronized tree and array identities |
-| [Graph BFS](examples/graph.html) | Cycles, disconnected components, shortest distances and an animated queue |
+| [Binary search](examples/binary-search.html) | First occurrence in sorted input, closed search intervals and lazy playback |
+| [Graph BFS](examples/graph.html) | Queue, layers, shortest paths, unreachable targets and history/generator playback |
+| [Graph DFS](examples/dfs.html) | Recursive call frames, backtracking, tree depth and paths; history/generator playback |
 | [Tree traversal](examples/tree.html) | Custom nodes, edges and pointer with Canvas and retained SVG backends |
 
 All examples reuse [demo-player.mjs](examples/demo-player.mjs) and
@@ -465,6 +513,12 @@ in-place algorithm uses O(1) auxiliary space. This demo copies input and retains
 O(n) adjacent snapshot data in generator mode; full history can use O(n² log n).
 It is not stable: [2a, 2b, 1] becomes [1, 2b, 2a].
 
+### Binary search
+
+The [algorithm](examples/binary-search-algorithm.mjs) finds the first occurrence, including duplicates. Equal values save a candidate and continue searching left. Input must be sorted; invalid loads preserve the current session. Generate sorted arrays by count with the shared history/generator limits. The counter counts inspected middle elements.
+
+The [scene](examples/binary-search-scene.mjs) uses stable index-based IDs and viewport-independent projection. Up to 32 cells wrap; larger arrays use a dense strip and suppress unreadable labels. Search takes O(log n) time and O(1) extra algorithm space. The demo validates and copies input in O(n), shares a frozen array across snapshots and stores O(n + log n) history data. The example is not part of the npm package and needs no new public export.
+
 ### Tree traversal
 
 The example defines its own `node`, `edge` and `pointer` types. The pointer follows
@@ -476,16 +530,47 @@ No tree-specific algorithm or renderer is added to the package.
 
 ### Graph breadth-first search
 
-Open [examples/graph.html](examples/graph.html) and choose a start vertex.
-The example explores only its connected component, marks vertices when enqueued
-and shows shortest unweighted distances. Its custom vertex, connection and queue
-entry types are projected from immutable algorithm state. Both playback modes use
-the same generator; changing the start creates a new traversal.
+Open [examples/graph.html](examples/graph.html), choose a graph, start and optional
+target, then Apply. BFS marks on enqueue, completes the reachable component and
+restores one shortest path by following parents. Try the isolated H, a zero-edge
+path to the start, a chain or a diamond with equal-length paths. The original
+disconnected graph shown in the README GIF remains a separate preset.
+
+The scene shows a fixed graph, an animated queue, distances, parent/path edges and
+explicit discovery/processing/neighbor-inspection counters. On narrow screens the
+queue wraps below the graph. Canvas rendering uses logical coordinates and DPR.
+Self-loops and parallel edges remain supported; neighbor order can change which
+shortest path is chosen, but not its length.
+
+Both playback modes use the same immutable generator. Restart and mode changes
+replay the applied graph/start/target, not draft controls. Generator mode consumes
+lazily without collecting history. Full history enables backward seeks and has an
+O(V(V + E)) snapshot-space upper bound, separately from graph and algorithm data.
 
 See [Building a custom graph example](docs/custom-graph-example.md) for the
 algorithm, projection and renderer boundaries. This example uses the existing
 public APIs and adds no graph-specific package exports.
 
+### Graph depth-first search
+
+Open [examples/dfs.html](examples/dfs.html) to compare DFS with BFS on the same
+graph layouts. Choose a graph, start and optional target. Each explicit call frame
+stores its next neighbor cursor; marking happens before entry. Returning pops the
+finished call and resumes its parent. The stack contains the active branch only.
+
+The default discovery order is A, B, D, G, E, C, F; return order is F, C, E, G, D, B, A.
+The DFS tree path to F has 6 edges; BFS finds A → C → F with 2. DFS tree depth is not
+a shortest distance. H is unreachable. Traversal finishes before reconstructing the
+path. The example accepts simple undirected graphs; self-loops and parallel edges
+are rejected. Neighbor order follows edge input order.
+
+The fixed-capacity stack moves below the graph on narrow screens. Canvas uses
+logical coordinates and DPR. Both modes share one immutable generator and the
+[shared demo player](examples/demo-player.mjs); restart reuses applied inputs.
+Generator playback is lazy, while history enables backward seeks. The traversal
+uses O(V + E) time and O(V) auxiliary space; snapshot history has a separate
+O(V(V + E)) upper bound. No graph API or built-in DFS is added to the package.
+
 ## Development
 
 Requires Node.js 22 or later and npm.

package/dist/array/index.d.ts

@@ -1,6 +1,6 @@
 export { createArrayTrace, defineArrayAlgorithm } from "./trace.js";
 export type { ArrayTrace, ArrayAlgorithm, SortedRegions } from "./trace.js";
-export type { Item, SortEvent as ArrayEvent, SortSnapshot as ArraySnapshot, SortStep as ArrayStep } from "./types.js";
+export type { Item, ArrayEvent, ArraySnapshot, ArrayStep } from "./types.js";
 export { createArrayPlayer } from "./player.js";
 export { createArrayTimeline } from "./timeline.js";
 export type { ArrayPlayer } from "./player.js";

package/dist/array/player.d.ts

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

package/dist/array/snapshot-builder.d.ts

@@ -1,4 +1,4 @@
-import type { Item, SortEvent, SortStep } from "./types.js";
+import type { Item, ArrayEvent, ArrayStep } from "./types.js";
 /** Internal mutable workspace; only emit() exposes immutable snapshots. */
 export declare function createSortTrace(values: readonly number[]): {
     state: {
@@ -7,5 +7,5 @@ export declare function createSortTrace(values: readonly number[]): {
         sortedPrefixLength: number;
         sortedSuffixLength?: number;
     };
-    emit: (event: SortEvent) => SortStep;
+    emit: (event: ArrayEvent) => ArrayStep;
 };

package/dist/array/timeline.d.ts

@@ -1,8 +1,8 @@
 import { type Frame, type Timeline } from "../playback/index.js";
-import type { SortEvent, SortSnapshot, SortStep } from "./types.js";
-export type ArrayFrame = Frame<SortSnapshot, SortEvent>;
-export type ArrayTimeline = Timeline<SortSnapshot, SortEvent>;
-export declare function createArrayTimeline(steps: readonly SortStep[], options: {
+import type { ArrayEvent, ArraySnapshot, ArrayStep } from "./types.js";
+export type ArrayFrame = Frame<ArraySnapshot, ArrayEvent>;
+export type ArrayTimeline = Timeline<ArraySnapshot, ArrayEvent>;
+export declare function createArrayTimeline(steps: readonly ArrayStep[], options: {
     stepDurationMs: number;
     finalHoldMs: number;
 }): ArrayTimeline;

package/dist/array/trace.d.ts

@@ -1,4 +1,4 @@
-import type { Item, SortStep } from "./types.js";
+import type { Item, ArrayStep } from "./types.js";
 export interface SortedRegions {
     readonly sortedPrefixLength?: number;
     readonly sortedSuffixLength?: number;
@@ -7,21 +7,21 @@ export interface ArrayTrace {
     readonly length: number;
     readonly held: Item | null;
     at(index: number): Item | null;
-    start(regions?: SortedRegions): SortStep;
-    compare(left: number | "held", right: number | "held"): SortStep;
-    highlight(positions: readonly (number | "held")[]): SortStep;
-    swap(left: number, right: number, regions?: SortedRegions): SortStep;
-    select(from: number, regions?: SortedRegions): SortStep;
-    shift(from: number, to: number, regions?: SortedRegions): SortStep;
-    insert(to: number, regions?: SortedRegions): SortStep;
-    pass(end: number, regions?: SortedRegions): SortStep;
-    done(regions?: SortedRegions): SortStep;
+    start(regions?: SortedRegions): ArrayStep;
+    compare(left: number | "held", right: number | "held"): ArrayStep;
+    highlight(positions: readonly (number | "held")[]): ArrayStep;
+    swap(left: number, right: number, regions?: SortedRegions): ArrayStep;
+    select(from: number, regions?: SortedRegions): ArrayStep;
+    shift(from: number, to: number, regions?: SortedRegions): ArrayStep;
+    insert(to: number, regions?: SortedRegions): ArrayStep;
+    pass(end: number, regions?: SortedRegions): ArrayStep;
+    done(regions?: SortedRegions): ArrayStep;
 }
 /** Operations own mutations, counters and immutable snapshots, but no algorithm. */
 export declare function createArrayTrace(values: readonly number[]): ArrayTrace;
 export interface ArrayAlgorithm {
-    iterate(values: readonly number[]): Generator<SortStep, void, unknown>;
-    steps(values: readonly number[]): readonly SortStep[];
+    iterate(values: readonly number[]): Generator<ArrayStep, void, unknown>;
+    steps(values: readonly number[]): readonly ArrayStep[];
 }
 /** Each iterator owns its workspace; input is read on its first next(). */
-export declare function defineArrayAlgorithm(algorithm: (array: ArrayTrace) => Generator<SortStep, void, unknown>): ArrayAlgorithm;
+export declare function defineArrayAlgorithm(algorithm: (array: ArrayTrace) => Generator<ArrayStep, void, unknown>): ArrayAlgorithm;

package/dist/array/types.d.ts

@@ -2,7 +2,7 @@ export type Item = Readonly<{
     id: string;
     value: number;
 }>;
-export type SortEvent = Readonly<{
+export type ArrayEvent = Readonly<{
     type: "start";
 } | {
     type: "select";
@@ -36,7 +36,7 @@ export type SortEvent = Readonly<{
 } | {
     type: "done";
 }>;
-export interface SortSnapshot {
+export interface ArraySnapshot {
     readonly slots: readonly (Item | null)[];
     readonly held: Item | null;
     /** Sorted leading occupied slots; during insertion it ends at the hole. */
@@ -47,9 +47,9 @@ export interface SortSnapshot {
     /** Writes into array slots; selecting a key does not count as a write. */
     readonly writes: number;
 }
-export interface SortStep {
+export interface ArrayStep {
     readonly index: number;
-    readonly event: SortEvent;
+    readonly event: ArrayEvent;
     /** Complete immutable state immediately after the event. */
-    readonly state: SortSnapshot;
+    readonly state: ArraySnapshot;
 }

package/dist/canvas/index.d.ts

@@ -1,5 +1,5 @@
-import type { Item, SortSnapshot } from "../array/types.js";
-import type { ArrayFrame as SortFrame } from "../array/timeline.js";
+import type { Item, ArraySnapshot } from "../array/types.js";
+import type { ArrayFrame } from "../array/timeline.js";
 import { type Scene } from "../scene/index.js";
 export type ArrayObjects = {
     bar: {
@@ -9,7 +9,7 @@ export type ArrayObjects = {
     };
 };
 /** Adapts array identities to the same public scene contract used by custom objects. */
-export declare function arrayScene(state: SortSnapshot): Scene<ArrayObjects>;
+export declare function arrayScene(state: ArraySnapshot): Scene<ArrayObjects>;
 /** Canvas color strings for the semantic roles in the array renderer. */
 export interface ArrayPalette {
     readonly background: string;
@@ -20,13 +20,15 @@ export interface ArrayPalette {
     readonly held: string;
 }
 /** Overrides are copied at renderer creation; omitted roles retain the theme color. */
-export type ArrayPaletteOverrides = Partial<ArrayPalette>;
+export type ArrayPaletteOverrides = {
+    readonly [Role in keyof ArrayPalette]?: ArrayPalette[Role] | undefined;
+};
 export interface ArrayRendererOptions {
     readonly theme: "light" | "dark";
     readonly colors?: ArrayPaletteOverrides;
 }
-export { createSortRenderer as createArrayRenderer };
+export { createArrayRenderer as createSortRenderer };
 /** Stateless full-frame renderer. Bitmap dimensions determine layout and video size. */
-export declare function createSortRenderer(options: ArrayRendererOptions): Readonly<{
-    render(ctx: CanvasRenderingContext2D, frame: SortFrame): void;
+export declare function createArrayRenderer(options: ArrayRendererOptions): Readonly<{
+    render(ctx: CanvasRenderingContext2D, frame: ArrayFrame): void;
 }>;

package/dist/canvas/index.js

@@ -23,7 +23,7 @@ const palettes = {
         held: "#7c3aed"
     }
 };
-export { createSortRenderer as createArrayRenderer };
+export { createArrayRenderer as createSortRenderer };
 function positions(state) {
     const result = new Map();
     state.slots.forEach((item, index) => {
@@ -35,7 +35,7 @@ function positions(state) {
     return result;
 }
 /** Stateless full-frame renderer. Bitmap dimensions determine layout and video size. */
-export function createSortRenderer(options) {
+export function createArrayRenderer(options) {
     const colors = { ...palettes[options.theme] };
     for (const key of Object.keys(colors)) {
         const color = options.colors?.[key];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grundyjs/algiviz",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "TypeScript toolkit for custom algorithm visualizations with step-by-step playback and extensible rendering",
   "type": "module",
   "files": [
@@ -9,6 +9,7 @@
     "dist/scene",
     "dist/canvas",
     "README.md",
+    "ru/README.md",
     "LICENSE",
     "CHANGELOG.md"
   ],

package/ru/README.md

@@ -0,0 +1,652 @@
+# AlgiViz
+
+[English](../README.md)
+
+**Ваши алгоритмы и объекты. Пошаговое воспроизведение и собственная отрисовка.**
+
+![BFS из вершины A: собственные вершины графа, рёбра и очередь, анимированные с AlgiViz](https://raw.githubusercontent.com/urffin/algiviz/master/docs/assets/bfs.gif)
+
+*Алгоритм обхода графа в ширину с собственными объектами, реализованный в приложении.
+Экспортировано с [CanvasTake](https://github.com/urffin/canvas-take) —
+[попробуйте интерактивную сортировку](https://grundyjs.ru/algorithms/insertion-sort/)
+или изучите [исходный код BFS](https://github.com/urffin/algiviz/blob/master/examples/graph-demo.mjs).*
+
+TypeScript-библиотека для интерактивного объяснения алгоритмов. Напишите алгоритм
+как генератор, выдавайте неизменяемые состояния и определяйте внешний вид объектов.
+AlgiViz управляет воспроизведением и сопоставляет объекты сцен; операции над массивами
+и готовый Canvas-рендерер помогают начать работу.
+
+[Интерактивная сортировка](https://grundyjs.ru/algorithms/insertion-sort/) ·
+[Обзор библиотеки](https://grundyjs.ru/algiviz/) ·
+[Пакет npm](https://www.npmjs.com/package/@grundyjs/algiviz) ·
+[Исходный код минимального примера](https://github.com/urffin/algiviz/blob/master/examples/minimal.mjs)
+
+- **Ваш алгоритм:** вы управляете циклами, условиями и порядком операций.
+- **Ваши объекты:** определяйте собственные типы и обработчики для Canvas, SVG или другой среды отрисовки.
+- **Два режима воспроизведения:** сохраняйте историю для перемотки или читайте генератор,
+  оставляя в плеере только соседние снимки состояния.
+- **Без зависимостей во время выполнения:** ESM и декларации TypeScript;
+  воспроизведение работает без DOM, React и Next.js.
+
+Используйте библиотеку для учебных примеров, интерактивных статей и пошаговых разборов.
+Алгоритмы и расположение объектов остаются в приложении; AlgiViz предоставляет API
+воспроизведения и отрисовки. Этот README описывает версию 0.8.2.
+
+## Начните с одного собственного объекта
+
+Четыре состояния одного круга: `40 → 200 → 360 → 560`. Генератор задаёт
+координаты, обработчик `dot` рисует круг, а плеер запрашивает следующее состояние.
+Добавьте Canvas и кнопку в HTML, а JavaScript ниже подключите как модуль через
+сборщик, разрешающий импорты установленного npm-пакета.
+
+```html
+<canvas width="600" height="160"></canvas>
+<button id="next">Следующее состояние</button>
+```
+
+```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)
+объясняет локальный запуск, владение снимками состояния и жизненный цикл.
+Более крупный пример с собственными объектами описан в
+[разборе BFS](https://github.com/urffin/algiviz/blob/master/docs/custom-graph-example.md).
+
+Цельный пример на TypeScript с двумя типами объектов и кнопками запуска, паузы
+и перезапуска: [custom-objects.ts](../examples/custom-objects.ts).
+[Инструкция запуска](../docs/minimal-example.md#a-complete-typescript-integration)
+объясняет типизацию, подключение и очистку при удалении визуализации.
+
+## Установка
+
+```sh
+npm install @grundyjs/algiviz
+```
+
+У пакета нет корневой точки входа и сборки CommonJS. Импортируйте нужные модули:
+`/array`, `/playback`, `/scene` и `/canvas`.
+
+Алгоритмы находятся в коде приложения и примерах. Для новых интеграций используйте
+API ниже. В версии 0.x минорные релизы могут нарушать обратную совместимость;
+при обновлении сверяйтесь с [CHANGELOG.md](../CHANGELOG.md).
+
+## Собственные алгоритмы
+
+Новые приложения используют следующие точки входа, не импортирующие готовые алгоритмы:
+
+- `@grundyjs/algiviz/array`: операции над массивами и определение генераторов.
+- `@grundyjs/algiviz/playback`: универсальное воспроизведение неизменяемых состояний и событий.
+- `@grundyjs/algiviz/scene`: типизированные объекты и пользовательские визуализации.
+- `@grundyjs/algiviz/canvas`: готовый рендерер массива.
+
+Циклы, условия и порядок операций определяете вы. Регистрация в библиотеке
+или изменение AlgiViz не требуются. Например, разворот массива:
+
+```js
+import { defineArrayAlgorithm, createArrayPlayer, createArrayTimeline } from "@grundyjs/algiviz/array";
+import { createArrayRenderer } from "@grundyjs/algiviz/canvas";
+
+const reverse = defineArrayAlgorithm(function* (array) {
+    yield array.start();
+    for (let i = 0; i < Math.floor(array.length / 2); i++) {
+        yield array.highlight([i, array.length - 1 - i]);
+        yield array.swap(i, array.length - 1 - i);
+    }
+    yield array.done();
+});
+
+const options = { stepDurationMs: 350, finalHoldMs: 1000 };
+const ctx = canvas.getContext("2d");
+const renderer = createArrayRenderer({ theme: "dark" });
+const player = createArrayPlayer(reverse.iterate([1, 2, 3, 4]), {
+    ...options,
+    render: frame => renderer.render(ctx, frame)
+});
+// Your animation loop calls player.advance(deltaMs * speed).
+// No calls while paused; advance(0) redraws after resizing.
+// On teardown: cancel your animation loop and call player.dispose().
+
+// Alternatively, retain history and seek:
+const timeline = createArrayTimeline(reverse.steps([1, 2, 3, 4]), options);
+renderer.render(ctx, timeline.sample(500));
+```
+
+`defineArrayAlgorithm` возвращает `iterate(values)` и `steps(values)`. Каждый итератор
+владеет отдельным рабочим состоянием, копирует и проверяет входные данные при первом
+`next()`. `steps` собирает итератор в замороженный массив. Выдавайте результат каждой
+операции сразу через `yield`, начинайте с `start` и заканчивайте `done`. Операция
+обновляет рабочее состояние и возвращает неизменяемый снимок, но ничего не рисует.
+Плеер вызывает переданный `render` при создании и каждом `advance`.
+Ошибки отрисовки закрывают итератор и передаются вызывающему коду.
+
+### Операции над массивом
+
+| Операция | Действие |
+| --- | --- |
+| `at(index)`, `held`, `length` | Прочитать замороженный элемент, удерживаемый элемент или длину массива |
+| `start(regions?)` | Выдать начальное состояние; вызывается один раз |
+| `compare(left, right)` | Подсветить две позиции и учесть одно сравнение; любая позиция может быть `"held"` |
+| `highlight(positions)` | Подсветить элементы на этом шаге без изменения счётчиков |
+| `swap(left, right, regions?)` | Обменять занятые позиции и учесть две записи; поддерживаются несоседние позиции |
+| `select(from, regions?)` | Удержать элемент, оставив пустую позицию; записи не учитываются |
+| `shift(from, to, regions?)` | Переместить элемент в пустую позицию и учесть одну запись |
+| `insert(to, regions?)` | Заполнить пустую позицию удерживаемым элементом и учесть одну запись |
+| `pass(end, regions?)` | Описать завершённый проход без изменения элементов и счётчиков |
+| `done(regions?)` | Завершить работу; удерживаемого элемента быть не должно; не сортирует и не определяет отсортированные области |
+
+`regions` может содержать `sortedPrefixLength` и `sortedSuffixLength`.
+Пропущенные маркеры сохраняют предыдущие значения. Автор алгоритма решает, когда область
+отсортирована; AlgiViz проверяет границы, но не доказывает упорядоченность. Индексы
+начинаются с нуля. Неверные позиции, занятые места назначения и неправильный порядок
+операций вызывают исключение до изменения рабочего состояния. Читайте снимки, а не
+изменяйте элементы самостоятельно. `createArrayTrace(values)` предоставляет те же
+операции напрямую и сразу проверяет входные данные — для собственной оболочки генератора.
+
+Сортировки вставками и пузырьком реализованы в [examples/algorithms.mjs](../examples/algorithms.mjs).
+Алгоритмы принадлежат приложению и не требуют изменений библиотеки.
+
+### Собственные структуры и рендереры
+
+`/playback` ничего не знает о массивах, сортировках, Canvas и названиях событий.
+Источник выдаёт объекты `Step<State, Event>` с числовым `index`,
+неизменяемыми `state` и `event`. Передайте `isTerminal`, чтобы определить последний
+шаг, и `render`, чтобы рисовать интерполированные кадры любым способом:
+
+Оба движка сохраняют исходный индекс: он не обязан начинаться с нуля или идти
+без пропусков. Время определяется порядком шагов. `createStepEmitter` для удобства
+создаёт последовательные индексы от нуля.
+
+```js
+import { createPlayer, createTimeline } from "@grundyjs/algiviz/playback";
+
+const player = createPlayer(myTraversal(), {
+    stepDurationMs: 300,
+    finalHoldMs: 1000,
+    isTerminal: step => step.event.kind === "finished",
+    render: frame => drawGraph(frame.previous, frame.current, frame.progress, frame.event)
+});
+```
+
+Функция `render` необязательна: без неё читайте `player.frame` и рисуйте самостоятельно.
+`createTimeline(steps, timing)` поддерживает перемотку с тем же универсальным форматом
+кадра; передавайте рендереру результат `sample(timeMs)`. Универсальный движок не
+копирует и не замораживает пользовательские состояния — это обязанность источника.
+Плеер хранит только соседние снимки, а временная шкала — переданную историю.
+Собственные события массива и операции с деревьями или графами могут использовать
+этот контракт и свой рендерер. API сцен ниже направляет отдельные объекты обработчикам;
+встроенного алгоритма или набора операций для графов и деревьев нет.
+
+### Контракты воспроизведения
+
+При воспроизведении снимки приложения сохраняются без копирования: шаги, состояния
+и события должны оставаться неизменяемыми, пока используются. Временная шкала копирует
+только входной массив. Время определяется позицией в массиве, а конечные значения
+времени ограничиваются диапазоном шкалы. Генератор должен явно выдать завершающий
+шаг; раннее окончание вызывает исключение. `dispose()` закрывает источник не более
+одного раза, сохраняет доступ к последнему кадру и запрещает дальнейшее продвижение.
+Для перезапуска нужен новый источник.
+
+Начиная с 0.7.0 `stepIndex` временной шкалы сохраняет исходный `step.index`, как и плеер.
+Если чтение источника, проверка завершения или отрисовка выбрасывают исключение,
+выполняется попытка очистки без подмены исходной ошибки. Самостоятельная ошибка
+очистки при `dispose()` или штатном завершении по-прежнему передаётся вызывающему коду.
+
+### Вспомогательная функция выдачи шагов (с 0.6.0)
+
+В версии 0.6.0 в `/playback` появилась `createStepEmitter`.
+Она автоматически нумерует шаги и замораживает объект-обёртку шага:
+
+```js
+import { createStepEmitter } from '@grundyjs/algiviz/playback';
+
+function* counter() {
+    let count = 0;
+    const emit = createStepEmitter(() => Object.freeze({ count }));
+    yield emit('start');
+    count++;
+    yield emit('done');
+}
+```
+
+Создавайте emitter внутри каждого итератора. Его функция вызывается один раз на выдачу;
+индексы начинаются с нуля, а неудачный захват состояния не расходует индекс.
+Функция не копирует и не замораживает данные состояния и события, не определяет
+завершающие события и не хранит историю. Захват должен возвращать обособленные
+неизменяемые снимки; общие неизменяемые структуры можно переиспользовать.
+Возврат изменяемого рабочего объекта сам по себе не превращает его в снимок.
+
+### Собственные объекты и визуализации
+
+Определите карту типов со своими данными и визуализацию для каждого типа.
+AlgiViz сопоставляет объекты по идентификаторам и вызывает обработчики;
+обработчики определяют геометрию и способ интерполяции данных.
+
+```ts
+import { createSceneRenderer, type Scene } from "@grundyjs/algiviz/scene";
+
+interface MyObjects {
+    badge: { x: number; y: number; label: string };
+}
+
+const renderer = createSceneRenderer<MyObjects, CanvasRenderingContext2D>({
+    badge(ctx, object) {
+        const from = (object.previous ?? object.current)!.data;
+        const to = (object.current ?? object.previous)!.data;
+        const x = from.x + (to.x - from.x) * object.progress;
+        const y = from.y + (to.y - from.y) * object.progress;
+        ctx.save();
+        try {
+            ctx.globalAlpha = object.presence;
+            ctx.fillText(to.label, x, y);
+        } finally { ctx.restore(); }
+    }
+});
+
+const before: Scene<MyObjects> = {
+    objects: [{ id: "first", type: "badge", data: { x: 20, y: 30, label: "A" } }]
+};
+const after: Scene<MyObjects> = {
+    objects: [{ id: "first", type: "badge", data: { x: 120, y: 30, label: "A" } }]
+};
+// Keep these states immutable. A generic timeline/player can provide this frame.
+renderer.render(ctx, {
+    previous: before, current: after, progress: 0.5, stepIndex: 1, event: "move"
+});
+```
+
+- У объекта есть непустой стабильный `id`, `type`, пользовательские `data` и необязательный
+  конечный `zIndex` (по умолчанию ноль). ID уникальны внутри снимка. Сохранившийся ID
+  не может менять тип: для замены объектом другого типа нужен новый ID.
+- Обработчики получают объекты `previous` и `current`; отсутствующая сторона представлена
+  `null`. `phase` принимает `enter`, `update` или `exit`. `progress` — исходный прогресс
+  кадра от 0 до 1. `presence` равен progress при появлении, 1 при обновлении и 1−progress
+  при исчезновении; его можно использовать для прозрачности или масштаба. Автоматически
+  он не применяется.
+- Сначала рисуется меньший `zIndex`. При равенстве используется порядок объектов текущего
+  снимка; удалённые объекты следуют в своём прежнем порядке. При изменении слоя действует
+  текущее значение. Неявной раскладки и системы координат нет.
+- Третий аргумент обработчика предоставляет `scene.get(id)` для связей, указателей и других
+  ссылок. Он возвращает полный переход объекта с обеими сторонами; для отсутствующего
+  объекта — `undefined`. Приложение само обрабатывает такие случаи и интерполирует
+  координаты или смену цели.
+- `createSceneFrame(frame)` возвращает те же вычисленные переходы без отрисовки. Реестр
+  фиксируется при создании рендерера. Отсутствующие обработчики, повторные ID, неверный
+  progress, некорректные слои и смена типа вызывают ошибку до вызова любого обработчика.
+- Обработка сцены не хранит состояния и поддерживает произвольную перемотку. Обработчик
+  может получить объект с нулевым presence. Это отрисовка кадра, **а не гарантированные
+  вызовы жизненного цикла**: при пропуске шагов появление или исчезновение может быть
+  полностью пропущено. Очищайте Canvas в каждом кадре; SVG/DOM-рендерер с сохранением
+  элементов должен сам сверять их с текущим кадром и удалять устаревшие ID. Сохраняйте
+  и восстанавливайте состояние Canvas внутри каждого обработчика. Исключения передаются
+  вызывающему коду; уже выполненная отрисовка не откатывается.
+- Снимки и пользовательские данные не копируются и не замораживаются рекурсивно.
+  Их неизменяемость обеспечивает автор, как и при универсальном воспроизведении.
+  Индексация сцены требует O(n) дополнительной памяти, сортировка по слоям — O(n log n)
+  времени на кадр.
+
+`arrayScene(snapshot)` из `/canvas` преобразует массив в `Scene<ArrayObjects>`
+с объектами `bar`, в данных которых находятся `item`, `index` и `held`.
+Встроенный рендерер массива использует тот же механизм вызова обработчиков.
+Можно задать другую визуализацию `bar` через `createSceneRenderer<ArrayObjects, YourContext>`.
+
+### Проекция состояния в сцену
+
+`createSceneProjector` преобразует кадры воспроизведения из вашей модели состояния
+в сцены без изменения алгоритма:
+
+```js
+import { createSceneProjector } from '@grundyjs/algiviz/scene';
+const projectFrame = createSceneProjector(state => ({
+    objects: state.items.map(item => ({ id: item.id, type: 'node', data: item }))
+}));
+// Reuse the projector across renders, with either history or generator playback.
+renderer.render(ctx, projectFrame(frame));
+```
+
+Проекция получает только состояние, без события и прогресса. Используйте чистую функцию
+и неизменяемые состояния и сцены. Стороны перехода сравниваются через `Object.is`;
+изменение сохранённого состояния или захваченных настроек проекции не сбрасывает кэш.
+При смене настроек создавайте новый projector. Сохраняется не более двух проекций
+состояний; перемотка к старым состояниям может вычислять их повторно. События, индексы
+шагов и прогресс сохраняются. Раскладка под размер экрана и анимация относятся к
+обработчикам отрисовки, а не к этой кэшируемой проекции. Возвращаемый кадр заморожен;
+пользовательские состояния и сцены не копируются и не замораживаются рекурсивно.
+Проверка сцены по-прежнему выполняется в рендерере. Пример сортировки слиянием использует
+этот адаптер, чтобы не строить заново две сцены ячеек на каждом кадре анимации.
+Алгоритм, типы объектов и визуальное поведение остаются за пределами библиотеки.
+
+## Воспроизведение и отрисовка
+
+Плееры и временные шкалы массивов используют тот же формат кадра, что и универсальное
+воспроизведение: `previous`, `current`, `progress`, `stepIndex` и `event`.
+Кадр описывает переход к текущему шагу; состояние шага соответствует состоянию
+после выполнения его операции.
+
+| API | Поведение |
+| --- | --- |
+| `createArrayPlayer(iterable, options)` | Воспроизведение массива; распознаёт событие `done` |
+| `createPlayer(iterable, options)` | Универсальное воспроизведение; требует `isTerminal(step)` |
+| `createArrayTimeline(steps, timing)` / `createTimeline(steps, timing)` | Сохранённая история с `durationMs` и `sample(timeMs)` |
+| `createArrayRenderer({ theme: "dark" \| "light" })` | Отрисовка полного кадра массива на Canvas |
+| `createSceneRenderer(handlers)` | Передаёт собственные объекты вашим обработчикам визуализации |
+| `createSceneProjector(project)` | Преобразует неизменяемые состояния перехода в сцены с ограниченным кэшем |
+
+Плеер читает первый шаг при создании и предоставляет `frame`, `advance(deltaMs)`,
+`finished` и `dispose()`. У начального кадра progress равен 1.
+`advance` принимает конечное неотрицательное прошедшее время воспроизведения;
+ноль не читает новые шаги. Для паузы не вызывайте продвижение. Для изменения скорости
+умножайте прошедшее время. Необязательный `render` вызывается при создании и каждом advance.
+
+Источник должен дойти до завершающего шага. Плеер закрывает итератор после последнего
+перехода и переходит в finished после `finalHoldMs`. Преждевременное окончание,
+ошибки источника и отрисовки передаются вызывающему коду и закрывают итератор.
+`dispose()` закрывает его досрочно и допускает повторные вызовы; кадр остаётся доступен,
+но продвижение освобождённого плеера вызывает исключение. Для перезапуска создайте
+новые итератор и плеер.
+
+Временной шкале нужен массив шагов. Шаг i завершается в `i * stepDurationMs`;
+`finalHoldMs` продлевает последний кадр. Выборка ограничивает конечное время диапазоном
+шкалы и отвергает неконечные значения. При воспроизведении генератора нет перемотки
+и заранее известной общей длительности.
+
+Планированием анимации управляет приложение. Например:
+
+```js
+const player = createArrayPlayer(reverse.iterate([1, 2, 3, 4]), options);
+let last;
+let requestId;
+let paused = false;
+let speed = 1;
+
+function tick(now) {
+    const delta = last === undefined ? 0 : Math.min(100, now - last);
+    last = now;
+    if (!paused) player.advance(delta * speed);
+    renderer.render(ctx, player.frame);
+    if (!player.finished) requestId = requestAnimationFrame(tick);
+}
+requestId = requestAnimationFrame(tick);
+// On teardown: cancelAnimationFrame(requestId); player.dispose();
+// To replay after finishing, create a new player and schedule a new loop.
+```
+
+Это альтернатива настройке плеера из предыдущего примера с массивом; здесь используются
+его `reverse`, `options`, `ctx` и `renderer`. Большие интервалы времени синхронно читают
+промежуточные шаги, поэтому ограничивайте delta или приостанавливайте скрытые вкладки,
+чтобы избежать долгого наверстывания.
+
+Рендерер массива ожидает неизменяемые снимки. Для раскладки он использует размеры
+битовой карты Canvas, рисует полный кадр и восстанавливает состояние контекста.
+Высота столбца отрицательного значения определяется его модулем, а подпись сохраняет
+знак; это не график со знаковой осью. В плотных диаграммах подписи скрываются.
+Для записи используйте canvas с фиксированными размерами экспорта.
+Отрисовка не запускает цикл анимации и не записывает видео.
+
+#### Пользовательские цвета массива (с 0.8.0)
+
+Версия 0.8.0 принимает частичное переопределение палитры в `createArrayRenderer`
+и совместимом псевдониме `createSortRenderer`:
+
+```ts
+import { createArrayRenderer, type ArrayPaletteOverrides } from '@grundyjs/algiviz/canvas';
+const colors: ArrayPaletteOverrides = { background: '#ffffff', text: '#182230', active: '#e87900' };
+const renderer = createArrayRenderer({ theme: 'light', colors });
+renderer.render(ctx, currentFrame);
+```
+
+`ArrayPalette` задаёт шесть строковых ролей: `background` (весь canvas), `text`
+(все подписи), `bar` (обычные столбцы), `sorted` (отсортированный префикс/суффикс),
+`active` (подсвеченные, сравниваемые или перемещаемые элементы) и `held` (удерживаемый
+элемент; приоритет выше active и sorted). `ArrayPaletteOverrides` — частичная форма
+палитры, `ArrayRendererOptions` описывает объект настроек. Значения — строки цветов
+Canvas, передаваемые без CSS-проверки. Для пропущенных ролей и `undefined` используется
+выбранная тема. Вызовы только с темой и стандартные цвета не изменились.
+
+Переопределения копируются при создании рендерера. Последующее изменение входного
+объекта не влияет на результат. Для смены темы или палитры создайте новый рендерер
+и нарисуйте тот же текущий кадр. Меняются только цвета, но не воспроизведение,
+снимки, раскладка или обработка bitmap/DPR. Попробуйте темы, шесть полей выбора цвета
+и сброс в [лаборатории сортировок](../examples/index.html).
+
+## Память и стоимость генерации
+
+Операции массива копируют входные данные, проверяют конечность чисел и отвергают
+разреженные массивы. `defineArrayAlgorithm` делает это при первом `next()` итератора,
+а `createArrayTrace` — сразу. Каждый итератор владеет своим рабочим состоянием.
+Шаги массива, события, снимки и элементы заморожены; неизменяемые элементы могут
+быть общими у нескольких снимков.
+
+Воспроизведение генератора сохраняет соседние снимки, а не всю историю. Поэтому для
+массива требуется O(n) памяти снимков, если вызывающий код не хранит старые кадры.
+Произвольные состояния и внутренние структуры алгоритма могут иметь другую стоимость.
+Каждый полный снимок массива всё равно копирует n позиций: ленивость уменьшает
+хранимую историю, а не стоимость каждого шага. Сбор всех шагов возвращает затраты на
+историю. Например, трасса квадратичной сортировки со снимками размера O(n) может
+потребовать O(n³) времени и памяти истории. Итерация синхронна и может блокировать UI.
+
+## Примеры в браузере
+
+Соберите проект, раздайте корень репозитория статическим HTTP-сервером и откройте
+одну из страниц ниже. Примеры — код приложения в репозитории;
+в npm-архив они не входят.
+
+| Пример | Что демонстрирует |
+| --- | --- |
+| [Как рождается кадр](https://github.com/urffin/algiviz/blob/master/examples/visualization-pipeline.html) | Путь от генератора через плеер и сцену к отрисовке, показанный средствами AlgiViz |
+| [Лаборатория сортировок](../examples/index.html) | Сортировки вставками и пузырьком с операциями массива и готовым рендерером |
+| [Сортировка слиянием](../examples/merge.html) | Собственное состояние и сцена из двух строк для основного массива и буфера |
+| [Разбиения быстрой сортировки](../examples/quick.html) | Разбиения Ломуто и трёхстороннее с собственными состоянием и сценой |
+| [Пирамидальная сортировка](../examples/heap.html) | Построение max-heap и извлечение с согласованными идентификаторами элементов дерева и массива |
+| [Бинарный поиск](../examples/binary-search.html) | Первое вхождение в отсортированном массиве, замкнутый интервал поиска и ленивое воспроизведение |
+| [BFS графа](../examples/graph.html) | Очередь, слои, кратчайшие пути, недостижимая цель и история/генератор |
+| [DFS графа](../examples/dfs.html) | Стек вызовов, возвраты, глубина и путь дерева; история/генератор |
+| [Обход дерева](../examples/tree.html) | Собственные узлы, рёбра и указатель с Canvas и SVG с сохранением элементов |
+
+Все примеры используют общие [demo-player.mjs](../examples/demo-player.mjs) и
+[player-settings.mjs](../examples/player-settings.mjs): 650 мс на шаг, удержание последнего
+кадра 1 000 мс, скорости от 0,25× до 32×, воспроизведение/пауза, перезапуск и переходы
+по шагам. История позволяет идти назад и перематывать; режим генератора отключает
+обе возможности. При reduced motion интерполяция отключается, скрытые вкладки
+приостанавливают воспроизведение.
+
+Все примеры сортировок принимают до **64 конечных значений с историей** или **2 000
+в режиме генератора**. Введите значения или создайте массив заданной длины в порядке
+Random, Sorted или Reverse. Это ограничения демонстраций, а не библиотеки. Для
+переключения большого массива на историю сначала загрузите массив допустимой длины.
+Плотные диаграммы скрывают подписи; примеры с собственными сценами сортировок
+показывают в текстовом статусе первые 24 ячейки.
+
+### Сортировка слиянием
+
+[Алгоритм](../examples/merge-algorithm.mjs) и [рендерер](../examples/merge-scene.mjs)
+используют `/playback` и `/scene`. Равные значения получают буквенные суффиксы,
+чтобы показать устойчивость. Ячейки используют ID строки и позиции, поскольку
+копирование из буфера временно дублирует идентичности элементов. При равенстве
+выбирается левый элемент. Алгоритм использует O(n) дополнительной памяти;
+верхняя граница памяти полной истории снимков — O(n² log n).
+
+### Быстрая сортировка
+
+Выбирайте разбиение Ломуто или трёхстороннее, сохраняя загруженные значения.
+Оба алгоритма и их сцена находятся в примере. Трёхсторонняя рекурсия пропускает
+область равных: для n ≥ 2 одинаковых элементов нужны 2n скалярных проверок и ноль
+обменов, а для этого варианта Ломуто — n(n−1)/2 проверок. Ни один вариант не
+гарантирует устойчивость. В худшем случае время квадратичное, рекурсия может
+потребовать O(n) памяти стека. Отдельная верхняя граница памяти полной истории — O(n³).
+
+### Пирамидальная сортировка
+
+[Алгоритм](../examples/heap-algorithm.mjs) определяет неизменяемые состояния и события.
+[Сцена](../examples/heap-scene.mjs) задаёт каждому элементу отдельные визуальные ID в
+дереве и массиве и использует публичную проекцию сцен с состояниями, независимыми
+от размера экрана. Позиции дерева фиксированы при уменьшении кучи. До 15 ячеек
+массива переносятся на узких экранах; более крупные массивы используют плотную строку
+без нечитаемых подписей. Построение снизу вверх занимает O(n), сортировка в худшем
+случае — O(n log n), итеративный алгоритм на месте использует O(1) дополнительной
+памяти. Эта демонстрация копирует вход и хранит O(n) данных соседних снимков в режиме
+генератора; полная история может потребовать O(n² log n).
+Сортировка неустойчива: [2a, 2b, 1] превращается в [1, 2b, 2a].
+
+### Бинарный поиск
+
+[Алгоритм](../examples/binary-search-algorithm.mjs) находит первое вхождение, в том числе
+при дубликатах. При равенстве сохраняется кандидат и поиск продолжается слева.
+Входной массив должен быть отсортирован; неверный ввод сохраняет текущий сеанс.
+Можно генерировать отсортированные массивы заданной длины с общими ограничениями
+режимов истории и генератора. Счётчик учитывает проверенные средние элементы.
+
+[Сцена](../examples/binary-search-scene.mjs) использует стабильные ID по индексам и
+проекцию, независимую от размера экрана. До 32 ячеек переносятся; более крупные
+массивы отображаются плотной полосой без нечитаемых подписей. Поиск занимает
+O(log n) времени и O(1) дополнительной памяти алгоритма. Демонстрация проверяет
+и копирует вход за O(n), разделяет замороженный массив между снимками и хранит
+O(n + log n) данных истории. Пример не входит в npm-пакет и не требует нового экспорта.
+
+### Обход дерева
+
+Пример определяет собственные типы `node`, `edge` и `pointer`. Указатель проходит
+по рёбрам через общих предков между посещаемыми узлами. Выбор Renderer переключает
+Canvas и SVG без перезапуска воспроизведения. [tree-svg.mjs](../examples/tree-svg.mjs)
+сохраняет элементы по ID, восстанавливает порядок слоёв и удаляет устаревшие элементы,
+даже если перемотка пропустила переход исчезновения. Специальные алгоритм и рендерер
+дерева в пакет не добавляются.
+
+### Обход графа в ширину
+
+Откройте [examples/graph.html](../examples/graph.html), выберите граф, старт и
+необязательную цель, затем нажмите Apply. BFS отмечает вершины при добавлении в
+очередь, полностью обходит достижимую компоненту и восстанавливает один кратчайший
+путь по предкам. Попробуйте изолированную H, путь до старта длиной 0, цепочку или
+ромб с равными путями. Исходный несвязный граф из GIF в README сохранён отдельным
+вариантом.
+
+Сцена показывает неподвижный граф, анимированную очередь, расстояния, рёбра предков
+и пути, отдельные счётчики обнаружения, обработки и просмотров соседей. На узком
+экране очередь переносится под граф. Canvas использует логические координаты и DPR.
+Поддержка петель и параллельных рёбер сохранена; порядок соседей может изменить
+выбранный кратчайший путь, но не его длину.
+
+Оба режима воспроизведения используют один генератор с неизменяемыми состояниями.
+Перезапуск и смена режима используют применённые граф/старт/цель, а не черновые поля.
+Генератор вычисляет шаги лениво, без предварительного сбора истории. Полная история
+позволяет перематывать назад и имеет отдельную верхнюю границу памяти снимков
+O(V(V + E)), помимо хранения графа и данных алгоритма.
+
+В [разборе собственного примера графа](../docs/custom-graph-example.md) описаны границы
+алгоритма, проекции и рендерера. Пример использует существующий публичный API
+и не добавляет специальные экспорты для графов.
+
+### Обход графа в глубину
+
+Откройте [examples/dfs.html](../examples/dfs.html), чтобы сравнить DFS и BFS
+на одинаковых графах. Выберите граф, старт и необязательную цель. Каждый явный
+кадр вызова хранит курсор следующего соседа; вершина отмечается до входа.
+Возврат снимает завершённый вызов и возобновляет родителя. Стек содержит только
+активную ветку обхода.
+
+Порядок обнаружения по умолчанию — A, B, D, G, E, C, F; возвратов — F, C, E, G, D, B, A.
+Путь дерева DFS до F содержит 6 рёбер; BFS находит A → C → F длиной 2 ребра.
+Глубина дерева DFS не является кратчайшим расстоянием. H недостижима.
+Путь восстанавливается после полного обхода. Допустимы простые неориентированные
+графы; петли и параллельные рёбра отклоняются. Порядок соседей соответствует входу.
+
+На узком экране стек фиксированной вместимости переносится под граф.
+Canvas использует логические координаты и DPR. Оба режима используют один
+неизменяемый генератор и [общий плеер](../examples/demo-player.mjs); перезапуск
+повторяет применённые входные данные. Генератор вычисляет шаги лениво,
+история позволяет перематывать назад. Обход занимает O(V + E) времени и O(V)
+дополнительной памяти; верхняя граница памяти истории снимков отдельно составляет
+O(V(V + E)). Новые API графа или встроенный DFS в пакет не добавляются.
+
+## Разработка
+
+Требуются Node.js 22 или новее и npm.
+
+```sh
+npm ci
+npm test
+npm run test:package
+```
+
+`npm test` собирает библиотеку, проверяет TypeScript-примеры и запускает тесты.
+`npm run test:package` собирает архив, устанавливает его без сети в изолированное
+временное приложение, компилирует код с установленными декларациями и проверяет
+публичный API, включая отказ для удалённого экспорта `/core`.
+Затем временное приложение удаляется.
+
+GitHub Actions запускает обе проверки при push в `master` и в pull request,
+используя Node.js 22 и 24 на Linux и Windows. Проверки CI не публикуют пакеты.
+
+`npm pack` автоматически пересобирает пакет. Архив включает dist, README, LICENSE,
+CHANGELOG и метаданные пакета. Исходный код и задачи:
+[urffin/algiviz](https://github.com/urffin/algiviz). Лицензия MIT.
+
+### Проверки производительности
+
+Запустите `npm run benchmark` для массивов из 2 000 элементов: сортировки вставками,
+пузырьком, слиянием и оба варианта быстрой сортировки. Отчёт показывает генерацию
+1 000 шагов, медиану CPU-времени отрисовки по пяти выборкам из 100 кадров и занятую
+кучу Node после каждых 5 000 шагов до 25 000. Canvas заменён заглушкой: это сравнение
+CPU, а не измерение FPS браузера или GPU. Замеры кучи используют явную сборку мусора
+и включают процесс Node; это диагностика, а не универсальные пороги прохождения теста.
+
+## Выпуск версии
+
+Публикация выполняется сопровождающим проекта. Обновите версию пакета, lockfile
+и changelog; запустите `npm test` и `npm run test:package`, сделайте коммит,
+отправьте его и проверьте CI для этого коммита.
+
+[Workflow публикации](../.github/workflows/npm-publish.yml) запускается при публикации
+стабильного GitHub Release. Черновики, предварительные релизы и отправка одного
+лишь тега пакет не публикуют. Используйте `v` и точную версию пакета, например
+`v0.8.0`, на проверенном коммите.
+
+Workflow использует Node.js 24 и npm 11, проверяет версию и приложение с упакованным
+пакетом, затем публикует с provenance через npm trusted publishing (OIDC).
+Жизненный цикл публикации также запускает тесты и пересборку.
+Секрет `NPM_TOKEN` не требуется.
+
+Trusted publisher в npm должен соответствовать владельцу GitHub `urffin`,
+репозиторию `algiviz` и workflow `npm-publish.yml`. GitHub environment не используется.
+См. [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+После публикации проверьте запуск Actions и точную версию в npm.
+Никогда не используйте повторно уже опубликованную версию npm. Если workflow завершился
+ошибкой, проверьте, успел ли пакет опубликоваться, прежде чем запускать его повторно.