@grundyjs/canvas-take 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.1 — 2026-10-28
+
+- Correct package homepage to the CanvasTake page; refresh package description, keywords and English/Russian README navigation and test instructions.
+
+- Browser CI tests in Chromium and Firefox exercise the real GIF module Worker, cancellation and a fresh export on the same page. Downloaded GIFs are independently decoded to verify pixels, dimensions, frame timings and loop count.
+
+## 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.

package/README.md

@@ -1,5 +1,9 @@
 # CanvasTake
 
+[Русский](ru/README.md)
+
+[Website](https://grundyjs.ru/en/canvas-take/) · [npm](https://www.npmjs.com/package/@grundyjs/canvas-take) · [Issues](https://github.com/urffin/canvas-take/issues)
+
 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
@@ -25,7 +29,7 @@ recorder.dispose();
 
 Auto format order: WebM VP9, VP8, generic WebM, MP4. With audio, the VP9 and VP8 candidates include Opus. An explicit unsupported MIME fails without silently changing the format. The result reports the actual MIME and matching extension. FPS and bitrate are targets, not guarantees. durationMs measures recording wall time, not parsed file duration.
 
-Keep canvas bitmap dimensions fixed from start until stop. CSS scaling is allowed. Size changes fail the recording. Canvas must remain origin-clean. No screen capture, pause, frame-by-frame encoding or server upload. Chunks are retained in memory: the caller should limit duration. If background-tab throttling is unacceptable, the caller should dispose when the page becomes hidden. Codec support depends on the browser and available resources.
+Keep canvas bitmap dimensions fixed from start until stop. CSS scaling is allowed. Size changes fail the recording. Canvas must remain origin-clean. The video recorder does not support screen capture, pause, frame-by-frame video encoding or server upload. Chunks are retained in memory: the caller should limit duration. If background-tab throttling is unacceptable, the caller should dispose when the page becomes hidden. Codec support depends on the browser and available resources.
 
 Development: Node.js 22+, `npm install`, `npm test`, `npm pack`. ESM and declarations are emitted to dist. `npm pack` rebuilds automatically; `npm publish` runs tests before packing. The integration example expects AlgiViz in a sibling directory and is served by the included local server.
 
@@ -130,7 +134,33 @@ try {
 
 `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, 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.
+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
 
@@ -165,6 +195,10 @@ Recording requires a browser with `canvas.captureStream`, `MediaRecorder` and `M
 
 The integration example was verified with an actual VP9 recording at 1920×1080. This is not a promise that every browser can produce WebM or MP4. A canvas containing cross-origin content without CORS may not be captured.
 
+## Development checks
+
+Run `npm test` for unit and Node Worker tests, and `npm run test:package` for an isolated packed consumer. For real browser tests, first run `npx playwright install chromium firefox`, then `npm run test:browser`. These check GIF export, cancellation, a fresh export on the same page, Worker cleanup and independently decoded output. `npm run test:next` checks the packed library with Next.js/Turbopack. See [GIF verification details](docs/gif-encoder.md#verification).
+
 ## Release
 
 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.

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

@@ -26,6 +26,16 @@ export interface GifExportOptions {
     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 {

package/dist/gif.js

@@ -1,6 +1,9 @@
 /** 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')
@@ -16,6 +19,14 @@ export function createGifExporter(options) {
     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(() => { });
@@ -35,6 +46,7 @@ export function createGifExporter(options) {
         state = 'aborted';
         rejectCancelled(abortError());
         cleanup();
+        report('aborted');
     }
     signal?.addEventListener('abort', onAbort, { once: true });
     if (signal?.aborted)
@@ -57,6 +69,7 @@ export function createGifExporter(options) {
             if (state === 'encoding') {
                 state = 'failed';
                 cleanup();
+                report('failed');
             }
             throw error;
         }
@@ -94,6 +107,9 @@ export function createGifExporter(options) {
                 width = w;
                 height = h;
                 frames++;
+                duration += Math.round(durationMs / 10) * 10;
+                report('encoding');
+                active();
                 state = 'ready';
             });
         },
@@ -101,6 +117,8 @@ export function createGifExporter(options) {
             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 ||
@@ -110,15 +128,20 @@ export function createGifExporter(options) {
                 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';
-            rejectCancelled(new DOMException('GIF exporter disposed', 'AbortError'));
+            if (unfinished)
+                rejectCancelled(new DOMException('GIF exporter disposed', 'AbortError'));
             cleanup();
+            if (unfinished)
+                report('disposed');
         }
     });
 }

package/docs/gif-encoder.md

@@ -15,7 +15,7 @@ gifenc was selected for the supplied adapter, not embedded into the controller.
 
 ## Loading and execution
 
-Measured emitted files (uncompressed / gzip):
+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.
@@ -25,8 +25,18 @@ The adapter is bundled at build time; gifenc, esbuild and the test decoder are d
 
 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
 
+Run `npx playwright install chromium firefox` once, then `npm run test:browser`. The browser suite serves built modules with `worker-src 'self'`, observes actual Worker creation/closure, exports through a real canvas and downloads the GIF for independent decoding with gifuct-js. It checks every pixel, dimensions, frame count/durations, repeat count and progress events. An open-ended frame producer keeps the cancellation case active until the test clicks Cancel after observing a completed frame; no machine-speed-dependent delay is used. A second export on the same page must create and close a fresh Worker and produce the expected GIF. CI installs both browsers and retains the HTML report, GIF outputs, and failure screenshots/traces for seven days. These tests exercise direct module loading; the separate Next.js job covers bundler compilation.
+
+`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.

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@grundyjs/canvas-take",
-  "version": "0.3.0",
-  "description": "Record HTML canvas to video with explicit resource lifecycle",
+  "version": "0.4.1",
+  "description": "Record HTML canvas video with audio and export GIFs with pluggable encoders, Worker support and explicit resource cleanup",
   "type": "module",
   "files": [
     "dist",
     "README.md",
+    "ru/README.md",
     "LICENSE",
     "CHANGELOG.md",
     "docs/gif-encoder.md"
@@ -25,16 +26,25 @@
       "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 && 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",
+    "test:browser": "npm run build && playwright test"
   },
   "devDependencies": {
+    "@playwright/test": "1.64.1",
     "esbuild": "0.28.2",
     "gifenc": "1.0.3",
     "gifuct-js": "2.1.2",
@@ -45,12 +55,15 @@
     "name": "Grundy",
     "url": "https://grundyjs.ru/"
   },
-  "homepage": "https://grundyjs.ru/algorithms/insertion-sort/",
+  "homepage": "https://grundyjs.ru/canvas-take/",
   "keywords": [
     "canvas",
     "video",
     "recording",
     "mediarecorder",
+    "gif",
+    "audio",
+    "web-worker",
     "typescript"
   ],
   "sideEffects": false,

package/ru/README.md

@@ -0,0 +1,330 @@
+# CanvasTake
+
+[English](../README.md)
+
+[Сайт](https://grundyjs.ru/canvas-take/) · [npm](https://www.npmjs.com/package/@grundyjs/canvas-take) · [Ошибки и предложения](https://github.com/urffin/canvas-take/issues)
+
+Независимая 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` запускает модульные тесты и проверки Node Worker, а `npm run test:package`
+проверяет установку упакованной библиотеки в отдельный проект. Для настоящих браузеров
+сначала выполните `npx playwright install chromium firefox`, затем `npm run test:browser`.
+Проверяются GIF-экспорт, отмена, повторный экспорт на той же странице, завершение Worker
+и независимое декодирование результата. `npm run test:next` проверяет сборку
+упакованной библиотеки с Next.js/Turbopack. Подробности — в
+[описании проверок GIF](../docs/gif-encoder.md#verification).
+
+## Выпуск версии
+
+Запустите `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
+не используется. Публикация — отдельное действие сопровождающего проекта.