@neta-art/cohub-cli 10.8.2 → 10.10.0

package/README.md

@@ -57,12 +57,15 @@ 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,
+Board exports keep the requested resolution. Previews are fetched and decoded at the size
+the export needs: Cohub-hosted media (Space files included) provide resized images and
+video first frames, and larger sources are scaled down before decoding. 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.
+budget. Previews beyond it are drawn as placeholders with a warning; a background image
+that does not fit fails the export before native decoding. 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
@@ -602,6 +605,17 @@ cohub cron-jobs delete <cronJobId>
 
 Confirm before enabling, disabling, or deleting recurring scheduled prompts.
 
+## Feedback
+
+```bash
+cohub feedback "runtime up hangs after sign-in"
+cohub feedback "Board export is blurry" -f board.png -f export.log
+cohub feedback --runtime-logs "Codex chats stopped syncing"
+cat report.md | cohub feedback
+```
+
+Sends feedback to the Cohub team. CLI version, OS, environment, account, and `COHUB_*` Space/Chat context are attached; the working directory is not. `--runtime-logs` attaches recent local Runtime diagnostics for the target Space.
+
 ## Safety
 
 Confirm before:

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

@@ -2,7 +2,9 @@ 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 type BoardExportDecodeImage = (bytes: Uint8Array, mimeType?: string, maxEdge?: number) => ReturnType<BoardNodeRenderer["decodeImage"]>;
+/** Decodes within `maxBytes`, first scaling images down to `maxEdge` on their long edge. */
 export declare function createBoardExportImageBudget(renderer: BoardNodeRenderer, maxBytes: number): {
-    decodeImage: (bytes: Uint8Array, mimeType?: string) => Promise<import("@neta-art/cohub/board/export/node").BoardNodeTexture>;
+    decodeImage: BoardExportDecodeImage;
     readonly usedBytes: number;
 };

package/dist/board-export-resources.js

@@ -1,13 +1,24 @@
 export const BOARD_EXPORT_IMAGE_MEMORY_MIB = 256;
 export class BoardExportResourceError extends Error {
 }
+/** Decodes within `maxBytes`, first scaling images down to `maxEdge` on their long edge. */
 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 decodeImage = async (input, mimeType, maxEdge = Number.POSITIVE_INFINITY) => {
         const { default: sharp } = await import("sharp");
-        const { width, height } = await sharp(bytes, { limitInputPixels: false }).metadata();
+        let bytes = input;
+        let { width, height } = await sharp(bytes, { limitInputPixels: false }).metadata();
+        if (Math.max(width ?? 0, height ?? 0) > maxEdge) {
+            const resized = await sharp(bytes, { limitInputPixels: false })
+                .resize({ width: maxEdge, height: maxEdge, fit: "inside" })
+                .png({ compressionLevel: 0 })
+                .toBuffer({ resolveWithObject: true });
+            ({ width, height } = resized.info);
+            bytes = new Uint8Array(resized.data);
+            mimeType = "image/png";
+        }
         const required = (width ?? 0) * (height ?? 0) * 4;
         if (!Number.isSafeInteger(required) || required <= 0)
             throw new Error("Image dimensions could not be read.");

package/dist/board-export.d.ts

@@ -1,5 +1,6 @@
-import type { BoardDocument, BoardExportRegion, BoardSceneItem } from "@neta-art/cohub/board";
-import type { BoardNodeExportFormat, BoardNodeFont, BoardNodeRenderer, BoardNodeTexture } from "@neta-art/cohub/board/export/node";
+import type { BoardDocument, BoardExportRegion, BoardSceneItem, BoardThemeId } from "@neta-art/cohub/board";
+import type { BoardNodeExportFormat, BoardNodeFont, BoardNodeTexture } from "@neta-art/cohub/board/export/node";
+import { type BoardExportDecodeImage } from "./board-export-resources.js";
 export declare function resolveBundledFonts(): BoardNodeFont[];
 export type BoardExportSource = {
     document: BoardDocument;
@@ -7,18 +8,31 @@ export type BoardExportSource = {
     title: string | null;
 };
 export declare function loadBoardDocument(spaceId: string, target: string): Promise<BoardExportSource>;
+type TextureMiss = "error" | "unavailable" | "omitted";
 export type BoardExportTextureCache = {
     textures: Map<string, BoardNodeTexture>;
-    failed: Set<string>;
+    /** Long edge each texture was decoded for; Infinity once it is the whole source. */
+    edges: Map<string, number>;
+    /** Keys without a texture: failed to load, no picture Node can draw, or over the image budget. */
+    missed: Map<string, TextureMiss>;
 };
-export declare function loadBoardTextures(renderer: BoardNodeRenderer, spaceId: string, items: readonly BoardSceneItem[], options?: {
+/** Texture keys Node can draw; 3D model stills need a browser. */
+export declare function boardExportAssetKey(item: BoardSceneItem): string | null;
+/**
+ * Previews for `items` within what the image budget leaves after other images,
+ * such as the background. A preview that still does not fit is omitted.
+ */
+export declare function loadBoardTextures(images: {
+    decodeImage: BoardExportDecodeImage;
+    usedBytes: number;
+}, spaceId: string, items: readonly BoardSceneItem[], options: {
+    scale: number;
+    maxBytes: number;
     concurrency?: number;
     cache?: BoardExportTextureCache;
 }): Promise<{
     textures: Map<string, BoardNodeTexture>;
-    failed: string[];
-    omitted: string[];
-}>;
+} & Record<"failed" | "unavailable" | "omitted", string[]>>;
 export type BoardExportRunOptions = {
     spaceId: string;
     target: string;
@@ -27,7 +41,7 @@ export type BoardExportRunOptions = {
     animation?: string;
     scale: number;
     padding?: number;
-    colorScheme: "dark" | "light";
+    theme: BoardThemeId;
     background: "paper" | "transparent";
     format: BoardNodeExportFormat;
     quality?: number;
@@ -74,3 +88,4 @@ export declare function runBoardVideoExport(options: BoardVideoExportOptions): P
     warnings: string[];
 }>;
 export declare function runBoardExport(options: BoardExportRunOptions): Promise<BoardExportRunResult | null>;
+export {};

package/dist/board-export.js

@@ -10,12 +10,14 @@ import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
 const execFile = promisify(execFileCallback);
 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 { imageVariantUrl, MEDIA_VARIANT_MAX, mediaVariantSize, videoFrameUrl } from "@neta-art/cohub/media";
+import { hasBoardScripts, boardAssetKey, boardAssetKeySource, boardDocumentAt, boardRenderTheme, boardTextureEdge, boardTexturePixels, createBoardRenderSampler, buildBoardScene, createNodeBoardRenderer, createNodeBoardScriptHost, exportBoardImageBytes, parseBoardDocument, planBoardExport, prepareBoardExport, selectBoardExportAssets, } from "./board-kernel.js";
 import { resolveBoardId } from "./board-command-support.js";
+import { settleBoardDocument } from "./board-media.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";
+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);
@@ -53,55 +55,105 @@ export async function loadBoardDocument(spaceId, target) {
         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 cache = options.cache ?? { textures: new Map(), failed: new Set() };
-    const { textures, failed } = cache;
+/** Texture keys Node can draw; 3D model stills need a browser. */
+export function boardExportAssetKey(item) {
+    const key = boardAssetKey(item);
+    return key && boardAssetKeySource(key)?.media !== "model" ? key : null;
+}
+function textureEdge(item, scale) {
+    const edge = boardTextureEdge(item, scale);
+    return Number.isFinite(edge) ? edge : Math.ceil(boardTexturePixels(item, scale));
+}
+const textureBytes = (texture) => texture.width * texture.height * 4;
+/**
+ * Previews for `items` within what the image budget leaves after other images,
+ * such as the background. A preview that still does not fit is omitted.
+ */
+export async function loadBoardTextures(images, spaceId, items, options) {
+    const cache = options.cache ?? { textures: new Map(), edges: new Map(), missed: new Map() };
+    const { textures, edges, missed } = cache;
+    let previewBytes = 0;
+    for (const texture of textures.values())
+        previewBytes += textureBytes(texture);
+    const maxBytes = options.maxBytes - (images.usedBytes - previewBytes);
+    const selection = selectBoardExportAssets([...items], boardExportAssetKey, { scale: options.scale, maxBytes });
     const wanted = new Set(selection.keys);
     for (const [key, texture] of textures) {
         if (wanted.has(key))
             continue;
         texture.destroy(true);
         textures.delete(key);
+        edges.delete(key);
     }
-    for (const key of failed)
+    for (const key of missed.keys())
         if (!wanted.has(key))
-            failed.delete(key);
-    const pending = selection.keys.filter((key) => !textures.has(key) && !failed.has(key));
+            missed.delete(key);
+    const pending = selection.items.flatMap((item, index) => {
+        const key = selection.keys[index];
+        const edge = textureEdge(item, options.scale);
+        return missed.has(key) || (edges.get(key) ?? 0) >= edge ? [] : [{ key, item, edge }];
+    });
     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;
-            const source = boardImageKeySource(key);
-            if (!source) {
-                failed.add(key);
-                continue;
-            }
+        for (let task = pending.shift(); task; task = pending.shift()) {
+            const { key, item, edge } = task;
+            let miss = "unavailable";
             try {
-                const { bytes, mimeType } = source.kind === "file"
-                    ? await readSpaceFileBytes(client, spaceId, source.value)
-                    : await downloadPublicImage(source.value);
-                const texture = await renderer.decodeImage(bytes, mimeType);
-                textures.set(key, texture);
+                const source = boardAssetKeySource(key);
+                const picture = source && await fetchBoardPicture(client, spaceId, source, item, edge);
+                if (picture) {
+                    const texture = await images.decodeImage(picture.bytes, picture.mimeType, edge);
+                    textures.get(key)?.destroy(true);
+                    textures.set(key, texture);
+                    edges.set(key, Math.max(texture.width, texture.height) < edge ? Number.POSITIVE_INFINITY : edge);
+                    miss = null;
+                }
             }
             catch (error) {
-                if (error instanceof BoardExportResourceError)
-                    resourceError = error;
-                else
-                    failed.add(key);
+                miss = error instanceof BoardExportResourceError ? "omitted" : "error";
             }
+            // A preview already shown stays, at the sharpness it has.
+            if (miss && textures.has(key))
+                edges.set(key, Number.POSITIVE_INFINITY);
+            else if (miss)
+                missed.set(key, miss);
         }
     }
     await Promise.all(Array.from({ length: Math.min(concurrency, pending.length) }, worker));
-    if (resourceError)
-        throw resourceError;
-    return { textures, failed: [...failed], omitted: selection.omittedKeys };
+    const keys = (reason) => [...missed].flatMap(([key, value]) => (value === reason ? [key] : []));
+    return { textures, failed: keys("error"), unavailable: keys("unavailable"), omitted: [...selection.omittedKeys, ...keys("omitted")] };
+}
+/**
+ * The picture for a texture, `edge` pixels on its long edge where the host can
+ * resize: a CDN variant of an image, or the first frame of a video. Null when
+ * there is none, as for videos outside Cohub's media hosts.
+ */
+async function fetchBoardPicture(client, spaceId, source, item, edge) {
+    // Thumbnail edges below the smallest variant fetch that variant; decoding scales it down.
+    const variantEdge = Number.isFinite(edge) && edge <= MEDIA_VARIANT_MAX ? mediaVariantSize(edge) : null;
+    const video = source.media === "video";
+    const url = source.kind === "url"
+        ? source.value
+        : video || variantEdge
+            ? await client.space(spaceId).files.resolveUrl(source.value, { purpose: "playback" }).catch(() => null)
+            : null;
+    if (video) {
+        const { naturalWidth: w, naturalHeight: h } = (item.type === "video" && item.props.snapshot) || {};
+        const width = w && h ? Math.min(w, (edge * w) / Math.max(w, h)) : edge;
+        const frame = url && videoFrameUrl(url, mediaVariantSize(width));
+        return frame ? downloadPublicImage(frame) : null;
+    }
+    const variant = url && variantEdge && imageVariantUrl(url, variantEdge);
+    if (variant) {
+        try {
+            return await downloadPublicImage(variant);
+        }
+        catch {
+            // Fall back to the original below.
+        }
+    }
+    return source.kind === "url" ? downloadPublicImage(source.value) : readSpaceFileBytes(client, spaceId, source.value);
 }
 async function readSpaceFileBytes(client, spaceId, path) {
     const { blob, mimeType } = await client.space(spaceId).files.download(path);
@@ -122,7 +174,7 @@ export async function runBoardVideoExport(options) {
     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 document = options.document ?? await settleBoardDocument(options.spaceId, (await loadBoardDocument(options.spaceId, options.target)).document);
     const tempDir = await mkdtemp(join(tmpdir(), "cohub-board-export-"));
     try {
         let count = 0;
@@ -208,7 +260,7 @@ export async function runBoardVideoExport(options) {
 }
 export async function runBoardExport(options) {
     options.signal?.throwIfAborted();
-    const document = options.document ?? (await loadBoardDocument(options.spaceId, options.target)).document;
+    const document = options.document ?? await settleBoardDocument(options.spaceId, (await loadBoardDocument(options.spaceId, options.target)).document);
     if (options.animation && !document.animations[options.animation]) {
         throw new Error(`Animation ${options.animation} does not exist.`);
     }
@@ -230,10 +282,11 @@ export async function runBoardExport(options) {
         });
     };
     let scriptHost = null;
-    const textureCache = { textures: new Map(), failed: new Set() };
+    const textureCache = { textures: new Map(), edges: new Map(), missed: new Map() };
     let backgroundTexture;
     try {
-        const sampler = createBoardRenderSampler(document, options.animation ?? null, { colorScheme: options.colorScheme });
+        const theme = boardRenderTheme(options.theme);
+        const sampler = createBoardRenderSampler(document, options.animation ?? null, theme);
         const documentAt = (time) => time === null ? document : sampler.at(time).document;
         const plan = planBoardExport({
             scene: buildBoardScene(documentAt(times[0] ?? null)),
@@ -272,7 +325,6 @@ export async function runBoardExport(options) {
                 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,
@@ -282,18 +334,13 @@ export async function runBoardExport(options) {
                 },
             });
         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.`);
-        }
         const backgroundImage = backgroundTexture
             ? { texture: backgroundTexture, fit: declaredBackground.fit ?? "cover", position: "center", opacity: declaredBackground.opacity ?? 1 }
             : undefined;
-        const assetKey = options.withImages
-            ? (item) => {
-                const key = imageAssetKey(item);
-                return key && omittedKeys.has(key) ? null : key;
-            }
-            : undefined;
+        const assetKey = (item) => {
+            const key = boardExportAssetKey(item);
+            return key && omittedKeys.has(key) ? null : key;
+        };
         const frames = [];
         const reported = new Set();
         let completed = 0;
@@ -320,11 +367,15 @@ export async function runBoardExport(options) {
             }
             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 });
+                const visible = prepared.plan.items.filter((item) => prepared.scene.opacity(item.id) > 0);
+                const loaded = await loadBoardTextures(images, options.spaceId, visible, { scale: prepared.plan.scale, maxBytes: imageMemoryBytes, cache: textureCache });
                 omittedKeys = new Set(loaded.omitted);
+                const sources = (keys) => keys.slice(0, 3).map((key) => boardAssetKeySource(key)?.value ?? key).join(", ");
+                const plural = (count, noun) => `${count} ${noun}${count === 1 ? "" : "s"}`;
                 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,
+                    loaded.failed.length ? `${plural(loaded.failed.length, "preview")} could not be loaded: ${sources(loaded.failed)}` : null,
+                    loaded.unavailable.length ? `${plural(loaded.unavailable.length, "video")} drawn without a cover; Node exports take covers from Cohub-hosted media only.` : null,
+                    loaded.omitted.length ? `${plural(loaded.omitted.length, "preview")} drawn as placeholders to stay within the ${imageMemoryBytes / 1024 ** 2} MiB image budget; raise --image-memory to include them.` : null,
                 ];
                 for (const warning of assetWarnings)
                     if (warning && !reported.has(warning)) {
@@ -335,12 +386,12 @@ export async function runBoardExport(options) {
             trace("render", completed, prepared.plan);
             const result = exportBoardImageBytes(renderer, document, {
                 ...frameOptions,
-                colorScheme: options.colorScheme,
+                ...theme,
                 background: options.background,
                 textures,
                 scripts: scriptHost ?? undefined,
                 backgroundImage,
-                ...(assetKey ? { assetKey } : {}),
+                assetKey,
                 format: options.format,
                 quality: options.quality,
             });
@@ -387,7 +438,7 @@ function describeWarning(warning) {
     }
     if (warning.kind === "images-missing") {
         const keys = warning.keys;
-        return `${keys.length} image${keys.length === 1 ? "" : "s"} drawn as placeholders (use --images to fetch them).`;
+        return `${keys.length} preview${keys.length === 1 ? "" : "s"} drawn as placeholders; omit --no-images to fetch them.`;
     }
     if (warning.kind === "many-items") {
         return `${warning.count} items exported.`;

package/dist/board-fonts.d.ts

@@ -1,4 +1,8 @@
-/** Geist files `boards export` registers, copied into `dist/fonts` at build time. */
+/**
+ * Fonts `boards export` registers, copied into `dist/fonts` at build time. The
+ * variable files and family names are the ones the Web loads, so every weight
+ * draws with the same outlines; Figtree is the Neta Pixel theme's font.
+ */
 export type BoardExportFont = {
     pkg: string;
     file: string;

package/dist/board-fonts.js

@@ -1,10 +1,10 @@
-/** Geist files `boards export` registers, copied into `dist/fonts` at build time. */
-const subset = (pkg, family, weights) => weights.map((weight) => ({
-    pkg,
-    family,
-    file: `${pkg.split("/").pop()}-latin-${weight}-normal.woff2`,
-}));
+/**
+ * Fonts `boards export` registers, copied into `dist/fonts` at build time. The
+ * variable files and family names are the ones the Web loads, so every weight
+ * draws with the same outlines; Figtree is the Neta Pixel theme's font.
+ */
 export const BOARD_EXPORT_FONTS = [
-    ...subset("@fontsource/geist", "Geist", [400, 500, 600, 700]),
-    ...subset("@fontsource/geist-mono", "Geist Mono", [500, 600, 700]),
+    { pkg: "@fontsource-variable/geist", file: "geist-latin-wght-normal.woff2", family: "Geist Variable" },
+    { pkg: "@fontsource-variable/geist-mono", file: "geist-mono-latin-wght-normal.woff2", family: "Geist Mono Variable" },
+    { pkg: "@fontsource-variable/figtree", file: "figtree-latin-wght-normal.woff2", family: "Figtree Variable" },
 ];

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 { BOARD_SCRIPT_DRAWING_EXAMPLE, hasBoardScripts, boardAssetKey, boardAssetKeySource, boardDocumentAt, createBoardAnimationSampler, boardSequence, boardSequencePatch, boardPathTrack, boardTextureEdge, boardTexturePixels, buildBoardScene, parseBoardDocument, planBoardExport, selectBoardExportAssets, } from "@neta-art/cohub/board";
 export { prepareBoardExport } from "@neta-art/cohub/board/export";
-export { createBoardRenderSampler, inspectBoardScene, inspectBoardItems, measureBoardText } from "@neta-art/cohub/board/render";
+export { boardRenderTheme, createBoardRenderSampler, inspectBoardScene, inspectBoardItems, measureBoardText } from "@neta-art/cohub/board/render";
 export { createNodeBoardRenderer, createNodeBoardScriptHost, exportBoardImageBytes } from "@neta-art/cohub/board/export/node";