@grundyjs/canvas-take 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.4.0 — 2026-10-26
+
+- Ready-made `gif/worker` adapter with a dedicated module Worker, transferable frames, request timeouts and cleanup on completion/cancellation/errors.
+- Encoder-independent `onProgress` notifications with completed frame count, encoded duration, optional total frame hint and finalization/terminal phases.
+- Worker/progress example, integration tests and package asset checks.
+- Packed Next.js 16.3 / Turbopack consumer build in CI; browser-verified Worker export, progress and cancellation under same-origin Worker CSP.
+
+## 0.3.0 — 2026-10-15
+
+- Offline canvas GIF export via `@grundyjs/canvas-take/gif` with an injected encoder factory.
+- Optional isolated `gif/gifenc` adapter, configurable palette quality/color count, frame durations and repeat count.
+- AbortSignal cancellation, owned-resource cleanup and asynchronous/Worker adapter support.
+- Independent GIF decoding tests, package isolation checks and an offline canvas example.
+
 ## 0.2.0 — 2026-10-15
 
 - Optional caller-provided `audioTracks`, cloned at start to preserve caller ownership.

package/README.md

@@ -1,6 +1,8 @@
 # CanvasTake
 
-Independent TypeScript library for HTML canvas video recording with optional audio tracks. No runtime dependencies or dependency on AlgiViz. ESM only, with TypeScript declarations. MIT licensed. The package does not start or draw your animation.
+[Русский](ru/README.md)
+
+Independent TypeScript library for HTML canvas video recording with optional audio tracks and offline GIF export through a separate entry point. No external runtime dependencies or dependency on AlgiViz. ESM only, with TypeScript declarations. MIT licensed. The package does not start or draw your animation.
 
 ## Install
 
@@ -88,6 +90,103 @@ For a browser smoke test, run `node examples/server.cjs` after building and open
 
 The audio track list is copied at creation and validated again at start. CanvasTake clones the tracks at start and stops only its clones and canvas capture tracks on completion, disposal or failure. The caller owns the original tracks and AudioContext. Unexpected termination of a recorded clone fails recording. Calling `stop()` on an original track does not stop its clone; call `recorder.stop()` to finish the recording. Finishing an AudioBufferSource does not end the destination track either.
 
+## Offline GIF export
+
+Available since version 0.3.0.
+
+```js
+import { createGifExporter } from '@grundyjs/canvas-take/gif';
+import { createGifencEncoder } from '@grundyjs/canvas-take/gif/gifenc';
+
+const controller = new AbortController();
+const gif = createGifExporter({
+    encoder: createGifencEncoder({ maxColors: 128, quality: 'high' }),
+    repeat: 0,
+    signal: controller.signal,
+});
+try {
+    for (let time = 0; time < 6000; time += 50) {
+        drawTimeline(time); // Your deterministic renderer draws into canvas.
+        await gif.addFrame(canvas, 50);
+    }
+    drawTimeline(6000);
+    await gif.addFrame(canvas, 2000); // Hold the final frame for two seconds.
+    const blob = await gif.finish(); // image/gif; 8 seconds, 121 frames.
+    // Download/preview blob; revoke any object URL when no longer needed.
+} finally {
+    gif.dispose();
+}
+```
+
+`encoder` is required and supplied by the caller. The `/gif` entry has no codec dependency; `/gif/gifenc` is an optional, self-contained adapter bundling the MIT-licensed gifenc codec. The root video import loads neither GIF module. You can replace the adapter without changing the export loop.
+
+| Setting | Meaning |
+| --- | --- |
+| `repeat` | Default `0`: forever. `-1`: play once. `1..65535`: extra repetitions after the first play |
+| `signal` | Optional AbortSignal; abort rejects pending work and disposes the encoder |
+| `background` | RGB byte tuple, default `[255, 255, 255]`; composites transparency onto an opaque background |
+| Adapter `maxColors` | Maximum palette colors per frame, integer `2..256`, default `256` |
+| Adapter `quality` | `high` (default, RGB565) or `fast` (RGB444); no dithering |
+
+`addFrame(canvas, durationMs)` snapshots a 2D HTMLCanvasElement or OffscreenCanvas immediately, then yields before encoding. Await each call before another frame or `finish()`. All frames must have identical positive dimensions (GIF limit 65535 per axis). Durations must be finite and between 10 and 655350 ms; they are rounded to the nearest 10 ms. GIF players may clamp short delays; 50 ms is a practical timeline step. The drawing time and encoding wall time do not affect the GIF duration. The canvas remains caller-owned and unmodified. Tainted canvases fail with the readback error.
+
+`finish()` requires at least one frame, returns a Blob and releases the encoder. Each exporter produces one GIF. `dispose()` is idempotent, cancels pending work and releases encoder resources. Invalid frame data, changed dimensions and encoder errors make the exporter terminal. Concurrent calls are rejected without cancelling the ongoing operation. State is `ready`, `encoding`, `finished`, `failed`, `aborted` or `disposed`.
+
+The built-in adapter incrementally encodes full frames with individual palettes, retaining compressed output rather than all raw frames. It performs synchronous work per frame on the calling thread, with cancellation serviced between frames. For expensive frames, use the ready-made `/gif/worker` adapter, run with OffscreenCanvas in a Worker or supply an asynchronous Worker adapter; there is no automatic Worker pool. GIF bytes and the final Blob consume memory, so callers should bound dimensions and frame count. File size depends on visual complexity; an 800 px, 6–10 second animation is a target, not a guaranteed 2–3 MB output.
+
+### Worker adapter and progress (0.4.0)
+
+```js
+import { createGifExporter } from '@grundyjs/canvas-take/gif';
+import { createGifWorkerEncoder } from '@grundyjs/canvas-take/gif/worker';
+
+const gif = createGifExporter({
+    encoder: createGifWorkerEncoder({ maxColors: 128, quality: 'high' }),
+    signal: controller.signal,
+    totalFrames: 121,
+    onProgress({ phase, framesEncoded, totalFrames, durationMs }) {
+        status.textContent = `${phase}: ${framesEncoded}/${totalFrames}, ${durationMs} ms`;
+    },
+});
+```
+
+The dedicated module Worker performs quantization and GIF encoding. Canvas readback and alpha compositing remain on the calling thread. Each exporter owns one Worker, terminated on finish, cancellation, failure or disposal. Pixel buffers are transferred; the source canvas is unchanged. This adapter requires browser Worker support and does not silently fall back to main-thread encoding.
+
+The default Worker URL is resolved relative to the adapter module. For direct browser imports, serve `gif-worker.js`, `gif-worker-runtime.js` and `gifenc.js` together with JavaScript MIME types. With a bundler, ensure the Worker asset and its dependencies are emitted; if necessary, copy the runtime and `gifenc.js` to the same public directory and pass `workerUrl: '/assets/gif-worker-runtime.js'`. The runtime is also exported at `@grundyjs/canvas-take/gif/worker-runtime` for asset resolution (do not import it on the main thread). Follow your site's same-origin and CSP `worker-src` rules. No Blob URL or inline worker is required.
+
+`timeoutMs` defaults to 30000 ms **per request**, including startup, each frame and finalization. A timeout, script-load error or message-transfer error rejects work and terminates the Worker; increase the timeout explicitly for unusually expensive frames.
+
+Progress works with every encoder, not just the Worker adapter. Immutable snapshots arrive after each completed frame (`encoding`), before finishing (`finalizing`), and at `finished`, `failed`, `aborted` or unfinished `disposed`. `framesEncoded` and `durationMs` include only successfully encoded frames, using rounded GIF durations. `totalFrames` is an optional positive-integer display hint, not a limit; absent hints are omitted from events. No percentage or ETA is guessed; a full frame count does not mean finalization is complete. There is no initial event. Observer exceptions are ignored; aborting or disposing from an observer is supported. Disposing after a terminal outcome emits no additional event.
+
+The offline `examples/gif.html` now demonstrates this adapter, progress and cancellation.
+
+### Supplying another encoder
+
+Implement the exported `GifEncoderFactory` contract:
+
+```ts
+import type { GifEncoderFactory } from '@grundyjs/canvas-take/gif';
+
+const encoder: GifEncoderFactory = ({ repeat }) => ({
+    addFrame({ data, width, height, durationMs }) {
+        // Pass the opaque RGBA snapshot to your codec; may return Promise<void>.
+    },
+    async finish() {
+        // Return complete GIF bytes as Uint8Array.
+        return encodedBytes;
+    },
+    dispose() {
+        // Drop buffers, terminate owned Workers, settle pending operations.
+    },
+});
+```
+
+Each factory call must allocate a fresh encoder and honor the supplied repeat count. The exporter calls methods sequentially and invokes `dispose()` once on success, failure or cancellation. The adapter may transfer the owned frame buffer to a Worker; it must release frame references after each operation and support disposal during pending work. Cancellation rejects exporter operations immediately, but cleanup of external work belongs to the adapter. Synchronous codec work cannot be preempted on the same thread. Cleanup exceptions are suppressed to preserve the primary outcome.
+
+Run `node examples/server.cjs` after building and open `http://127.0.0.1:3012/canvas-take/examples/gif.html` for a standalone offline example with cancel, preview and download. Codec rationale and measured module sizes are in [docs/gif-encoder.md](docs/gif-encoder.md).
+
+With a built AlgiViz checkout in the sibling `algiviz` directory, open `http://127.0.0.1:3012/canvas-take/examples/gif-bfs.html` for the real BFS integration. Verified output: 800×560, 141 frames, 9 seconds including a 2-second final hold, about 1.60 MB. The example uses AlgiViz's existing algorithm and renderer and does not modify that project.
+
 ## Browser and server use
 
 Recording requires a browser with `canvas.captureStream`, `MediaRecorder` and `MutationObserver`. Importing the module does not access these APIs; creating a recorder checks capture/encoder support. Node.js has no recording implementation. Codec support is detected at runtime, not inferred from the browser name.
@@ -99,4 +198,3 @@ The integration example was verified with an actual VP9 recording at 1920×1080.
 Run `npm test` and `npm run test:package` (packs and installs the tarball in an isolated consumer, then checks TypeScript declarations and runtime imports). The archive contains dist, README, LICENSE, CHANGELOG and package metadata. Source and issues: [urffin/canvas-take](https://github.com/urffin/canvas-take). The 0.x API may change in later minor releases.
 
 After CI passes on the release commit, publish a stable GitHub Release tagged `v<package version>`. The `npm-publish.yml` workflow checks version consistency, verifies the packed consumer and publishes with OIDC/provenance. Configure npm's trusted publisher for owner `urffin`, repository `canvas-take`, workflow `npm-publish.yml` before the first automated release. No npm token is used. Publishing is a separate maintainer action.
-

package/dist/gif-worker-runtime.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/gif-worker-runtime.js

@@ -0,0 +1,33 @@
+import { createGifencEncoder } from './gifenc.js';
+const scope = globalThis;
+let encoder;
+scope.onmessage = event => {
+    const { id, action, value } = event.data;
+    try {
+        if (action === 'init') {
+            if (encoder)
+                throw new Error('GIF Worker already initialized');
+            const options = value;
+            encoder = createGifencEncoder(options)({ repeat: options.repeat });
+        }
+        else if (!encoder)
+            throw new Error('GIF Worker is not initialized');
+        else if (action === 'frame')
+            encoder.addFrame(value);
+        else if (action === 'finish') {
+            const bytes = encoder.finish();
+            encoder.dispose();
+            encoder = undefined;
+            scope.postMessage({ id, bytes }, [bytes.buffer]);
+            return;
+        }
+        else
+            throw new Error('Unknown GIF Worker request');
+        scope.postMessage({ id });
+    }
+    catch (error) {
+        encoder?.dispose();
+        encoder = undefined;
+        scope.postMessage({ id, error: error instanceof Error ? error.message : String(error) });
+    }
+};

package/dist/gif-worker.d.ts

@@ -0,0 +1,10 @@
+import type { GifEncoderFactory } from './gif.js';
+import type { GifencOptions } from './gifenc.js';
+export interface GifWorkerOptions extends GifencOptions {
+    /** Override the module Worker asset URL when copying assets or using a bundler. */
+    readonly workerUrl?: string | URL;
+    /** Per-request timeout, including Worker startup. Default 30000 ms. */
+    readonly timeoutMs?: number;
+}
+/** One dedicated module Worker per exporter. No codec runs on the calling thread. */
+export declare function createGifWorkerEncoder(options?: GifWorkerOptions): GifEncoderFactory;

package/dist/gif-worker.js

@@ -0,0 +1,91 @@
+/** One dedicated module Worker per exporter. No codec runs on the calling thread. */
+export function createGifWorkerEncoder(options = {}) {
+    const maxColors = options.maxColors ?? 256, quality = options.quality ?? 'high';
+    const timeoutMs = options.timeoutMs ?? 30000;
+    const workerUrl = options.workerUrl;
+    if (!Number.isInteger(maxColors) || maxColors < 2 || maxColors > 256)
+        throw new RangeError('maxColors must be 2..256');
+    if (quality !== 'high' && quality !== 'fast')
+        throw new TypeError('quality must be high or fast');
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647)
+        throw new RangeError('timeoutMs must be in (0, 2147483647]');
+    return ({ repeat }) => {
+        if (typeof Worker === 'undefined')
+            throw new Error('GIF Worker encoding is not supported in this environment');
+        let worker = workerUrl === undefined
+            ? new Worker(new URL('./gif-worker-runtime.js', import.meta.url), { type: 'module' })
+            : new Worker(workerUrl, { type: 'module' });
+        let nextId = 0;
+        let failure;
+        const pending = new Map();
+        function close(error) {
+            failure ??= error;
+            const owned = worker;
+            worker = undefined;
+            if (owned) {
+                owned.removeEventListener('message', onMessage);
+                owned.removeEventListener('error', onError);
+                owned.removeEventListener('messageerror', onMessageError);
+                owned.terminate();
+            }
+            for (const request of pending.values()) {
+                clearTimeout(request.timer);
+                request.reject(failure);
+            }
+            pending.clear();
+        }
+        function onMessage(event) {
+            const message = event.data;
+            const request = pending.get(message?.id);
+            if (!request)
+                return;
+            if (typeof message.error === 'string') {
+                close(new Error(message.error));
+                return;
+            }
+            pending.delete(message.id);
+            clearTimeout(request.timer);
+            request.resolve(message.bytes);
+        }
+        function onError(event) { close(new Error(event.message || 'GIF Worker failed to load or execute')); }
+        function onMessageError() { close(new Error('GIF Worker message could not be decoded')); }
+        worker.addEventListener('message', onMessage);
+        worker.addEventListener('error', onError);
+        worker.addEventListener('messageerror', onMessageError);
+        function send(action, value, transfer = []) {
+            if (!worker)
+                return Promise.reject(failure ?? new Error('GIF Worker is disposed'));
+            return new Promise((resolve, reject) => {
+                const id = ++nextId;
+                const timer = setTimeout(() => close(new Error(`GIF Worker ${action} timed out`)), timeoutMs);
+                pending.set(id, { resolve, reject, timer });
+                try {
+                    worker.postMessage({ id, action, value }, transfer);
+                }
+                catch (error) {
+                    close(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        }
+        const initialized = send('init', { repeat, maxColors, quality });
+        void initialized.catch(() => { });
+        return {
+            async addFrame(frame) {
+                await initialized;
+                await send('frame', frame, [frame.data.buffer]);
+            },
+            async finish() {
+                await initialized;
+                const bytes = await send('finish');
+                if (!(bytes instanceof Uint8Array)) {
+                    const error = new Error('GIF Worker returned invalid bytes');
+                    close(error);
+                    throw error;
+                }
+                close(new Error('GIF Worker finished'));
+                return bytes;
+            },
+            dispose() { close(new DOMException('GIF Worker disposed', 'AbortError')); }
+        };
+    };
+}

package/dist/gif.d.ts

@@ -0,0 +1,49 @@
+/** An immutable frame description; the encoder may use the owned pixel copy until addFrame settles. */
+export interface GifFrame {
+    readonly width: number;
+    readonly height: number;
+    readonly data: Uint8ClampedArray;
+    /** Milliseconds, rounded to GIF's 10 ms units by the exporter. */
+    readonly durationMs: number;
+}
+export interface GifEncoderOptions {
+    /** -1: play once; 0: forever; 1..65535: extra repetitions. */
+    readonly repeat: number;
+}
+/** Implementations may encode synchronously or use a Worker. Never retain frames after completion. */
+export interface GifFrameEncoder {
+    addFrame(frame: GifFrame): void | Promise<void>;
+    /** Return a complete GIF file. */
+    finish(): Uint8Array | Promise<Uint8Array>;
+    /** Must release buffers/terminate owned Workers, including during pending operations. */
+    dispose(): void;
+}
+/** Must return a fresh, exclusively owned encoder for each export. */
+export type GifEncoderFactory = (options: GifEncoderOptions) => GifFrameEncoder;
+export interface GifExportOptions {
+    readonly encoder: GifEncoderFactory;
+    readonly repeat?: number;
+    readonly signal?: AbortSignal;
+    /** Transparent pixels are composited onto this RGB color. Default: white. */
+    readonly background?: readonly [number, number, number];
+    /** Optional display hint; does not limit the number of frames. */
+    readonly totalFrames?: number;
+    /** Observer exceptions are ignored. Called after frames and on terminal/finalizing states. */
+    readonly onProgress?: (progress: GifExportProgress) => void;
+}
+export interface GifExportProgress {
+    readonly phase: 'encoding' | 'finalizing' | 'finished' | 'failed' | 'aborted' | 'disposed';
+    readonly framesEncoded: number;
+    readonly durationMs: number;
+    readonly totalFrames?: number;
+}
+export type GifExportState = 'ready' | 'encoding' | 'finished' | 'failed' | 'aborted' | 'disposed';
+export interface GifExporter {
+    readonly state: GifExportState;
+    /** Snapshot a 2D canvas immediately. Await completion before adding another frame or finishing. */
+    addFrame(canvas: HTMLCanvasElement | OffscreenCanvas, durationMs: number): Promise<void>;
+    finish(): Promise<Blob>;
+    dispose(): void;
+}
+/** Offline, sequential GIF export. No timers are used to determine frame durations. */
+export declare function createGifExporter(options: GifExportOptions): GifExporter;

package/dist/gif.js

@@ -0,0 +1,147 @@
+/** Offline, sequential GIF export. No timers are used to determine frame durations. */
+export function createGifExporter(options) {
+    const { signal, encoder: factory } = options;
+    const { totalFrames, onProgress } = options;
+    if (totalFrames !== undefined && (!Number.isSafeInteger(totalFrames) || totalFrames < 1))
+        throw new RangeError('totalFrames must be a positive safe integer');
+    const repeat = options.repeat ?? 0;
+    const background = [...(options.background ?? [255, 255, 255])];
+    if (typeof factory !== 'function')
+        throw new TypeError('An encoder factory is required');
+    if (!Number.isInteger(repeat) || repeat < -1 || repeat > 65535)
+        throw new RangeError('repeat must be -1..65535');
+    if (background.length !== 3 || background.some(v => !Number.isInteger(v) || v < 0 || v > 255)) {
+        throw new RangeError('background must contain three RGB bytes');
+    }
+    const abortError = () => signal?.reason ?? new DOMException('GIF export aborted', 'AbortError');
+    if (signal?.aborted)
+        throw abortError();
+    let encoder = factory(Object.freeze({ repeat }));
+    let state = 'ready';
+    let width = 0, height = 0, frames = 0;
+    let duration = 0;
+    function report(phase) {
+        try {
+            onProgress?.(Object.freeze({ phase, framesEncoded: frames, durationMs: duration,
+                ...(totalFrames === undefined ? {} : { totalFrames }) }));
+        }
+        catch { }
+    }
+    let rejectCancelled;
+    const cancelled = new Promise((_, reject) => { rejectCancelled = reject; });
+    void cancelled.catch(() => { });
+    function cleanup() {
+        signal?.removeEventListener('abort', onAbort);
+        const owned = encoder;
+        encoder = undefined;
+        // Preserve the original failure/cancellation even if an adapter's cleanup throws.
+        try {
+            owned?.dispose();
+        }
+        catch { }
+    }
+    function onAbort() {
+        if (state !== 'ready' && state !== 'encoding')
+            return;
+        state = 'aborted';
+        rejectCancelled(abortError());
+        cleanup();
+        report('aborted');
+    }
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted)
+        onAbort();
+    function ready() {
+        if (state !== 'ready')
+            throw new Error(`GIF exporter is ${state}`);
+    }
+    function active() {
+        if (state !== 'encoding')
+            throw new Error(`GIF exporter is ${state}`);
+    }
+    async function operation(work) {
+        ready();
+        state = 'encoding';
+        try {
+            return await Promise.race([work(), cancelled]);
+        }
+        catch (error) {
+            if (state === 'encoding') {
+                state = 'failed';
+                cleanup();
+                report('failed');
+            }
+            throw error;
+        }
+    }
+    return Object.freeze({
+        get state() { return state; },
+        addFrame(canvas, durationMs) {
+            return operation(async () => {
+                if (!Number.isFinite(durationMs) || durationMs < 10 || durationMs > 655350) {
+                    throw new RangeError('durationMs must be between 10 and 655350');
+                }
+                const w = canvas.width, h = canvas.height;
+                if (!Number.isInteger(w) || !Number.isInteger(h) || w < 1 || h < 1 || w > 65535 || h > 65535) {
+                    throw new RangeError('Canvas dimensions must be integers in 1..65535');
+                }
+                if (frames && (w !== width || h !== height))
+                    throw new Error('GIF frame dimensions must remain fixed');
+                const context = canvas.getContext('2d');
+                if (!context)
+                    throw new Error('GIF export requires a 2D canvas');
+                const data = new Uint8ClampedArray(context.getImageData(0, 0, w, h).data);
+                if (data.length !== w * h * 4)
+                    throw new Error('Invalid canvas pixel data');
+                // Yield between frames so UI cancellation can be delivered; snapshot is already owned.
+                await new Promise(resolve => setTimeout(resolve, 0));
+                active();
+                for (let i = 0; i < data.length; i += 4) {
+                    const alpha = data[i + 3] / 255;
+                    for (let c = 0; c < 3; c++)
+                        data[i + c] = Math.round(data[i + c] * alpha + background[c] * (1 - alpha));
+                    data[i + 3] = 255;
+                }
+                await encoder.addFrame({ width: w, height: h, data, durationMs: Math.round(durationMs / 10) * 10 });
+                active();
+                width = w;
+                height = h;
+                frames++;
+                duration += Math.round(durationMs / 10) * 10;
+                report('encoding');
+                active();
+                state = 'ready';
+            });
+        },
+        finish() {
+            return operation(async () => {
+                if (!frames)
+                    throw new Error('GIF export requires at least one frame');
+                report('finalizing');
+                active();
+                const bytes = await encoder.finish();
+                active();
+                if (!(bytes instanceof Uint8Array) || bytes.length < 6 ||
+                    !['GIF87a', 'GIF89a'].includes(String.fromCharCode(...bytes.subarray(0, 6)))) {
+                    throw new Error('Encoder did not return GIF bytes');
+                }
+                const blob = new Blob([new Uint8Array(bytes)], { type: 'image/gif' });
+                state = 'finished';
+                cleanup();
+                report('finished');
+                return blob;
+            });
+        },
+        dispose() {
+            if (state === 'disposed')
+                return;
+            const unfinished = state === 'ready' || state === 'encoding';
+            state = 'disposed';
+            if (unfinished)
+                rejectCancelled(new DOMException('GIF exporter disposed', 'AbortError'));
+            cleanup();
+            if (unfinished)
+                report('disposed');
+        }
+    });
+}

package/dist/gifenc-LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+Copyright (c) 2017 Matt DesLauriers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.
+

package/dist/gifenc.d.ts

@@ -0,0 +1,9 @@
+import type { GifEncoderFactory } from './gif.js';
+export interface GifencOptions {
+    /** Maximum colors per frame: 2..256. Default 256. */
+    readonly maxColors?: number;
+    /** high: RGB565 quantization; fast: RGB444. Default high. No dithering. */
+    readonly quality?: 'high' | 'fast';
+}
+/** Optional gifenc adapter. Import only when using this implementation. */
+export declare function createGifencEncoder(options?: GifencOptions): GifEncoderFactory;

package/dist/gifenc.js

@@ -0,0 +1,2 @@
+/*! Includes gifenc (MIT). See gifenc-LICENSE.txt. */
+var ce=Object.create;var W=Object.defineProperty;var se=Object.getOwnPropertyDescriptor;var le=Object.getOwnPropertyNames;var ae=Object.getPrototypeOf,fe=Object.prototype.hasOwnProperty;var ue=(e,t)=>()=>{try{return t||e((t={exports:{}}).exports,t),t.exports}catch(o){throw t=0,o}};var de=(e,t,o,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of le(t))!fe.call(e,r)&&r!==o&&W(e,r,{get:()=>t[r],enumerable:!(n=se(t,r))||n.enumerable});return e};var ge=(e,t,o)=>(o=e!=null?ce(ae(e)):{},de(t||!e||!e.__esModule?W(o,"default",{value:e,enumerable:!0}):o,e));var ie=ue(N=>{var Y=Object.defineProperty,he=e=>Y(e,"__esModule",{value:!0}),ye=(e,t)=>{for(var o in t)Y(e,o,{get:t[o],enumerable:!0})};he(N);ye(N,{GIFEncoder:()=>re,applyPalette:()=>Ce,default:()=>Ge,nearestColor:()=>Ee,nearestColorIndex:()=>te,nearestColorIndexWithDistance:()=>ne,prequantize:()=>ve,quantize:()=>Ae,snapColorsToPalette:()=>ke});var we={signature:"GIF",version:"89a",trailer:59,extensionIntroducer:33,applicationExtensionLabel:255,graphicControlExtensionLabel:249,imageSeparator:44,signatureSize:3,versionSize:3,globalColorTableFlagMask:128,colorResolutionMask:112,sortFlagMask:8,globalColorTableSizeMask:7,applicationIdentifierSize:8,applicationAuthCodeSize:3,disposalMethodMask:28,userInputFlagMask:2,transparentColorFlagMask:1,localColorTableFlagMask:128,interlaceFlagMask:64,idSortFlagMask:32,localColorTableSizeMask:7};function J(e=256){let t=0,o=new Uint8Array(e);return{get buffer(){return o.buffer},reset(){t=0},bytesView(){return o.subarray(0,t)},bytes(){return o.slice(0,t)},writeByte(r){n(t+1),o[t]=r,t++},writeBytes(r,i=0,c=r.length){n(t+c);for(let l=0;l<c;l++)o[t++]=r[l+i]},writeBytesView(r,i=0,c=r.byteLength){n(t+c),o.set(r.subarray(i,i+c),t),t+=c}};function n(r){var i=o.length;if(i>=r)return;var c=1024*1024;r=Math.max(r,i*(i<c?2:1.125)>>>0),i!=0&&(r=Math.max(r,256));let l=o;o=new Uint8Array(r),t>0&&o.set(l.subarray(0,t),0)}}var O=12,Z=5003,be=[0,1,3,7,15,31,63,127,255,511,1023,2047,4095,8191,16383,32767,65535];function pe(e,t,o,n,r=J(512),i=new Uint8Array(256),c=new Int32Array(Z),l=new Int32Array(Z)){let d=c.length,f=Math.max(2,n);i.fill(0),l.fill(0),c.fill(-1);let a=0,s=0,g=f+1,p=g,h=!1,y=p,A=(1<<y)-1,u=1<<g-1,_=u+1,B=u+2,w=0,I=o[0],F=0;for(let x=d;x<65536;x*=2)++F;F=8-F,r.writeByte(f),C(u);let b=o.length;for(let x=1;x<b;x++)e:{let k=o[x],E=(k<<O)+I,v=k<<F^I;if(c[v]===E){I=l[v];break e}let P=v===0?1:d-v;for(;c[v]>=0;)if(v-=P,v<0&&(v+=d),c[v]===E){I=l[v];break e}C(I),I=k,B<1<<O?(l[v]=B++,c[v]=E):(c.fill(-1),B=u+2,h=!0,C(u))}return C(I),C(_),r.writeByte(0),r.bytesView();function C(x){for(a&=be[s],s>0?a|=x<<s:a=x,s+=y;s>=8;)i[w++]=a&255,w>=254&&(r.writeByte(w),r.writeBytesView(i,0,w),w=0),a>>=8,s-=8;if((B>A||h)&&(h?(y=p,A=(1<<y)-1,h=!1):(++y,A=y===O?1<<y:(1<<y)-1)),x==_){for(;s>0;)i[w++]=a&255,w>=254&&(r.writeByte(w),r.writeBytesView(i,0,w),w=0),a>>=8,s-=8;w>0&&(r.writeByte(w),r.writeBytesView(i,0,w),w=0)}}}var xe=pe;function Q(e,t,o){return e<<8&63488|t<<2&992|o>>3}function $(e,t,o,n){return e>>4|t&240|(o&240)<<4|(n&240)<<8}function ee(e,t,o){return e>>4<<8|t&240|o>>4}function U(e,t,o){return e<t?t:e>o?o:e}function G(e){return e*e}function K(e,t,o){var n=0,r=1e100;let i=e[t],c=i.cnt,l=i.ac,d=i.rc,f=i.gc,a=i.bc;for(var s=i.fw;s!=0;s=e[s].fw){let p=e[s],h=p.cnt,y=c*h/(c+h);if(!(y>=r)){var g=0;o&&(g+=y*G(p.ac-l),g>=r)||(g+=y*G(p.rc-d),!(g>=r)&&(g+=y*G(p.gc-f),!(g>=r)&&(g+=y*G(p.bc-a),!(g>=r)&&(r=g,n=s))))}}i.err=r,i.nn=n}function L(){return{ac:0,rc:0,gc:0,bc:0,cnt:0,nn:0,fw:0,bk:0,tm:0,mtm:0,err:0}}function Be(e,t){let o=t==="rgb444"?4096:65536,n=new Array(o),r=e.length;if(t==="rgba4444")for(let i=0;i<r;++i){let c=e[i],l=c>>24&255,d=c>>16&255,f=c>>8&255,a=c&255,s=$(a,f,d,l),g=s in n?n[s]:n[s]=L();g.rc+=a,g.gc+=f,g.bc+=d,g.ac+=l,g.cnt++}else if(t==="rgb444")for(let i=0;i<r;++i){let c=e[i],l=c>>16&255,d=c>>8&255,f=c&255,a=ee(f,d,l),s=a in n?n[a]:n[a]=L();s.rc+=f,s.gc+=d,s.bc+=l,s.cnt++}else for(let i=0;i<r;++i){let c=e[i],l=c>>16&255,d=c>>8&255,f=c&255,a=Q(f,d,l),s=a in n?n[a]:n[a]=L();s.rc+=f,s.gc+=d,s.bc+=l,s.cnt++}return n}function Ae(e,t,o={}){let{format:n="rgb565",clearAlpha:r=!0,clearAlphaColor:i=0,clearAlphaThreshold:c=0,oneBitAlpha:l=!1}=o;if(!e||!e.buffer)throw new Error("quantize() expected RGBA Uint8Array data");if(!(e instanceof Uint8Array)&&!(e instanceof Uint8ClampedArray))throw new Error("quantize() expected RGBA Uint8Array data");let d=new Uint32Array(e.buffer),f=o.useSqrt!==!1,a=n==="rgba4444",s=Be(d,n),g=s.length,p=g-1,h=new Uint32Array(g+1);for(var y=0,u=0;u<g;++u){let M=s[u];if(M!=null){var A=1/M.cnt;a&&(M.ac*=A),M.rc*=A,M.gc*=A,M.bc*=A,s[y++]=M}}G(t)/y<.022&&(f=!1);for(var u=0;u<y-1;++u)s[u].fw=u+1,s[u+1].bk=u,f&&(s[u].cnt=Math.sqrt(s[u].cnt));f&&(s[u].cnt=Math.sqrt(s[u].cnt));var _,B,w;for(u=0;u<y;++u){K(s,u,!1);var I=s[u].err;for(B=++h[0];B>1&&(w=B>>1,!(s[_=h[w]].err<=I));B=w)h[B]=_;h[B]=u}var F=y-t;for(u=0;u<F;){for(var b;;){var C=h[1];if(b=s[C],b.tm>=b.mtm&&s[b.nn].mtm<=b.tm)break;b.mtm==p?C=h[1]=h[h[0]--]:(K(s,C,!1),b.tm=u);var I=s[C].err;for(B=1;(w=B+B)<=h[0]&&(w<h[0]&&s[h[w]].err>s[h[w+1]].err&&w++,!(I<=s[_=h[w]].err));B=w)h[B]=_;h[B]=C}var x=s[b.nn],k=b.cnt,E=x.cnt,A=1/(k+E);a&&(b.ac=A*(k*b.ac+E*x.ac)),b.rc=A*(k*b.rc+E*x.rc),b.gc=A*(k*b.gc+E*x.gc),b.bc=A*(k*b.bc+E*x.bc),b.cnt+=x.cnt,b.mtm=++u,s[x.bk].fw=x.fw,s[x.fw].bk=x.bk,x.mtm=p}let v=[];var P=0;for(u=0;;++P){let R=U(Math.round(s[u].rc),0,255),M=U(Math.round(s[u].gc),0,255),V=U(Math.round(s[u].bc),0,255),q=255;a&&(q=U(Math.round(s[u].ac),0,255),l&&(q=q<=(typeof l=="number"?l:127)?0:255),r&&q<=c&&(R=M=V=i,q=0));let H=a?[R,M,V,q]:[R,M,V];if(Ie(v,H)||v.push(H),(u=s[u].fw)==0)break}return v}function Ie(e,t){for(let o=0;o<e.length;o++){let n=e[o],r=n[0]===t[0]&&n[1]===t[1]&&n[2]===t[2],i=n.length>=4&&t.length>=4?n[3]===t[3]:!0;if(r&&i)return!0}return!1}function D(e,t){var o=0,n;for(n=0;n<e.length;n++){let r=e[n]-t[n];o+=r*r}return o}function S(e,t){return t>1?Math.round(e/t)*t:e}function ve(e,{roundRGB:t=5,roundAlpha:o=10,oneBitAlpha:n=null}={}){let r=new Uint32Array(e.buffer);for(let i=0;i<r.length;i++){let c=r[i],l=c>>24&255,d=c>>16&255,f=c>>8&255,a=c&255;l=S(l,o),n&&(l=l<=(typeof n=="number"?n:127)?0:255),a=S(a,t),f=S(f,t),d=S(d,t),r[i]=l<<24|d<<16|f<<8|a<<0}}function Ce(e,t,o="rgb565"){if(!e||!e.buffer)throw new Error("quantize() expected RGBA Uint8Array data");if(!(e instanceof Uint8Array)&&!(e instanceof Uint8ClampedArray))throw new Error("quantize() expected RGBA Uint8Array data");if(t.length>256)throw new Error("applyPalette() only works with 256 colors or less");let n=new Uint32Array(e.buffer),r=n.length,i=o==="rgb444"?4096:65536,c=new Uint8Array(r),l=new Array(i),d=o==="rgba4444";if(o==="rgba4444")for(let f=0;f<r;f++){let a=n[f],s=a>>24&255,g=a>>16&255,p=a>>8&255,h=a&255,y=$(h,p,g,s),A=y in l?l[y]:l[y]=Me(h,p,g,s,t);c[f]=A}else{let f=o==="rgb444"?ee:Q;for(let a=0;a<r;a++){let s=n[a],g=s>>16&255,p=s>>8&255,h=s&255,y=f(h,p,g),A=y in l?l[y]:l[y]=_e(h,p,g,t);c[a]=A}}return c}function Me(e,t,o,n,r){let i=0,c=1e100;for(let l=0;l<r.length;l++){let d=r[l],f=d[3],a=z(f-n);if(a>c)continue;let s=d[0];if(a+=z(s-e),a>c)continue;let g=d[1];if(a+=z(g-t),a>c)continue;let p=d[2];a+=z(p-o),!(a>c)&&(c=a,i=l)}return i}function _e(e,t,o,n){let r=0,i=1e100;for(let c=0;c<n.length;c++){let l=n[c],d=l[0],f=z(d-e);if(f>i)continue;let a=l[1];if(f+=z(a-t),f>i)continue;let s=l[2];f+=z(s-o),!(f>i)&&(i=f,r=c)}return r}function ke(e,t,o=5){if(!e.length||!t.length)return;let n=e.map(c=>c.slice(0,3)),r=o*o,i=e[0].length;for(let c=0;c<t.length;c++){let l=t[c];l.length<i?l=[l[0],l[1],l[2],255]:l.length>i?l=l.slice(0,3):l=l.slice();let d=ne(n,l.slice(0,3),D),f=d[0],a=d[1];a>0&&a<=r&&(e[f]=l)}}function z(e){return e*e}function te(e,t,o=D){let n=1/0,r=-1;for(let i=0;i<e.length;i++){let c=e[i],l=o(t,c);l<n&&(n=l,r=i)}return r}function ne(e,t,o=D){let n=1/0,r=-1;for(let i=0;i<e.length;i++){let c=e[i],l=o(t,c);l<n&&(n=l,r=i)}return[r,n]}function Ee(e,t,o=D){return e[te(e,t,o)]}function re(e={}){let{initialCapacity:t=4096,auto:o=!0}=e,n=J(t),r=5003,i=new Uint8Array(256),c=new Int32Array(r),l=new Int32Array(r),d=!1;return{reset(){n.reset(),d=!1},finish(){n.writeByte(we.trailer)},bytes(){return n.bytes()},bytesView(){return n.bytesView()},get buffer(){return n.buffer},get stream(){return n},writeHeader:f,writeFrame(a,s,g,p={}){let{transparent:h=!1,transparentIndex:y=0,delay:A=0,palette:u=null,repeat:_=0,colorDepth:B=8,dispose:w=-1}=p,I=!1;if(o?d||(I=!0,f(),d=!0):I=!!p.first,s=Math.max(0,Math.floor(s)),g=Math.max(0,Math.floor(g)),I){if(!u)throw new Error("First frame must include a { palette } option");me(n,s,g,u,B),X(n,u),_>=0&&ze(n,_)}let F=Math.round(A/10);Fe(n,w,F,h,y);let b=!!u&&!I;qe(n,s,g,b?u:null),b&&X(n,u),Te(n,a,s,g,B,i,c,l)}};function f(){oe(n,"GIF89a")}}function Fe(e,t,o,n,r){e.writeByte(33),e.writeByte(249),e.writeByte(4),r<0&&(r=0,n=!1);var i,c;n?(i=1,c=2):(i=0,c=0),t>=0&&(c=t&7),c<<=2,e.writeByte(0|c|0|i),m(e,o),e.writeByte(r||0),e.writeByte(0)}function me(e,t,o,n,r=8){let l=j(n.length)-1,d=128|r-1<<4|0|l,f=0,a=0;m(e,t),m(e,o),e.writeBytes([d,f,a])}function ze(e,t){e.writeByte(33),e.writeByte(255),e.writeByte(11),oe(e,"NETSCAPE2.0"),e.writeByte(3),e.writeByte(1),m(e,t),e.writeByte(0)}function X(e,t){let o=1<<j(t.length);for(let n=0;n<o;n++){let r=[0,0,0];n<t.length&&(r=t[n]),e.writeByte(r[0]),e.writeByte(r[1]),e.writeByte(r[2])}}function qe(e,t,o,n){if(e.writeByte(44),m(e,0),m(e,0),m(e,t),m(e,o),n){let c=j(n.length)-1;e.writeByte(128|c)}else e.writeByte(0)}function Te(e,t,o,n,r=8,i,c,l){xe(o,n,t,r,e,i,c,l)}function m(e,t){e.writeByte(t&255),e.writeByte(t>>8&255)}function oe(e,t){for(var o=0;o<t.length;o++)e.writeByte(t.charCodeAt(o))}function j(e){return Math.max(Math.ceil(Math.log2(e)),1)}var Ge=re});var T=ge(ie(),1);function Re(e={}){let t=e.maxColors??256,o=e.quality??"high";if(!Number.isInteger(t)||t<2||t>256)throw new RangeError("maxColors must be 2..256");if(o!=="high"&&o!=="fast")throw new TypeError("quality must be high or fast");let n=o==="high"?"rgb565":"rgb444";return({repeat:r})=>{let i=(0,T.GIFEncoder)();return{addFrame({data:c,width:l,height:d,durationMs:f}){if(!i)throw new Error("GIF encoder is disposed");let a=(0,T.quantize)(c,t,{format:n}),s=(0,T.applyPalette)(c,a,n);i.writeFrame(s,l,d,{palette:a,delay:f,repeat:r,dispose:1})},finish(){if(!i)throw new Error("GIF encoder is disposed");i.finish();let c=i.bytes();return i=void 0,c},dispose(){i=void 0}}}}export{Re as createGifencEncoder};

package/docs/gif-encoder.md

@@ -0,0 +1,42 @@
+# GIF encoder selection and integration
+
+The export controller accepts a `GifEncoderFactory`. Codec-specific tuning belongs to the adapter factory, not the controller. This keeps frame scheduling, cancellation and resource ownership independent of palette algorithms or Worker transport.
+
+## Candidates inspected
+
+| Encoder | License | Shipped JavaScript | Worker model | Fit |
+| --- | --- | --- | --- | --- |
+| [gifenc 1.0.3](https://github.com/mattdesl/gifenc) | MIT | CanvasTake's bundled adapter is 10,478 bytes / 4,539 gzip | No automatic pool; can encode in Workers | Incremental frames, palette controls, no dependencies, fits flat algorithm graphics |
+| [gif.js 0.2.0](https://github.com/jnordberg/gif.js) | MIT | 13,451-byte main script + 16,636-byte Worker script, excluding maps | Built-in Worker orchestration with a separately hosted workerScript | Useful full exporter, but overlaps our controller and needs another deployment asset |
+
+Sizes were measured from the installed/published versions on 2026-10-15; they are not comparative speed benchmarks. gifenc's npm unpacked size is 172,516 bytes including sources/maps. gif.js's npm unpacked size is 3,096,699 bytes including its demo media; this is not its browser download cost. The chosen adapter copies gifenc's complete MIT license into `dist/gifenc-LICENSE.txt`.
+
+gifenc was selected for the supplied adapter, not embedded into the controller. It has no dithering and is less suited to photographs. Per-frame palettes may change quantized colors between frames. The current adapter encodes full opaque frames, not changed rectangles; size savings depend on the source. Alpha is composited onto the controller's configurable background before reaching any adapter.
+
+## Loading and execution
+
+Measured emitted files in release 0.3.0 (uncompressed / gzip, before Worker/progress additions):
+
+- `dist/index.js`: 8,120 / 2,128 bytes. The video entry remains unchanged.
+- `dist/gif.js`: 5,207 / 1,688 bytes. Controller only, no runtime imports.
+- `dist/gifenc.js`: 10,478 / 4,539 bytes. Self-contained optional codec adapter.
+
+The adapter is bundled at build time; gifenc, esbuild and the test decoder are development dependencies. Consumers install no additional runtime packages. Bundle-graph tests verify that each entry is standalone. Packed-consumer tests import all three public entries, compile their types and produce GIF bytes after installing the tarball in an isolated project.
+
+The supplied adapter runs on the calling thread. The controller snapshots pixels before its first yield and yields before each frame, allowing UI cancellation between frames. It cannot interrupt synchronous quantization halfway through a frame. For large workloads, the caller can run the exporter with OffscreenCanvas in a Worker or supply an async Worker adapter. The adapter owns its Workers; `dispose()` must terminate them, reject pending calls and release buffers. A real Node Worker integration test transfers the owned pixel copies and independently decodes the returned result, then verifies Worker termination.
+
+### Ready-made Worker adapter (0.4.0)
+
+The `/gif/worker` entry provides `createGifWorkerEncoder`, with one dedicated module Worker per export. It transfers owned pixel buffers and runs quantization and encoding in that Worker; canvas readback and alpha compositing stay on the calling thread. The default runtime URL is relative to the adapter. Serve the runtime and `gifenc.js` together, or configure `workerUrl` when deploying copied/bundled assets. The runtime is exported at `/gif/worker-runtime` for asset resolution only. Startup, frame and finish requests each have a configurable 30-second default timeout. Success, failure, cancellation and disposal terminate the Worker and settle pending calls. Real Worker tests independently decode its result and verify termination; fault tests cover startup cancellation, transport errors and timeouts.
+
+The controller's optional `onProgress` observer works with every encoder. It reports completed frames and their accumulated rounded duration, finalization, and terminal outcomes. `totalFrames` is an optional display hint, not a frame limit. See the README for event semantics and deployment details. The browser example now uses this adapter; the measurements below describe the synchronous adapter in 0.3.0.
+
+## Verification
+
+`npm run test:next` packs the local library and builds an isolated Next.js 16.3.0 / React 19.2.8 consumer with Turbopack. These are the site's installed versions at the time this fixture was added. Its client component uses the default Worker URL, export progress and cancellation under `worker-src 'self'`. The temporary directory is printed and retained for browser checks with the printed `npm start` command. A build pass alone does not establish browser execution or cancellation; verify those separately. This check does not modify the website checkout or publish a package. CI runs the build as a separate job.
+
+Tests use gifuct-js as an independent parser/LZW decoder, checking full pixel patches, dimensions, frame delays, long final holds, loop extension values, alpha composition and palette limits. Lifecycle tests cover pre-abort, abort/dispose during pending frame/finalization calls, late rejection, codec exceptions, tainted canvas, resize, empty exports, duplicate operations and exactly-once adapter disposal. Releasing references makes buffers eligible for garbage collection; tests do not claim a particular GC schedule.
+
+A real browser export from `examples/gif.html` produced 121 frames at 800×450: 120 × 50 ms plus a 2000 ms final hold, repeat forever. The downloaded GIF was independently decoded again: 8000 ms total, distinct first/final pixels, 931,669 bytes. Encoding took approximately 4.2 seconds on the test machine. This is a synthetic flat-graphics sample, not the future AlgiViz BFS animation; its size does not guarantee the size or rendering time of other scenes.
+
+The integration example `examples/gif-bfs.html` additionally imports the actual BFS generator, graph renderer and timeline from a sibling AlgiViz checkout without modifying it. Its 36 algorithm steps are sampled every 50 ms across 7000 ms, followed by one 2000 ms final frame. Browser output independently decoded to 141 frames, 800×560, 9000 ms and an infinite loop, at 1,597,694 bytes (about 1.60 MB). Encoding took about 5.7 seconds. Visual inspection of decoded initial/middle/final frames confirmed readable labels and distinct state colors. Final distances from A were A=0, B=C=1, D=2, E=3; F and G remained unreachable. This meets the intended 6–10 second, roughly 800 px and under 2–3 MB README target for this graph. The example saves a test copy to `canvastake-test.gif` in the local server's temporary directory.

package/package.json

@@ -1,29 +1,51 @@
 {
   "name": "@grundyjs/canvas-take",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Record HTML canvas to video with explicit resource lifecycle",
   "type": "module",
   "files": [
     "dist",
     "README.md",
+    "ru/README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs/gif-encoder.md"
   ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
-    }
+    },
+    "./gif": {
+      "types": "./dist/gif.d.ts",
+      "import": "./dist/gif.js",
+      "default": "./dist/gif.js"
+    },
+    "./gif/gifenc": {
+      "types": "./dist/gifenc.d.ts",
+      "import": "./dist/gifenc.js",
+      "default": "./dist/gifenc.js"
+    },
+    "./gif/worker": {
+      "types": "./dist/gif-worker.d.ts",
+      "import": "./dist/gif-worker.js",
+      "default": "./dist/gif-worker.js"
+    },
+    "./gif/worker-runtime": "./dist/gif-worker-runtime.js"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && node scripts/build-gif.mjs",
     "test": "npm run build && node --test test/*.test.mjs",
     "prepack": "npm run build",
     "prepublishOnly": "npm test",
-    "test:package": "node scripts/test-package.mjs"
+    "test:package": "node scripts/test-package.mjs",
+    "test:next": "node scripts/test-next.mjs"
   },
   "devDependencies": {
+    "esbuild": "0.28.2",
+    "gifenc": "1.0.3",
+    "gifuct-js": "2.1.2",
     "typescript": "6.0.3"
   },
   "license": "MIT",

package/ru/README.md

@@ -0,0 +1,318 @@
+# CanvasTake
+
+[English](../README.md)
+
+Независимая TypeScript-библиотека для записи видео с HTML canvas с необязательными
+аудиодорожками и покадрового экспорта GIF через отдельную точку входа. Без внешних
+зависимостей во время выполнения и без зависимости от AlgiViz. Только ESM,
+с декларациями TypeScript. Лицензия MIT. Пакет не запускает и не рисует вашу анимацию.
+
+## Установка
+
+```sh
+npm install @grundyjs/canvas-take
+```
+
+## Запись canvas
+
+```js
+import { createCanvasRecorder } from "@grundyjs/canvas-take";
+const recorder = createCanvasRecorder(canvas, { fps: 30 });
+await recorder.start();
+// Run your animation, then:
+const { blob, extension, mimeType, durationMs } = await recorder.stop();
+const url = URL.createObjectURL(blob);
+// Use url in a video player or download link. Revoke it when no longer needed.
+recorder.dispose();
+```
+
+`start` завершается после события start от MediaRecorder. `stop` ждёт последних
+событий dataavailable и stop; повторные вызовы возвращают тот же promise.
+При ошибках ожидающие операции отклоняются, принадлежащие рекордеру дорожки
+останавливаются, а накопленные фрагменты освобождаются. `dispose` отменяет незавершённую
+запись и допускает повторные вызовы. Каждый экземпляр записывает один раз.
+Пока start ожидает завершения, состояние остаётся idle; повторный start отклоняется.
+
+Порядок автоматического выбора формата: WebM VP9, VP8, обычный WebM, MP4.
+При записи со звуком варианты VP9 и VP8 включают Opus. Явно заданный неподдерживаемый
+MIME вызывает ошибку без скрытой смены формата. Результат содержит фактический MIME
+и соответствующее расширение. FPS и битрейт — целевые значения, а не гарантии.
+durationMs измеряет реальное время записи, а не длительность, прочитанную из файла.
+
+Не меняйте размеры битовой карты canvas от start до stop. Масштабирование через CSS
+допускается. Изменение размеров завершает запись ошибкой. Canvas должен оставаться
+origin-clean. Захват экрана, пауза записи, покадровое кодирование видео и отправка
+на сервер не поддерживаются. Фрагменты хранятся в памяти: ограничивайте длительность.
+Если замедление фоновой вкладки недопустимо, вызывайте dispose при скрытии страницы.
+Поддержка кодеков зависит от браузера и доступных ресурсов.
+
+Разработка: Node.js 22+, `npm install`, `npm test`, `npm pack`. ESM и декларации
+создаются в dist. `npm pack` автоматически пересобирает пакет; `npm publish`
+запускает тесты до упаковки. Интеграционный пример ожидает AlgiViz в соседнем
+каталоге и запускается через включённый в репозиторий локальный сервер.
+
+См. [остановку MediaRecorder](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder/stop)
+и [проверку формата](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder/isTypeSupported_static).
+WebM от MediaRecorder может не содержать метаданные длительности: воспроизведение
+работает, но плеер показывает неопределённую длительность. Для надёжной перемотки
+или публикации отдельно перепакуйте контейнер. CanvasTake не переписывает его метаданные.
+
+## Настройки и результат
+
+| Настройка | Значение |
+| --- | --- |
+| `fps` | Обязательная положительная конечная целевая частота захвата |
+| `videoBitsPerSecond` | Необязательный положительный конечный целевой битрейт кодировщика |
+| `mimeType` | Необязательный явно заданный поддерживаемый MIME `video/webm` или `video/mp4`, включая кодеки |
+| `audioTracks` | Необязательный список только для чтения из активных звуковых `MediaStreamTrack`; без него или с пустым списком запись идёт без звука |
+
+`stop()` возвращает `{ blob, mimeType, extension, durationMs }`. Используйте рекордер
+в try/finally и вызывайте `dispose()`, даже если анимация завершилась ошибкой.
+Освобождайте object URL, когда они больше не нужны.
+
+## Запись с озвучкой
+
+Сведите звук в одну выходную дорожку Web Audio: несколько звуковых дорожек
+поддерживает не каждый кодировщик. Декодируйте озвучку до начала записи.
+Вызывайте код из обработчика действия пользователя, чтобы браузер мог возобновить
+аудиоконтекст:
+
+```js
+async function recordNarration(canvas, narrationBytes) {
+    const audio = new AudioContext();
+    let recorder;
+    let destination;
+    try {
+        await audio.resume();
+        const buffer = await audio.decodeAudioData(narrationBytes);
+        destination = audio.createMediaStreamDestination();
+        const source = audio.createBufferSource();
+        source.buffer = buffer;
+        source.connect(destination);
+        recorder = createCanvasRecorder(canvas, {
+            fps: 30,
+            mimeType: "video/mp4",
+            audioTracks: destination.stream.getAudioTracks(),
+        });
+        const finished = new Promise(resolve => {
+            source.addEventListener("ended", resolve, { once: true });
+        });
+        await recorder.start();
+        source.start();
+        // Run your canvas animation while the narration plays.
+        await finished;
+        return await recorder.stop();
+    } finally {
+        recorder?.dispose();
+        destination?.stream.getTracks().forEach(track => track.stop());
+        await audio.close();
+    }
+}
+```
+
+Для MP4 со звуком нужна поддержка кодировщика в браузере; явный запрос MP4
+никогда не переключается на WebM. CanvasTake использует MediaRecorder напрямую
+и не перекодирует результат. Воспроизведением звука и анимацией canvas управляет
+приложение; они работают в реальном времени.
+
+`video/mp4` выбирает контейнер, а не конкретные кодеки: браузер может записать
+VP9/Opus в MP4. Если площадке нужны H.264/AAC, укажите MIME с кодеками, например
+`video/mp4;codecs=avc1,mp4a.40.2`, и обработайте ошибку неподдерживаемого формата.
+
+Для быстрой проверки в браузере после сборки запустите `node examples/server.cjs`
+и откройте `http://127.0.0.1:3012/canvas-take/examples/audio.html`. Пример записывает
+сгенерированный тон и движущийся canvas 1080×1920 с явно заданными H.264/AAC,
+запрашивает остановку через две секунды, показывает результат и сохраняет его
+как `canvastake-test.mp4` во временном каталоге сервера. Ранее проверенный результат
+в локальном браузере: H.264 Constrained Baseline, прогрессивная развёртка 4:2:0,
+стерео AAC-LC 48 кГц, 2,476 секунды и примерно 29,1 fps. Перекодирование и перепаковка
+не использовались. Фактические длительность, частота кадров и поддержка кодеков
+зависят от браузера и нагрузки во время выполнения.
+
+Список аудиодорожек копируется при создании и повторно проверяется при start.
+CanvasTake клонирует дорожки при start и при завершении, dispose или ошибке
+останавливает только свои копии и дорожки захвата canvas. Исходными дорожками
+и AudioContext владеет вызывающий код. Неожиданное завершение записываемой копии
+вызывает ошибку записи. `stop()` исходной дорожки не останавливает её копию;
+для завершения записи вызовите `recorder.stop()`. Окончание AudioBufferSource
+также не завершает выходную дорожку.
+
+## Покадровый экспорт GIF
+
+Доступен с версии 0.3.0.
+
+```js
+import { createGifExporter } from '@grundyjs/canvas-take/gif';
+import { createGifencEncoder } from '@grundyjs/canvas-take/gif/gifenc';
+
+const controller = new AbortController();
+const gif = createGifExporter({
+    encoder: createGifencEncoder({ maxColors: 128, quality: 'high' }),
+    repeat: 0,
+    signal: controller.signal,
+});
+try {
+    for (let time = 0; time < 6000; time += 50) {
+        drawTimeline(time); // Your deterministic renderer draws into canvas.
+        await gif.addFrame(canvas, 50);
+    }
+    drawTimeline(6000);
+    await gif.addFrame(canvas, 2000); // Hold the final frame for two seconds.
+    const blob = await gif.finish(); // image/gif; 8 seconds, 121 frames.
+    // Download/preview blob; revoke any object URL when no longer needed.
+} finally {
+    gif.dispose();
+}
+```
+
+`encoder` обязателен и передаётся приложением. Точка входа `/gif` не зависит от
+кодека; `/gif/gifenc` — необязательный самостоятельный адаптер со встроенным
+кодеком gifenc под MIT. Корневой импорт видео не загружает ни один GIF-модуль.
+Адаптер можно заменить без изменения цикла экспорта.
+
+| Настройка | Значение |
+| --- | --- |
+| `repeat` | По умолчанию `0`: бесконечно. `-1`: один просмотр. `1..65535`: дополнительные повторы после первого просмотра |
+| `signal` | Необязательный AbortSignal; отмена отклоняет ожидающие операции и освобождает кодировщик |
+| `background` | Тройка байтов RGB, по умолчанию `[255, 255, 255]`; прозрачность накладывается на непрозрачный фон |
+| `maxColors` адаптера | Максимум цветов палитры на кадр: целое `2..256`, по умолчанию `256` |
+| `quality` адаптера | `high` (по умолчанию, RGB565) или `fast` (RGB444); без дизеринга |
+
+`addFrame(canvas, durationMs)` немедленно снимает копию 2D HTMLCanvasElement или
+OffscreenCanvas, затем отдаёт управление перед кодированием. Дожидайтесь каждого
+вызова перед следующим кадром или `finish()`. Все кадры должны иметь одинаковые
+положительные размеры, не более 65535 по каждой оси — предел GIF. Длительности
+должны быть конечными и находиться в диапазоне от 10 до 655350 мс; они округляются
+до ближайших 10 мс. GIF-плееры могут увеличивать короткие задержки; 50 мс —
+практичный шаг временной шкалы. Время рисования и реальное время кодирования
+не влияют на длительность GIF. Canvas остаётся у приложения и не изменяется.
+Для canvas с ограниченным доступом к пикселям операция завершается ошибкой чтения.
+
+`finish()` требует хотя бы один кадр, возвращает Blob и освобождает кодировщик.
+Каждый экземпляр создаёт один GIF. `dispose()` допускает повторные вызовы,
+отменяет ожидающие операции и освобождает ресурсы кодировщика. Неверные данные
+кадра, изменение размеров и ошибки кодировщика делают дальнейший экспорт невозможным.
+Одновременные вызовы отклоняются, не отменяя текущую операцию. Возможные состояния:
+`ready`, `encoding`, `finished`, `failed`, `aborted` и `disposed`.
+
+Встроенный адаптер постепенно кодирует полные кадры с отдельными палитрами,
+сохраняя сжатый результат вместо всех исходных кадров. Обработка каждого кадра
+синхронна и выполняется в вызывающем потоке; отмена обрабатывается между кадрами.
+Для тяжёлых кадров используйте готовый адаптер `/gif/worker`, OffscreenCanvas в Worker или передайте асинхронный
+адаптер с Worker; автоматического пула Worker нет. Байты GIF и итоговый Blob
+занимают память, поэтому ограничивайте размеры и число кадров. Размер файла
+зависит от визуальной сложности; анимация шириной 800 px и длиной 6–10 секунд —
+целевой сценарий, а не гарантия файла размером 2–3 МБ.
+
+### Worker-адаптер и прогресс (0.4.0)
+
+```ts
+import { createGifExporter } from '@grundyjs/canvas-take/gif';
+import { createGifWorkerEncoder } from '@grundyjs/canvas-take/gif/worker';
+
+const gif = createGifExporter({
+    encoder: createGifWorkerEncoder({ maxColors: 128, quality: 'high' }),
+    totalFrames: 121,
+    onProgress({ phase, framesEncoded, totalFrames, durationMs }) {
+        console.log(phase, framesEncoded, totalFrames, durationMs);
+    },
+});
+// Последовательно: await gif.addFrame(canvas, durationMs), затем await gif.finish().
+```
+
+Квантование и кодирование выполняются в отдельном module Worker. Чтение canvas
+и наложение прозрачности на фон остаются в вызывающем потоке. Каждый экспортёр
+владеет одним Worker и завершает его при успехе, ошибке, отмене или `dispose()`.
+Буферы пикселей передаются без копирования; исходный canvas не меняется.
+Требуется поддержка Worker; автоматического перехода к синхронному кодированию нет.
+
+При прямом импорте в браузере размещайте `gif-worker.js`, `gif-worker-runtime.js`
+и `gifenc.js` рядом, с MIME-типом JavaScript. Для сборщика проверьте, что Worker
+и его зависимости попали в результат сборки. При необходимости скопируйте runtime
+и `gifenc.js` в один публичный каталог и передайте `workerUrl: '/assets/gif-worker-runtime.js'`.
+Путь пакета `/gif/worker-runtime` предназначен для разрешения адреса ресурса,
+а не для импорта в основном потоке. Учитывайте same-origin и CSP `worker-src`;
+Blob URL и встроенный код Worker не требуются.
+
+`timeoutMs` по умолчанию равен 30000 мс **на каждый запрос**: запуск, отдельный кадр
+и финализацию. При тайм-ауте, ошибке загрузки или передачи сообщения ожидающие
+операции отклоняются, а Worker завершается.
+
+`onProgress` работает с любым кодировщиком. Неизменяемый снимок приходит после
+успешного кадра (`encoding`), перед финализацией (`finalizing`) и при результате
+`finished`, `failed`, `aborted` или преждевременном `disposed`. Начального события нет.
+`framesEncoded` и `durationMs` учитывают только завершённые кадры с округлёнными
+длительностями GIF. Необязательный `totalFrames` — положительное безопасное целое
+для отображения, а не ограничение числа кадров; без него поле отсутствует.
+Полное число кадров ещё не означает завершение финализации. Процент и ETA
+автоматически не вычисляются. Исключения наблюдателя игнорируются; из него можно
+отменить или освободить экспортёр. `dispose()` после конечного результата
+не создаёт дополнительного события.
+
+### Подключение другого кодировщика
+
+Реализуйте экспортируемый контракт `GifEncoderFactory`:
+
+```ts
+import type { GifEncoderFactory } from '@grundyjs/canvas-take/gif';
+
+const encoder: GifEncoderFactory = ({ repeat }) => ({
+    addFrame({ data, width, height, durationMs }) {
+        // Pass the opaque RGBA snapshot to your codec; may return Promise<void>.
+    },
+    async finish() {
+        // Return complete GIF bytes as Uint8Array.
+        return encodedBytes;
+    },
+    dispose() {
+        // Drop buffers, terminate owned Workers, settle pending operations.
+    },
+});
+```
+
+Каждый вызов фабрики должен создавать новый кодировщик и учитывать переданное число
+повторов. Экспортёр вызывает методы последовательно и вызывает `dispose()` один
+раз при успехе, ошибке или отмене. Адаптер может передать принадлежащий ему буфер
+кадра в Worker; он должен освобождать ссылки на кадр после каждой операции
+и поддерживать dispose во время ожидающей операции. Отмена немедленно отклоняет
+операции экспортёра, но внешнюю работу очищает адаптер. Синхронную работу кодека
+нельзя прервать в том же потоке. Исключения очистки подавляются, чтобы сохранить
+основной результат операции.
+
+После сборки запустите `node examples/server.cjs` и откройте
+`http://127.0.0.1:3012/canvas-take/examples/gif.html` — отдельный пример покадрового
+экспорта с отменой, предпросмотром и скачиванием. Обоснование выбора кодека
+и измеренные размеры модулей приведены в [docs/gif-encoder.md](../docs/gif-encoder.md).
+
+Если собранный AlgiViz находится в соседнем каталоге `algiviz`, откройте
+`http://127.0.0.1:3012/canvas-take/examples/gif-bfs.html` для интеграции с настоящим
+BFS. Ранее проверенный результат: 800×560, 141 кадр, 9 секунд с удержанием последнего
+кадра 2 секунды, около 1,60 МБ. Пример использует существующие алгоритм и рендерер
+AlgiViz и не изменяет тот проект.
+
+## Использование в браузере и на сервере
+
+Для записи нужен браузер с `canvas.captureStream`, `MediaRecorder` и `MutationObserver`.
+Импорт модуля не обращается к этим API; создание рекордера проверяет поддержку
+захвата и кодировщика. Реализации записи для Node.js нет. Поддержка кодеков
+определяется во время выполнения, а не по названию браузера.
+
+Интеграционный пример ранее проверен настоящей записью VP9 в 1920×1080.
+Это не обещание, что любой браузер создаст WebM или MP4. Canvas с содержимым
+из другого источника без CORS может оказаться недоступен для захвата.
+
+## Выпуск версии
+
+Запустите `npm test` и `npm run test:package`: последняя команда упаковывает архив,
+устанавливает его в изолированное приложение и проверяет декларации TypeScript
+и импорты во время выполнения. Архив содержит dist, README, LICENSE, CHANGELOG
+и метаданные пакета. Исходный код и задачи:
+[urffin/canvas-take](https://github.com/urffin/canvas-take). API версии 0.x может
+меняться в следующих минорных релизах.
+
+После успешного CI для коммита релиза опубликуйте стабильный GitHub Release
+с тегом `v<package version>`. Workflow `npm-publish.yml` проверяет согласованность
+версий, тестирует приложение с упакованным пакетом и публикует с OIDC/provenance.
+Перед первым автоматическим релизом настройте npm trusted publisher для владельца
+`urffin`, репозитория `canvas-take` и workflow `npm-publish.yml`. Токен npm
+не используется. Публикация — отдельное действие сопровождающего проекта.