@neta-art/cohub-cli 3.0.0 → 3.1.0

package/dist/board-export.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Board image export for the CLI.
+ *
+ * Rendering runs through the same PixiJS card renderers the web editor uses (see
+ * `@neta-art/cohub-board`), on a Canvas2D backend. Everything platform-specific
+ * lives here: fetching the document over HTTP, pulling image bytes out of the
+ * space, and locating fonts on disk.
+ */
+import { type BoardDocument, type BoardItem } from "@neta-art/cohub-board";
+import { type BoardExportRegion } from "@neta-art/cohub-board/export";
+import { type BoardHeadlessExportFormat, type BoardHeadlessFont, type BoardHeadlessRenderer, type BoardHeadlessTexture } from "@neta-art/cohub-board/headless";
+export declare const BOARD_EXPORT_FORMATS: BoardHeadlessExportFormat[];
+/** Infer the output format from the file extension, defaulting to PNG. */
+export declare function formatFromPath(path: string): BoardHeadlessExportFormat;
+/**
+ * Geist, as shipped to the browser.
+ *
+ * The board asks for the "Geist" family; registering the exact same font files
+ * the web app loads is what makes CLI output match the editor rather than
+ * substituting whatever sans-serif the host happens to have. Resolution is
+ * best-effort: if the font package is not installed the export still succeeds,
+ * falling back through the font stack.
+ */
+export declare function resolveBundledFonts(): BoardHeadlessFont[];
+export type BoardExportSource = {
+    document: BoardDocument;
+    boardId: string;
+    title: string | null;
+};
+/**
+ * Load a board document by board id or by the path of its `.board` file.
+ *
+ * A `.board` file is a manifest holding a board id, so both forms converge on
+ * the same inspect call — which is also what the web client does.
+ */
+export declare function loadBoardDocument(spaceId: string, target: string): Promise<BoardExportSource>;
+/**
+ * Fetch every image in `items`, keyed the way the renderers ask for it.
+ *
+ * Takes the planned items rather than the whole document so a partial export
+ * does not download the rest of the board. Failures are collected rather than
+ * thrown: one unreadable image should cost a placeholder and a warning, not the
+ * whole export. Downloads run concurrently but bounded, so a board with hundreds
+ * of images does not open hundreds of sockets.
+ */
+export declare function loadBoardTextures(headless: BoardHeadlessRenderer, spaceId: string, items: BoardItem[], options?: {
+    concurrency?: number;
+}): Promise<{
+    textures: Map<string, BoardHeadlessTexture>;
+    failed: string[];
+    omitted: string[];
+}>;
+export type BoardExportRunOptions = {
+    spaceId: string;
+    target: string;
+    region: BoardExportRegion;
+    scale: number;
+    padding?: number;
+    colorScheme: "dark" | "light";
+    background: "paper" | "transparent";
+    format: BoardHeadlessExportFormat;
+    quality?: number;
+    withImages: boolean;
+};
+export type BoardExportRunResult = {
+    bytes: Uint8Array;
+    width: number;
+    height: number;
+    scale: number;
+    itemCount: number;
+    format: BoardHeadlessExportFormat;
+    warnings: string[];
+};
+/** Render a board to image bytes. Returns null when the region is empty. */
+export declare function runBoardExport(options: BoardExportRunOptions): Promise<BoardExportRunResult | null>;

package/dist/board-export.js

@@ -0,0 +1,221 @@
+/**
+ * Board image export for the CLI.
+ *
+ * Rendering runs through the same PixiJS card renderers the web editor uses (see
+ * `@neta-art/cohub-board`), on a Canvas2D backend. Everything platform-specific
+ * lives here: fetching the document over HTTP, pulling image bytes out of the
+ * space, and locating fonts on disk.
+ */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { boardBootstrapToDocument, boardImageKeySource, imageAssetKey, isBoardPath, parseBoardManifest, } from "@neta-art/cohub-board";
+import { planBoardExport, selectBoardExportAssets, } from "@neta-art/cohub-board/export";
+import { createBoardHeadlessRenderer, exportBoardImageBytes, } from "@neta-art/cohub-board/headless";
+import { createClient } from "./client.js";
+export const BOARD_EXPORT_FORMATS = ["png", "jpeg", "webp"];
+/** Infer the output format from the file extension, defaulting to PNG. */
+export function formatFromPath(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".jpg") || lower.endsWith(".jpeg"))
+        return "jpeg";
+    if (lower.endsWith(".webp"))
+        return "webp";
+    return "png";
+}
+/**
+ * Geist, as shipped to the browser.
+ *
+ * The board asks for the "Geist" family; registering the exact same font files
+ * the web app loads is what makes CLI output match the editor rather than
+ * substituting whatever sans-serif the host happens to have. Resolution is
+ * best-effort: if the font package is not installed the export still succeeds,
+ * falling back through the font stack.
+ */
+export function resolveBundledFonts() {
+    const require = createRequire(import.meta.url);
+    const fonts = [];
+    const candidates = [
+        { pkg: "@fontsource/geist", file: "geist-latin-500-normal.woff2", family: "Geist" },
+        { pkg: "@fontsource/geist", file: "geist-latin-400-normal.woff2", family: "Geist" },
+        { pkg: "@fontsource/geist", file: "geist-latin-600-normal.woff2", family: "Geist" },
+        { pkg: "@fontsource/geist-mono", file: "geist-mono-latin-400-normal.woff2", family: "Geist Mono" },
+    ];
+    for (const candidate of candidates) {
+        try {
+            const root = dirname(require.resolve(`${candidate.pkg}/package.json`));
+            const path = join(root, "files", candidate.file);
+            if (existsSync(path))
+                fonts.push({ path, family: candidate.family });
+        }
+        catch {
+            // Font package absent; the stack's system fallbacks cover it.
+        }
+    }
+    return fonts;
+}
+/**
+ * Load a board document by board id or by the path of its `.board` file.
+ *
+ * A `.board` file is a manifest holding a board id, so both forms converge on
+ * the same inspect call — which is also what the web client does.
+ */
+export async function loadBoardDocument(spaceId, target) {
+    const client = createClient();
+    const boardId = isBoardPath(target)
+        ? await resolveManifestBoardId(spaceId, target)
+        : target;
+    const bootstrap = await client.space(spaceId).board(boardId).inspect({ include: ["nodes"] });
+    return {
+        document: boardBootstrapToDocument(bootstrap),
+        boardId: bootstrap.board.id,
+        title: bootstrap.board.title ?? null,
+    };
+}
+async function resolveManifestBoardId(spaceId, path) {
+    const file = await createClient().space(spaceId).files.read(path);
+    if (!("content" in file) || typeof file.content !== "string") {
+        throw new Error(`${path} is not a readable board manifest.`);
+    }
+    return parseBoardManifest(file.content).boardId;
+}
+/**
+ * Fetch every image in `items`, keyed the way the renderers ask for it.
+ *
+ * Takes the planned items rather than the whole document so a partial export
+ * does not download the rest of the board. Failures are collected rather than
+ * thrown: one unreadable image should cost a placeholder and a warning, not the
+ * whole export. Downloads run concurrently but bounded, so a board with hundreds
+ * of images does not open hundreds of sockets.
+ */
+export async function loadBoardTextures(headless, spaceId, items, options = {}) {
+    const selection = selectBoardExportAssets(items, imageAssetKey);
+    const textures = new Map();
+    const failed = [];
+    const pending = [...selection.keys];
+    const concurrency = Math.max(1, Math.min(options.concurrency ?? 6, 16));
+    const client = createClient();
+    async function worker() {
+        for (;;) {
+            const key = pending.shift();
+            if (!key)
+                return;
+            const source = boardImageKeySource(key);
+            if (!source) {
+                failed.push(key);
+                continue;
+            }
+            try {
+                const { bytes, mimeType } = source.kind === "file"
+                    ? await readSpaceFileBytes(client, spaceId, source.value)
+                    : await readUrlBytes(source.value);
+                const texture = await headless.decodeImage(bytes, mimeType);
+                textures.set(key, texture);
+            }
+            catch {
+                failed.push(key);
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, pending.length) }, worker));
+    return { textures, failed, omitted: selection.omittedKeys };
+}
+async function readSpaceFileBytes(client, spaceId, path) {
+    const { blob, mimeType } = await client.space(spaceId).files.download(path);
+    return { bytes: new Uint8Array(await blob.arrayBuffer()), mimeType };
+}
+async function readUrlBytes(url) {
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status}`);
+    return {
+        bytes: new Uint8Array(await response.arrayBuffer()),
+        mimeType: response.headers.get("content-type") ?? "image/png",
+    };
+}
+/** Render a board to image bytes. Returns null when the region is empty. */
+export async function runBoardExport(options) {
+    const { document } = await loadBoardDocument(options.spaceId, options.target);
+    // Plan before fetching: a --frame / --items / --rect export should only pull
+    // the images it will actually draw, and an empty region should pull none.
+    const plan = planBoardExport({
+        document,
+        region: options.region,
+        scale: options.scale,
+        ...(options.padding === undefined ? {} : { padding: options.padding }),
+    });
+    if (!plan)
+        return null;
+    const headless = await createBoardHeadlessRenderer({ fonts: resolveBundledFonts() });
+    try {
+        const warnings = [];
+        let textures;
+        let omittedKeys = new Set();
+        if (options.withImages) {
+            const loaded = await loadBoardTextures(headless, 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 videoCount = plan.items.filter((item) => item.type === "video").length;
+        if (videoCount > 0) {
+            warnings.push(`${videoCount} video preview${videoCount === 1 ? " was" : "s were"} drawn as placeholders; headless video decoding is unavailable.`);
+        }
+        const result = exportBoardImageBytes(headless, document, {
+            region: options.region,
+            scale: options.scale,
+            padding: options.padding,
+            colorScheme: options.colorScheme,
+            background: options.background,
+            textures,
+            ...(options.withImages
+                ? {
+                    assetKey: (item) => {
+                        const key = imageAssetKey(item);
+                        return key && omittedKeys.has(key) ? null : key;
+                    },
+                }
+                : {}),
+            format: options.format,
+            quality: options.quality,
+        });
+        if (!result)
+            return null;
+        for (const warning of result.warnings) {
+            // Missing-image warnings are already reported above with their paths.
+            if (warning.kind === "images-missing" && options.withImages)
+                continue;
+            warnings.push(describeWarning(warning));
+        }
+        return {
+            bytes: result.bytes,
+            width: result.plan.width,
+            height: result.plan.height,
+            scale: result.plan.scale,
+            itemCount: result.plan.items.length,
+            format: result.format,
+            warnings,
+        };
+    }
+    finally {
+        headless.destroy();
+    }
+}
+function describeWarning(warning) {
+    if (warning.kind === "scale-clamped") {
+        return `Scale reduced from ${warning.requested}x to ${Number(warning.applied).toFixed(2)}x to stay within the size limit.`;
+    }
+    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).`;
+    }
+    if (warning.kind === "many-items") {
+        return `${warning.count} items exported.`;
+    }
+    return warning.kind;
+}

package/dist/commands/boards.js

@@ -1,7 +1,8 @@
 import { randomUUID } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
+import { BOARD_EXPORT_FORMATS, formatFromPath, runBoardExport } from "../board-export.js";
 import { createClient, createRealtimeClient } from "../client.js";
-import { handleHttp, json as outJson, jsonRequested, ok, table } from "../output.js";
+import { error, handleHttp, json as outJson, jsonRequested, ok, table } from "../output.js";
 import { resolveSpace } from "../space.js";
 const INSPECT_SECTIONS = ["nodes", "effects", "sequences", "clips", "playback"];
 function isObject(value) {
@@ -170,6 +171,118 @@ function registerTransactionCommand(boards, name) {
 function commandId(options) {
     return options.commandId?.trim() || randomUUID();
 }
+/**
+ * Resolve the mutually exclusive region flags.
+ *
+ * Selecting more than one is rejected rather than silently ranked: "why did
+ * --items win over --frame" is a worse experience than being told to pick one.
+ */
+function parseExportRegion(options) {
+    const chosen = [
+        options.frame ? "--frame" : null,
+        options.items ? "--items" : null,
+        options.rect ? "--rect" : null,
+    ].filter(Boolean);
+    if (chosen.length > 1) {
+        throw new Error(`Pick one region: ${chosen.join(", ")} cannot be combined`);
+    }
+    if (options.frame)
+        return { kind: "frame", id: options.frame };
+    if (options.items) {
+        const ids = options.items.split(",").map((id) => id.trim()).filter(Boolean);
+        if (ids.length === 0)
+            throw new Error("--items needs at least one node id");
+        return { kind: "items", ids };
+    }
+    if (options.rect) {
+        const rect = parseViewport(options.rect);
+        if (!rect)
+            throw new Error("--rect must be x,y,width,height");
+        return { kind: "rect", rect };
+    }
+    return { kind: "all" };
+}
+function parseExportFormat(options, outPath) {
+    if (!options.format)
+        return formatFromPath(outPath);
+    const format = options.format.toLowerCase();
+    if (!BOARD_EXPORT_FORMATS.includes(format)) {
+        throw new Error(`Unknown format "${options.format}"; use ${BOARD_EXPORT_FORMATS.join(", ")}`);
+    }
+    return format;
+}
+function parseColorMode(value) {
+    if (!value || value === "dark")
+        return "dark";
+    if (value === "light")
+        return "light";
+    throw new Error('--theme must be "dark" or "light"');
+}
+function parseBackground(value) {
+    if (!value || value === "paper")
+        return "paper";
+    if (value === "transparent")
+        return "transparent";
+    throw new Error('--background must be "paper" or "transparent"');
+}
+function registerExportCommand(boards) {
+    withJson(boards.command("export <board>")
+        .description("Render a Board to an image (board id or .board path)")
+        .requiredOption("-o, --out <file>", "Output file; extension selects the format")
+        .option("--scale <factor>", "Output pixels per world unit", "2")
+        .option("--padding <units>", "World-space padding around the content")
+        .option("--frame <node-id>", "Export a single frame as a page")
+        .option("--items <ids>", "Comma-separated node ids to export")
+        .option("--rect <rect>", "World rect as x,y,width,height")
+        .option("--theme <mode>", "dark or light", "dark")
+        .option("--background <mode>", "paper or transparent", "paper")
+        .option("--format <format>", `Override format (${BOARD_EXPORT_FORMATS.join(", ")})`)
+        .option("--quality <q>", "JPEG/WebP quality from 0 to 1", "0.92")
+        .option("--no-images", "Skip image downloads and draw placeholders"))
+        .action(async (board, options) => {
+        try {
+            const out = options.out;
+            if (!out)
+                throw new Error("--out is required");
+            const result = await runBoardExport({
+                spaceId: resolveSpace(boards),
+                target: board,
+                region: parseExportRegion(options),
+                scale: parseNumber(options.scale ?? "2", "scale", { min: 0.01, max: 16 }),
+                ...(options.padding === undefined
+                    ? {}
+                    : { padding: parseNumber(options.padding, "padding", { min: 0 }) }),
+                colorScheme: parseColorMode(options.theme),
+                background: parseBackground(options.background),
+                format: parseExportFormat(options, out),
+                quality: parseNumber(options.quality ?? "0.92", "quality", { min: 0, max: 1 }),
+                withImages: options.images !== false,
+            });
+            if (!result) {
+                return error("Nothing to export", "The selected region contains no items.");
+            }
+            await writeFile(out, result.bytes);
+            if (jsonRequested(options)) {
+                return outJson({
+                    path: out,
+                    width: result.width,
+                    height: result.height,
+                    scale: result.scale,
+                    items: result.itemCount,
+                    format: result.format,
+                    bytes: result.bytes.length,
+                    warnings: result.warnings,
+                });
+            }
+            ok(`Exported ${result.width}×${result.height} ${result.format.toUpperCase()} to ${out}`);
+            for (const warning of result.warnings)
+                console.log(`  ! ${warning}`);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+}
 export function registerBoards(program) {
     const boards = program
         .command("boards")
@@ -239,6 +352,7 @@ export function registerBoards(program) {
     });
     registerTransactionCommand(boards, "validate");
     registerTransactionCommand(boards, "apply");
+    registerExportCommand(boards);
     withJson(boards.command("play <board-id> <sequence-id>")
         .description("Start shared playback")
         .option("--position <time>", "Initial position in milliseconds")
@@ -322,9 +436,12 @@ export function registerBoards(program) {
                     if (event.type === "board.transaction.applied") {
                         process.stdout.write(`version ${event.payload.version}  transaction ${event.payload.txId}  operations ${event.payload.operations.length}\n`);
                     }
-                    else {
+                    else if (event.type === "board.playback.changed") {
                         process.stdout.write(`${event.payload.status}  sequence ${event.payload.sequenceId}  position ${event.payload.position}\n`);
                     }
+                    else {
+                        process.stdout.write(`awareness ${event.payload.actorName}  ${event.payload.update.type}\n`);
+                    }
                 },
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "license": "Apache-2.0",
@@ -18,7 +18,8 @@
     "@neta-art/generation": "^0.1.16",
     "commander": "^15.0.0",
     "sharp": "^0.35.3",
-    "@neta-art/cohub": "3.0.0"
+    "@neta-art/cohub": "3.1.0",
+    "@neta-art/cohub-board": "0.2.0"
   },
   "publishConfig": {
     "access": "public"
@@ -27,6 +28,9 @@
     "@types/node": "^26.1.1",
     "typescript": "^7.0.2"
   },
+  "optionalDependencies": {
+    "@napi-rs/canvas": "^1.0.2"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit"