@grundyjs/canvas-take 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 — unreleased
+
+- Silent canvas recording with automatic WebM/MP4 format selection.
+- Promise-based start and stop, final-chunk handling and idempotent disposal.
+- Resource cleanup on errors, resize and unexpected track termination.
+- ESM and TypeScript declarations; no runtime dependencies.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grundy
+
+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/README.md

@@ -1,4 +1,54 @@
-# Temporary Holding Version
+# CanvasTake
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+Independent TypeScript library for silent HTML canvas video recording. No runtime dependencies or dependency on AlgiViz. ESM only, with TypeScript declarations. MIT licensed. The package does not start or draw your animation.
+
+## Install
+
+```sh
+npm install @grundyjs/canvas-take
+```
+
+## Record a 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` resolves after the MediaRecorder start event. `stop` waits for the final dataavailable and stop events; repeated calls return the same promise. Errors reject pending operations, stop owned tracks and release chunks. `dispose` cancels an unfinished recording; it is idempotent. Each instance records once. State stays idle while start is pending; a second start is rejected.
+
+Auto format order: WebM VP9, VP8, generic WebM, MP4. 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 audio, 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.
+
+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.
+
+See [MediaRecorder stop](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder/stop) and [format support](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder/isTypeSupported_static).
+MediaRecorder WebM output may omit duration metadata: playback can work while the player reports an indefinite duration. For reliable seeking or publication, remux the output separately. CanvasTake does not rewrite container metadata.
+
+## Options and result
+
+| Option | Meaning |
+| --- | --- |
+| `fps` | Required positive finite capture rate target |
+| `videoBitsPerSecond` | Optional positive finite encoder bitrate target |
+| `mimeType` | Optional explicit supported `video/webm` or `video/mp4` MIME, including codecs |
+
+`stop()` returns `{ blob, mimeType, extension, durationMs }`. Keep the recorder in a try/finally and call `dispose()` even if your animation fails. Revoke object URLs when no longer needed.
+
+## 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.
+
+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.
+
+## Release
+
+Run `npm test`, `npm pack --dry-run` and install the tarball in a separate consumer project. The archive contains dist, README, LICENSE, CHANGELOG and package metadata. Source and issues: [urffin/canvas-take](https://github.com/urffin/canvas-take). Version 0.1 is an initial API and may change in later minor releases. Publishing is a separate maintainer action.
+

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export interface RecordingResult {
+    readonly blob: Blob;
+    readonly mimeType: string;
+    readonly extension: "webm" | "mp4";
+    readonly durationMs: number;
+}
+export interface RecorderOptions {
+    readonly fps: number;
+    readonly videoBitsPerSecond?: number;
+    readonly mimeType?: string;
+}
+export type RecorderState = "idle" | "recording" | "stopping" | "stopped" | "disposed";
+export interface CanvasRecorder {
+    readonly state: RecorderState;
+    start(): Promise<void>;
+    stop(): Promise<RecordingResult>;
+    dispose(): void;
+}
+/** One recorder instance produces one silent video; drawing is managed by the caller. */
+export declare function createCanvasRecorder(canvas: HTMLCanvasElement, options: RecorderOptions): CanvasRecorder;

package/dist/index.js

@@ -0,0 +1,182 @@
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
+    // Errors may occur before the caller asks for the final result.
+    void promise.catch(() => { });
+    return { promise, resolve, reject };
+}
+function extension(mime) {
+    const base = mime.split(";", 1)[0].trim().toLowerCase();
+    if (base === "video/webm")
+        return "webm";
+    if (base === "video/mp4")
+        return "mp4";
+    throw new TypeError(`Unsupported video container: ${mime}`);
+}
+/** One recorder instance produces one silent video; drawing is managed by the caller. */
+export function createCanvasRecorder(canvas, options) {
+    if (!Number.isFinite(options.fps) || options.fps <= 0)
+        throw new RangeError("fps must be positive and finite");
+    if (options.videoBitsPerSecond !== undefined &&
+        (!Number.isFinite(options.videoBitsPerSecond) || options.videoBitsPerSecond <= 0)) {
+        throw new RangeError("videoBitsPerSecond must be positive and finite");
+    }
+    if (typeof MediaRecorder === "undefined" || typeof canvas.captureStream !== "function") {
+        throw new Error("Canvas video recording is not supported in this environment");
+    }
+    const requested = options.mimeType;
+    if (requested !== undefined)
+        extension(requested);
+    const mime = requested ?? ["video/webm;codecs=vp9", "video/webm;codecs=vp8", "video/webm", "video/mp4"]
+        .find(candidate => MediaRecorder.isTypeSupported(candidate));
+    if (!mime || !MediaRecorder.isTypeSupported(mime))
+        throw new Error(`Unsupported recording format: ${mime ?? "none"}`);
+    let state = "idle";
+    let recorder;
+    let stream;
+    let observer;
+    let width = 0, height = 0, startedAt = 0, stoppedAt;
+    let chunks = [];
+    let startResult;
+    const result = deferred();
+    let stopPromise;
+    let failure;
+    function cleanup() {
+        observer?.disconnect();
+        recorder?.removeEventListener("start", onStart);
+        recorder?.removeEventListener("dataavailable", onData);
+        recorder?.removeEventListener("stop", onStop);
+        recorder?.removeEventListener("error", onError);
+        for (const track of stream?.getTracks() ?? []) {
+            track.removeEventListener("ended", onEnded);
+        }
+        try {
+            if (recorder && recorder.state !== "inactive")
+                recorder.stop();
+        }
+        catch { }
+        for (const track of stream?.getTracks() ?? [])
+            track.stop();
+        chunks = [];
+    }
+    function fail(error) {
+        if (state === "disposed" || state === "stopped")
+            return;
+        failure = error;
+        state = "stopped";
+        startResult?.reject(error);
+        result.reject(error);
+        cleanup();
+    }
+    function unchanged() { return canvas.width === width && canvas.height === height; }
+    function onStart() {
+        startedAt = performance.now();
+        state = "recording";
+        startResult.resolve();
+    }
+    function onData(event) { if (event.data.size)
+        chunks.push(event.data); }
+    function onError(event) {
+        fail(event.error ?? new Error("Video recording failed"));
+    }
+    function onEnded() { fail(new Error("Canvas capture track ended unexpectedly")); }
+    function onStop() {
+        if (!unchanged()) {
+            fail(new Error("Canvas bitmap size changed during recording"));
+            return;
+        }
+        if (state !== "stopping") {
+            fail(new Error("Recording stopped unexpectedly"));
+            return;
+        }
+        try {
+            const actualMime = recorder.mimeType || chunks.find(chunk => chunk.type)?.type || mime;
+            const ext = extension(actualMime);
+            const blob = new Blob(chunks, { type: actualMime });
+            if (!blob.size)
+                throw new Error("Recording produced an empty video");
+            state = "stopped";
+            result.resolve(Object.freeze({ blob, mimeType: actualMime, extension: ext,
+                durationMs: Math.max(0, (stoppedAt ?? performance.now()) - startedAt) }));
+            cleanup();
+        }
+        catch (error) {
+            fail(error);
+        }
+    }
+    function beginStop() {
+        if (state === "disposed")
+            return Promise.reject(new Error("Recorder is disposed"));
+        if (failure)
+            return result.promise;
+        if (state === "stopped" || state === "stopping")
+            return result.promise;
+        if (!unchanged()) {
+            fail(new Error("Canvas bitmap size changed during recording"));
+            return result.promise;
+        }
+        state = "stopping";
+        stoppedAt = performance.now();
+        try {
+            recorder.stop();
+        }
+        catch (error) {
+            fail(error);
+        }
+        return result.promise;
+    }
+    return Object.freeze({
+        get state() { return state; },
+        start() {
+            if (state !== "idle" || startResult)
+                return Promise.reject(new Error("Recorder can only start once"));
+            startResult = deferred();
+            try {
+                width = canvas.width;
+                height = canvas.height;
+                if (!width || !height)
+                    throw new RangeError("Canvas must have a positive bitmap size");
+                stream = canvas.captureStream(options.fps);
+                if (!stream.getVideoTracks().length)
+                    throw new Error("Canvas stream has no video track");
+                recorder = new MediaRecorder(stream, { mimeType: mime, videoBitsPerSecond: options.videoBitsPerSecond });
+                recorder.addEventListener("start", onStart);
+                recorder.addEventListener("dataavailable", onData);
+                recorder.addEventListener("stop", onStop);
+                recorder.addEventListener("error", onError);
+                for (const track of stream.getTracks())
+                    track.addEventListener("ended", onEnded);
+                if (typeof MutationObserver !== "undefined") {
+                    observer = new MutationObserver(() => {
+                        if (!unchanged())
+                            fail(new Error("Canvas bitmap size changed during recording"));
+                    });
+                    observer.observe(canvas, { attributes: true, attributeFilter: ["width", "height"] });
+                }
+                recorder.start(1000);
+            }
+            catch (error) {
+                fail(error);
+            }
+            return startResult.promise;
+        },
+        stop() {
+            if (state === "disposed")
+                return Promise.reject(new Error("Recorder is disposed"));
+            if (!startResult)
+                return Promise.reject(new Error("Recorder has not started"));
+            stopPromise ??= startResult.promise.then(beginStop);
+            return stopPromise;
+        },
+        dispose() {
+            if (state === "disposed")
+                return;
+            const error = new Error("Recording was disposed");
+            state = "disposed";
+            startResult?.reject(error);
+            result.reject(error);
+            cleanup();
+        }
+    });
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@grundyjs/canvas-take",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Record HTML canvas to video with explicit resource lifecycle",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Grundy",
+    "url": "https://grundyjs.ru/"
+  },
+  "homepage": "https://grundyjs.ru/algorithms/insertion-sort/",
+  "keywords": [
+    "canvas",
+    "video",
+    "recording",
+    "mediarecorder",
+    "typescript"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "url": "git+https://github.com/urffin/canvas-take.git",
+    "type": "git"
+  },
+  "bugs": {
+    "url": "https://github.com/urffin/canvas-take/issues"
+  }
+}