@grundyjs/algiviz 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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.

package/README.md

@@ -28,7 +28,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.7.1.
+and rendering API. This README describes version 0.8.0.
 
 ## Start with one custom object
 
@@ -365,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()`;
@@ -499,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.1`, 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,6 +1,6 @@
 {
   "name": "@grundyjs/algiviz",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "TypeScript toolkit for custom algorithm visualizations with step-by-step playback and extensible rendering",
   "type": "module",
   "files": [