@grundyjs/algiviz 0.8.2 → 0.8.3

package/ru/README.md

@@ -4,13 +4,6 @@
 
 **Ваши алгоритмы и объекты. Пошаговое воспроизведение и собственная отрисовка.**
 
-![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 управляет воспроизведением и сопоставляет объекты сцен; операции над массивами
@@ -19,7 +12,7 @@ AlgiViz управляет воспроизведением и сопостав
 [Интерактивная сортировка](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)
+[Исходный код минимального примера](https://github.com/urffin/algiviz/blob/master/examples/visualization-pipeline.html)
 
 - **Ваш алгоритм:** вы управляете циклами, условиями и порядком операций.
 - **Ваши объекты:** определяйте собственные типы и обработчики для Canvas, SVG или другой среды отрисовки.
@@ -30,7 +23,19 @@ AlgiViz управляет воспроизведением и сопостав
 
 Используйте библиотеку для учебных примеров, интерактивных статей и пошаговых разборов.
 Алгоритмы и расположение объектов остаются в приложении; AlgiViz предоставляет API
-воспроизведения и отрисовки. Этот README описывает версию 0.8.2.
+воспроизведения и отрисовки.
+
+## Установка
+
+```sh
+npm install @grundyjs/algiviz
+```
+
+У пакета нет корневой точки входа и сборки CommonJS. Импортируйте нужные модули:
+`/array`, `/playback`, `/scene` и `/canvas`.
+
+Алгоритмы находятся в коде приложения и примерах. В версии 0.x минорные релизы могут нарушать обратную совместимость;
+при обновлении сверяйтесь с [CHANGELOG.md](../CHANGELOG.md).
 
 ## Начните с одного собственного объекта
 
@@ -39,6 +44,10 @@ AlgiViz управляет воспроизведением и сопостав
 Добавьте Canvas и кнопку в HTML, а JavaScript ниже подключите как модуль через
 сборщик, разрешающий импорты установленного npm-пакета.
 
+![Минимальный пример AlgiViz: код, последовательная подсветка вызовов и состояние Canvas](https://raw.githubusercontent.com/urffin/algiviz/master/docs/assets/minimal.gif)
+
+*Реальные вызовы примера показаны замедленно. Точка меняет позицию на этапе отрисовки. [Открыть интерактивный разбор](https://github.com/urffin/algiviz/blob/master/examples/visualization-pipeline.html).*
+
 ```html
 <canvas width="600" height="160"></canvas>
 <button id="next">Следующее состояние</button>
@@ -82,571 +91,64 @@ document.querySelector('#next').onclick = () => player.advance(1000);
 
 [Интерактивный разбор с последовательной подсветкой кода](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).
+Это страница примера в репозитории; запускайте её по [инструкции локальной настройки](https://github.com/urffin/algiviz/blob/master/docs/minimal-example.md).
 
-## Собственные алгоритмы
+## Как это устроено
 
-Новые приложения используют следующие точки входа, не импортирующие готовые алгоритмы:
+- **Алгоритм** выдаёт независимые снимки состояния через генератор.
+- **Плеер** запрашивает шаги и передаёт кадр вашей функции отрисовки.
+- **Сцена** описывает объекты: стабильный `id`, тип и собственные данные.
+- **Обработчик** выбирает геометрию и способ рисования. Плавность — его решение.
 
-- `@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();
-});
+Состояния после выдачи нельзя изменять. Плееру нужен явный завершающий шаг;
+при удалении визуализации вызовите `dispose()`. Алгоритмы, раскладка и цикл
+анимации принадлежат приложению.
 
-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));
-```
+| | Генератор: `createPlayer` | История: `createTimeline` |
+| --- | --- | --- |
+| Получение шагов | По мере продвижения | Все шаги заранее |
+| Хранение | Соседние снимки | Вся история |
+| Перемотка назад | Нет | Да, через `sample(timeMs)` |
+| Общая длительность | Заранее неизвестна | Доступна |
 
-`defineArrayAlgorithm` возвращает `iterate(values)` и `steps(values)`. Каждый итератор
-владеет отдельным рабочим состоянием, копирует и проверяет входные данные при первом
-`next()`. `steps` собирает итератор в замороженный массив. Выдавайте результат каждой
-операции сразу через `yield`, начинайте с `start` и заканчивайте `done`. Операция
-обновляет рабочее состояние и возвращает неизменяемый снимок, но ничего не рисует.
-Плеер вызывает переданный `render` при создании и каждом `advance`.
-Ошибки отрисовки закрывают итератор и передаются вызывающему коду.
+Генератор сокращает хранимую историю, но не стоимость создания каждого снимка.
+[Подробнее о памяти](https://github.com/urffin/algiviz/blob/master/docs/ru/performance.md).
 
-### Операции над массивом
+## Модули и документация
 
-| Операция | Действие |
+| Модуль | Назначение |
 | --- | --- |
-| `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()` или штатном завершении по-прежнему передаётся вызывающему коду.
+| [`/playback`](https://github.com/urffin/algiviz/blob/master/docs/ru/playback.md) | Шаги, плеер, история, завершение и жизненный цикл |
+| [`/scene`](https://github.com/urffin/algiviz/blob/master/docs/ru/scene.md) | Собственные типы, сопоставление объектов и проекция |
+| [`/array` и `/canvas`](https://github.com/urffin/algiviz/blob/master/docs/ru/array.md) | Операции массива, готовый рендерер и палитра |
 
-### Вспомогательная функция выдачи шагов (с 0.6.0)
+[Полный пример TypeScript](https://github.com/urffin/algiviz/blob/master/examples/custom-objects.ts) ·
+[Настройка проекта и интеграция](https://github.com/urffin/algiviz/blob/master/docs/minimal-example.md) ·
+[Разбор собственных объектов графа](https://github.com/urffin/algiviz/blob/master/docs/custom-graph-example.md)
 
-В версии 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 для этого коммита.
+| [Лаборатория сортировок](https://github.com/urffin/algiviz/blob/master/examples/index.html) | Сортировки вставками и пузырьком с операциями массива и готовым рендерером |
+| [Сортировка слиянием](https://github.com/urffin/algiviz/blob/master/examples/merge.html) | Собственное состояние и сцена из двух строк для основного массива и буфера |
+| [Разбиения быстрой сортировки](https://github.com/urffin/algiviz/blob/master/examples/quick.html) | Разбиения Ломуто и трёхстороннее с собственными состоянием и сценой |
+| [Пирамидальная сортировка](https://github.com/urffin/algiviz/blob/master/examples/heap.html) | Построение max-heap и извлечение с согласованными идентификаторами элементов дерева и массива |
+| [Бинарный поиск](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/tree.html) | Собственные узлы, рёбра и указатель с Canvas и SVG с сохранением элементов |
 
-[Workflow публикации](../.github/workflows/npm-publish.yml) запускается при публикации
-стабильного GitHub Release. Черновики, предварительные релизы и отправка одного
-лишь тега пакет не публикуют. Используйте `v` и точную версию пакета, например
-`v0.8.0`, на проверенном коммите.
+[Полный каталог, локальный запуск и особенности алгоритмов](https://github.com/urffin/algiviz/blob/master/docs/ru/examples.md).
+Примеры находятся в репозитории и не входят в npm-пакет.
 
-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/).
+[Участие в разработке](https://github.com/urffin/algiviz/blob/master/ru/CONTRIBUTING.md) ·
+[История изменений](https://github.com/urffin/algiviz/blob/master/CHANGELOG.md) ·
+[Сообщить об ошибке](https://github.com/urffin/algiviz/issues)
 
-После публикации проверьте запуск Actions и точную версию в npm.
-Никогда не используйте повторно уже опубликованную версию npm. Если workflow завершился
-ошибкой, проверьте, успел ли пакет опубликоваться, прежде чем запускать его повторно.
+Лицензия [MIT](https://github.com/urffin/algiviz/blob/master/LICENSE). В версии 0.x минорные релизы могут менять API.