@neta-art/cohub 8.23.0 → 9.0.0

package/dist/board/geometry.js

@@ -44,17 +44,9 @@ const DEFAULT_BOARD_VIEWPORT = {
 	y: 0,
 	zoom: 1
 };
-/** Smallest an item can be resized to, in world units. */
 const MIN_ITEM_SIZE = 24;
-/** Extra world-space padding applied when fitting content into view. */
 const FIT_PADDING = 64;
-/**
-* Fraction of the viewport's larger dimension used as an off-screen margin for
-* both card culling and texture preloading. Keeping them equal means a card's
-* texture is already requested before the card scrolls into view.
-*/
 const VIEWPORT_MARGIN_RATIO = .5;
-/** Viewport plus margin, snapped to a grid so small pans return the same rect. */
 function stableCullRect(view) {
 	const margin = Math.max(view.width, view.height, 1) * VIEWPORT_MARGIN_RATIO;
 	const step = 2 ** Math.floor(Math.log2(margin / 2));
@@ -73,7 +65,6 @@ function clampZoom(zoom) {
 	const value = Number.isFinite(zoom) ? zoom : DEFAULT_BOARD_VIEWPORT.zoom;
 	return Math.min(8, Math.max(MIN_BOARD_ZOOM, value));
 }
-/** Keep transient camera state finite without discarding its last valid axes. */
 function normalizeViewport(viewport, fallback = DEFAULT_BOARD_VIEWPORT) {
 	const fallbackX = Number.isFinite(fallback.x) ? fallback.x : DEFAULT_BOARD_VIEWPORT.x;
 	const fallbackY = Number.isFinite(fallback.y) ? fallback.y : DEFAULT_BOARD_VIEWPORT.y;
@@ -166,7 +157,6 @@ function rotatePointAround(point, center, angleRad) {
 		y: center.y + dx * sin + dy * cos
 	};
 }
-/** Axis-aligned bounding box of a (possibly rotated) frame. */
 function itemBounds(frame) {
 	const rotation = frame.rotation || 0;
 	if (rotation === 0) return frameRect(frame);
@@ -188,7 +178,6 @@ function itemBounds(frame) {
 function selectionBounds(frames) {
 	return unionRects(frames.map(itemBounds));
 }
-/** Exact point-in-frame test, accounting for rotation. */
 function frameContainsPoint(frame, point) {
 	const rect = frameRect(frame);
 	const rotation = frame.rotation || 0;
@@ -196,7 +185,6 @@ function frameContainsPoint(frame, point) {
 	if (rotation !== 0) local = rotatePointAround(point, rectCenter(rect), -degToRad(rotation));
 	return rectContainsPoint(rect, local);
 }
-/** World position of a resize handle on a single (possibly rotated) frame. */
 function frameHandlePosition(frame, handle) {
 	const rect = frameRect(frame);
 	const position = handlePosition(rect, handle);
@@ -204,7 +192,6 @@ function frameHandlePosition(frame, handle) {
 	if (rotation === 0) return position;
 	return rotatePointAround(position, rectCenter(rect), degToRad(rotation));
 }
-/** Corners in clockwise order, following the frame's rotation. */
 function frameCorners(frame) {
 	return [
 		"nw",
@@ -213,9 +200,7 @@ function frameCorners(frame) {
 		"sw"
 	].map((handle) => frameHandlePosition(frame, handle));
 }
-/** Screen-space radius (px) within which a pointer grabs a handle. */
 const HANDLE_HIT_RADIUS = 8;
-/** Screen-space offset (px) from the selection's lower-facing edge. */
 const ROTATION_HANDLE_OFFSET = 28;
 function frameRayIntersection(frame, pointer) {
 	const center = rectCenter(frame);
@@ -257,7 +242,6 @@ const EDGE_RESIZE_HANDLES = [
 	"s",
 	"w"
 ];
-/** Screen-space depth of the rotation zone outside each resize corner. */
 const CORNER_ROTATION_ZONE_WIDTH = 16;
 const RESIZE_HANDLES = [
 	"nw",
@@ -269,10 +253,6 @@ const RESIZE_HANDLES = [
 	"sw",
 	"w"
 ];
-/**
-* Hit-test the outward quadrant around each corner, outside its resize target.
-* This gives fine pointers Figma-style corner rotation without adding chrome.
-*/
 function frameCornerRotationHandleAt(frame, point, zoom, screenRadius = 8) {
 	const rect = frameRect(frame);
 	const center = rectCenter(rect);
@@ -291,10 +271,6 @@ function frameCornerRotationHandleAt(frame, point, zoom, screenRadius = 8) {
 	}
 	return null;
 }
-/**
-* Hit-test the continuous edge zones of a rotated frame. Corners are inset so
-* their resize handles retain priority even on small nodes.
-*/
 function frameEdgeHandleAt(frame, point, zoom, screenRadius = 8) {
 	const rect = frameRect(frame);
 	const center = rectCenter(rect);
@@ -327,7 +303,6 @@ function frameEdgeHandleAt(frame, point, zoom, screenRadius = 8) {
 	}
 	return closest;
 }
-/** Direction of a handle from the rect center: -1, 0, or 1 per axis. */
 const HANDLE_DIRECTION = {
 	nw: {
 		x: -1,
@@ -362,12 +337,10 @@ const HANDLE_DIRECTION = {
 		y: 0
 	}
 };
-/** Position of a handle on an unrotated rect. */
 function handlePosition(rect, handle) {
 	const direction = HANDLE_DIRECTION[handle];
 	return worldPoint(rect.x + rect.width / 2 + direction.x * rect.width / 2, rect.y + rect.height / 2 + direction.y * rect.height / 2);
 }
-/** Resize a frame to exact dimensions while keeping the opposite handle fixed. */
 function resizeFrameToSize(frame, handle, width, height) {
 	const direction = HANDLE_DIRECTION[handle];
 	const rect = frameRect(frame);
@@ -397,11 +370,6 @@ function resizeFrameToSize(frame, handle, width, height) {
 		rotation: frame.rotation || 0
 	};
 }
-/**
-* Resize a frame by dragging a handle to a world-space pointer position.
-* The edge/corner opposite the handle stays anchored. Works correctly for
-* rotated frames by performing the resize in the frame's local space.
-*/
 function resizeFrame(frame, handle, pointer, minSize = 24, keepAspect = false) {
 	const direction = HANDLE_DIRECTION[handle];
 	const rect = frameRect(frame);
@@ -434,10 +402,6 @@ function resizeFrame(frame, handle, pointer, minSize = 24, keepAspect = false) {
 	}
 	return resizeFrameToSize(frame, handle, width, height);
 }
-/**
-* Proportionally scale a group of frames by dragging a corner handle of their
-* combined bounds. Individual rotations are preserved.
-*/
 function scaleFrames(frames, bounds, handle, pointer, minSize = 24, scaleRange) {
 	const direction = HANDLE_DIRECTION[handle];
 	if (direction.x === 0 || direction.y === 0) return frames;
@@ -470,14 +434,9 @@ function scaleFrames(frames, bounds, handle, pointer, minSize = 24, scaleRange)
 		};
 	});
 }
-/** Angle (degrees) from a center to a world-space pointer. */
 function angleFromCenter(center, pointer) {
 	return radToDeg(Math.atan2(pointer.y - center.y, pointer.x - center.x));
 }
-/**
-* Rotate a set of frames around a pivot by a delta (degrees). Each frame's
-* center orbits the pivot and its own rotation increases by the delta.
-*/
 function rotateFrames(frames, pivot, deltaDeg) {
 	const rad = degToRad(deltaDeg);
 	return frames.map((frame) => {
@@ -491,14 +450,12 @@ function rotateFrames(frames, pivot, deltaDeg) {
 		};
 	});
 }
-/** Normalize a rotation into the [-180, 180] range for tidy persistence. */
 function normalizeRotation(degrees) {
 	let value = degrees % 360;
 	if (value > 180) value -= 360;
 	if (value < -180) value += 360;
 	return Math.abs(value) < .01 ? 0 : value;
 }
-/** Convert a surface-relative screen point into world space. */
 function pointToWorld(point, viewport) {
 	return worldPoint((point.x - viewport.x) / viewport.zoom, (point.y - viewport.y) / viewport.zoom);
 }
@@ -508,7 +465,6 @@ function worldToScreen(point, viewport) {
 function screenToWorld(clientX, clientY, rect, viewport) {
 	return pointToWorld(screenPoint(clientX - rect.left, clientY - rect.top), viewport);
 }
-/** Zoom while keeping a surface-relative screen point fixed under the cursor. */
 function zoomAround(viewport, anchor, nextZoom) {
 	const current = normalizeViewport(viewport);
 	const zoom = Number.isFinite(nextZoom) ? clampZoom(nextZoom) : current.zoom;
@@ -534,10 +490,7 @@ function cameraForState(state, surface) {
 		zoom
 	});
 }
-function cameraForRect(content, surface, options = {
-	fit: "contain",
-	padding: 32
-}) {
+function cameraForRect(content, surface, options = {}) {
 	const padding = Math.max(0, Number.isFinite(options.padding) ? options.padding : 32);
 	const availableW = Math.max(1, surface.width - padding * 2);
 	const availableH = Math.max(1, surface.height - padding * 2);
@@ -553,26 +506,14 @@ function cameraForRect(content, surface, options = {
 	}, surface);
 }
 function rectForCameraFocus(focus, getFrame) {
-	if (focus.type === "rect") return focus.rect;
-	if (focus.type === "item") {
-		const frame = getFrame(focus.itemId);
-		return frame ? itemBounds(frame) : null;
-	}
-	if (focus.type === "frame") {
-		const frame = getFrame(focus.frameId);
-		return frame ? itemBounds(frame) : null;
-	}
-	const frames = focus.itemIds.flatMap((id) => {
-		const frame = getFrame(id);
-		return frame ? [frame] : [];
-	});
-	return frames.length === focus.itemIds.length ? selectionBounds(frames) : null;
+	if (typeof focus !== "string") return focus;
+	const frame = getFrame(focus);
+	return frame ? itemBounds(frame) : null;
 }
-function cameraForFocus(params, getFrame, surface) {
-	const rect = rectForCameraFocus(params.focus, getFrame);
-	return rect ? cameraForRect(rect, surface, params) : null;
+function cameraForFocus(focus, getFrame, surface, options = {}) {
+	const rect = rectForCameraFocus(focus, getFrame);
+	return rect ? cameraForRect(rect, surface, options) : null;
 }
-/** Compute a viewport that frames the given world rect within the surface. */
 function fitToContent(content, surface, padding = 64) {
 	const availableW = Math.max(1, surface.width - padding * 2);
 	const availableH = Math.max(1, surface.height - padding * 2);
@@ -583,7 +524,6 @@ function fitToContent(content, surface, padding = 64) {
 		zoom
 	};
 }
-/** World-space rectangle currently visible in the board stage. */
 function visibleWorldRect(viewport, surfaceWidth, surfaceHeight) {
 	const width = Math.max(0, surfaceWidth);
 	const height = Math.max(0, surfaceHeight);

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

@@ -1,5 +1,8 @@
-import { BoardDocument } from "../../protocol/dist/board-document.js";
+import { BoardDocument } from "../../protocol/dist/board-model.js";
+import "../../protocol/dist/index.js";
+import { BoardSketchHost } from "../render/renderers/board-renderer-registry.js";
 import { BoardExportOptions, BoardExportResult } from "../export/index.js";
+import { createBoardHeadlessSketchHost } from "./sketch.js";
 import { Renderer } from "pixi.js";
 //#region src/board/headless/index.d.ts
 type HeadlessCanvasModule = {
@@ -8,51 +11,29 @@ type HeadlessCanvasModule = {
   GlobalFonts: {
     registerFromPath: (path: string, name?: string) => unknown;
     has: (name: string) => boolean;
+    setAlias?: (fontName: string, alias: string) => boolean;
   };
 };
 type BoardHeadlessFont = {
-  /** Absolute path to a font file (woff2, ttf and otf all work). */
   path: string;
-  /** Family name renderers should ask for. Defaults to the board text family. */
   family?: string;
 };
 type BoardHeadlessRendererOptions = {
-  /**
-   * Fonts to register before the first measurement. Board text asks for
-   * "Geist"; without a matching family the platform substitutes one, which
-   * changes glyph shapes and text metrics.
-   */
   fonts?: BoardHeadlessFont[];
-  /** Override the canvas module (tests, or a pre-imported instance). */
   canvasModule?: HeadlessCanvasModule;
 };
-/**
- * A decoded image, opaque to callers.
- *
- * Node consumers (the CLI) should not need PixiJS in their own type surface just
- * to hand textures back to the exporter, so the concrete `Texture` stays inside
- * this module.
- */
 type BoardHeadlessTexture = {
   readonly __boardTexture: unique symbol;
 };
 type BoardHeadlessRenderer = {
   renderer: Renderer;
   canvasModule: HeadlessCanvasModule;
-  /** Decode image bytes into a texture the exporter accepts. */
   decodeImage: (bytes: Uint8Array, mimeType?: string) => Promise<BoardHeadlessTexture>;
   destroy: () => void;
 };
-/**
- * Create a Canvas2D renderer backed by Skia.
- *
- * `skipExtensionImports` is essential: it stops Pixi from auto-loading its
- * browser environment bundle, which would pull in DOM-only pipes.
- */
 declare function createBoardHeadlessRenderer(options?: BoardHeadlessRendererOptions): Promise<BoardHeadlessRenderer>;
 type BoardHeadlessExportFormat = "png" | "jpeg" | "webp";
 type BoardHeadlessExportOptions = Omit<BoardExportOptions, "textures" | "backgroundImage"> & {
-  /** Textures from `decodeImage`, keyed by image key. */
   textures?: Map<string, BoardHeadlessTexture>;
   backgroundImage?: {
     texture: BoardHeadlessTexture;
@@ -60,8 +41,8 @@ type BoardHeadlessExportOptions = Omit<BoardExportOptions, "textures" | "backgro
     position: "center" | "top" | "bottom" | "left" | "right";
     opacity: number;
   };
+  sketches?: BoardSketchHost;
   format?: BoardHeadlessExportFormat;
-  /** JPEG/WebP quality, 0–1. Ignored for PNG. */
   quality?: number;
 };
 type BoardHeadlessExportResult = Omit<BoardExportResult, "canvas"> & {
@@ -69,7 +50,6 @@ type BoardHeadlessExportResult = Omit<BoardExportResult, "canvas"> & {
   format: BoardHeadlessExportFormat;
 };
 declare function boardHeadlessMimeType(format: BoardHeadlessExportFormat): string;
-/** Render a document to encoded image bytes. Returns null for an empty region. */
 declare function exportBoardImageBytes(headless: BoardHeadlessRenderer, document: BoardDocument, options?: BoardHeadlessExportOptions): BoardHeadlessExportResult | null;
 //#endregion
-export { BoardHeadlessExportFormat, BoardHeadlessExportOptions, BoardHeadlessExportResult, BoardHeadlessFont, BoardHeadlessRenderer, BoardHeadlessRendererOptions, BoardHeadlessTexture, HeadlessCanvasModule, boardHeadlessMimeType, createBoardHeadlessRenderer, exportBoardImageBytes };
+export { BoardHeadlessExportFormat, BoardHeadlessExportOptions, BoardHeadlessExportResult, BoardHeadlessFont, BoardHeadlessRenderer, BoardHeadlessRendererOptions, BoardHeadlessTexture, HeadlessCanvasModule, boardHeadlessMimeType, createBoardHeadlessRenderer, createBoardHeadlessSketchHost, exportBoardImageBytes };

package/dist/board/headless/index.js

@@ -1,15 +1,23 @@
 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 { CanvasGraphicsContextSystem, CanvasGraphicsPipe, CanvasRenderer, CanvasRendererTextSystem, CanvasTextPipe, CanvasTextSystem, DOMAdapter, GraphicsContextSystem, GraphicsPipe, ImageSource, Texture, extensions } from "pixi.js";
 //#region src/board/headless/index.ts
-/**
-* A minimal WebGL stand-in.
-*
-* `ParticleContainerPipe` builds a `GlProgram` when the renderer registers its
-* pipes, and that probes shader precision through a throwaway context — even
-* though the Canvas2D backend never draws with it. Returning a stub keeps
-* registration working; nothing here is ever used to render.
-*/
+const SYSTEM_UI_FAMILIES = [
+	"Noto Sans",
+	"DejaVu Sans",
+	"Liberation Sans",
+	"FreeSans",
+	"Helvetica Neue",
+	"Arial",
+	"Segoe UI"
+];
+function aliasSystemUi(fonts) {
+	if (!fonts.setAlias || fonts.has("system-ui")) return;
+	const family = SYSTEM_UI_FAMILIES.find((name) => fonts.has(name));
+	if (family) fonts.setAlias(family, "system-ui");
+}
 const WEBGL_PROBE_STUB = {
 	getShaderPrecisionFormat: () => ({
 		precision: 1,
@@ -29,7 +37,6 @@ async function loadCanvasModule() {
 		throw new Error("Board image export needs the optional '@napi-rs/canvas' package. Install it with: npm i @napi-rs/canvas", { cause });
 	}
 }
-/** Node has no rAF; Pixi's scheduler only needs a callback pump. */
 function installAnimationFrameShim() {
 	const globals = globalThis;
 	if (globals.requestAnimationFrame) return () => {};
@@ -54,17 +61,11 @@ function installAnimationFrameShim() {
 		globals.cancelAnimationFrame = void 0;
 	};
 }
-/**
-* Create a Canvas2D renderer backed by Skia.
-*
-* `skipExtensionImports` is essential: it stops Pixi from auto-loading its
-* browser environment bundle, which would pull in DOM-only pipes.
-*/
 async function createBoardHeadlessRenderer(options = {}) {
 	const canvasModule = options.canvasModule ?? await loadCanvasModule();
-	const { CanvasGraphicsContextSystem, CanvasGraphicsPipe, CanvasRenderer, CanvasRendererTextSystem, CanvasTextPipe, CanvasTextSystem, DOMAdapter, extensions, GraphicsContextSystem, GraphicsPipe, ImageSource, Texture } = await import("pixi.js");
 	extensions.add(CanvasGraphicsPipe, GraphicsPipe, CanvasGraphicsContextSystem, GraphicsContextSystem, CanvasRendererTextSystem, CanvasTextSystem, CanvasTextPipe);
 	for (const font of options.fonts ?? []) canvasModule.GlobalFonts.registerFromPath(font.path, font.family ?? "Geist");
+	aliasSystemUi(canvasModule.GlobalFonts);
 	function createCanvas(width = 1, height = 1) {
 		const canvas = canvasModule.createCanvas(Math.max(1, Math.ceil(width)), Math.max(1, Math.ceil(height)));
 		const nativeGetContext = canvas.getContext.bind(canvas);
@@ -129,11 +130,11 @@ const MIME = {
 function boardHeadlessMimeType(format) {
 	return MIME[format];
 }
-/** Render a document to encoded image bytes. Returns null for an empty region. */
 function exportBoardImageBytes(headless, document, options = {}) {
-	const { format = "png", quality = .92, textures, backgroundImage, ...rest } = options;
+	const { format = "png", quality = .92, textures, sketches, backgroundImage, ...rest } = options;
 	const result = renderBoardExport(headless.renderer, document, {
 		...rest,
+		...sketches ? { sketches } : {},
 		...textures ? { textures } : {},
 		...backgroundImage ? { backgroundImage: {
 			...backgroundImage,
@@ -151,4 +152,4 @@ function exportBoardImageBytes(headless, document, options = {}) {
 	};
 }
 //#endregion
-export { boardHeadlessMimeType, createBoardHeadlessRenderer, exportBoardImageBytes };
+export { boardHeadlessMimeType, createBoardHeadlessRenderer, createBoardHeadlessSketchHost, exportBoardImageBytes };

package/dist/board/headless/sketch.d.ts

@@ -0,0 +1,19 @@
+import { BoardSketchItem } from "../../protocol/dist/board-model.js";
+import "../../protocol/dist/index.js";
+import { SceneItem } from "../core/scene.js";
+import { BoardSketchHost } from "../render/renderers/board-renderer-registry.js";
+import { BoardHeadlessRenderer } from "./index.js";
+//#region src/board/headless/sketch.d.ts
+type SketchFrame = SceneItem<BoardSketchItem>;
+type PreparedSketchHost = BoardSketchHost & {
+  prepare: (items: readonly SketchFrame[], times: readonly number[], zoom: number) => Promise<void>;
+  destroy: () => void;
+};
+type BoardHeadlessSketchOptions = {
+  readModule: (src: string) => Promise<string>;
+  timeoutMs?: number;
+  readTimeoutMs?: number;
+};
+declare function createBoardHeadlessSketchHost(headless: BoardHeadlessRenderer, options: BoardHeadlessSketchOptions): PreparedSketchHost;
+//#endregion
+export { BoardHeadlessSketchOptions, createBoardHeadlessSketchHost };

package/dist/board/headless/sketch.js

@@ -0,0 +1,146 @@
+import { ImageSource, Texture } from "pixi.js";
+import { Script, createContext } from "node:vm";
+//#region src/board/headless/sketch.ts
+const MAX_EDGE = 2048;
+const DEFAULT_TIMEOUT_MS = 2e3;
+const DEFAULT_READ_TIMEOUT_MS = 15e3;
+const MAX_PREPARE_CONCURRENCY = 4;
+function transformModule(code, src) {
+	return `(function(module, exports) {\n${code.replace(/export\s+default\s+/g, "module.exports.default = ").replace(/export\s+(async\s+)?function\s+draw\b/g, (_match, asyncKeyword = "") => `module.exports.draw = ${asyncKeyword}function draw`).replace(/export\s+(const|let|var)\s+draw\s*=/g, "module.exports.draw =")}\n})(module, module.exports);\n//# sourceURL=${JSON.stringify(src)}`;
+}
+function runModule(code, src, timeoutMs) {
+	const module = { exports: {} };
+	const context = createContext({
+		module,
+		exports: module.exports,
+		console: {
+			log() {},
+			warn() {},
+			error() {}
+		},
+		fetch: void 0,
+		XMLHttpRequest: void 0,
+		WebSocket: void 0,
+		EventSource: void 0,
+		importScripts: void 0,
+		indexedDB: void 0,
+		caches: void 0,
+		process: void 0,
+		require: void 0
+	});
+	new Script(transformModule(code, src), { filename: src }).runInContext(context, { timeout: timeoutMs });
+	const value = module.exports.default && typeof module.exports.default === "object" ? {
+		...module.exports.default,
+		...module.exports
+	} : module.exports;
+	if (typeof value.draw !== "function") throw new Error(`${src} does not export draw(ctx, frame)`);
+	if (value.draw.constructor?.name === "AsyncFunction") throw new Error(`${src} must export a synchronous draw(ctx, frame) for headless export.`);
+	return {
+		module: value,
+		context
+	};
+}
+function withTimeout(promise, timeoutMs, src) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`${src} exceeded the ${timeoutMs}ms sketch timeout.`)), timeoutMs);
+		promise.then(resolve, reject).finally(() => clearTimeout(timer));
+	});
+}
+function frameKey(item, time, scale) {
+	return `${item.id}|${time}|${item.frame.width}|${item.frame.height}|${scale}|${item.props.seed ?? item.id}|${JSON.stringify(item.props.params)}`;
+}
+function frameScale(resolution, width, height) {
+	return Math.min(4, Math.max(.25, resolution), MAX_EDGE / Math.max(1, width), MAX_EDGE / Math.max(1, height));
+}
+function textureFromCanvas(canvas) {
+	return new Texture({ source: new ImageSource({
+		resource: canvas,
+		width: canvas.width,
+		height: canvas.height
+	}) });
+}
+function createBoardHeadlessSketchHost(headless, options) {
+	const textures = /* @__PURE__ */ new Map();
+	const errors = /* @__PURE__ */ new Map();
+	const lastErrors = /* @__PURE__ */ new Map();
+	const modules = /* @__PURE__ */ new Map();
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const readTimeoutMs = options.readTimeoutMs ?? DEFAULT_READ_TIMEOUT_MS;
+	const loadModule = (src) => {
+		let pending = modules.get(src);
+		if (!pending) {
+			pending = withTimeout(options.readModule(src), readTimeoutMs, src).then((code) => runModule(code, src, timeoutMs));
+			modules.set(src, pending);
+			pending.catch(() => modules.delete(src));
+		}
+		return pending;
+	};
+	const render = async (item, time, scale) => {
+		const key = frameKey(item, time, scale);
+		if (textures.has(key) || errors.has(key)) return;
+		try {
+			const runtime = await loadModule(item.props.src);
+			const width = Math.max(1, Math.round(item.frame.width * scale));
+			const height = Math.max(1, Math.round(item.frame.height * scale));
+			const canvas = headless.canvasModule.createCanvas(width, height);
+			const context = canvas.getContext("2d");
+			context.scale(scale, scale);
+			const frame = {
+				...item.props,
+				t: time,
+				width: item.frame.width,
+				height: item.frame.height,
+				seed: item.props.seed ?? item.id
+			};
+			runtime.context.__boardDraw = runtime.module.draw;
+			runtime.context.__boardDrawContext = context;
+			runtime.context.__boardFrame = frame;
+			try {
+				const drawResult = new Script("__boardDraw(__boardDrawContext, __boardFrame)", { filename: item.props.src }).runInContext(runtime.context, { timeout: timeoutMs });
+				if (drawResult && typeof drawResult.then === "function") throw new Error(`${item.props.src} must export a synchronous draw(ctx, frame) for headless export.`);
+			} finally {
+				delete runtime.context.__boardDraw;
+				delete runtime.context.__boardDrawContext;
+				delete runtime.context.__boardFrame;
+			}
+			textures.set(key, textureFromCanvas(canvas));
+			lastErrors.delete(item.id);
+		} catch (error) {
+			errors.set(key, error instanceof Error ? error.message : String(error));
+			lastErrors.set(item.id, error instanceof Error ? error.message : String(error));
+		}
+	};
+	return {
+		frame(item, time, resolution) {
+			const scale = frameScale(resolution, item.frame.width, item.frame.height);
+			return textures.get(frameKey(item, time, scale)) ?? null;
+		},
+		error: (id) => lastErrors.get(id) ?? null,
+		release: () => {},
+		async prepare(items, times, zoom) {
+			const sketches = items.filter((item) => item.type === "sketch");
+			const jobs = [];
+			for (const item of sketches) {
+				const scale = frameScale(zoom, item.frame.width, item.frame.height);
+				for (const time of times) jobs.push(() => render(item, time, scale));
+			}
+			let next = 0;
+			const worker = async () => {
+				while (next < jobs.length) {
+					const job = jobs[next++];
+					if (job) await job();
+				}
+			};
+			await Promise.all(Array.from({ length: Math.min(MAX_PREPARE_CONCURRENCY, jobs.length) }, worker));
+		},
+		destroy() {
+			for (const texture of textures.values()) texture.destroy(true);
+			textures.clear();
+			errors.clear();
+			lastErrors.clear();
+			modules.clear();
+		}
+	};
+}
+//#endregion
+export { createBoardHeadlessSketchHost };

package/dist/board/image-key.d.ts

@@ -1,16 +1,6 @@
-import { BoardItem } from "../protocol/dist/board-document.js";
+import { BoardSceneItem } from "./core/scene.js";
 //#region src/board/image-key.d.ts
-/**
- * Stable cache key for an item's image resource, or null when it has none.
- *
- * Space files and remote URLs are namespaced so they can never collide, and file
- * cards contribute their cover image — which means covers ride the exact same
- * reference counting, LRU cooling pool and viewport preloading as image nodes,
- * with no second loader to keep in step. The exporter resolves the same keys, so
- * an exported card shows the same picture the editor does.
- */
-declare function imageAssetKey(item: BoardItem): string | null;
-/** The source a key resolves from, recovered from its namespace prefix. */
+declare function imageAssetKey(item: BoardSceneItem): string | null;
 declare function boardImageKeySource(key: string): {
   kind: "file" | "url";
   value: string;

package/dist/board/image-key.js

@@ -1,29 +1,19 @@
 import { featuredTaskArtifact, taskArtifactPreviewUrl } from "./task.js";
 //#region src/board/image-key.ts
-/**
-* Stable cache key for an item's image resource, or null when it has none.
-*
-* Space files and remote URLs are namespaced so they can never collide, and file
-* cards contribute their cover image — which means covers ride the exact same
-* reference counting, LRU cooling pool and viewport preloading as image nodes,
-* with no second loader to keep in step. The exporter resolves the same keys, so
-* an exported card shows the same picture the editor does.
-*/
 function imageAssetKey(item) {
-	if (item.type === "image") return `file:${item.ref.path}`;
+	if (item.type === "image") return `file:${item.props.src}`;
 	if (item.type === "file") {
-		const snapshot = item.snapshot;
+		const snapshot = item.props.snapshot;
 		if (snapshot?.coverPath) return `file:${snapshot.coverPath}`;
 		if (snapshot?.coverUrl) return `url:${snapshot.coverUrl}`;
 		return null;
 	}
 	if (item.type === "task") {
-		const url = taskArtifactPreviewUrl(featuredTaskArtifact(item.snapshot.artifacts));
+		const url = taskArtifactPreviewUrl(featuredTaskArtifact(item.props.snapshot.artifacts));
 		return url ? `url:${url}` : null;
 	}
 	return null;
 }
-/** The source a key resolves from, recovered from its namespace prefix. */
 function boardImageKeySource(key) {
 	if (key.startsWith("file:")) return {
 		kind: "file",