@neta-art/cohub-cli 10.3.0 → 10.4.1

package/README.md

@@ -55,6 +55,36 @@ and, if needed, `COHUB_AUTH_RESOURCE` and `COHUB_AUTH_SCOPE`. Stored login sessi
 Home Space caches, and Runtime directory bindings are scoped to the API base URL.
 Sign in once for each custom server, or supply `COHUB_EXECUTION_TOKEN`.
 
+## Board export resources
+
+Board exports keep the requested resolution and source image quality. Before rendering,
+`boards export` prints the output dimensions and frame count (except with `--json`).
+Decoded image textures, including background and script output images, share a 256 MiB
+budget. Oversized images fail before native decoding rather than silently becoming
+placeholders. Use `--image-memory <MiB>` to raise the budget when the environment has
+sufficient memory; it is an image budget, not a limit on total process memory.
+`--size` controls the viewport only with `--camera`.
+
+```bash
+cohub boards export lesson.board --animation lecture --at 0:92s:40ms --camera --size 1600x900 -o lecture.mp4
+NODE_DEBUG=cohub:board-export cohub boards export lesson.board --animation lecture --at 0:92s:40ms -o lecture.mp4
+```
+
+Debug output reports render stages, RSS, heap, external buffers, reserved image bytes,
+and available/constrained process memory. Video encoding is reported separately.
+MP4 exports require even output dimensions and fail before rendering if the initial
+export dimensions are odd. Video frame dimensions must remain constant.
+
+For a repeatable 2,301-frame native export memory benchmark, run from the repository root:
+
+```bash
+node --import tsx packages/cli/scripts/bench-board-export.ts
+```
+
+Set `BOARD_EXPORT_BENCH_FRAMES`, `BOARD_EXPORT_BENCH_WIDTH`, or
+`BOARD_EXPORT_BENCH_HEIGHT` to change the workload. The benchmark discards PNGs
+as they are produced and stops if RSS exceeds 1 GiB.
+
 ## Usage
 
 Use `--json` when reading output for decisions, extracting IDs, or chaining commands.

package/dist/board-export-resources.d.ts

@@ -0,0 +1,8 @@
+import type { BoardNodeRenderer } from "@neta-art/cohub/board/export/node";
+export declare const BOARD_EXPORT_IMAGE_MEMORY_MIB = 256;
+export declare class BoardExportResourceError extends Error {
+}
+export declare function createBoardExportImageBudget(renderer: BoardNodeRenderer, maxBytes: number): {
+    decodeImage: (bytes: Uint8Array, mimeType?: string) => Promise<import("@neta-art/cohub/board/export/node").BoardNodeTexture>;
+    readonly usedBytes: number;
+};

package/dist/board-export-resources.js

@@ -0,0 +1,39 @@
+export const BOARD_EXPORT_IMAGE_MEMORY_MIB = 256;
+export class BoardExportResourceError extends Error {
+}
+export function createBoardExportImageBudget(renderer, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0)
+        throw new Error("Image memory budget must be a positive integer.");
+    let usedBytes = 0;
+    const decodeImage = async (bytes, mimeType) => {
+        const { default: sharp } = await import("sharp");
+        const { width, height } = await sharp(bytes, { limitInputPixels: false }).metadata();
+        const required = (width ?? 0) * (height ?? 0) * 4;
+        if (!Number.isSafeInteger(required) || required <= 0)
+            throw new Error("Image dimensions could not be read.");
+        if (required > maxBytes - usedBytes) {
+            throw new BoardExportResourceError(`Image ${width}x${height} needs ${Math.ceil(required / 1024 ** 2)} MiB; ` +
+                `${Math.ceil(usedBytes / 1024 ** 2)} MiB is already reserved against the ${Math.floor(maxBytes / 1024 ** 2)} MiB image budget. ` +
+                "Use smaller source images, export a smaller region, or increase --image-memory if enough memory is available.");
+        }
+        usedBytes += required;
+        try {
+            const texture = await renderer.decodeImage(bytes, mimeType);
+            const destroy = texture.destroy.bind(texture);
+            let released = false;
+            texture.destroy = (destroySource) => {
+                if (destroySource && !released) {
+                    released = true;
+                    usedBytes -= required;
+                }
+                destroy(destroySource);
+            };
+            return texture;
+        }
+        catch (error) {
+            usedBytes -= required;
+            throw error;
+        }
+    };
+    return { decodeImage, get usedBytes() { return usedBytes; } };
+}

package/dist/board-export.d.ts

@@ -38,6 +38,12 @@ export type BoardExportRunOptions = {
     };
     document?: BoardDocument;
     signal?: AbortSignal;
+    imageMemoryMiB?: number;
+    onPlan?: (plan: {
+        width: number;
+        height: number;
+        frames: number;
+    }) => void;
     onFrame?: (frame: BoardExportFrame, index: number) => Promise<void>;
     onProgress?: (completed: number, total: number) => void;
 };

package/dist/board-export.js

@@ -3,7 +3,7 @@ import { mkdtemp, rm, writeFile, copyFile, link, rename, unlink } from "node:fs/
 import { constants } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { execFile as execFileCallback } from "node:child_process";
-import { promisify } from "node:util";
+import { debuglog, promisify } from "node:util";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -15,6 +15,8 @@ import { resolveBoardId } from "./board-command-support.js";
 import { BOARD_EXPORT_FONTS } from "./board-fonts.js";
 import { createClient } from "./client.js";
 import { downloadPublicAudio, downloadPublicImage } from "./safe-remote-image.js";
+import { BOARD_EXPORT_IMAGE_MEMORY_MIB, BoardExportResourceError, createBoardExportImageBudget } from "./board-export-resources.js";
+const debugExport = debuglog("cohub:board-export");
 export function resolveBundledFonts() {
     const require = createRequire(import.meta.url);
     const bundled = fileURLToPath(new URL("./fonts/", import.meta.url));
@@ -66,10 +68,13 @@ export async function loadBoardTextures(renderer, spaceId, items, options = {})
         if (!wanted.has(key))
             failed.delete(key);
     const pending = selection.keys.filter((key) => !textures.has(key) && !failed.has(key));
-    const concurrency = Math.max(1, Math.min(options.concurrency ?? 4, 16));
+    const concurrency = Math.max(1, Math.min(options.concurrency ?? 2, 16));
     const client = createClient();
+    let resourceError;
     async function worker() {
         for (;;) {
+            if (resourceError)
+                return;
             const key = pending.shift();
             if (!key)
                 return;
@@ -85,12 +90,17 @@ export async function loadBoardTextures(renderer, spaceId, items, options = {})
                 const texture = await renderer.decodeImage(bytes, mimeType);
                 textures.set(key, texture);
             }
-            catch {
-                failed.add(key);
+            catch (error) {
+                if (error instanceof BoardExportResourceError)
+                    resourceError = error;
+                else
+                    failed.add(key);
             }
         }
     }
     await Promise.all(Array.from({ length: Math.min(concurrency, pending.length) }, worker));
+    if (resourceError)
+        throw resourceError;
     return { textures, failed: [...failed], omitted: selection.omittedKeys };
 }
 async function readSpaceFileBytes(client, spaceId, path) {
@@ -117,7 +127,14 @@ export async function runBoardVideoExport(options) {
     try {
         let count = 0;
         let dimensions = { width: 0, height: 0 };
-        const result = await runBoardExport({ ...options, document, format: "png", onFrame: async (frame, index) => {
+        const result = await runBoardExport({ ...options, document, format: "png", onPlan: (plan) => {
+                if (options.format === "mp4" && (plan.width % 2 || plan.height % 2)) {
+                    throw new Error(`MP4 needs even dimensions, but the export is ${plan.width}x${plan.height}. Use --camera --size with even dimensions, or adjust the export region.`);
+                }
+                options.onPlan?.(plan);
+            }, onFrame: async (frame, index) => {
+                if (count && (frame.width !== dimensions.width || frame.height !== dimensions.height))
+                    throw new Error("Video frame dimensions changed. Use a fixed export region or a smaller camera viewport.");
                 await writeFile(join(tempDir, `${String(index + 1).padStart(6, "0")}.png`), frame.bytes, { signal: options.signal });
                 dimensions = { width: frame.width, height: frame.height };
                 count++;
@@ -160,6 +177,7 @@ export async function runBoardVideoExport(options) {
             args.push("-c:v", "libvpx-vp9", "-crf", "32", "-b:v", "0", "-c:a", "libopus", "-f", "webm");
         const encoded = join(tempDir, `video.${options.format}`);
         args.push("-t", duration.toFixed(3), encoded);
+        debugExport("%j", { stage: "encode", width: dimensions.width, height: dimensions.height, frames: count, memory: process.memoryUsage() });
         try {
             await execFile("ffmpeg", args, { encoding: "utf8", maxBuffer: 2 * 1024 * 1024, signal: options.signal });
         }
@@ -195,7 +213,22 @@ export async function runBoardExport(options) {
         throw new Error(`Animation ${options.animation} does not exist.`);
     }
     const times = options.times?.length ? options.times : [null];
-    const renderer = await createNodeBoardRenderer({ fonts: resolveBundledFonts() });
+    const imageMemoryBytes = (options.imageMemoryMiB ?? BOARD_EXPORT_IMAGE_MEMORY_MIB) * 1024 ** 2;
+    if (!Number.isSafeInteger(imageMemoryBytes) || imageMemoryBytes <= 0)
+        throw new Error("Image memory budget must be a positive integer.");
+    const nodeRenderer = await createNodeBoardRenderer({ fonts: resolveBundledFonts() });
+    const images = createBoardExportImageBudget(nodeRenderer, imageMemoryBytes);
+    const renderer = { ...nodeRenderer, decodeImage: images.decodeImage };
+    const trace = (stage, completed, dimensions) => {
+        if (!debugExport.enabled || completed % 30 !== 0)
+            return;
+        debugExport("%j", {
+            stage, completed, total: times.length,
+            ...(dimensions ? { width: dimensions.width, height: dimensions.height } : {}),
+            imageBytes: images.usedBytes, memory: process.memoryUsage(),
+            availableMemory: process.availableMemory(), constrainedMemory: process.constrainedMemory(),
+        });
+    };
     let scriptHost = null;
     const textureCache = { textures: new Map(), failed: new Set() };
     let backgroundTexture;
@@ -210,6 +243,17 @@ export async function runBoardExport(options) {
         });
         if (!plan)
             return null;
+        const region = times.length > 1 && !options.camera ? { kind: "rect", rect: plan.world } : options.region;
+        const firstTime = times[0] ?? null;
+        const first = prepareBoardExport(document, {
+            sampler, region, camera: options.camera, scale: options.scale,
+            padding: times.length > 1 ? 0 : options.padding,
+            ...(firstTime === null ? {} : { at: { animation: options.animation, time: firstTime } }),
+        });
+        if (!first)
+            return null;
+        options.onPlan?.({ width: first.plan.width, height: first.plan.height, frames: times.length });
+        trace("plan", 0, first.plan);
         const warnings = [];
         const textures = textureCache.textures;
         let omittedKeys = new Set();
@@ -222,19 +266,21 @@ export async function runBoardExport(options) {
                 const { bytes, mimeType } = await downloadPublicImage(declaredBackground.imageUrl);
                 backgroundTexture = await renderer.decodeImage(bytes, mimeType);
             }
-            catch {
+            catch (error) {
+                if (error instanceof BoardExportResourceError)
+                    throw error;
                 warnings.push("The board background image could not be loaded; the fallback color was exported.");
             }
         }
         const videoCount = plan.items.filter((item) => item.type === "video").length;
         if (hasBoardScripts(document))
             scriptHost = createNodeBoardScriptHost(renderer, {
+                concurrency: 2,
                 readModule: async (src) => {
                     const { bytes } = await readSpaceFileBytes(createClient(), options.spaceId, src);
                     return new TextDecoder().decode(bytes);
                 },
             });
-        const region = times.length > 1 && !options.camera ? { kind: "rect", rect: plan.world } : options.region;
         const host = scriptHost;
         if (videoCount > 0) {
             warnings.push(`${videoCount} video preview${videoCount === 1 ? " was" : "s were"} drawn as placeholders; video decoding is unavailable in Node.`);
@@ -259,6 +305,7 @@ export async function runBoardExport(options) {
             if (!initial)
                 continue;
             let prepared = initial;
+            trace("prepare", completed, initial.plan);
             if (host) {
                 await host.prepare(initial.scene.items, [time ?? 0], initial.plan.scale);
                 for (const item of initial.scene.items) {
@@ -271,6 +318,7 @@ export async function runBoardExport(options) {
                     continue;
                 prepared = scripted;
             }
+            trace("images", completed, prepared.plan);
             if (options.withImages) {
                 const loaded = await loadBoardTextures(renderer, options.spaceId, prepared.plan.items.filter((item) => prepared.scene.opacity(item.id) > 0), { cache: textureCache });
                 omittedKeys = new Set(loaded.omitted);
@@ -284,6 +332,7 @@ export async function runBoardExport(options) {
                         reported.add(warning);
                     }
             }
+            trace("render", completed, prepared.plan);
             const result = exportBoardImageBytes(renderer, document, {
                 ...frameOptions,
                 colorScheme: options.colorScheme,
@@ -320,6 +369,7 @@ export async function runBoardExport(options) {
                 frames.push(frame);
             completed++;
             options.onProgress?.(completed, times.length);
+            trace("rendered", completed, result.plan);
         }
         return completed ? { frames, warnings } : null;
     }

package/dist/board-kernel.d.ts

@@ -1,4 +1,4 @@
 export { BOARD_SCRIPT_DRAWING_EXAMPLE, hasBoardScripts, boardDocumentAt, createBoardAnimationSampler, boardSequence, boardSequencePatch, boardPathTrack, boardImageKeySource, buildBoardScene, imageAssetKey, parseBoardDocument, planBoardExport, selectBoardExportAssets, } from "@neta-art/cohub/board";
 export { prepareBoardExport } from "@neta-art/cohub/board/export";
-export { createBoardRenderSampler, inspectBoardScene, measureBoardText } from "@neta-art/cohub/board/render";
+export { createBoardRenderSampler, inspectBoardScene, inspectBoardItems, measureBoardText } from "@neta-art/cohub/board/render";
 export { createNodeBoardRenderer, createNodeBoardScriptHost, exportBoardImageBytes } from "@neta-art/cohub/board/export/node";

package/dist/board-kernel.js

@@ -1,4 +1,4 @@
-import { $ as groupD8, A as bgr2rgb, B as Bounds, C as Sprite, D as TexturePool, E as RenderGroup, G as TextureStyle, H as Texture, I as BigPool, J as deprecation, K as definedProps, L as GlobalResourceRegistry, M as multiplyHexColors, N as getGlobalBounds, O as InstructionSet, P as FilterEffect, Q as Rectangle, R as warn, S as DOMAdapter, T as Container, U as TextureMatrix, V as updateQuadBounds, W as TextureSource, X as v8_3_4, Y as v8_0_0, Z as uid$1, _ as Cache, a as Geometry, at as extensions, b as ImageSource, c as Filter, d as RendererType, et as Matrix, f as BindGroup, g as getTestContext, h as GlProgram, i as canUseNewCanvasBlendModes, it as ExtensionType, j as multiplyColors, k as getLocalBounds, l as State, m as GpuProgram, n as CanvasPool, nt as eventemitter3_default, o as Buffer$1, p as UniformGroup, q as nextPow2, r as canvasUtils, rt as ObservablePoint, s as BufferUsage, t as getPo2TextureFromSource, tt as Point, u as Shader, v as Ticker, w as ViewContainer, x as CanvasSource, z as Color } from "./board-kernel/getPo2TextureFromSource.js";
+import { $ as groupD8, A as bgr2rgb, B as Bounds, C as Sprite, D as TexturePool, E as RenderGroup, G as TextureStyle, H as Texture, I as BigPool, J as deprecation, K as definedProps, L as GlobalResourceRegistry, M as multiplyHexColors, N as getGlobalBounds, O as InstructionSet, P as FilterEffect, Q as Rectangle, R as warn, S as DOMAdapter, T as Container, U as TextureMatrix, V as updateQuadBounds, W as TextureSource, X as v8_3_4, Y as v8_0_0, Z as uid$1, _ as Cache, a as Geometry, at as extensions, b as ImageSource, c as Filter, d as RendererType, et as Matrix, f as BindGroup, g as getTestContext, h as GlProgram, i as canUseNewCanvasBlendModes, it as ExtensionType, j as multiplyColors, k as getLocalBounds, l as State, m as GpuProgram, n as CanvasPool, nt as eventemitter3_default, o as Buffer, p as UniformGroup, q as nextPow2, r as canvasUtils, rt as ObservablePoint, s as BufferUsage, t as getPo2TextureFromSource, tt as Point, u as Shader, v as Ticker, w as ViewContainer, x as CanvasSource, z as Color } from "./board-kernel/getPo2TextureFromSource.js";
 import { Worker } from "node:worker_threads";
 import { fileURLToPath } from "node:url";
 //#region ../../node_modules/.pnpm/zod@4.6.5/node_modules/zod/v4/core/util.js
@@ -12305,13 +12305,13 @@ const placeHolderBufferData = /* @__PURE__ */ new Float32Array(1);
 const placeHolderIndexData = /* @__PURE__ */ new Uint32Array(1);
 var BatchGeometry = class extends Geometry {
 	constructor() {
-		const attributeBuffer = new Buffer$1({
+		const attributeBuffer = new Buffer({
 			data: placeHolderBufferData,
 			label: "attribute-batch-buffer",
 			usage: BufferUsage.VERTEX | BufferUsage.COPY_DST,
 			shrinkToFit: false
 		});
-		const indexBuffer = new Buffer$1({
+		const indexBuffer = new Buffer({
 			data: placeHolderIndexData,
 			label: "index-batch-buffer",
 			usage: BufferUsage.INDEX | BufferUsage.COPY_DST,
@@ -18288,19 +18288,19 @@ const _MeshGeometry = class _MeshGeometry extends Geometry {
 			3
 		]);
 		const shrinkToFit = options.shrinkBuffersToFit;
-		const positionBuffer = new Buffer$1({
+		const positionBuffer = new Buffer({
 			data: positions,
 			label: "attribute-mesh-positions",
 			shrinkToFit,
 			usage: BufferUsage.VERTEX | BufferUsage.COPY_DST
 		});
-		const uvBuffer = new Buffer$1({
+		const uvBuffer = new Buffer({
 			data: uvs,
 			label: "attribute-mesh-uvs",
 			shrinkToFit,
 			usage: BufferUsage.VERTEX | BufferUsage.COPY_DST
 		});
-		const indexBuffer = new Buffer$1({
+		const indexBuffer = new Buffer({
 			data: indices,
 			label: "index-mesh-buffer",
 			shrinkToFit,
@@ -27161,12 +27161,24 @@ function measureBoardText(props) {
 		missingCharacters: characters
 	};
 }
-function inspectBoardScene(scene, limit = 100) {
+function inspectBoardItems(scene, ids) {
+	return {
+		diagnostics: inspectBoardScene(scene, 100, ids),
+		items: scene.items.filter((item) => !ids || ids.has(item.id)).map((item) => ({
+			id: item.id,
+			bounds: item.frame,
+			worldBounds: itemBounds(item.frame),
+			opacity: scene.opacity(item.id),
+			...item.type === "text" ? { text: measureBoardText(item.props) } : {}
+		}))
+	};
+}
+function inspectBoardScene(scene, limit = 100, ids) {
 	ensureBoardTextMeasurement();
 	const diagnostics = [];
 	const texts = scene.items.filter((item) => item.type === "text" && scene.opacity(item.id) > .01);
 	const push = (entry) => {
-		if (diagnostics.length < limit) diagnostics.push(entry);
+		if (diagnostics.length < limit && (!ids || ids.has(entry.item) || Boolean(entry.related && ids.has(entry.related)))) diagnostics.push(entry);
 	};
 	for (const item of scene.items) {
 		if (diagnostics.length >= limit) break;
@@ -27178,7 +27190,7 @@ function inspectBoardScene(scene, limit = 100) {
 	let glyphBudget = 256;
 	for (const item of texts) {
 		if (diagnostics.length >= limit || item.type !== "text") break;
-		if (glyphBudget-- > 0) {
+		if ((!ids || ids.has(item.id)) && glyphBudget-- > 0) {
 			const measured = measureBoardText(item.props);
 			if (measured.missingCharacters) push({
 				code: "glyph-unavailable",
@@ -27217,6 +27229,7 @@ function inspectBoardScene(scene, limit = 100) {
 			const b = sorted[j];
 			if (!b) continue;
 			if (b.rect.x >= a.rect.x + a.rect.width) break;
+			if (ids && !ids.has(a.item.id) && !ids.has(b.item.id)) continue;
 			if (++comparisons > 1e4) return diagnostics;
 			if (a.item.parent === b.item.parent && rectsIntersect(a.rect, b.rect)) push({
 				code: "text-overlap",
@@ -31338,13 +31351,24 @@ function renderBoardExport(renderer, input, options = {}) {
 		backgroundImage: options.backgroundImage
 	});
 	try {
-		const canvas = renderer.extract.canvas({
+		const texture = renderer.textureGenerator.generateTexture({
 			target: exportScene.root,
 			frame: new Rectangle(0, 0, plan.width, plan.height),
 			resolution: 1,
 			antialias: true,
 			clearColor: options.background === "transparent" ? void 0 : palette.bg
 		});
+		let canvas;
+		const surface = renderer.type === RendererType.CANVAS ? texture.source.resource : void 0;
+		try {
+			canvas = renderer.texture.generateCanvas(texture);
+		} finally {
+			texture.destroy(true);
+			if (surface) {
+				surface.width = 1;
+				surface.height = 1;
+			}
+		}
 		const warnings = [];
 		if (plan.clamped) warnings.push({
 			kind: "scale-clamped",
@@ -31369,11 +31393,55 @@ function renderBoardExport(renderer, input, options = {}) {
 	}
 }
 //#endregion
+//#region ../sdk/src/board/export/node/fonts.ts
+function initializeBoardFonts(registry, fonts) {
+	for (const font of fonts) registry.registerFromPath(font.path, font.family);
+	if (!registry.setAlias) return;
+	for (const [alias, candidates] of Object.entries({
+		"system-ui": [
+			"Noto Sans",
+			"DejaVu Sans",
+			"Liberation Sans",
+			"FreeSans",
+			"Helvetica Neue",
+			"Arial",
+			"Segoe UI"
+		],
+		"sans-serif": [
+			"Geist",
+			"Noto Sans",
+			"DejaVu Sans",
+			"Liberation Sans",
+			"FreeSans",
+			"Arial"
+		],
+		serif: [
+			"Noto Serif",
+			"DejaVu Serif",
+			"Liberation Serif",
+			"FreeSerif",
+			"Times New Roman"
+		],
+		monospace: [
+			"Geist Mono",
+			"DejaVu Sans Mono",
+			"Liberation Mono",
+			"FreeMono",
+			"Courier New"
+		]
+	})) {
+		if (registry.has(alias)) continue;
+		const family = candidates.find((name) => registry.has(name));
+		if (family) registry.setAlias(family, alias);
+	}
+}
+//#endregion
 //#region ../sdk/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 {createCanvas, GlobalFonts} = require(workerData.canvasModule);
+(${initializeBoardFonts.toString()})(GlobalFonts, workerData.fonts);
 const instances = new Map();
 const graphs = new Map();
 const update = new Script('__runtime.update(JSON.parse(__inputJson)); __runtime.step(__time)');
@@ -31382,7 +31450,10 @@ 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 {}}
+ if(entry) {
+  try {dispose.runInContext(entry.context,{timeout:workerData.timeout});} catch {}
+  if(entry.canvas) {entry.canvas.width=1;entry.canvas.height=1;}
+ }
 }
 async function create(data) {
  const context = createContext({console:{log(){},warn(){},error(){}},structuredClone},{codeGeneration:{strings:false,wasm:false}});
@@ -31432,22 +31503,29 @@ parentPort.on('message',async data=>{
    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;
+   if(canvas.width!==width || canvas.height!==height) {canvas.width=width;canvas.height=height;}
+   const drawing=canvas.getContext('2d');drawing.reset();drawing.scale(data.scale,data.scale);
+   context.__drawing=drawing;
+   try {
+    draw.runInContext(context,{timeout:workerData.timeout});
+    png=canvas.toBuffer('image/png');
+   } finally {
+    delete context.__drawing;canvas.width=1;canvas.height=1;
+   }
   }
   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)}); }
+ } catch(error) { release(data.input?.id);parentPort.postMessage({error:String(error.stack||error)}); }
 });
 `;
 function createNodeBoardScriptHost(renderer, options) {
+	const concurrency = options.concurrency ?? 4;
+	if (!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > 4) throw new Error("Script concurrency must be an integer between 1 and 4.");
 	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 }, () => ({
+	const lanes = Array.from({ length: concurrency }, () => ({
 		worker: null,
 		tail: Promise.resolve(),
 		graphs: /* @__PURE__ */ new Set()
@@ -31488,6 +31566,7 @@ function createNodeBoardScriptHost(renderer, options) {
 				workerData: {
 					runtime: createScriptRuntime.toString(),
 					timeout,
+					fonts: renderer.fonts ?? [],
 					canvasModule: fileURLToPath(import.meta.resolve("@napi-rs/canvas"))
 				}
 			});
@@ -31621,20 +31700,6 @@ function createNodeBoardScriptHost(renderer, options) {
 }
 //#endregion
 //#region ../sdk/src/board/export/node/index.ts
-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,
@@ -31681,8 +31746,11 @@ function installAnimationFrameShim() {
 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");
-	aliasSystemUi(canvasModule.GlobalFonts);
+	const fonts = (options.fonts ?? []).map((font) => ({
+		...font,
+		family: font.family ?? "Geist"
+	}));
+	initializeBoardFonts(canvasModule.GlobalFonts, fonts);
 	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);
@@ -31719,14 +31787,16 @@ async function createNodeBoardRenderer(options = {}) {
 	return {
 		renderer,
 		canvasModule,
-		decodeImage: async (bytes, mimeType = "image/png") => {
+		fonts,
+		decodeImage: async (bytes) => {
 			const image = new canvasModule.Image();
-			const base64 = Buffer.from(bytes).toString("base64");
 			await new Promise((resolve, reject) => {
 				image.onload = () => resolve();
 				image.onerror = (error) => reject(error);
-				image.src = `data:${mimeType};base64,${base64}`;
+				image.src = bytes;
 			});
+			image.onload = void 0;
+			image.onerror = void 0;
 			return new Texture({ source: new ImageSource({
 				resource: image,
 				width: image.width,
@@ -31760,7 +31830,7 @@ function exportBoardImageBytes(renderer, document, options = {}) {
 	try {
 		const bytes = format === "png" ? canvas.toBuffer(MIME.png) : canvas.toBuffer(MIME[format], Math.round(quality * 100));
 		return {
-			bytes: new Uint8Array(bytes),
+			bytes: new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength),
 			plan: result.plan,
 			warnings: result.warnings,
 			format
@@ -31771,4 +31841,4 @@ function exportBoardImageBytes(renderer, document, options = {}) {
 	}
 }
 //#endregion
-export { BOARD_SCRIPT_DRAWING_EXAMPLE, boardDocumentAt, boardImageKeySource, boardPathTrack, boardSequence, boardSequencePatch, buildBoardScene, createBoardAnimationSampler, createBoardRenderSampler, createNodeBoardRenderer, createNodeBoardScriptHost, exportBoardImageBytes, hasBoardScripts, imageAssetKey, inspectBoardScene, measureBoardText, parseBoardDocument, planBoardExport, prepareBoardExport, selectBoardExportAssets };
+export { BOARD_SCRIPT_DRAWING_EXAMPLE, boardDocumentAt, boardImageKeySource, boardPathTrack, boardSequence, boardSequencePatch, buildBoardScene, createBoardAnimationSampler, createBoardRenderSampler, createNodeBoardRenderer, createNodeBoardScriptHost, exportBoardImageBytes, hasBoardScripts, imageAssetKey, inspectBoardItems, inspectBoardScene, measureBoardText, parseBoardDocument, planBoardExport, prepareBoardExport, selectBoardExportAssets };

package/dist/commands/boards/authoring.js

@@ -1,6 +1,6 @@
 import { readBoardJsonObject } from "../../board-command-support.js";
 import { loadBoardDocument, resolveBundledFonts } from "../../board-export.js";
-import { boardPathTrack, boardSequencePatch, buildBoardScene, createBoardAnimationSampler, createNodeBoardRenderer, inspectBoardScene, measureBoardText, } from "../../board-kernel.js";
+import { boardPathTrack, boardSequencePatch, buildBoardScene, createBoardAnimationSampler, createNodeBoardRenderer, inspectBoardItems, } from "../../board-kernel.js";
 import { parseBoardTimes } from "../../board-time.js";
 import { handleHttp, json as outJson } from "../../output.js";
 import { resolveSpace } from "../../space.js";
@@ -9,9 +9,14 @@ export function registerBoardAuthoringCommands(boards) {
         .command("inspect <board>")
         .description("Measure items and report visible layout hints without changing the Board")
         .option("--animation <id>", "Animation to sample")
-        .option("--at <times>", "Time, comma-separated times, or start:end:step", "0")
+        .option("--at <times>", "Time, comma-separated times, or start:end:step (up to 100 samples)", "0")
         .option("--items <ids>", "Limit measurements to comma-separated item ids")
         .option("--json", "Output as JSON")
+        .addHelpText("after", `
+Without --animation, inspects the static document, not playback.
+Bounds use world units with x/y at the top left; worldBounds includes rotation.
+Checks native layout only, not camera cropping or content drawn inside scripts.
+Example: cohub boards inspect lesson.board --animation lecture --at 0:20s:1s --json`)
         .action(async (target, options) => {
         try {
             const { document } = await loadBoardDocument(await resolveSpace(boards), target);
@@ -21,20 +26,13 @@ export function registerBoardAuthoringCommands(boards) {
             try {
                 const ids = options.items ? new Set(options.items.split(",")) : null;
                 outJson({
-                    samples: times.map((time) => {
-                        const scene = sampler?.at(time).scene ?? buildBoardScene(document);
-                        return {
-                            time,
-                            diagnostics: inspectBoardScene(scene),
-                            items: scene.items
-                                .filter((item) => !ids || ids.has(item.id))
-                                .map((item) => ({
-                                id: item.id,
-                                bounds: item.frame,
-                                ...(item.type === "text" ? { text: measureBoardText(item.props) } : {}),
-                            })),
-                        };
-                    }),
+                    mode: sampler ? "animation" : "static",
+                    animation: options.animation ?? null,
+                    coverage: "Native layout in world coordinates; excludes camera cropping and script-drawn content.",
+                    samples: times.map((time) => ({
+                        time,
+                        ...inspectBoardItems(sampler?.at(time).scene ?? buildBoardScene(document), ids ?? undefined),
+                    })),
                 });
             }
             finally {

package/dist/commands/boards.d.ts

@@ -1,6 +1,7 @@
 import type { Command } from "commander";
 import { parseBoardJsonObject } from "../board-command-support.js";
 export declare const parseJsonObject: typeof parseBoardJsonObject;
+export declare function boardSchemaField(schema: Record<string, unknown> | undefined, path: string): unknown;
 export declare function parseRect(value: string, name?: string): {
     x: number;
     y: number;