@neta-art/cohub 10.0.0 → 11.0.0

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

@@ -1,9 +1,12 @@
 import { BoardDocument } from "../../protocol/dist/board-model.js";
+import { BoardFrame } from "../../protocol/dist/board-layout.js";
 import "../../protocol/dist/index.js";
-import { BoardSceneItem } from "../model/scene.js";
+import { BoardScene, BoardSceneItem } from "../model/scene.js";
+import { BoardEvaluation } from "../model/animation.js";
+import { BoardAnimationSampler } from "../model/sampling.js";
 import { BoardExportPlan, BoardExportPlanInput, BoardExportRegion } from "../model/export-plan.js";
 import { BoardShapeColors } from "../model/palette.js";
-import { BoardCardRendererResolver, BoardRenderPalette, BoardSketchHost } from "../render/renderers/board-renderer-registry.js";
+import { BoardCardRendererResolver, BoardRenderPalette, BoardScriptHost } from "../render/renderers/board-renderer-registry.js";
 import "../render/index.js";
 import { BoardExportScene, BoardExportSceneInput, createBoardExportScene } from "./scene.js";
 import { ICanvas, Renderer, Texture } from "pixi.js";
@@ -11,6 +14,11 @@ import { ICanvas, Renderer, Texture } from "pixi.js";
 type BoardExportBackground = "paper" | "transparent" | number;
 type BoardExportOptions = {
   region?: BoardExportRegion;
+  camera?: {
+    width: number;
+    height: number;
+  };
+  sampler?: BoardAnimationSampler;
   at?: {
     animation?: string;
     time: number;
@@ -22,7 +30,7 @@ type BoardExportOptions = {
   palette?: Partial<BoardRenderPalette>;
   colors?: BoardShapeColors;
   textures?: Map<string, Texture>;
-  sketches?: BoardSketchHost;
+  scripts?: BoardScriptHost;
   assetKey?: (item: BoardSceneItem) => string | null;
   renderers?: BoardCardRendererResolver;
   backgroundImage?: {
@@ -50,7 +58,20 @@ type BoardExportResult = {
   plan: BoardExportPlan;
   warnings: BoardExportWarning[];
 };
+declare function prepareBoardExport(input: BoardDocument, options?: BoardExportOptions): {
+  document: BoardDocument;
+  scene: BoardScene;
+  plan: BoardExportPlan;
+  sampler: {
+    frameAt(id: string, time: number): BoardFrame | undefined;
+    at(time: number): {
+      document: BoardDocument;
+      evaluation: BoardEvaluation;
+      scene: BoardScene;
+    };
+  } | undefined;
+} | null;
 declare function renderBoardExport(renderer: Renderer, input: BoardDocument, options?: BoardExportOptions): BoardExportResult | null;
 declare function describeBoardExportWarning(warning: BoardExportWarning): string;
 //#endregion
-export { BoardExportBackground, BoardExportOptions, type BoardExportPlan, type BoardExportPlanInput, type BoardExportRegion, BoardExportResult, type BoardExportScene, type BoardExportSceneInput, BoardExportWarning, createBoardExportScene, describeBoardExportWarning, renderBoardExport };
+export { BoardExportBackground, BoardExportOptions, type BoardExportPlan, type BoardExportPlanInput, type BoardExportRegion, BoardExportResult, type BoardExportScene, type BoardExportSceneInput, BoardExportWarning, createBoardExportScene, describeBoardExportWarning, prepareBoardExport, renderBoardExport };

package/dist/board/export/index.js

@@ -1,8 +1,9 @@
-import { boardDocumentAt } from "../model/animation.js";
-import { normalizeBoardDocument, planBoardExport } from "../model/export-plan.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,13 +70,14 @@ 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),
@@ -89,4 +122,4 @@ function describeBoardExportWarning(warning) {
 	}
 }
 //#endregion
-export { createBoardExportScene, describeBoardExportWarning, renderBoardExport };
+export { createBoardExportScene, describeBoardExportWarning, prepareBoardExport, renderBoardExport };

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

@@ -1,8 +1,8 @@
 import { BoardDocument } from "../../../protocol/dist/board-model.js";
 import "../../../protocol/dist/index.js";
-import { BoardSketchHost } from "../../render/renderers/board-renderer-registry.js";
+import { BoardScriptHost } from "../../render/renderers/board-renderer-registry.js";
 import { BoardExportOptions, BoardExportResult } from "../index.js";
-import { createNodeBoardSketchHost } from "./sketch.js";
+import { createNodeBoardScriptHost } from "./scripts.js";
 import { Renderer } from "pixi.js";
 //#region src/board/export/node/index.d.ts
 type NodeCanvasModule = {
@@ -24,6 +24,7 @@ type BoardNodeRendererOptions = {
 };
 type BoardNodeTexture = {
   readonly __boardTexture: unique symbol;
+  destroy: (destroySource?: boolean) => void;
 };
 type BoardNodeRenderer = {
   renderer: Renderer;
@@ -41,7 +42,7 @@ type BoardNodeExportOptions = Omit<BoardExportOptions, "textures" | "backgroundI
     position: "center" | "top" | "bottom" | "left" | "right";
     opacity: number;
   };
-  sketches?: BoardSketchHost;
+  scripts?: BoardScriptHost;
   format?: BoardNodeExportFormat;
   quality?: number;
 };
@@ -52,4 +53,4 @@ type BoardNodeExportResult = Omit<BoardExportResult, "canvas"> & {
 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, createNodeBoardSketchHost, exportBoardImageBytes };
+export { BoardNodeExportFormat, BoardNodeExportOptions, BoardNodeExportResult, BoardNodeFont, BoardNodeRenderer, BoardNodeRendererOptions, BoardNodeTexture, NodeCanvasModule, boardImageMimeType, createNodeBoardRenderer, createNodeBoardScriptHost, exportBoardImageBytes };

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

@@ -1,7 +1,7 @@
 import "../../../protocol/dist/board-constants.js";
 import { installBoardTextMeasurement } from "../../render/text-measurement.js";
 import { renderBoardExport } from "../index.js";
-import { createNodeBoardSketchHost } from "./sketch.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/export/node/index.ts
 const SYSTEM_UI_FAMILIES = [
@@ -131,10 +131,10 @@ function boardImageMimeType(format) {
 	return MIME[format];
 }
 function exportBoardImageBytes(renderer, document, options = {}) {
-	const { format = "png", quality = .92, textures, sketches, backgroundImage, ...rest } = 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(renderer, 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 { boardImageMimeType, createNodeBoardRenderer, createNodeBoardSketchHost, 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

@@ -12,13 +12,14 @@ 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;

package/dist/board/export/scene.js

@@ -1,7 +1,7 @@
 import { buildFallbackShapeColors } from "../model/palette.js";
 import { imageAssetKey } from "../model/image-key.js";
-import { clippingAncestor, isClippingFrame, syncClipGroup } from "../render/clip.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) => {
@@ -77,13 +78,26 @@ function createBoardExportScene(input) {
 	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 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 = input.scene.opacity(item.id);
+		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/model/animation.d.ts

@@ -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 = {

package/dist/board/model/animation.js

@@ -183,11 +183,21 @@ function hex(color) {
 	return `#${Math.max(0, Math.min(16777215, Math.round(color))).toString(16).padStart(6, "0")}`;
 }
 function mixColor(a, b, t, resolve) {
-	const from = resolve(a);
-	const to = resolve(b);
-	if (from === null || to === null) return t < 1 ? a : b;
-	const channel = (shift) => Math.round(lerp(from >> shift & 255, to >> shift & 255, t));
-	return hex(channel(16) << 16 | channel(8) << 8 | channel(0));
+	const left = resolve(a);
+	const right = resolve(b);
+	if (left === null || right === null) return t < 1 ? a : b;
+	const from = typeof left === "number" ? {
+		color: left,
+		alpha: 1
+	} : left;
+	const to = typeof right === "number" ? {
+		color: right,
+		alpha: 1
+	} : right;
+	const alpha = lerp(from.alpha, to.alpha, t);
+	const channel = (shift) => alpha > 0 ? Math.round(lerp((from.color >> shift & 255) * from.alpha, (to.color >> shift & 255) * to.alpha, t) / alpha) : 0;
+	const rgb = hex(channel(16) << 16 | channel(8) << 8 | channel(0));
+	return alpha >= 1 ? rgb : `${rgb}${Math.round(Math.max(0, alpha) * 255).toString(16).padStart(2, "0")}`;
 }
 function parseHexColor(color) {
 	if (typeof color !== "string") return null;
@@ -196,6 +206,23 @@ function parseHexColor(color) {
 	const digits = match[1].length === 3 ? [...match[1]].map((digit) => digit + digit).join("") : match[1];
 	return Number.parseInt(digits, 16);
 }
+function parseAnimationColor(color) {
+	if (typeof color === "string") {
+		if (color.trim().toLowerCase() === "transparent") return {
+			color: 0,
+			alpha: 0
+		};
+		const match = /^#([0-9a-f]{4}|[0-9a-f]{8})$/i.exec(color.trim());
+		if (match?.[1]) {
+			const digits = match[1].length === 4 ? [...match[1]].map((digit) => digit + digit).join("") : match[1];
+			return {
+				color: Number.parseInt(digits.slice(0, 6), 16),
+				alpha: Number.parseInt(digits.slice(6), 16) / 255
+			};
+		}
+	}
+	return parseHexColor(color);
+}
 function blend(track, index, time, resolveColor) {
 	const { times, values } = track;
 	const from = values[index];
@@ -229,7 +256,7 @@ function blend(track, index, time, resolveColor) {
 		default: return progress >= 1 ? to : from;
 	}
 }
-function sampleBoardTrack(track, time, resolveColor = parseHexColor) {
+function sampleBoardTrack(track, time, resolveColor = parseAnimationColor) {
 	const index = keyframeIndex(track.times, time);
 	if (index < 0) return track.values[0];
 	return blend(track, index, time, resolveColor);
@@ -302,7 +329,7 @@ function outranks(track, time, other, otherTime) {
 	return track.id > other.id;
 }
 function evaluateBoardAnimations(compiled, times, options = {}) {
-	const resolveColor = options.resolveColor ?? parseHexColor;
+	const resolveColor = options.resolveColor ?? parseAnimationColor;
 	const local = new Map(times instanceof Map ? times : Object.entries(times));
 	for (const id of compiled.order) {
 		const animation = compiled.animations.get(id);