@grundyjs/algiviz 0.8.1 → 0.8.3

package/README.md

@@ -4,13 +4,6 @@
 
 **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)
-
-*An application-owned BFS algorithm with custom objects. Exported with
-[CanvasTake](https://github.com/urffin/canvas-take) —
-[try an interactive sorting demo](https://grundyjs.ru/algorithms/insertion-sort/)
-or explore the [BFS source](https://github.com/urffin/algiviz/blob/master/examples/graph-demo.mjs).*
-
 A TypeScript toolkit for building interactive algorithm explanations. Write your
 algorithm as a generator, emit immutable states and choose how your objects look.
 AlgiViz handles playback and scene matching; optional array operations and a Canvas
@@ -19,7 +12,7 @@ renderer help you get started.
 [Live sorting demo](https://grundyjs.ru/algorithms/insertion-sort/) ·
 [Library overview](https://grundyjs.ru/algiviz/) ·
 [npm package](https://www.npmjs.com/package/@grundyjs/algiviz) ·
-[Minimal example source](https://github.com/urffin/algiviz/blob/master/examples/minimal.mjs)
+[Minimal example source](https://github.com/urffin/algiviz/blob/master/examples/visualization-pipeline.html)
 
 - **Your algorithm:** control the loops, conditions and order of operations.
 - **Your objects:** define custom types and handlers for Canvas, SVG or another target.
@@ -30,33 +23,7 @@ renderer help you get started.
 
 Use it for educational demos, interactive articles and algorithm walkthroughs.
 Algorithms and layouts belong to your application; AlgiViz provides the playback
-and rendering API. This README describes version 0.8.1.
-
-## 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:
-
-```js
-import { createTokenPlayer } from './minimal.mjs';
-
-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.
-```
-
-[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).
+and rendering API.
 
 ## Install
 
@@ -68,522 +35,122 @@ There is no root entry point or CommonJS build. Import the modules you need:
 `/array`, `/playback`, `/scene` and `/canvas`.
 
 Algorithms live in application code and examples.
-For new integrations, use the APIs below. Version 0.x may introduce breaking changes
+Version 0.x may introduce breaking changes
 in minor releases; consult [CHANGELOG.md](CHANGELOG.md) when updating.
 
-## User-defined algorithms
+## Start with one custom object
 
+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.
 
-New applications use these entry points, which do not import bundled algorithms:
+![Minimal AlgiViz example: code, sequential call highlighting and Canvas state](https://raw.githubusercontent.com/urffin/algiviz/master/docs/assets/minimal.gif)
 
-- `@grundyjs/algiviz/array`: array operations and generator definitions.
-- `@grundyjs/algiviz/playback`: generic playback of any immutable states and events.
-- `@grundyjs/algiviz/scene`: typed objects and user-provided visualizations.
-- `@grundyjs/algiviz/canvas`: the ready-made array renderer.
+*Actual example calls replayed slowly. The dot changes position at the drawing stage. [Explore the interactive walkthrough](https://github.com/urffin/algiviz/blob/master/examples/visualization-pipeline.html).*
 
-You own the loops, conditions and operation order. No library registration or
-changes to AlgiViz are required. For example, reversing an array:
+```html
+<canvas width="600" height="160"></canvas>
+<button id="next">Next state</button>
+```
 
 ```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);
+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' };
     }
-    yield array.done();
+}
+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 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)
+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);
+    },
 });
-// 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` returns `iterate(values)` and `steps(values)`. Each
-iterator owns a separate workspace and copies/validates input on the first
-`next()`. `steps` collects the iterator into a frozen array. Yield every
-operation immediately, begin with `start`, and end with `done`. Each operation
-updates the workspace and returns an immutable snapshot; it does not draw.
-The player invokes the supplied `render` initially and on every `advance`.
-Rendering errors close the iterator and propagate to the caller.
-
-### Array operations
-
-| Operation | Effect |
-| --- | --- |
-| `at(index)`, `held`, `length` | Read a frozen item, the held item or array length |
-| `start(regions?)` | Emit initial state; call once |
-| `compare(left, right)` | Highlight two positions and count one comparison; either position can be `"held"` |
-| `highlight(positions)` | Highlight items for this step without changing counters |
-| `swap(left, right, regions?)` | Exchange occupied positions; count two writes (non-adjacent swaps are supported) |
-| `select(from, regions?)` | Hold an item and leave a hole; no counted writes |
-| `shift(from, to, regions?)` | Move an item into the hole; count one write |
-| `insert(to, regions?)` | Fill the hole with the held item; count one write |
-| `pass(end, regions?)` | Describe a completed pass without changing items or counters |
-| `done(regions?)` | Finish; requires no held item; does not sort or infer sorted regions |
-
-`regions` can contain `sortedPrefixLength` and `sortedSuffixLength`.
-Omitted markers retain their previous values. The author decides when regions
-are sorted; AlgiViz validates their bounds but does not prove that claim. Positions
-are zero-based; invalid positions, occupied destinations and invalid operation
-order throw before mutating the workspace. Read snapshots rather than modifying
-items yourself. `createArrayTrace(values)` exposes the same operations directly,
-with immediate input validation, for authors writing their own generator wrapper.
-
-Insertion and bubble sort implementations live in [examples/algorithms.mjs](examples/algorithms.mjs).
-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 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:
-
-```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)
-});
-```
-
-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
-engine does not clone or freeze user states; that is the source's responsibility.
-It retains adjacent snapshots only; the timeline retains the supplied history.
-Custom array events or tree/graph operations can use this contract and a custom
-renderer. The scene API below dispatches individual objects; there is no built-in
-graph/tree algorithm or operation set.
-
-### Playback contracts
-
-Playback retains application snapshots without cloning them; keep steps, state and
-events immutable while they are in use. A timeline copies the input array only.
-Timeline timing follows array position, and finite sample times are clamped to its
-range. Generator playback requires an explicit terminal step; an early end throws.
-`dispose()` closes the source at most once, keeps the last frame readable and
-prevents further advancement. Restart uses a fresh source.
-
-Version 0.7.0 makes timeline `stepIndex` preserve the source `step.index`,
-matching the player. If source consumption, a terminal predicate or rendering
-throws, cleanup is attempted without replacing that primary error. A standalone
-cleanup error from disposal or normal completion still propagates.
-
-### Step emission helper (since 0.6.0)
-
-Version 0.6.0 adds `createStepEmitter` from `/playback`. It removes manual step numbering and freezes the step wrapper:
-
-```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');
-}
+document.querySelector('#next').onclick = () => player.advance(1000);
 ```
 
-Create the emitter inside each iterator. Its callback runs once per emission;
-indices start at zero and failed captures do not consume an index. The helper
-does not clone or freeze state/event data, infer terminal events or store history.
-The callback must produce isolated immutable snapshots; immutable shared structures
-can be reused. Returning a mutable workspace directly does not make it a snapshot.
+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.
 
-### User-defined objects and visualizations
+[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 [local setup instructions](https://github.com/urffin/algiviz/blob/master/docs/minimal-example.md).
 
-Define a type map with your own data, then
-provide a visualization for every type. AlgiViz matches identities and dispatches
-objects; your handlers decide how data becomes geometry and how it interpolates.
+## How it works
 
-```ts
-import { createSceneRenderer, type Scene } from "@grundyjs/algiviz/scene";
+- **Algorithm:** a generator emits independent state snapshots.
+- **Player:** requests steps and passes frames to your rendering callback.
+- **Scene:** describes objects with stable IDs, types and application-owned data.
+- **Handler:** chooses geometry and drawing behavior, including interpolation.
 
-interface MyObjects {
-    badge: { x: number; y: number; label: string };
-}
+Do not mutate emitted states. Players require an explicit terminal step;
+call `dispose()` when removing a visualization. Algorithms, layouts and animation
+scheduling belong to the application.
 
-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(); }
-    }
-});
+## Playback modes
 
-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"
-});
-```
+| | Generator: `createPlayer` | History: `createTimeline` |
+| --- | --- | --- |
+| Steps | Consumed on demand | Collected up front |
+| Retention | Adjacent snapshots | Complete history |
+| Seeking backward | No | Yes, via `sample(timeMs)` |
+| Total duration | Unknown in advance | Available |
 
-- An object has a non-empty stable `id`, a `type`, user-defined `data` and an
-  optional finite `zIndex` (default zero). IDs are unique within a snapshot. A
-  retained ID cannot change type; use a new ID to replace an object of another type.
-- Handlers receive `previous` and `current` objects, with `null` for a missing
-  endpoint. `phase` is `enter`, `update` or `exit`. `progress` is the raw 0–1 frame
-  progress. `presence` is progress on entry, 1 on update and 1−progress on exit;
-  handlers may use it for opacity or scale. It is not applied automatically.
-- Lower `zIndex` draws first. Ties follow the current snapshot's object order;
-  removed objects follow in their previous order. The current layer wins when it
-  changes. There is no implicit layout or coordinate system.
-- The third handler argument exposes `scene.get(id)` for links, pointers and other
-  references. It returns the referenced object's full transition, including both
-  endpoints; missing references return `undefined`. The application decides how to
-  handle them and how to interpolate positions or changing targets.
-- `createSceneFrame(frame)` exposes the same resolved transitions without drawing.
-  The registry is captured at renderer construction. Missing handlers, duplicate
-  IDs, invalid progress/layers and changed types fail before any handler is called.
-- Scene processing is stateless, so arbitrary seeking is supported. Handlers may
-  see zero-presence objects. They are frame draws, **not guaranteed lifecycle
-  callbacks**: skipping steps can skip appearances/exits entirely. Clear Canvas
-  each frame; a retained SVG/DOM backend must reconcile its elements against the
-  current frame, removing stale IDs itself. Save/restore Canvas state inside each
-  handler. Exceptions propagate; there is no rollback of drawing already performed.
-- Snapshots and user data are not cloned or deep-frozen. The author owns their
-  immutability, as with generic playback. Scene indexing uses O(n) additional
-  memory and layer ordering O(n log n) time per frame.
-
-`arrayScene(snapshot)` from `/canvas` adapts an array to a `Scene<ArrayObjects>`
-with `bar` objects whose data contains `item`, `index` and `held`. The built-in
-array renderer uses this same dispatcher. You can provide a different `bar`
-visualization using `createSceneRenderer<ArrayObjects, YourContext>`.
-
-### State-to-scene projection
-
-`createSceneProjector` adapts
-playback frames from your state model to scenes without changing the algorithm:
+Generators reduce retained history, not the cost of producing each snapshot.
+[Memory and performance details](https://github.com/urffin/algiviz/blob/master/docs/performance.md).
 
-```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));
-```
+## Modules and documentation
 
-The projection receives only a state, not an event or progress. Use a pure
-function and immutable states/scenes. Endpoints are compared with `Object.is`;
-mutating a retained state or changing captured projection settings will not
-invalidate the cache. Create a new projector when those settings change.
-At most two endpoint projections are retained; seeking to older states may
-recompute them. Events, step indices and progress are preserved. Viewport layout
-and animation belong in render handlers, not in this cached projection.
-The returned frame is frozen; user states and projected scenes are not cloned
-or deep-frozen. Scene validation still happens in the scene renderer.
-The merge example uses this adapter to avoid rebuilding two cell scenes on every
-animation frame. The algorithm, object types and visual behavior remain external.
-
-## Playback and rendering
-
-Array players and timelines use the same frame shape as generic playback:
-`previous`, `current`, `progress`, `stepIndex` and `event`.
-A frame describes the transition into the current step; that step's state is the
-state after its operation.
-
-| API | Behavior |
+| Module | Purpose |
 | --- | --- |
-| `createArrayPlayer(iterable, options)` | Array playback; recognizes the `done` event |
-| `createPlayer(iterable, options)` | Generic playback; requires `isTerminal(step)` |
-| `createArrayTimeline(steps, timing)` / `createTimeline(steps, timing)` | Retained history with `durationMs` and `sample(timeMs)` |
-| `createArrayRenderer({ theme: "dark" \| "light" })` | Full-frame Canvas array rendering |
-| `createSceneRenderer(handlers)` | Dispatches custom objects to your visualization handlers |
-| `createSceneProjector(project)` | Adapts immutable state endpoints to scenes with a bounded cache |
-
-Players read the first step at construction and expose `frame`, `advance(deltaMs)`,
-`finished` and `dispose()`. The initial frame has progress 1.
-`advance` accepts finite, non-negative elapsed playback time; zero consumes no steps.
-Pause by not advancing. Apply speed by multiplying elapsed time.
-The optional render callback runs initially and on every advance.
-
-The source must reach a terminal step. The player closes the iterator after its
-final transition and becomes finished after `finalHoldMs`. Premature exhaustion,
-source errors and render errors propagate and close the iterator.
-`dispose()` closes early and can be repeated; the frame remains readable, but
-advancing a disposed player throws. Restart with a new iterator and player.
-
-Timelines require an array of steps. Step i completes at `i * stepDurationMs`;
-`finalHoldMs` extends the last frame. Sampling clamps finite times to the timeline
-range and rejects non-finite times. There is no seeking or known total duration
-in generator playback.
-
-Animation scheduling belongs to your application. For example:
-
-```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.
-```
-
-This is an alternative to the player setup in the earlier array example, reusing
-its `reverse`, `options`, `ctx` and `renderer`. Large deltas consume intervening steps
-synchronously, so cap elapsed time or pause on hidden tabs to avoid a long catch-up.
+| [`/playback`](https://github.com/urffin/algiviz/blob/master/docs/playback.md) | Steps, players, timelines, termination and lifecycle |
+| [`/scene`](https://github.com/urffin/algiviz/blob/master/docs/scene.md) | Custom types, object matching and projection |
+| [`/array` and `/canvas`](https://github.com/urffin/algiviz/blob/master/docs/array.md) | Array operations, ready-made rendering and palettes |
 
-The array renderer expects immutable snapshots. It uses Canvas bitmap dimensions
-for layout, draws a full frame and restores context state. Negative values use
-magnitude for bar height and retain their sign in labels; this is not a signed-axis
-plot. Dense charts hide labels. For recording, use a canvas with fixed export
-dimensions. Rendering does not start an animation loop or record video.
+[Complete TypeScript example](https://github.com/urffin/algiviz/blob/master/examples/custom-objects.ts) ·
+[Project setup and integration](https://github.com/urffin/algiviz/blob/master/docs/minimal-example.md) ·
+[Custom graph walkthrough](https://github.com/urffin/algiviz/blob/master/docs/custom-graph-example.md)
 
-#### Custom array colors (since 0.8.0)
-
-Version 0.8.0 accepts partial palette overrides on both `createArrayRenderer`
-and its compatible alias `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` defines six string roles: `background` (full canvas), `text`
-(all labels), `bar` (ordinary bars), `sorted` (sorted prefix/suffix), `active`
-(highlighted/compared/moved items), and `held` (the held item, taking precedence
-over active and sorted). `ArrayPaletteOverrides` is its partial form;
-`ArrayRendererOptions` describes the options object. Values are Canvas color
-strings, passed through without CSS validation. Omitted or undefined roles use
-the selected theme. Existing theme-only calls and default colors are unchanged.
-
-Overrides are copied when creating a renderer. Changing the input object later
-has no effect. To switch theme or palette, create a new renderer and render the
-same current frame. This changes colors only, not playback, snapshots, layout or
-bitmap/DPR handling. Try the theme presets, six color inputs and reset control
-in [Sorting lab](examples/index.html).
-
-## Memory and generation cost
-
-Array operations copy the input, validate finite numbers and reject sparse inputs.
-`defineArrayAlgorithm` performs this work on the first iterator `next()`;
-`createArrayTrace` validates immediately. Each iterator owns its workspace.
-Array steps, events, snapshots and items are frozen; immutable items can be shared
-between snapshots.
-
-Generator playback retains adjacent snapshots, not the entire history. Array
-playback therefore uses O(n) snapshot memory if the caller does not retain old
-frames. Generic states and algorithm-specific storage may have different costs.
-Each full array snapshot still copies n slots: laziness reduces retained history,
-not the cost of producing every step. Collecting steps restores the history cost.
-For example, a quadratic sorting trace with O(n)-sized snapshots can take O(n³)
-time and history space. Iteration is synchronous and can block the UI.
-
-## Browser examples
-
-Build the project, serve the repository root with a static HTTP server and open
-one of these pages. Examples are application code in the repository and are not
-included in the npm archive.
+## Examples
 
 | Example | What it demonstrates |
 | --- | --- |
-| [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 |
-| [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
-[player-settings.mjs](examples/player-settings.mjs): 650 ms per step, 1,000 ms final
-hold, speeds 0.25× through 32×, play/pause, restart and step controls.
-History enables backward stepping and seeking; generator mode disables both.
-Reduced motion disables interpolation, and hidden tabs pause playback.
-
-All sorting examples accept up to **64 finite values with history** or **2,000 in
-generator mode**. Enter values or generate an array by count with Random, Sorted or
-Reverse order. These are demo limits, not library restrictions. Switching a large
-array to history requires first loading an array within the history limit.
-Dense charts hide labels; custom sorting examples preview the first 24 cells in
-their text status.
-
-### Merge sort
-
-The [algorithm](examples/merge-algorithm.mjs) and
-[renderer](examples/merge-scene.mjs) use `/playback` and `/scene`.
-Equal values have letter suffixes to demonstrate stability. Cells use row/position
-IDs because copy-back temporarily duplicates item identities. Left wins ties.
-The algorithm uses O(n) auxiliary memory; full snapshot history has an
-O(n² log n) space upper bound.
-
-### Quick sort
-
-Choose Lomuto or three-way partitioning while preserving loaded values.
-Both algorithms and their scene belong to the example. Three-way recursion skips
-the equal band: n ≥ 2 equal items take 2n scalar checks and zero swaps, versus
-n(n−1)/2 checks with this Lomuto variant. Neither variant guarantees stability.
-Worst-case algorithm time is quadratic; recursion can use O(n) stack space.
-Full snapshot history has a separate O(n³) space upper bound.
-
-### Heap sort
-
-The [algorithm](examples/heap-algorithm.mjs) owns immutable states and events.
-The [scene](examples/heap-scene.mjs) assigns separate tree/array visual IDs to each
-element and uses the public scene projector with viewport-independent endpoints.
-Tree positions stay fixed as the heap shrinks. At most 15 array cells wrap on narrow
-screens; larger arrays use a dense row and hide unreadable labels.
-Bottom-up construction is O(n), worst-case sorting O(n log n), and the iterative
-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
-tree edges through shared ancestors between visited nodes. The Renderer selector
-switches between Canvas and SVG without restarting playback.
-[tree-svg.mjs](examples/tree-svg.mjs) retains elements by ID, restores layer order
-and removes stale elements even after seeking skips exit transitions.
-No tree-specific algorithm or renderer is added to the package.
-
-### Graph breadth-first search
-
-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.
-
-```sh
-npm ci
-npm test
-npm run test:package
-```
-
-`npm test` builds the library, checks TypeScript fixtures and runs the tests.
-`npm run test:package` builds a tarball, installs it offline in an isolated temporary
-consumer, compiles against the installed declarations and exercises public APIs,
-including rejection of the removed `/core` export. The temporary consumer is removed afterward.
-
-GitHub Actions runs both checks on pushes to `master` and pull requests, using
-Node.js 22 and 24 on Linux and Windows. CI checks do not publish packages.
-
-`npm pack` rebuilds automatically. The archive includes dist, README, LICENSE,
-CHANGELOG and package metadata. Source and issues:
-[urffin/algiviz](https://github.com/urffin/algiviz). Licensed under MIT.
-
-### Performance checks
-
-Run `npm run benchmark` for 2,000-element insertion, bubble, merge and both quick-sort
-variants. It reports generation of 1,000 steps, median rendering CPU time over five
-100-frame samples and retained Node heap after each 5,000 playback steps, up to
-25,000. Drawing uses a mock Canvas: these are CPU comparisons, not browser FPS or
-GPU measurements. Heap samples use explicit GC and include the Node process;
-they are diagnostics, not portable pass/fail thresholds.
-
-## Release
-
-Publishing is a maintainer action. Update the package version, lockfile and changelog;
-run `npm test` and `npm run test:package`, commit and push, and check CI on the
-candidate commit.
-
-The [publish workflow](.github/workflows/npm-publish.yml) runs when a stable GitHub
-Release is published. Drafts, prereleases and tag pushes alone do not publish.
-Use `v` followed by the exact package version, such as `v0.8.0`, at the tested commit.
-
-The workflow uses Node.js 24 and npm 11, checks the version and packed consumer,
-then publishes with provenance through npm trusted publishing (OIDC).
-The publish lifecycle also runs tests and rebuilds. No `NPM_TOKEN` secret is required.
-
-The npm trusted publisher must match GitHub owner `urffin`, repository `algiviz`
-and workflow `npm-publish.yml`. The workflow does not use a GitHub environment.
-See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
-
-After publication, verify the Actions run and the exact version in npm.
-Never reuse an already published npm version. If a workflow fails, check whether
-publication occurred before deciding whether to rerun it.
+| [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](https://github.com/urffin/algiviz/blob/master/examples/index.html) | Insertion and bubble sort using the array operations and renderer |
+| [Merge sort](https://github.com/urffin/algiviz/blob/master/examples/merge.html) | Custom state and a two-row scene for the main array and buffer |
+| [Quick sort partitions](https://github.com/urffin/algiviz/blob/master/examples/quick.html) | Lomuto and three-way partitioning with custom state and scene |
+| [Heap sort](https://github.com/urffin/algiviz/blob/master/examples/heap.html) | Max-heap construction and extraction with synchronized tree and array identities |
+| [Binary search](https://github.com/urffin/algiviz/blob/master/examples/binary-search.html) | First occurrence in sorted input, closed search intervals and lazy playback |
+| [Graph BFS](https://github.com/urffin/algiviz/blob/master/examples/graph.html) | Queue, layers, shortest paths, unreachable targets and history/generator playback |
+| [Graph DFS](https://github.com/urffin/algiviz/blob/master/examples/dfs.html) | Recursive call frames, backtracking, tree depth and paths; history/generator playback |
+| [Tree traversal](https://github.com/urffin/algiviz/blob/master/examples/tree.html) | Custom nodes, edges and pointer with Canvas and retained SVG backends |
+
+[Full catalog, local setup and algorithm details](https://github.com/urffin/algiviz/blob/master/docs/examples.md).
+Examples live in the repository and are not included in the npm package.
+
+## Development and license
+
+[Contributing](https://github.com/urffin/algiviz/blob/master/CONTRIBUTING.md) ·
+[Changelog](https://github.com/urffin/algiviz/blob/master/CHANGELOG.md) ·
+[Report an issue](https://github.com/urffin/algiviz/issues)
+
+Licensed under [MIT](https://github.com/urffin/algiviz/blob/master/LICENSE). Minor releases in 0.x may change the API.