@neta-art/cohub 9.0.1 → 11.0.0

package/dist/board/export/index.js

@@ -1,8 +1,9 @@
-import { boardDocumentAt } from "../animation.js";
-import { normalizeBoardDocument, planBoardExport } from "../core/export-plan.js";
-import { buildBoardScene } from "../core/scene.js";
+import { buildBoardScene } from "../model/scene.js";
+import { resolveBoardAnimationCamera } from "../model/sampling.js";
+import { normalizeBoardDocument, planBoardExport } from "../model/export-plan.js";
 import { parseBoardCssColor } from "../render/css-color.js";
 import { defaultBoardPalette } from "../render/palette.js";
+import { createBoardRenderSampler } from "../render/sampling.js";
 import { ensureBoardTextMeasurement } from "../render/text-measurement.js";
 import { createBoardExportScene } from "./scene.js";
 import { Rectangle } from "pixi.js";
@@ -14,20 +15,51 @@ function resolveBackground(background, palette, document, colorScheme) {
 	const css = typeof declared === "object" ? declared[colorScheme] : declared;
 	return css ? parseBoardCssColor(css) ?? palette.bg : palette.bg;
 }
-function renderBoardExport(renderer, input, options = {}) {
+function prepareBoardExport(input, options = {}) {
 	ensureBoardTextMeasurement();
-	const base = normalizeBoardDocument(input);
-	const document = options.at ? boardDocumentAt(base, options.at.animation ?? null, options.at.time).document : base;
-	const scene = buildBoardScene(document);
+	const base = options.sampler ? input : normalizeBoardDocument(input);
+	if (options.camera && options.region && options.region.kind !== "all") throw new Error("Camera export cannot be combined with a fixed region.");
+	if (options.camera && !options.at) throw new Error("Camera export needs an animation time.");
+	if (options.camera && ![options.camera.width, options.camera.height].every((n) => Number.isSafeInteger(n) && n > 0)) throw new Error("Camera dimensions must be positive integers.");
+	const sampler = options.at ? options.sampler ?? createBoardRenderSampler(base, options.at.animation ?? null, options) : void 0;
+	const sample = options.at ? sampler?.at(options.at.time) : void 0;
+	const sampled = sample?.document ?? base;
+	const document = options.scripts?.document?.(sampled, options.at?.time ?? 0) ?? sampled;
+	const scene = document === sampled ? sample?.scene ?? buildBoardScene(document) : buildBoardScene(document);
+	const camera = options.camera ? resolveBoardAnimationCamera(sample?.evaluation.camera ?? {}, (id) => scene.get(id)?.frame, options.camera, options.at?.time ?? 0) : void 0;
+	const region = camera && options.camera ? {
+		kind: "rect",
+		rect: {
+			x: -camera.x / camera.zoom,
+			y: -camera.y / camera.zoom,
+			width: options.camera.width / camera.zoom,
+			height: options.camera.height / camera.zoom
+		}
+	} : options.region ?? { kind: "all" };
 	const plan = planBoardExport({
 		scene,
-		region: options.region ?? { kind: "all" },
-		scale: options.scale,
-		padding: options.padding,
+		region,
+		scale: camera?.zoom ?? options.scale,
+		padding: camera ? 0 : options.padding,
 		maxEdge: options.maxEdge,
 		maxPixels: options.maxPixels
 	});
-	if (!plan) return null;
+	if (plan && camera && options.camera) {
+		const ratio = plan.clamped ? plan.scale / camera.zoom : 1;
+		plan.width = Math.max(1, Math.floor(options.camera.width * ratio));
+		plan.height = Math.max(1, Math.floor(options.camera.height * ratio));
+	}
+	return plan ? {
+		document,
+		scene,
+		plan,
+		sampler
+	} : null;
+}
+function renderBoardExport(renderer, input, options = {}) {
+	const prepared = prepareBoardExport(input, options);
+	if (!prepared) return null;
+	const { document, scene, plan, sampler } = prepared;
 	const colorScheme = options.colorScheme ?? "dark";
 	const palette = {
 		...defaultBoardPalette(colorScheme),
@@ -38,14 +70,16 @@ function renderBoardExport(renderer, input, options = {}) {
 		scene,
 		items: plan.items,
 		time: options.at?.time ?? 0,
+		frameAt: sampler?.frameAt,
 		world: plan.world,
 		scale: plan.scale,
 		colorScheme,
 		palette,
 		colors: options.colors,
 		textures: options.textures,
-		sketches: options.sketches,
+		scripts: options.scripts,
 		assetKey: options.assetKey,
+		renderers: options.renderers,
 		background: resolveBackground(options.background, palette, document, colorScheme),
 		backgroundImage: options.backgroundImage
 	});
@@ -88,4 +122,4 @@ function describeBoardExportWarning(warning) {
 	}
 }
 //#endregion
-export { createBoardExportScene, describeBoardExportWarning, renderBoardExport };
+export { createBoardExportScene, describeBoardExportWarning, prepareBoardExport, renderBoardExport };

package/dist/board/export/node/index.d.ts

@@ -0,0 +1,56 @@
+import { BoardDocument } from "../../../protocol/dist/board-model.js";
+import "../../../protocol/dist/index.js";
+import { BoardScriptHost } from "../../render/renderers/board-renderer-registry.js";
+import { BoardExportOptions, BoardExportResult } from "../index.js";
+import { createNodeBoardScriptHost } from "./scripts.js";
+import { Renderer } from "pixi.js";
+//#region src/board/export/node/index.d.ts
+type NodeCanvasModule = {
+  createCanvas: (width: number, height: number) => unknown;
+  Image: new () => unknown;
+  GlobalFonts: {
+    registerFromPath: (path: string, name?: string) => unknown;
+    has: (name: string) => boolean;
+    setAlias?: (fontName: string, alias: string) => boolean;
+  };
+};
+type BoardNodeFont = {
+  path: string;
+  family?: string;
+};
+type BoardNodeRendererOptions = {
+  fonts?: BoardNodeFont[];
+  canvasModule?: NodeCanvasModule;
+};
+type BoardNodeTexture = {
+  readonly __boardTexture: unique symbol;
+  destroy: (destroySource?: boolean) => void;
+};
+type BoardNodeRenderer = {
+  renderer: Renderer;
+  canvasModule: NodeCanvasModule;
+  decodeImage: (bytes: Uint8Array, mimeType?: string) => Promise<BoardNodeTexture>;
+  destroy: () => void;
+};
+declare function createNodeBoardRenderer(options?: BoardNodeRendererOptions): Promise<BoardNodeRenderer>;
+type BoardNodeExportFormat = "png" | "jpeg" | "webp";
+type BoardNodeExportOptions = Omit<BoardExportOptions, "textures" | "backgroundImage"> & {
+  textures?: Map<string, BoardNodeTexture>;
+  backgroundImage?: {
+    texture: BoardNodeTexture;
+    fit: "cover" | "contain" | "repeat";
+    position: "center" | "top" | "bottom" | "left" | "right";
+    opacity: number;
+  };
+  scripts?: BoardScriptHost;
+  format?: BoardNodeExportFormat;
+  quality?: number;
+};
+type BoardNodeExportResult = Omit<BoardExportResult, "canvas"> & {
+  bytes: Uint8Array;
+  format: BoardNodeExportFormat;
+};
+declare function boardImageMimeType(format: BoardNodeExportFormat): string;
+declare function exportBoardImageBytes(renderer: BoardNodeRenderer, document: BoardDocument, options?: BoardNodeExportOptions): BoardNodeExportResult | null;
+//#endregion
+export { BoardNodeExportFormat, BoardNodeExportOptions, BoardNodeExportResult, BoardNodeFont, BoardNodeRenderer, BoardNodeRendererOptions, BoardNodeTexture, NodeCanvasModule, boardImageMimeType, createNodeBoardRenderer, createNodeBoardScriptHost, exportBoardImageBytes };

package/dist/board/{headless → export/node}/index.js

@@ -1,9 +1,9 @@
-import "../../protocol/dist/board-constants.js";
-import { installBoardTextMeasurement } from "../render/text-measurement.js";
-import { renderBoardExport } from "../export/index.js";
-import { createBoardHeadlessSketchHost } from "./sketch.js";
+import "../../../protocol/dist/board-constants.js";
+import { installBoardTextMeasurement } from "../../render/text-measurement.js";
+import { renderBoardExport } from "../index.js";
+import { createNodeBoardScriptHost } from "./scripts.js";
 import { CanvasGraphicsContextSystem, CanvasGraphicsPipe, CanvasRenderer, CanvasRendererTextSystem, CanvasTextPipe, CanvasTextSystem, DOMAdapter, GraphicsContextSystem, GraphicsPipe, ImageSource, Texture, extensions } from "pixi.js";
-//#region src/board/headless/index.ts
+//#region src/board/export/node/index.ts
 const SYSTEM_UI_FAMILIES = [
 	"Noto Sans",
 	"DejaVu Sans",
@@ -61,7 +61,7 @@ function installAnimationFrameShim() {
 		globals.cancelAnimationFrame = void 0;
 	};
 }
-async function createBoardHeadlessRenderer(options = {}) {
+async function createNodeBoardRenderer(options = {}) {
 	const canvasModule = options.canvasModule ?? await loadCanvasModule();
 	extensions.add(CanvasGraphicsPipe, GraphicsPipe, CanvasGraphicsContextSystem, GraphicsContextSystem, CanvasRendererTextSystem, CanvasTextSystem, CanvasTextPipe);
 	for (const font of options.fonts ?? []) canvasModule.GlobalFonts.registerFromPath(font.path, font.family ?? "Geist");
@@ -78,14 +78,14 @@ async function createBoardHeadlessRenderer(options = {}) {
 		getCanvasRenderingContext2D: () => createCanvas(1, 1).getContext("2d").constructor,
 		getWebGLRenderingContext: () => WEBGL_PROBE_STUB,
 		getNavigator: () => ({
-			userAgent: "cohub-board-headless",
+			userAgent: "cohub-board-node",
 			gpu: null
 		}),
 		getBaseUrl: () => "file://",
 		getFontFaceSet: () => null,
 		fetch: (url, init) => fetch(url, init),
 		parseXML: () => {
-			throw new Error("XML parsing is not available in headless board export.");
+			throw new Error("XML parsing is not available in Node board export.");
 		}
 	});
 	installBoardTextMeasurement();
@@ -127,14 +127,14 @@ const MIME = {
 	jpeg: "image/jpeg",
 	webp: "image/webp"
 };
-function boardHeadlessMimeType(format) {
+function boardImageMimeType(format) {
 	return MIME[format];
 }
-function exportBoardImageBytes(headless, document, options = {}) {
-	const { format = "png", quality = .92, textures, sketches, backgroundImage, ...rest } = options;
-	const result = renderBoardExport(headless.renderer, document, {
+function exportBoardImageBytes(renderer, document, options = {}) {
+	const { format = "png", quality = .92, textures, scripts, backgroundImage, ...rest } = options;
+	const result = renderBoardExport(renderer.renderer, document, {
 		...rest,
-		...sketches ? { sketches } : {},
+		...scripts ? { scripts } : {},
 		...textures ? { textures } : {},
 		...backgroundImage ? { backgroundImage: {
 			...backgroundImage,
@@ -143,13 +143,18 @@ function exportBoardImageBytes(headless, document, options = {}) {
 	});
 	if (!result) return null;
 	const canvas = result.canvas;
-	const bytes = format === "png" ? canvas.toBuffer(MIME.png) : canvas.toBuffer(MIME[format], Math.round(quality * 100));
-	return {
-		bytes: new Uint8Array(bytes),
-		plan: result.plan,
-		warnings: result.warnings,
-		format
-	};
+	try {
+		const bytes = format === "png" ? canvas.toBuffer(MIME.png) : canvas.toBuffer(MIME[format], Math.round(quality * 100));
+		return {
+			bytes: new Uint8Array(bytes),
+			plan: result.plan,
+			warnings: result.warnings,
+			format
+		};
+	} finally {
+		canvas.width = 1;
+		canvas.height = 1;
+	}
 }
 //#endregion
-export { boardHeadlessMimeType, createBoardHeadlessRenderer, createBoardHeadlessSketchHost, exportBoardImageBytes };
+export { boardImageMimeType, createNodeBoardRenderer, createNodeBoardScriptHost, exportBoardImageBytes };

package/dist/board/export/node/scripts.d.ts

@@ -0,0 +1,16 @@
+import { BoardSceneItem } from "../../model/scene.js";
+import { BoardScriptHost } from "../../render/renderers/board-renderer-registry.js";
+import { BoardNodeRenderer } from "./index.js";
+//#region src/board/export/node/scripts.d.ts
+type BoardNodeScriptOptions = {
+  readModule(src: string): Promise<string>;
+  timeoutMs?: number;
+  readTimeoutMs?: number;
+};
+declare function createNodeBoardScriptHost(renderer: BoardNodeRenderer, options: BoardNodeScriptOptions): BoardScriptHost & {
+  prepare(items: readonly BoardSceneItem[], times: readonly number[], zoom: number): Promise<void>;
+  clearFrames(): void;
+  destroy(): void;
+};
+//#endregion
+export { BoardNodeScriptOptions, createNodeBoardScriptHost };

package/dist/board/export/node/scripts.js

@@ -0,0 +1,258 @@
+import { boardScriptScope, composeBoardScriptItems } from "../../model/script-scene.js";
+import { buildBoardScene } from "../../model/scene.js";
+import { createBoardScriptModuleReader, loadBoardScriptSources } from "../../../protocol/dist/board-script-modules.js";
+import { createScriptRuntime } from "../../render/script-runtime.js";
+import { Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+//#region src/board/export/node/scripts.ts
+const WORKER = `
+const {parentPort, workerData} = require('node:worker_threads');
+const {createContext, Script, SourceTextModule} = require('node:vm');
+const {createCanvas} = require(workerData.canvasModule);
+const instances = new Map();
+const graphs = new Map();
+const update = new Script('__runtime.update(JSON.parse(__inputJson)); __runtime.step(__time)');
+const draw = new Script('__runtime.draw(__drawing)');
+const output = new Script('JSON.stringify(__runtime.output())');
+const dispose = new Script('__runtime.destroy()');
+function release(id) {
+ const entry=instances.get(id);instances.delete(id);
+ if(entry) {try {dispose.runInContext(entry.context,{timeout:workerData.timeout});} catch {}}
+}
+async function create(data) {
+ const context = createContext({console:{log(){},warn(){},error(){}},structuredClone},{codeGeneration:{strings:false,wasm:false}});
+ new Script("const __name=(value,name)=>Object.defineProperty(value,'name',{value:name,configurable:true})").runInContext(context);
+ const sources = graphs.get(data.src);
+ if(!sources) throw new Error('Module graph is unavailable.');
+ const modules = new Map();
+ const resolve = (from,name) => {
+  const parts=from.split('/').slice(0,-1);
+  for(const part of name.split('/')) { if(part==='..') parts.pop(); else if(part!=='.') parts.push(part); }
+  return parts.join('/');
+ };
+ const link = (name,ref) => load(resolve(ref.identifier,name));
+ function load(path) {
+  if(modules.has(path)) return modules.get(path);
+  const source=sources[path];
+  if(!source) throw new Error('Module is unavailable: '+path);
+  const module=new SourceTextModule(source.code,{context,identifier:path,importModuleDynamically:async name=>{
+   const child=load(resolve(path,name));
+   if(child.status==='unlinked') await child.link(link);
+   if(child.status==='linked') await child.evaluate({timeout:workerData.timeout});
+   return child;
+  }});
+  modules.set(path,module);return module;
+ }
+ const root=load(data.src);
+ await root.link(link);await root.evaluate({timeout:workerData.timeout});
+ context.__module=root.namespace;
+ context.__inputJson=JSON.stringify(data.input);
+ new Script('globalThis.__runtime=('+workerData.runtime+')(__module,JSON.parse(__inputJson),{call:async()=>{throw new Error("Capabilities are unavailable during export.")},invalidate(){}})').runInContext(context,{timeout:workerData.timeout});
+ return {context,signature:data.signature,time:-1,draw:!!root.namespace.draw,canvas:null};
+}
+parentPort.on('message',async data=>{
+ try {
+  if(data.release) {for(const id of data.release) release(id);return;}
+  if(data.sources) graphs.set(data.src,data.sources);
+  let entry=instances.get(data.input.id);
+  if(!entry || entry.signature!==data.signature || data.time<entry.time) {
+   release(data.input.id);
+   entry=await create(data);instances.set(data.input.id,entry);
+  }
+  const context=entry.context;
+  context.__inputJson=JSON.stringify(data.input);context.__time=data.time;
+  update.runInContext(context,{timeout:workerData.timeout});entry.time=data.time;
+  let png;
+  if(entry.draw) {
+   const width=Math.max(1,Math.round(data.input.width*data.scale));
+   const height=Math.max(1,Math.round(data.input.height*data.scale));
+   const canvas=entry.canvas??=createCanvas(width,height);
+   canvas.width=width;canvas.height=height;
+   const drawing=canvas.getContext('2d');drawing.scale(data.scale,data.scale);
+   context.__drawing=drawing;draw.runInContext(context,{timeout:workerData.timeout});
+   png=canvas.toBuffer('image/png');delete context.__drawing;
+  }
+  parentPort.postMessage({png,output:JSON.parse(output.runInContext(context,{timeout:workerData.timeout}))});
+ } catch(error) { instances.delete(data.input?.id);parentPort.postMessage({error:String(error.stack||error)}); }
+});
+`;
+function createNodeBoardScriptHost(renderer, options) {
+	const textures = /* @__PURE__ */ new Map();
+	const outputs = /* @__PURE__ */ new Map();
+	const errors = /* @__PURE__ */ new Map();
+	const sources = /* @__PURE__ */ new Map();
+	const modules = createBoardScriptModuleReader(options.readModule, options.readTimeoutMs);
+	const lanes = Array.from({ length: 4 }, () => ({
+		worker: null,
+		tail: Promise.resolve(),
+		graphs: /* @__PURE__ */ new Set()
+	}));
+	const assignments = /* @__PURE__ */ new Map();
+	let disposed = false;
+	let nextLane = 0;
+	const timeout = options.timeoutMs ?? 2e3;
+	const key = (id, time) => `${id}|${time}`;
+	function stop(lane) {
+		const worker = lane.worker;
+		lane.worker = null;
+		lane.graphs.clear();
+		worker?.terminate();
+	}
+	function sample(input, graph, time, scale) {
+		let lane = assignments.get(input.id);
+		if (!lane) {
+			lane = lanes[nextLane++ % lanes.length];
+			assignments.set(input.id, lane);
+		}
+		const selected = lane;
+		const task = selected.tail.then(() => new Promise((resolve, reject) => {
+			if (disposed) {
+				reject(/* @__PURE__ */ new Error("Script host is disposed."));
+				return;
+			}
+			if (!Number.isFinite(time) || time < 0 || time > 6e5) {
+				reject(/* @__PURE__ */ new Error("Script export time must be between 0 and 600000 ms."));
+				return;
+			}
+			const freshWorker = !selected.worker;
+			selected.worker ??= new Worker(WORKER, {
+				eval: true,
+				execArgv: ["--experimental-vm-modules", "--disable-warning=ExperimentalWarning"],
+				env: {},
+				resourceLimits: { maxOldGenerationSizeMb: 128 },
+				workerData: {
+					runtime: createScriptRuntime.toString(),
+					timeout,
+					canvasModule: fileURLToPath(import.meta.resolve("@napi-rs/canvas"))
+				}
+			});
+			const worker = selected.worker;
+			if (freshWorker) {
+				const stopped = (error) => {
+					if (selected.worker !== worker) return;
+					if (selected.reject) selected.reject(error);
+					else stop(selected);
+				};
+				worker.on("error", stopped);
+				worker.on("exit", () => stopped(/* @__PURE__ */ new Error("Script worker stopped.")));
+			}
+			const cleanup = () => {
+				clearTimeout(timer);
+				worker.off("message", message);
+				selected.reject = void 0;
+			};
+			const failure = (error) => {
+				cleanup();
+				stop(selected);
+				reject(error);
+			};
+			const message = (value) => {
+				cleanup();
+				if (value.error) reject(new Error(value.error));
+				else resolve(value);
+			};
+			const timer = setTimeout(() => failure(/* @__PURE__ */ new Error("Script export timed out.")), Math.max(timeout, 15e3));
+			selected.reject = failure;
+			worker.once("message", message);
+			const src = input.item.script?.src ?? "";
+			worker.postMessage({
+				input,
+				src,
+				signature: JSON.stringify(input.item.script),
+				sources: selected.graphs.has(src) ? void 0 : graph,
+				time,
+				scale
+			});
+			selected.graphs.add(src);
+		}));
+		selected.tail = task.catch(() => void 0);
+		return task;
+	}
+	return {
+		ready: (id) => [...outputs.values()].some((at) => at.has(id)),
+		frame: (item, time) => textures.get(key(item.id, time)) ?? null,
+		error: (id) => errors.get(id) ?? null,
+		release() {},
+		document(document, time) {
+			const at = outputs.get(time);
+			if (!at?.size) return document;
+			const items = { ...document.items };
+			for (const [id, item] of composeBoardScriptItems(document, buildBoardScene(document), at)) items[id] = item;
+			return {
+				...document,
+				items
+			};
+		},
+		clearFrames() {
+			for (const texture of textures.values()) texture.destroy(true);
+			textures.clear();
+			outputs.clear();
+			errors.clear();
+		},
+		async prepare(items, times, zoom) {
+			const scripted = items.filter((item) => item.script?.enabled);
+			const alive = new Set(scripted.map((item) => item.id));
+			for (const [id, lane] of assignments) if (!alive.has(id)) {
+				lane.worker?.postMessage({ release: [id] });
+				assignments.delete(id);
+			}
+			if (!scripted.length) return;
+			const all = Object.fromEntries(items.map(({ id, frame: _frame, ...item }) => [id, item]));
+			await Promise.all(scripted.map(async (item) => {
+				const base = all[item.id];
+				const src = item.script?.src;
+				if (!base || !src) return;
+				try {
+					let graph = sources.get(src);
+					if (!graph) {
+						graph = loadBoardScriptSources(src, modules.read, options.readTimeoutMs);
+						sources.set(src, graph);
+					}
+					const resolved = await graph;
+					const width = "size" in item ? item.size.width : item.frame.width;
+					const height = "size" in item ? item.size.height : item.frame.height;
+					const scale = Math.min(4, Math.max(.25, zoom), 2048 / Math.max(1, width, height));
+					const scoped = Object.fromEntries([...boardScriptScope({ items: all }, item.id)].flatMap((id) => all[id] ? [[id, all[id]]] : []));
+					for (const time of times) {
+						const result = await sample({
+							id: item.id,
+							item: base,
+							items: scoped,
+							width,
+							height
+						}, resolved, time, scale);
+						if (disposed) return;
+						if (result.png) {
+							const frameKey = key(item.id, time);
+							textures.get(frameKey)?.destroy(true);
+							textures.set(frameKey, await renderer.decodeImage(result.png));
+						}
+						let at = outputs.get(time);
+						if (!at) {
+							at = /* @__PURE__ */ new Map();
+							outputs.set(time, at);
+						}
+						at.set(item.id, result.output);
+					}
+				} catch (error) {
+					errors.set(item.id, error instanceof Error ? error.message : String(error));
+				}
+			}));
+		},
+		destroy() {
+			disposed = true;
+			for (const lane of lanes) {
+				lane.reject?.(/* @__PURE__ */ new Error("Script host is disposed."));
+				stop(lane);
+			}
+			for (const texture of textures.values()) texture.destroy(true);
+			textures.clear();
+			outputs.clear();
+			sources.clear();
+			modules.destroy();
+			assignments.clear();
+		}
+	};
+}
+//#endregion
+export { createNodeBoardScriptHost };

package/dist/board/export/scene.d.ts

@@ -1,9 +1,9 @@
 import { BoardSettings } from "../../protocol/dist/board-model.js";
 import "../../protocol/dist/index.js";
-import { Rect } from "../geometry.js";
-import { BoardScene, BoardSceneItem } from "../core/scene.js";
-import { BoardShapeColors } from "../core/palette.js";
-import { BoardRenderContext, BoardRenderPalette } from "../render/renderers/board-renderer-registry.js";
+import { Rect } from "../model/geometry.js";
+import { BoardScene, BoardSceneItem } from "../model/scene.js";
+import { BoardShapeColors } from "../model/palette.js";
+import { BoardCardRendererResolver, BoardRenderContext, BoardRenderPalette } from "../render/renderers/board-renderer-registry.js";
 import "../render/index.js";
 import { Container, Texture } from "pixi.js";
 //#region src/board/export/scene.d.ts
@@ -12,14 +12,17 @@ type BoardExportSceneInput = {
   scene: BoardScene;
   items: readonly BoardSceneItem[];
   time?: number;
+  frameAt?: BoardRenderContext["frameAt"];
   world: Rect;
   scale: number;
   colorScheme: "dark" | "light";
   palette?: Partial<BoardRenderPalette>;
   colors?: BoardShapeColors;
   textures?: Map<string, Texture>;
-  sketches?: BoardRenderContext["sketches"];
+  scripts?: BoardRenderContext["scripts"];
   assetKey?: (item: BoardSceneItem) => string | null;
+  /** Renderers for item types beyond the built-ins. */
+  renderers?: BoardCardRendererResolver;
   background?: number | null;
   backgroundImage?: {
     texture: Texture;

package/dist/board/export/scene.js

@@ -1,7 +1,7 @@
-import { imageAssetKey } from "../image-key.js";
-import { buildFallbackShapeColors } from "../core/palette.js";
-import { clippingAncestor, isClippingFrame, syncClipGroup } from "../render/clip.js";
+import { buildFallbackShapeColors } from "../model/palette.js";
+import { imageAssetKey } from "../model/image-key.js";
 import { defaultBoardPalette } from "../render/palette.js";
+import { clippingAncestor, isClippingFrame, syncClipGroup } from "../render/clip.js";
 import { getBoardCardRenderer } from "../render/renderers/board-renderer-registry.js";
 import { Container, Graphics, Sprite, TilingSprite } from "pixi.js";
 //#region src/board/export/scene.ts
@@ -13,6 +13,7 @@ function buildContext(input) {
 			settings: input.settings,
 			scene: input.scene,
 			time: input.time ?? 0,
+			frameAt: input.frameAt,
 			selectedIds: /* @__PURE__ */ new Set(),
 			hoveredId: null,
 			resizingIds: /* @__PURE__ */ new Set(),
@@ -24,7 +25,7 @@ function buildContext(input) {
 			colorScheme: input.colorScheme,
 			rendererType: "canvas",
 			zoom: input.scale,
-			sketches: input.sketches,
+			scripts: input.scripts,
 			assetKey: input.assetKey ?? imageAssetKey,
 			getTexture: (key) => textures.get(key) ?? null,
 			hasError: (key) => {
@@ -75,14 +76,28 @@ function createBoardExportScene(input) {
 	});
 	world.scale.set(input.scale);
 	world.position.set(-input.world.x * input.scale, -input.world.y * input.scale);
+	const resolve = input.renderers ?? getBoardCardRenderer;
 	const groups = /* @__PURE__ */ new Map();
-	for (const item of input.items) {
+	function hostFor(item) {
 		const clip = clippingAncestor(input.scene, item);
-		const host = clip && groups.get(clip) || world;
-		const container = getBoardCardRenderer(item, context).create(item, context);
-		container.alpha = input.scene.opacity(item.id);
+		const ancestor = clip ? input.scene.get(clip) : void 0;
+		if (!ancestor) return world;
+		let group = groups.get(ancestor.id);
+		if (!group) {
+			group = syncClipGroup(void 0, ancestor).group;
+			hostFor(ancestor).addChild(group);
+			groups.set(ancestor.id, group);
+		}
+		return group;
+	}
+	for (const item of input.items) {
+		const opacity = input.scene.opacity(item.id);
+		if (opacity <= 0) continue;
+		const host = hostFor(item);
+		const container = resolve(item, context).create(item, context);
+		container.alpha = opacity;
 		host.addChild(container);
-		if (isClippingFrame(item)) {
+		if (isClippingFrame(item) && !groups.has(item.id)) {
 			const { group } = syncClipGroup(void 0, item);
 			host.addChild(group);
 			groups.set(item.id, group);

package/dist/board/{animation.d.ts → model/animation.d.ts}

@@ -1,7 +1,7 @@
-import { BoardAnimationHeader, BoardColor, BoardDocument, BoardItem, BoardVec2 } from "../protocol/dist/board-model.js";
-import { BoardValueKind } from "../protocol/dist/board-patch.js";
-import "../protocol/dist/index.js";
-//#region src/board/animation.d.ts
+import { BoardAnimationHeader, BoardColor, BoardDocument, BoardItem, BoardVec2 } from "../../protocol/dist/board-model.js";
+import { BoardValueKind } from "../../protocol/dist/board-patch.js";
+import "../../protocol/dist/index.js";
+//#region src/board/model/animation.d.ts
 type BoardEaseFunction = (progress: number) => number;
 declare function boardEase(ease: string | undefined): BoardEaseFunction;
 declare function boardAnimationTime(header: Pick<BoardAnimationHeader, "duration" | "delay" | "loop" | "end" | "play">, elapsed: number): number | null;
@@ -35,7 +35,10 @@ type CompiledBoardAnimations = {
   readonly document: BoardDocument;
 };
 declare function compileBoardAnimations(document: BoardDocument): CompiledBoardAnimations;
-type BoardColorResolver = (color: BoardColor) => number | null;
+type BoardColorResolver = (color: BoardColor) => number | {
+  color: number;
+  alpha: number;
+} | null;
 declare function parseHexColor(color: BoardColor): number | null;
 declare function sampleBoardTrack(track: CompiledTrack, time: number, resolveColor?: BoardColorResolver): unknown;
 type BoardCameraOverride = {