@grundyjs/algiviz 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.11.2 — 2026-11-05
+
+- Avoid argument-count limits when scaling large arrays in the Canvas renderer.
+- Isolate Canvas composite, filter and shadow settings alongside transform/alpha;
+  restore caller settings even when drawing throws.
+- Reject invalid frame progress before drawing; preserve the zero-sized bitmap no-op.
+- Require a valid light/dark theme at runtime and allow explicitly undefined colors
+  with exactOptionalPropertyTypes. Preserve the createSortRenderer compatibility alias.
+- Document Canvas coordinates, context ownership, scene adaptation, color priority
+  and error behavior in English and Russian; add renderer and packed-consumer regressions.
+
+## 0.11.1 — 2026-11-05
+
+- Validate both numeric positions in array swap/shift before reading or mutating
+  the trace, rejecting invalid JavaScript arguments without losing item identities
+  or changing snapshots, counters, markers or the next step index.
+- Allow explicitly undefined sorted-region inputs with exactOptionalPropertyTypes,
+  matching the existing runtime behavior of preserving the current marker.
+- Document array guarantees in English and Russian: fixed length, one held item,
+  trace-local IDs, immutable snapshots, counters and author-supplied sorted markers.
+- Add an application-owned object lifecycle example and expand playback completion,
+  strict type and installed-package consumer checks. No new public exports.
+
 ## 0.11.0 — 2026-11-02
 
 - Add createStatePlayer() for lazy playback of plain immutable states without

package/README.md

@@ -102,8 +102,8 @@ the [local setup instructions](https://github.com/urffin/algiviz/blob/master/doc
 - **Scene:** describes objects with stable IDs, types and application-owned data.
 - **Handler:** chooses geometry and drawing behavior, including interpolation.
 
-Do not mutate emitted states. Players require an explicit terminal step;
-call `dispose()` when removing a visualization. Algorithms, layouts and animation
+Do not mutate emitted states. `createStatePlayer` completes on source exhaustion;
+`createPlayer` requires an explicit terminal step. Call `dispose()` when removing a visualization. Algorithms, layouts and animation
 scheduling belong to the application.
 
 ## Playback modes

package/dist/array/trace.d.ts

@@ -1,7 +1,8 @@
 import type { Item, ArrayStep } from "./types.js";
+/** Omitted or undefined markers preserve their current values. */
 export interface SortedRegions {
-    readonly sortedPrefixLength?: number;
-    readonly sortedSuffixLength?: number;
+    readonly sortedPrefixLength?: number | undefined;
+    readonly sortedSuffixLength?: number | undefined;
 }
 export interface ArrayTrace {
     readonly length: number;

package/dist/array/trace.js

@@ -54,6 +54,8 @@ export function createArrayTrace(values) {
         },
         swap(left, right, update) {
             active();
+            index(left);
+            index(right);
             const a = item(left), b = item(right);
             if (left === right)
                 throw new RangeError("Swap requires distinct positions");
@@ -74,8 +76,9 @@ export function createArrayTrace(values) {
         },
         shift(from, to, update) {
             active();
-            const moved = item(from);
+            index(from);
             index(to);
+            const moved = item(from);
             if (slots[to] !== null)
                 throw new Error("Shift destination must be empty");
             regions(update);

package/dist/canvas/index.d.ts

@@ -8,7 +8,7 @@ export type ArrayObjects = {
         held: boolean;
     };
 };
-/** Adapts array identities to the same public scene contract used by custom objects. */
+/** Adapts immutable array snapshots; freezes scene wrappers but retains Item references. */
 export declare function arrayScene(state: ArraySnapshot): Scene<ArrayObjects>;
 /** Canvas color strings for the semantic roles in the array renderer. */
 export interface ArrayPalette {
@@ -25,10 +25,10 @@ export type ArrayPaletteOverrides = {
 };
 export interface ArrayRendererOptions {
     readonly theme: "light" | "dark";
-    readonly colors?: ArrayPaletteOverrides;
+    readonly colors?: ArrayPaletteOverrides | undefined;
 }
 export { createArrayRenderer as createSortRenderer };
-/** Stateless full-frame renderer. Bitmap dimensions determine layout and video size. */
+/** Full-frame bitmap renderer; the caller owns sizing and must provide an unclipped context. */
 export declare function createArrayRenderer(options: ArrayRendererOptions): Readonly<{
     render(ctx: CanvasRenderingContext2D, frame: ArrayFrame): void;
 }>;

package/dist/canvas/index.js

@@ -1,5 +1,5 @@
 import { createSceneRenderer, createSceneProjector } from "../scene/index.js";
-/** Adapts array identities to the same public scene contract used by custom objects. */
+/** Adapts immutable array snapshots; freezes scene wrappers but retains Item references. */
 export function arrayScene(state) {
     return Object.freeze({
         objects: Object.freeze([...positions(state)].map(([id, data]) => Object.freeze({ id, type: "bar", data: Object.freeze(data) })))
@@ -34,9 +34,12 @@ function positions(state) {
         result.set(state.held.id, { item: state.held, index: state.slots.indexOf(null), held: true });
     return result;
 }
-/** Stateless full-frame renderer. Bitmap dimensions determine layout and video size. */
+/** Full-frame bitmap renderer; the caller owns sizing and must provide an unclipped context. */
 export function createArrayRenderer(options) {
-    const colors = { ...palettes[options.theme] };
+    const theme = options?.theme;
+    if (theme !== "light" && theme !== "dark")
+        throw new TypeError("Array renderer theme must be light or dark");
+    const colors = { ...palettes[theme] };
     for (const key of Object.keys(colors)) {
         const color = options.colors?.[key];
         if (color !== undefined)
@@ -48,6 +51,9 @@ export function createArrayRenderer(options) {
             const { width, height } = ctx.canvas;
             if (width <= 0 || height <= 0)
                 return;
+            if (!Number.isFinite(frame.progress) || frame.progress < 0 || frame.progress > 1) {
+                throw new RangeError("Array frame progress must be between zero and one");
+            }
             const projected = projectFrame(frame);
             const items = projected.current.objects;
             const count = frame.current.slots.length;
@@ -55,7 +61,9 @@ export function createArrayRenderer(options) {
             const cell = (width - 2 * margin) / Math.max(count, 1);
             const barWidth = cell * 0.7;
             const available = height * 0.48;
-            const maxMagnitude = Math.max(1, ...items.map(({ data }) => Math.abs(data.item.value)));
+            let maxMagnitude = 1;
+            for (const { data } of items)
+                maxMagnitude = Math.max(maxMagnitude, Math.abs(data.item.value));
             const baseline = height * 0.69;
             const fontSize = Math.max(9, Math.min(20, cell * 0.45, width * 0.035));
             const progress = frame.progress;
@@ -65,6 +73,12 @@ export function createArrayRenderer(options) {
             try {
                 ctx.setTransform(1, 0, 0, 1, 0, 0);
                 ctx.globalAlpha = 1;
+                ctx.globalCompositeOperation = "source-over";
+                ctx.filter = "none";
+                ctx.shadowColor = "rgba(0, 0, 0, 0)";
+                ctx.shadowBlur = 0;
+                ctx.shadowOffsetX = 0;
+                ctx.shadowOffsetY = 0;
                 ctx.fillStyle = colors.background;
                 ctx.fillRect(0, 0, width, height);
                 ctx.font = `${Math.max(12, Math.min(24, width * 0.045))}px sans-serif`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grundyjs/algiviz",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "TypeScript toolkit for custom algorithm visualizations with step-by-step playback and extensible rendering",
   "type": "module",
   "files": [

package/ru/README.md

@@ -100,7 +100,8 @@ document.querySelector('#next').onclick = () => player.nextStep();
 - **Сцена** описывает объекты: стабильный `id`, тип и собственные данные.
 - **Обработчик** выбирает геометрию и способ рисования. Плавность — его решение.
 
-Состояния после выдачи нельзя изменять. Плееру нужен явный завершающий шаг;
+Состояния после выдачи нельзя изменять. `createStatePlayer` завершается при исчерпании
+источника; `createPlayer` требует явного завершающего шага;
 при удалении визуализации вызовите `dispose()`. Алгоритмы, раскладка и цикл
 анимации принадлежат приложению.