@neta-art/cohub-cli 10.3.0 → 10.4.2

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";