@neta-art/cohub-cli 9.1.2 → 10.1.0

package/README.md

@@ -33,6 +33,28 @@ ENV=dev cohub auth login
 ENV=dev cohub spaces ls
 ```
 
+Use a custom API endpoint for self-hosted deployments or proxies:
+
+```bash
+cohub --base-url https://api.example.com spaces ls
+COHUB_BASE_URL=https://api.example.com cohub spaces ls
+```
+
+`--base-url` takes precedence over `COHUB_BASE_URL`. Without either, the CLI uses
+the selected environment's default API address. Configure other endpoints separately:
+
+| Variable | Endpoint |
+| --- | --- |
+| `COHUB_BASE_URL` | API base URL |
+| `COHUB_WS_URL` | Realtime gateway URL (`http(s)` or `ws(s)`) |
+| `COHUB_WEB_URL` | Web base URL used in links |
+
+Changing the API base URL does not change the gateway or authentication provider.
+For self-hosted authentication, set `COHUB_AUTH_ISSUER`, `COHUB_AUTH_CLIENT_ID`,
+and, if needed, `COHUB_AUTH_RESOURCE` and `COHUB_AUTH_SCOPE`. Stored login sessions,
+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`.
+
 ## Usage
 
 Use `--json` when reading output for decisions, extracting IDs, or chaining commands.

package/dist/auth.d.ts

@@ -12,6 +12,7 @@ type DeviceCode = {
 type AuthSession = {
     schemaVersion: 1;
     env: CohubEnvironment;
+    baseUrl?: string;
     issuer: string;
     clientId: string;
     resource: string;
@@ -28,7 +29,7 @@ export declare class AuthRequiredError extends Error {
     constructor(message?: string);
 }
 export declare const readAuthSession: () => AuthSession | null;
-export declare const clearAuthSession: () => void;
+export declare const clearAuthSession: (env?: CohubEnvironment, baseUrl?: string) => void;
 export declare const authSource: () => AuthSource;
 export declare function resolveAccessToken(options?: {
     forceRefresh?: boolean;

package/dist/auth.js

@@ -1,6 +1,6 @@
-import { resolveCohubEnvironment } from "@neta-art/cohub";
+import { COHUB_ENVIRONMENTS, normalizeBaseUrl, resolveApiBaseUrl, resolveCohubEnvironment } from "@neta-art/cohub";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { withRuntimeSpaceBindingsLock } from "./runtime/space-binding.js";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -28,9 +28,17 @@ const authConfig = (env = currentEnv()) => {
         scope: process.env[`${prefix}_AUTH_SCOPE`] ?? process.env.COHUB_AUTH_SCOPE ?? DEFAULT_SCOPE,
     };
 };
-const sessionPath = (env = currentEnv()) => join(CONFIG_DIR, env === "dev" ? "auth.dev.json" : "auth.json");
-const deviceCodePath = (env = currentEnv()) => join(CONFIG_DIR, env === "dev" ? "device-code.dev.json" : "device-code.json");
-const legacyTokenPath = (env = currentEnv()) => join(CONFIG_DIR, env === "dev" ? "token.dev" : "token");
+const endpointSuffix = (env, baseUrl = resolveApiBaseUrl({ env })) => {
+    const url = normalizeBaseUrl(baseUrl);
+    const endpoint = url === COHUB_ENVIRONMENTS[env].apiBaseUrl
+        ? ""
+        : `.${createHash("sha256").update(url).digest("hex")}`;
+    return `${env === "dev" ? ".dev" : ""}${endpoint}`;
+};
+const sessionPath = (env = currentEnv(), baseUrl) => join(CONFIG_DIR, `auth${endpointSuffix(env, baseUrl)}.json`);
+const deviceCodePath = (env = currentEnv(), baseUrl) => join(CONFIG_DIR, `device-code${endpointSuffix(env, baseUrl)}.json`);
+const legacyTokenPath = (env = currentEnv(), baseUrl) => join(CONFIG_DIR, `token${endpointSuffix(env, baseUrl)}`);
+const sessionBaseUrl = (session) => session.baseUrl ?? COHUB_ENVIRONMENTS[session.env].apiBaseUrl;
 const writePrivateJson = (path, value) => {
     mkdirSync(CONFIG_DIR, { recursive: true });
     const temporary = `${path}.${randomUUID()}.tmp`;
@@ -106,6 +114,7 @@ const toSession = (token, config, env, previous) => {
     return {
         schemaVersion: 1,
         env,
+        baseUrl: previous ? sessionBaseUrl(previous) : resolveApiBaseUrl({ env }),
         issuer: config.issuer,
         clientId: config.clientId,
         resource: config.resource,
@@ -120,13 +129,10 @@ const toSession = (token, config, env, previous) => {
     };
 };
 export const readAuthSession = () => readJson(sessionPath());
-const clearDeviceCode = () => {
-    removeIfExists(deviceCodePath());
-};
-export const clearAuthSession = () => {
-    removeIfExists(sessionPath());
-    clearDeviceCode();
-    removeIfExists(legacyTokenPath());
+export const clearAuthSession = (env = currentEnv(), baseUrl = resolveApiBaseUrl({ env })) => {
+    removeIfExists(sessionPath(env, baseUrl));
+    removeIfExists(deviceCodePath(env, baseUrl));
+    removeIfExists(legacyTokenPath(env, baseUrl));
 };
 export const authSource = () => {
     if (process.env.COHUB_EXECUTION_TOKEN?.trim())
@@ -152,14 +158,15 @@ export async function requireAccessToken() {
         throw new AuthRequiredError();
     return token;
 }
-let refreshInFlight = null;
+const refreshesInFlight = new Map();
 export function refreshAccessToken(session = readAuthSession()) {
     if (!session?.refreshToken)
         return Promise.reject(new AuthRequiredError());
-    if (refreshInFlight)
-        return refreshInFlight;
-    const path = sessionPath(session.env);
-    refreshInFlight = withRuntimeSpaceBindingsLock(async () => {
+    const path = sessionPath(session.env, sessionBaseUrl(session));
+    const inFlight = refreshesInFlight.get(path);
+    if (inFlight)
+        return inFlight;
+    const refresh = withRuntimeSpaceBindingsLock(async () => {
         const current = readJson(path);
         if (!current)
             throw new AuthRequiredError();
@@ -167,11 +174,13 @@ export function refreshAccessToken(session = readAuthSession()) {
         if (current.refreshToken !== session.refreshToken || current.updatedAt !== session.updatedAt)
             return current.accessToken;
         return performRefresh(current);
-    }, { path, lockPath: `${path}.refresh.lock` }).finally(() => { refreshInFlight = null; });
-    return refreshInFlight;
+    }, { path, lockPath: `${path}.refresh.lock` }).finally(() => { refreshesInFlight.delete(path); });
+    refreshesInFlight.set(path, refresh);
+    return refresh;
 }
 async function performRefresh(session) {
     const config = authConfig(session.env);
+    const path = sessionPath(session.env, sessionBaseUrl(session));
     const { response, data } = await formPost(tokenEndpoint(session.issuer), new URLSearchParams({
         client_id: session.clientId,
         grant_type: "refresh_token",
@@ -181,24 +190,25 @@ async function performRefresh(session) {
     }));
     if (!response.ok) {
         if (isUnrecoverableRefreshError(data)) {
-            if (readJson(sessionPath(session.env))?.refreshToken === session.refreshToken)
-                clearAuthSession();
+            if (readJson(path)?.refreshToken === session.refreshToken)
+                clearAuthSession(session.env, sessionBaseUrl(session));
             return null;
         }
         throw new Error(formatAuthError(data, response.status));
     }
     const next = toSession(data, config, session.env, session);
     // Never overwrite a login/logout that completed while the request was in flight.
-    const current = readJson(sessionPath(session.env));
+    const current = readJson(path);
     if (!current)
         throw new AuthRequiredError();
     if (current.refreshToken !== session.refreshToken)
         return current.accessToken;
-    writePrivateJson(sessionPath(session.env), next);
+    writePrivateJson(path, next);
     return next.accessToken;
 }
 export async function requestDeviceCode() {
     const env = currentEnv();
+    const baseUrl = resolveApiBaseUrl({ env });
     const config = authConfig(env);
     const { response, data } = await formPost(deviceEndpoint(config.issuer), new URLSearchParams({
         client_id: config.clientId,
@@ -224,13 +234,14 @@ export async function requestDeviceCode() {
         interval,
         createdAt: now,
     };
-    writePrivateJson(deviceCodePath(env), deviceCode);
+    writePrivateJson(deviceCodePath(env, baseUrl), deviceCode);
     return deviceCode;
 }
 export async function verifyDeviceCode() {
     const env = currentEnv();
+    const baseUrl = resolveApiBaseUrl({ env });
     const config = authConfig(env);
-    const deviceCode = readJson(deviceCodePath(env));
+    const deviceCode = readJson(deviceCodePath(env, baseUrl));
     if (!deviceCode)
         throw new Error("Device code not found. Run `cohub auth login --request-code` first.");
     if (deviceCode.expiresAt <= Date.now())
@@ -243,9 +254,9 @@ export async function verifyDeviceCode() {
     }));
     if (!response.ok)
         throw new Error(formatAuthError(data, response.status));
-    const session = toSession(data, config, env);
-    writePrivateJson(sessionPath(env), session);
-    removeIfExists(deviceCodePath(env));
+    const session = { ...toSession(data, config, env), baseUrl };
+    writePrivateJson(sessionPath(env, sessionBaseUrl(session)), session);
+    removeIfExists(deviceCodePath(env, baseUrl));
     return session;
 }
 export async function loginWithDeviceFlow(onCode, onPoll) {

package/dist/board-export.d.ts

@@ -7,8 +7,13 @@ export type BoardExportSource = {
     title: string | null;
 };
 export declare function loadBoardDocument(spaceId: string, target: string): Promise<BoardExportSource>;
+export type BoardExportTextureCache = {
+    textures: Map<string, BoardNodeTexture>;
+    failed: Set<string>;
+};
 export declare function loadBoardTextures(renderer: BoardNodeRenderer, spaceId: string, items: readonly BoardSceneItem[], options?: {
     concurrency?: number;
+    cache?: BoardExportTextureCache;
 }): Promise<{
     textures: Map<string, BoardNodeTexture>;
     failed: string[];
@@ -27,6 +32,14 @@ export type BoardExportRunOptions = {
     format: BoardNodeExportFormat;
     quality?: number;
     withImages: boolean;
+    camera?: {
+        width: number;
+        height: number;
+    };
+    document?: BoardDocument;
+    signal?: AbortSignal;
+    onFrame?: (frame: BoardExportFrame, index: number) => Promise<void>;
+    onProgress?: (completed: number, total: number) => void;
 };
 export type BoardExportFrame = {
     time: number | null;
@@ -46,6 +59,7 @@ export type BoardVideoExportOptions = Omit<BoardExportRunOptions, "format"> & {
     format: BoardVideoExportFormat;
     fps: number;
     output: string;
+    force?: boolean;
 };
 export declare function runBoardVideoExport(options: BoardVideoExportOptions): Promise<{
     width: number;

package/dist/board-export.js

@@ -1,5 +1,7 @@
 import { existsSync } from "node:fs";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, rm, writeFile, copyFile, link, rename, unlink } from "node:fs/promises";
+import { constants } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { execFile as execFileCallback } from "node:child_process";
 import { promisify } from "node:util";
 import { createRequire } from "node:module";
@@ -7,11 +9,12 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
 const execFile = promisify(execFileCallback);
-import { boardDocumentAt, boardImageKeySource, buildBoardScene, createNodeBoardRenderer, createNodeBoardSketchHost, exportBoardImageBytes, imageAssetKey, parseBoardDocument, planBoardExport, selectBoardExportAssets, } from "./board-kernel.js";
+import { parseBoardMediaSource } from "@neta-art/cohub/board";
+import { hasBoardScripts, boardDocumentAt, createBoardRenderSampler, boardImageKeySource, buildBoardScene, createNodeBoardRenderer, createNodeBoardScriptHost, exportBoardImageBytes, imageAssetKey, parseBoardDocument, planBoardExport, prepareBoardExport, selectBoardExportAssets, } from "./board-kernel.js";
 import { resolveBoardId } from "./board-command-support.js";
 import { BOARD_EXPORT_FONTS } from "./board-fonts.js";
 import { createClient } from "./client.js";
-import { downloadPublicImage } from "./safe-remote-image.js";
+import { downloadPublicAudio, downloadPublicImage } from "./safe-remote-image.js";
 export function resolveBundledFonts() {
     const require = createRequire(import.meta.url);
     const bundled = fileURLToPath(new URL("./fonts/", import.meta.url));
@@ -35,21 +38,34 @@ export function resolveBundledFonts() {
 export async function loadBoardDocument(spaceId, target) {
     const board = createClient().space(spaceId).board(await resolveBoardId(spaceId, target));
     let result = await board.get();
+    const snapshot = result;
     const items = { ...result.items };
     while (result.next) {
         result = await board.get({ only: ["items"], cursor: result.next });
+        if (result.version !== snapshot.version)
+            throw new Error("Board changed while reading. Retry the export.");
         Object.assign(items, result.items);
     }
-    const parsed = parseBoardDocument({ board: result.board, items, animations: result.animations ?? {} });
+    const parsed = parseBoardDocument({ board: snapshot.board, items, animations: snapshot.animations ?? {} });
     if (!parsed.ok)
         throw new Error(`Board ${result.id} could not be read: ${parsed.diagnostics[0]?.path}: ${parsed.diagnostics[0]?.message}`);
     return { document: parsed.document, boardId: result.id, title: result.title };
 }
 export async function loadBoardTextures(renderer, spaceId, items, options = {}) {
     const selection = selectBoardExportAssets([...items], imageAssetKey);
-    const textures = new Map();
-    const failed = [];
-    const pending = [...selection.keys];
+    const cache = options.cache ?? { textures: new Map(), failed: new Set() };
+    const { textures, failed } = cache;
+    const wanted = new Set(selection.keys);
+    for (const [key, texture] of textures) {
+        if (wanted.has(key))
+            continue;
+        texture.destroy(true);
+        textures.delete(key);
+    }
+    for (const key of failed)
+        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 client = createClient();
     async function worker() {
@@ -59,7 +75,7 @@ export async function loadBoardTextures(renderer, spaceId, items, options = {})
                 return;
             const source = boardImageKeySource(key);
             if (!source) {
-                failed.push(key);
+                failed.add(key);
                 continue;
             }
             try {
@@ -70,12 +86,12 @@ export async function loadBoardTextures(renderer, spaceId, items, options = {})
                 textures.set(key, texture);
             }
             catch {
-                failed.push(key);
+                failed.add(key);
             }
         }
     }
     await Promise.all(Array.from({ length: Math.min(concurrency, pending.length) }, worker));
-    return { textures, failed, omitted: selection.omittedKeys };
+    return { textures, failed: [...failed], omitted: selection.omittedKeys };
 }
 async function readSpaceFileBytes(client, spaceId, path) {
     const { blob, mimeType } = await client.space(spaceId).files.download(path);
@@ -93,24 +109,36 @@ export async function runBoardVideoExport(options) {
     const derivedFps = 1000 / step;
     if (Math.abs(options.fps - derivedFps) > 0.01)
         throw new Error(`--fps must match the --at step (${derivedFps.toFixed(3)} fps).`);
-    const result = await runBoardExport({ ...options, format: "png" });
-    if (!result)
-        throw new Error("Nothing to export: the region contains no items.");
+    if (times.some((time, index) => index > 0 && Math.abs(time - times[index - 1] - step) > 0.001))
+        throw new Error("Video export needs evenly spaced times.");
+    await execFile("ffmpeg", ["-version"], { signal: options.signal }).catch(() => { throw new Error("Video export needs ffmpeg. Install ffmpeg and try again."); });
+    const document = options.document ?? (await loadBoardDocument(options.spaceId, options.target)).document;
     const tempDir = await mkdtemp(join(tmpdir(), "cohub-board-export-"));
     try {
-        for (const [index, frame] of result.frames.entries())
-            await writeFile(join(tempDir, `${String(index + 1).padStart(6, "0")}.png`), frame.bytes);
-        const document = (await loadBoardDocument(options.spaceId, options.target)).document;
+        let count = 0;
+        let dimensions = { width: 0, height: 0 };
+        const result = await runBoardExport({ ...options, document, format: "png", onFrame: async (frame, index) => {
+                await writeFile(join(tempDir, `${String(index + 1).padStart(6, "0")}.png`), frame.bytes, { signal: options.signal });
+                dimensions = { width: frame.width, height: frame.height };
+                count++;
+            } });
+        if (!result || !count)
+            throw new Error("Nothing to export: the region contains no items.");
         const audioDocument = boardDocumentAt(document, options.animation, times[0]).document;
         const audio = Object.values(audioDocument.items).filter((item) => item.type === "audio");
         const audioInputs = [];
         for (const [index, item] of audio.entries()) {
-            const { bytes } = await readSpaceFileBytes(createClient(), options.spaceId, item.props.src);
-            const path = join(tempDir, `audio-${index}-${item.props.src.split("/").pop() ?? "track"}`);
+            const source = parseBoardMediaSource(item.props.src);
+            if (!source)
+                throw new Error("Invalid board audio source");
+            const { bytes } = source.kind === "url"
+                ? await downloadPublicAudio(source.value)
+                : await readSpaceFileBytes(createClient(), options.spaceId, source.value);
+            const path = join(tempDir, `audio-${index}`);
             await writeFile(path, bytes);
             audioInputs.push({ path, offset: Math.max(0, item.props.time ?? 0) / 1000 });
         }
-        const duration = Math.max(0.001, result.frames.length / options.fps);
+        const duration = Math.max(0.001, count / options.fps);
         const args = ["-y", "-f", "image2", "-framerate", String(options.fps), "-i", join(tempDir, "%06d.png")];
         for (const input of audioInputs) {
             if (input.offset > 0)
@@ -130,9 +158,10 @@ export async function runBoardVideoExport(options) {
             args.push("-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac", "-movflags", "+faststart", "-f", "mp4");
         else
             args.push("-c:v", "libvpx-vp9", "-crf", "32", "-b:v", "0", "-c:a", "libopus", "-f", "webm");
-        args.push("-t", duration.toFixed(3), options.output);
+        const encoded = join(tempDir, `video.${options.format}`);
+        args.push("-t", duration.toFixed(3), encoded);
         try {
-            await execFile("ffmpeg", args, { encoding: "utf8", maxBuffer: 2 * 1024 * 1024 });
+            await execFile("ffmpeg", args, { encoding: "utf8", maxBuffer: 2 * 1024 * 1024, signal: options.signal });
         }
         catch (error) {
             const cause = error;
@@ -140,45 +169,50 @@ export async function runBoardVideoExport(options) {
                 throw new Error("Video export needs ffmpeg. Install ffmpeg and try again.");
             throw new Error(`ffmpeg could not encode the video: ${(cause.stderr ?? cause.message ?? "unknown error").trim().split("\n").slice(-6).join("\n")}`);
         }
-        return { width: result.frames[0]?.width ?? 0, height: result.frames[0]?.height ?? 0, frames: result.frames.length, warnings: result.warnings };
+        options.signal?.throwIfAborted();
+        const staged = `${options.output}.${randomUUID()}.tmp`;
+        try {
+            await copyFile(encoded, staged, constants.COPYFILE_EXCL);
+            options.signal?.throwIfAborted();
+            if (options.force)
+                await rename(staged, options.output);
+            else
+                await link(staged, options.output);
+        }
+        finally {
+            await unlink(staged).catch(() => undefined);
+        }
+        return { ...dimensions, frames: count, warnings: result.warnings };
     }
     finally {
         await rm(tempDir, { recursive: true, force: true });
     }
 }
 export async function runBoardExport(options) {
-    const { document } = await loadBoardDocument(options.spaceId, options.target);
+    options.signal?.throwIfAborted();
+    const document = options.document ?? (await loadBoardDocument(options.spaceId, options.target)).document;
     if (options.animation && !document.animations[options.animation]) {
         throw new Error(`Animation ${options.animation} does not exist.`);
     }
     const times = options.times?.length ? options.times : [null];
-    const documentAt = (time) => time === null ? document : boardDocumentAt(document, options.animation ?? null, time).document;
-    const plan = planBoardExport({
-        scene: buildBoardScene(documentAt(times[0] ?? null)),
-        region: options.region,
-        scale: options.scale,
-        ...(options.padding === undefined ? {} : { padding: options.padding }),
-    });
-    if (!plan)
-        return null;
     const renderer = await createNodeBoardRenderer({ fonts: resolveBundledFonts() });
-    let sketchHost = null;
+    let scriptHost = null;
+    const textureCache = { textures: new Map(), failed: new Set() };
+    let backgroundTexture;
     try {
+        const sampler = createBoardRenderSampler(document, options.animation ?? null, { colorScheme: options.colorScheme });
+        const documentAt = (time) => time === null ? document : sampler.at(time).document;
+        const plan = planBoardExport({
+            scene: buildBoardScene(documentAt(times[0] ?? null)),
+            region: options.region,
+            scale: options.scale,
+            ...(options.padding === undefined ? {} : { padding: options.padding }),
+        });
+        if (!plan)
+            return null;
         const warnings = [];
-        let textures;
-        let backgroundTexture;
+        const textures = textureCache.textures;
         let omittedKeys = new Set();
-        if (options.withImages) {
-            const loaded = await loadBoardTextures(renderer, options.spaceId, plan.items);
-            textures = loaded.textures;
-            omittedKeys = new Set(loaded.omitted);
-            if (loaded.failed.length > 0) {
-                warnings.push(`${loaded.failed.length} image${loaded.failed.length === 1 ? "" : "s"} could not be loaded: ${loaded.failed.slice(0, 3).join(", ")}${loaded.failed.length > 3 ? ", …" : ""}`);
-            }
-            if (loaded.omitted.length > 0) {
-                warnings.push(`${loaded.omitted.length} previews were drawn as placeholders to stay within the export texture limit.`);
-            }
-        }
         const declaredBackground = document.board.background;
         if (options.withImages &&
             options.background === "paper" &&
@@ -193,32 +227,15 @@ export async function runBoardExport(options) {
             }
         }
         const videoCount = plan.items.filter((item) => item.type === "video").length;
-        sketchHost = createNodeBoardSketchHost(renderer, {
-            readModule: async (src) => {
-                const { bytes } = await readSpaceFileBytes(createClient(), options.spaceId, src);
-                return new TextDecoder().decode(bytes);
-            },
-        });
-        const region = times.length > 1 ? { kind: "rect", rect: plan.world } : options.region;
-        const host = sketchHost;
-        if (!host)
-            throw new Error("Node sketch host could not be created.");
-        const sketchVariants = new Map();
-        for (const time of times) {
-            const sketchPlan = planBoardExport({
-                scene: buildBoardScene(documentAt(time)),
-                region,
-                scale: options.scale,
-                ...(times.length > 1 ? { padding: 0 } : options.padding === undefined ? {} : { padding: options.padding }),
+        if (hasBoardScripts(document))
+            scriptHost = createNodeBoardScriptHost(renderer, {
+                readModule: async (src) => {
+                    const { bytes } = await readSpaceFileBytes(createClient(), options.spaceId, src);
+                    return new TextDecoder().decode(bytes);
+                },
             });
-            for (const item of sketchPlan?.items.filter((entry) => entry.type === "sketch") ?? []) {
-                const key = `${item.id}:${item.frame.width}:${item.frame.height}:${item.props.src}:${item.props.seed ?? ""}:${JSON.stringify(item.props.params)}`;
-                const variant = sketchVariants.get(key) ?? { item, times: [] };
-                variant.times.push(time ?? 0);
-                sketchVariants.set(key, variant);
-            }
-        }
-        await Promise.all([...sketchVariants.values()].map((variant) => host.prepare([variant.item], variant.times, plan.scale)));
+        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.`);
         }
@@ -233,16 +250,46 @@ export async function runBoardExport(options) {
             : undefined;
         const frames = [];
         const reported = new Set();
+        let completed = 0;
         for (const time of times) {
+            options.signal?.throwIfAborted();
+            host?.clearFrames();
+            const frameOptions = { sampler, camera: options.camera, ...(time === null ? {} : { at: { animation: options.animation, time } }), region, scale: options.scale, padding: times.length > 1 ? 0 : options.padding };
+            const initial = prepareBoardExport(document, frameOptions);
+            if (!initial)
+                continue;
+            let prepared = initial;
+            if (host) {
+                await host.prepare(initial.scene.items, [time ?? 0], initial.plan.scale);
+                for (const item of initial.scene.items) {
+                    const error = host.error(item.id);
+                    if (error)
+                        throw new Error(`${item.script?.src ?? item.id}: ${error}`);
+                }
+                const scripted = prepareBoardExport(document, { ...frameOptions, scripts: host });
+                if (!scripted)
+                    continue;
+                prepared = scripted;
+            }
+            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);
+                const assetWarnings = [
+                    loaded.failed.length ? `${loaded.failed.length} image(s) could not be loaded: ${loaded.failed.slice(0, 3).join(", ")}` : null,
+                    loaded.omitted.length ? `${loaded.omitted.length} previews were drawn as placeholders to stay within the export texture limit.` : null,
+                ];
+                for (const warning of assetWarnings)
+                    if (warning && !reported.has(warning)) {
+                        warnings.push(warning);
+                        reported.add(warning);
+                    }
+            }
             const result = exportBoardImageBytes(renderer, document, {
-                ...(time === null ? {} : { at: { ...(options.animation ? { animation: options.animation } : {}), time } }),
-                region,
-                scale: options.scale,
-                padding: times.length > 1 ? 0 : options.padding,
+                ...frameOptions,
                 colorScheme: options.colorScheme,
                 background: options.background,
                 textures,
-                sketches: sketchHost ?? undefined,
+                scripts: scriptHost ?? undefined,
                 backgroundImage,
                 ...(assetKey ? { assetKey } : {}),
                 format: options.format,
@@ -258,7 +305,7 @@ export async function runBoardExport(options) {
                     warnings.push(text);
                 reported.add(text);
             }
-            frames.push({
+            const frame = {
                 time,
                 bytes: result.bytes,
                 width: result.plan.width,
@@ -266,12 +313,21 @@ export async function runBoardExport(options) {
                 scale: result.plan.scale,
                 itemCount: result.plan.items.length,
                 format: result.format,
-            });
+            };
+            if (options.onFrame)
+                await options.onFrame(frame, completed);
+            else
+                frames.push(frame);
+            completed++;
+            options.onProgress?.(completed, times.length);
         }
-        return frames.length ? { frames, warnings } : null;
+        return completed ? { frames, warnings } : null;
     }
     finally {
-        sketchHost?.destroy();
+        scriptHost?.destroy();
+        for (const texture of textureCache.textures.values())
+            texture.destroy(true);
+        backgroundTexture?.destroy(true);
         renderer.destroy();
     }
 }