@glissade/backend-canvas2d 0.18.0 → 0.19.0-pre.1

package/dist/index.d.ts

@@ -28,6 +28,13 @@ declare class Canvas2DBackend implements RenderBackend {
   measureText(text: string, font: FontSpec): TextMetricsLite$1;
   render(list: DisplayList): void;
   readPixels(): Promise<Uint8ClampedArray>;
+  /**
+   * The backend's underlying canvas. Exposed so the tree-shakeable
+   * `@glissade/backend-canvas2d/snapshot` subpath (`snapshotCanvas`) can read it
+   * WITHOUT pulling the data-URL/Blob-encode code onto this base index — a
+   * trivial getter that adds no encode bytes here.
+   */
+  get canvas(): AnyCanvas;
   dispose(): void;
   private context;
 }

package/dist/index.js

@@ -72,6 +72,15 @@ var Canvas2DBackend = class {
 	async readPixels() {
 		return this.context(this.target).getImageData(0, 0, this.target.width, this.target.height).data;
 	}
+	/**
+	* The backend's underlying canvas. Exposed so the tree-shakeable
+	* `@glissade/backend-canvas2d/snapshot` subpath (`snapshotCanvas`) can read it
+	* WITHOUT pulling the data-URL/Blob-encode code onto this base index — a
+	* trivial getter that adds no encode bytes here.
+	*/
+	get canvas() {
+		return this.target;
+	}
 	dispose() {
 		this.raster.dispose();
 	}

package/dist/snapshot.d.ts

@@ -0,0 +1,48 @@
+import { Canvas2DBackend } from "./index.js";
+import { Scene } from "@glissade/scene";
+import { Timeline } from "@glissade/core";
+
+//#region src/snapshot.d.ts
+
+type AnyCanvas = HTMLCanvasElement | OffscreenCanvas;
+/**
+ * Capture a canvas (or a `Canvas2DBackend`'s current canvas) as a
+ * `data:image/png;base64,…` URL — the DX seam an AI consumer hit ("can't
+ * screenshot a live canvas"). Render a frame first (`backend.render(list)`),
+ * then `await snapshotCanvas(backend)`.
+ *
+ * Browser-only: relies on `OffscreenCanvas.convertToBlob` /
+ * `HTMLCanvasElement.toDataURL`. Async to match the underlying serialization
+ * (OffscreenCanvas is Blob-based, hence Promise-shaped).
+ *
+ * @param canvasOrBackend a `Canvas2DBackend`, an `HTMLCanvasElement`, or an `OffscreenCanvas`.
+ * @param type image MIME type (default `image/png`); `quality` for lossy types.
+ */
+declare function snapshotCanvas(canvasOrBackend: AnyCanvas | Canvas2DBackend, type?: string, quality?: number): Promise<string>;
+/**
+ * One-shot DX convenience (0.19): `evaluate(scene, timeline, t)` →
+ * `Canvas2DBackend.render` → `snapshotCanvas()`, returning a
+ * `data:image/png;base64,…` URL for the frame. The "screenshot a frame" path a
+ * host/test reaches for when it can't drive a live `<canvas>` (the AI-consumer
+ * wall).
+ *
+ * Allocates an offscreen target sized to the scene (`OffscreenCanvas`, falling
+ * back to a detached `<canvas>`), so the caller needs no DOM canvas. Browser-only
+ * (same constraint as `snapshotCanvas()` — Skia/Node has its own encode path).
+ *
+ * Mirrors the `evaluate` overload pair: pass a timeline + time to sample an
+ * animated frame, or omit both for the controlled-drive form (host-owned
+ * playhead via `node.set(...)`, evaluated at the scene's current playhead).
+ *
+ * @param type image MIME type (default `image/png`); `quality` for lossy types.
+ */
+declare function renderToDataURL(scene: Scene, timeline: Timeline, t: number, opts?: {
+  type?: string;
+  quality?: number;
+}): Promise<string>;
+declare function renderToDataURL(scene: Scene, opts?: {
+  type?: string;
+  quality?: number;
+}): Promise<string>;
+//#endregion
+export { renderToDataURL, snapshotCanvas };

package/dist/snapshot.js

@@ -0,0 +1,77 @@
+import { Canvas2DBackend } from "./index.js";
+import { evaluate } from "@glissade/scene";
+//#region src/snapshot.ts
+/**
+* @glissade/backend-canvas2d/snapshot — the "screenshot a rendered frame as a
+* data URL" DX seam (the AI-consumer wall: "can't screenshot a live canvas").
+*
+* This is DX / screenshot TOOLING, NOT a render path: a no-build playback embed
+* never needs it. So it lives on this SEPARATE, tree-shakeable subpath — off the
+* `@glissade/backend-canvas2d` base index (which is on the base embed budget),
+* mirroring how `@glissade/scene/path` / `/layout` / `/describe` keep their
+* byte-expensive code off the base scene index. The data-URL/Blob-encode bytes
+* here must never enter the base embed bundle.
+*
+* Browser-only by design: relies on `OffscreenCanvas.convertToBlob` /
+* `HTMLCanvasElement.toDataURL`. The Skia/Node twin has its own
+* `encodePNG`/`toBuffer` path (@napi-rs/canvas). Importing this module in a
+* headless Node env never throws — the browser-only constraint is enforced at
+* call time, never at load.
+*/
+/**
+* Encode a `Blob` (from `OffscreenCanvas.convertToBlob`) as a `data:` URL.
+* `arrayBuffer()` + `btoa()` (both Web standards present in browser, worker, and
+* Node) — leaner than wiring a `FileReader` and with no Node `Buffer`
+* dependency, so the bundle stays browser-clean.
+*/
+async function blobToDataURL(blob) {
+	const bytes = new Uint8Array(await blob.arrayBuffer());
+	let binary = "";
+	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+	return `data:${blob.type || "image/png"};base64,${btoa(binary)}`;
+}
+/** Pull the underlying canvas out of a `Canvas2DBackend`, or pass a canvas through. */
+function canvasOf(canvasOrBackend) {
+	return canvasOrBackend instanceof Canvas2DBackend ? canvasOrBackend.canvas : canvasOrBackend;
+}
+/**
+* Capture a canvas (or a `Canvas2DBackend`'s current canvas) as a
+* `data:image/png;base64,…` URL — the DX seam an AI consumer hit ("can't
+* screenshot a live canvas"). Render a frame first (`backend.render(list)`),
+* then `await snapshotCanvas(backend)`.
+*
+* Browser-only: relies on `OffscreenCanvas.convertToBlob` /
+* `HTMLCanvasElement.toDataURL`. Async to match the underlying serialization
+* (OffscreenCanvas is Blob-based, hence Promise-shaped).
+*
+* @param canvasOrBackend a `Canvas2DBackend`, an `HTMLCanvasElement`, or an `OffscreenCanvas`.
+* @param type image MIME type (default `image/png`); `quality` for lossy types.
+*/
+async function snapshotCanvas(canvasOrBackend, type = "image/png", quality) {
+	const canvas = canvasOf(canvasOrBackend);
+	if (typeof OffscreenCanvas !== "undefined" && canvas instanceof OffscreenCanvas) return await blobToDataURL(await canvas.convertToBlob({
+		type,
+		...quality !== void 0 ? { quality } : {}
+	}));
+	const el = canvas;
+	if (typeof el.toDataURL !== "function") throw new Error("snapshotCanvas() is browser-only: canvas has no toDataURL/convertToBlob");
+	return quality !== void 0 ? el.toDataURL(type, quality) : el.toDataURL(type);
+}
+async function renderToDataURL(scene, timelineOrOpts, t, opts) {
+	const hasTimeline = timelineOrOpts !== void 0 && typeof timelineOrOpts.version === "number";
+	const timeline = hasTimeline ? timelineOrOpts : void 0;
+	const o = (hasTimeline ? opts : timelineOrOpts) ?? {};
+	const { w, h } = scene.size;
+	const backend = new Canvas2DBackend(typeof OffscreenCanvas !== "undefined" ? new OffscreenCanvas(w, h) : Object.assign(document.createElement("canvas"), {
+		width: w,
+		height: h
+	}));
+	try {
+		backend.render(timeline !== void 0 ? evaluate(scene, timeline, t ?? 0) : evaluate(scene));
+		return await snapshotCanvas(backend, o.type, o.quality);
+	} finally {
+		backend.dispose();
+	}
+}
+//#endregion
+export { renderToDataURL, snapshotCanvas };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/backend-canvas2d",
-  "version": "0.18.0",
+  "version": "0.19.0-pre.1",
   "description": "glissade Canvas 2D render backend: DisplayList -> CanvasRenderingContext2D/OffscreenCanvas.",
   "license": "Apache-2.0",
   "engines": {
@@ -12,14 +12,18 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./snapshot": {
+      "types": "./dist/snapshot.d.ts",
+      "default": "./dist/snapshot.js"
     }
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@glissade/core": "0.18.0",
-    "@glissade/scene": "0.18.0"
+    "@glissade/core": "0.19.0-pre.1",
+    "@glissade/scene": "0.19.0-pre.1"
   },
   "repository": {
     "type": "git",