@grundyjs/algiviz 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.8.0 — 2026-10-19
+
+- Add partial custom colors to the Canvas array renderer and its compatible alias,
+  with exported ArrayPalette, ArrayPaletteOverrides and ArrayRendererOptions types.
+- Preserve theme defaults and isolate copied overrides per renderer instance.
+- Add theme presets, six color controls and palette reset to Sorting lab without
+  restarting playback or changing the current frame.
+
+## 0.7.1 — 2026-10-15
+
+- Update package description and keywords for custom algorithm visualizations.
+- Improve the README introduction, demo links and standalone integration guide.
+- Add a BFS GIF preview exported with CanvasTake, hosted on GitHub.
+- No runtime API or behavior changes.
+
 ## 0.7.0 — 2026-10-15
 
 - Breaking: remove the deprecated /core entry point and bundled insertion/bubble

package/README.md

@@ -1,19 +1,56 @@
 # AlgiViz
 
-A TypeScript toolkit for user-defined algorithm visualizations. You write the
-algorithm and define your objects; AlgiViz provides array operations, playback,
-typed scene dispatch and a ready-made Canvas array renderer. No runtime dependencies.
-Playback works without DOM, React or Next.js. ESM only, with TypeScript declarations.
+**Your algorithms and objects. Step-by-step playback and custom rendering.**
 
-This README describes version 0.7.0.
+![BFS from A: custom graph vertices, edges and queue animated with AlgiViz](https://raw.githubusercontent.com/urffin/algiviz/master/docs/assets/bfs.gif)
 
-## Minimal custom object
+*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).*
 
-Start with [the standalone example](examples/minimal.html) and its
-[complete module](examples/minimal.mjs). It defines a custom token, emits immutable
-steps and draws interpolated positions using only public package imports.
-No shared demo controller is needed. See [the walkthrough](docs/minimal-example.md)
-for running it in your own application.
+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
+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)
+
+- **Your algorithm:** control the loops, conditions and order of operations.
+- **Your objects:** define custom types and handlers for Canvas, SVG or another target.
+- **Two playback modes:** retain history for seeking, or consume a generator with
+  only adjacent snapshots retained by the player.
+- **No runtime dependencies:** ESM and TypeScript declarations; playback works
+  without DOM, React or Next.js.
+
+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.
+
+## 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).
 
 ## Install
 
@@ -328,7 +365,33 @@ magnitude for bar height and retain their sign in labels; this is not a signed-a
 plot. Dense charts hide labels. For recording, use a canvas with fixed export
 dimensions. Rendering does not start an animation loop or record video.
 
-### Memory and generation cost
+#### 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()`;
@@ -462,7 +525,7 @@ 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.7.0`, at the tested commit.
+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).

package/dist/canvas/index.d.ts

@@ -10,10 +10,23 @@ export type ArrayObjects = {
 };
 /** Adapts array identities to the same public scene contract used by custom objects. */
 export declare function arrayScene(state: SortSnapshot): Scene<ArrayObjects>;
+/** Canvas color strings for the semantic roles in the array renderer. */
+export interface ArrayPalette {
+    readonly background: string;
+    readonly text: string;
+    readonly bar: string;
+    readonly sorted: string;
+    readonly active: string;
+    readonly held: string;
+}
+/** Overrides are copied at renderer creation; omitted roles retain the theme color. */
+export type ArrayPaletteOverrides = Partial<ArrayPalette>;
+export interface ArrayRendererOptions {
+    readonly theme: "light" | "dark";
+    readonly colors?: ArrayPaletteOverrides;
+}
 export { createSortRenderer as createArrayRenderer };
 /** Stateless full-frame renderer. Bitmap dimensions determine layout and video size. */
-export declare function createSortRenderer(options: {
-    theme: "light" | "dark";
-}): Readonly<{
+export declare function createSortRenderer(options: ArrayRendererOptions): Readonly<{
     render(ctx: CanvasRenderingContext2D, frame: SortFrame): void;
 }>;

package/dist/canvas/index.js

@@ -36,7 +36,12 @@ function positions(state) {
 }
 /** Stateless full-frame renderer. Bitmap dimensions determine layout and video size. */
 export function createSortRenderer(options) {
-    const colors = palettes[options.theme];
+    const colors = { ...palettes[options.theme] };
+    for (const key of Object.keys(colors)) {
+        const color = options.colors?.[key];
+        if (color !== undefined)
+            colors[key] = color;
+    }
     const projectFrame = createSceneProjector(arrayScene);
     return Object.freeze({
         render(ctx, frame) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@grundyjs/algiviz",
-  "version": "0.7.0",
-  "description": "Deterministic algorithm steps for educational visualizations",
+  "version": "0.8.0",
+  "description": "TypeScript toolkit for custom algorithm visualizations with step-by-step playback and extensible rendering",
   "type": "module",
   "files": [
     "dist/array",
@@ -52,10 +52,14 @@
   },
   "homepage": "https://grundyjs.ru/algiviz/",
   "keywords": [
+    "algorithm-visualization",
     "algorithms",
     "visualization",
-    "insertion-sort",
-    "bubble-sort",
+    "animation",
+    "step-by-step",
+    "playback",
+    "data-structures",
+    "educational",
     "canvas",
     "typescript"
   ],