@neta-art/cohub-cli 2.7.0 → 3.1.0

package/README.md

@@ -121,6 +121,55 @@ cohub -s <spaceId> spaces sessions rename <sessionId> "<new title>"
 
 Use `spaces prompt --session <sessionId>` to send to a Chat.
 
+## Boards
+
+Board commands use the selected Space and support `-h` at every level:
+
+```bash
+cohub boards -h
+cohub boards inspect -h
+cohub -s <spaceId> boards create boards/plan.board --title "Plan"
+cohub -s <spaceId> boards inspect <boardId> --json
+cohub -s <spaceId> boards capabilities <boardId>
+cohub -s <spaceId> boards watch <boardId> --json
+```
+
+Pass nodes, effects, and sequences as JSON when creating a Board. The path and
+title stay explicit in the command:
+
+```bash
+cohub -s <spaceId> boards create boards/plan.board \
+  --title "Plan" \
+  --input board-content.json
+```
+
+Transactions are JSON objects without `boardId`; the bound Board supplies it.
+`txId` is generated when omitted, while `baseVersion` must be provided in the
+input or with `--base-version`:
+
+```json
+{
+  "baseVersion": 3,
+  "operations": [
+    {
+      "type": "board.patch",
+      "payload": { "patch": { "title": "Updated plan" } }
+    }
+  ]
+}
+```
+
+```bash
+cohub -s <spaceId> boards validate <boardId> --input transaction.json
+cat transaction.json | cohub -s <spaceId> boards apply <boardId> --input - --json
+cohub -s <spaceId> boards play <boardId> <sequenceId>
+cohub -s <spaceId> boards seek <boardId> <playbackId> 400
+cohub -s <spaceId> boards stop <boardId> <playbackId>
+```
+
+Pass `--tx-id` or `--command-id` when a script needs a stable idempotency key
+across retries.
+
 ## Search
 
 Search Spaces, Chats, and prior turns:

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/client.d.ts

@@ -1,2 +1,3 @@
-import { CohubHttpClient } from "@neta-art/cohub";
+import { CohubClient, CohubHttpClient } from "@neta-art/cohub";
 export declare function createClient(): CohubHttpClient;
+export declare function createRealtimeClient(): CohubClient;

package/dist/client.js

@@ -1,11 +1,15 @@
-import { CohubHttpClient, readRequestSourceFromEnv } from "@neta-art/cohub";
+import { CohubClient, CohubHttpClient, readRequestSourceFromEnv } from "@neta-art/cohub";
 import { clearAuthSession, resolveAccessToken } from "./auth.js";
+const clientOptions = () => ({
+    getAccessToken: resolveAccessToken,
+    onUnauthorized: clearAuthSession,
+    requestSource: () => readRequestSourceFromEnv(process.env, { via: "cli" }) ?? {
+        via: "cli",
+    },
+});
 export function createClient() {
-    return new CohubHttpClient({
-        getAccessToken: resolveAccessToken,
-        onUnauthorized: clearAuthSession,
-        requestSource: () => readRequestSourceFromEnv(process.env, { via: "cli" }) ?? {
-            via: "cli",
-        },
-    });
+    return new CohubHttpClient(clientOptions());
+}
+export function createRealtimeClient() {
+    return new CohubClient(clientOptions());
 }

package/dist/commands/boards.d.ts

@@ -0,0 +1,14 @@
+import type { BoardInspectInput, BoardTransactionInput } from "@neta-art/cohub";
+import type { Command } from "commander";
+declare const INSPECT_SECTIONS: readonly ["nodes", "effects", "sequences", "clips", "playback"];
+type InspectSection = (typeof INSPECT_SECTIONS)[number];
+export declare function parseJsonObject(text: string, source?: string): Record<string, unknown>;
+export declare function readJsonObject(source: string): Promise<Record<string, unknown>>;
+export declare function parseInspectSections(value?: string): InspectSection[] | undefined;
+export declare function parseViewport(value?: string): BoardInspectInput["viewport"];
+export declare function createTransactionInput(input: Record<string, unknown>, options: {
+    txId?: string;
+    baseVersion?: string;
+}): BoardTransactionInput;
+export declare function registerBoards(program: Command): Command;
+export {};

package/dist/commands/boards.js

@@ -0,0 +1,453 @@
+import { randomUUID } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { BOARD_EXPORT_FORMATS, formatFromPath, runBoardExport } from "../board-export.js";
+import { createClient, createRealtimeClient } from "../client.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) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export function parseJsonObject(text, source = "input") {
+    if (!text.trim())
+        throw new Error(`${source} is empty`);
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (cause) {
+        throw new Error(`${source} must contain valid JSON`, { cause });
+    }
+    if (!isObject(value))
+        throw new Error(`${source} must contain a JSON object`);
+    return value;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function readJsonObject(source) {
+    const text = source === "-" ? await readStdin() : await readFile(source, "utf8");
+    return parseJsonObject(text, source === "-" ? "stdin" : source);
+}
+function parseNumber(value, name, options = {}) {
+    if (!value.trim())
+        throw new Error(`${name} must be a finite number`);
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        throw new Error(`${name} must be a finite number`);
+    if (options.integer && !Number.isSafeInteger(parsed))
+        throw new Error(`${name} must be an integer`);
+    if (options.min !== undefined && parsed < options.min)
+        throw new Error(`${name} must be at least ${options.min}`);
+    if (options.max !== undefined && parsed > options.max)
+        throw new Error(`${name} must be at most ${options.max}`);
+    return parsed;
+}
+export function parseInspectSections(value) {
+    if (!value)
+        return undefined;
+    const sections = value.split(",").map((item) => item.trim()).filter(Boolean);
+    const unknown = sections.filter((section) => !INSPECT_SECTIONS.includes(section));
+    if (unknown.length > 0)
+        throw new Error(`Unknown Board section: ${unknown.join(", ")}`);
+    return [...new Set(sections)];
+}
+export function parseViewport(value) {
+    if (!value)
+        return undefined;
+    const parts = value.split(",").map((part) => part.trim());
+    if (parts.length !== 4)
+        throw new Error("viewport must be x,y,width,height");
+    const [xValue, yValue, widthValue, heightValue] = parts;
+    if (xValue === undefined || yValue === undefined || widthValue === undefined || heightValue === undefined) {
+        throw new Error("viewport must be x,y,width,height");
+    }
+    const x = parseNumber(xValue, "viewport x");
+    const y = parseNumber(yValue, "viewport y");
+    const width = parseNumber(widthValue, "viewport width");
+    const height = parseNumber(heightValue, "viewport height");
+    if (width <= 0 || height <= 0)
+        throw new Error("viewport width and height must be greater than zero");
+    return { x, y, width, height };
+}
+export function createTransactionInput(input, options) {
+    if ("boardId" in input)
+        throw new Error("transaction input must not contain boardId");
+    if (!Array.isArray(input.operations))
+        throw new Error("transaction input must contain an operations array");
+    const rawBaseVersion = options.baseVersion ?? input.baseVersion;
+    if (rawBaseVersion === undefined)
+        throw new Error("baseVersion is required in input or --base-version");
+    const baseVersion = parseNumber(String(rawBaseVersion), "baseVersion", { min: 0, integer: true });
+    const rawTxId = options.txId ?? input.txId;
+    if (rawTxId !== undefined && (typeof rawTxId !== "string" || !rawTxId.trim())) {
+        throw new Error("txId must be a non-empty string");
+    }
+    return {
+        ...input,
+        txId: typeof rawTxId === "string" ? rawTxId : randomUUID(),
+        baseVersion,
+        operations: input.operations,
+    };
+}
+function showBoard(result) {
+    table([
+        {
+            id: result.board.id,
+            title: result.board.title,
+            version: result.board.version,
+            nodes: result.nodes.length,
+            effects: result.effects.length,
+            sequences: result.sequences.length,
+            clips: result.clips.length,
+        },
+    ], [
+        { key: "id", label: "ID" },
+        { key: "title", label: "Title" },
+        { key: "version", label: "Version" },
+        { key: "nodes", label: "Nodes" },
+        { key: "effects", label: "Effects" },
+        { key: "sequences", label: "Sequences" },
+        { key: "clips", label: "Clips" },
+    ]);
+}
+function showValidation(result) {
+    table([{ valid: result.valid, diagnostics: result.diagnostics.length }], [
+        { key: "valid", label: "Valid" },
+        { key: "diagnostics", label: "Diagnostics" },
+    ]);
+    if (result.diagnostics.length > 0) {
+        console.log();
+        table(result.diagnostics, [
+            { key: "severity", label: "Severity" },
+            { key: "code", label: "Code" },
+            { key: "path", label: "Path" },
+            { key: "message", label: "Message" },
+        ]);
+    }
+    console.log();
+    table([result.peakCost], Object.keys(result.peakCost).map((key) => ({ key, label: key })));
+}
+function showPlayback(result) {
+    table([result], [
+        { key: "playbackId", label: "Playback ID" },
+        { key: "sequenceId", label: "Sequence" },
+        { key: "status", label: "Status" },
+        { key: "position", label: "Position" },
+        { key: "timeScale", label: "Time Scale" },
+    ]);
+}
+function withJson(command) {
+    return command.option("--json", "Output as JSON");
+}
+function registerTransactionCommand(boards, name) {
+    withJson(boards.command(`${name} <board-id>`)
+        .description(name === "validate" ? "Validate a transaction" : "Apply a transaction")
+        .requiredOption("-i, --input <file>", "Transaction JSON file; use - for stdin")
+        .option("--tx-id <id>", "Override txId; generated when omitted")
+        .option("--base-version <version>", "Override baseVersion"))
+        .action(async (boardId, options) => {
+        try {
+            const transaction = createTransactionInput(await readJsonObject(options.input), options);
+            const board = createClient().space(resolveSpace(boards)).board(boardId);
+            const result = await board[name](transaction);
+            if (jsonRequested(options))
+                return outJson(result);
+            if (name === "validate")
+                showValidation(result);
+            else {
+                ok(`Board updated to version ${result.board.version}`);
+                showBoard(result);
+            }
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+}
+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")
+        .description("Inspect and update Boards")
+        .hook("preAction", () => { resolveSpace(boards); });
+    withJson(boards.command("create <path>")
+        .description("Create a Board")
+        .option("--title <title>", "Board title")
+        .option("-i, --input <file>", "Board content JSON file; use - for stdin"))
+        .action(async (path, options) => {
+        try {
+            const content = options.input ? await readJsonObject(options.input) : {};
+            if ("path" in content || "title" in content) {
+                throw new Error("create input must not contain path or title; use the command argument and --title");
+            }
+            const input = { ...content, path, ...(options.title ? { title: options.title } : {}) };
+            const result = await createClient().space(resolveSpace(boards)).boards.create(input);
+            if (jsonRequested(options))
+                return outJson(result);
+            ok(`Board created: ${result.board.id}`);
+            showBoard(result);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(boards.command("inspect <board-id>")
+        .alias("get")
+        .description("Inspect a Board")
+        .option("--include <sections>", "Comma-separated nodes,effects,sequences,clips,playback")
+        .option("--viewport <rect>", "Viewport as x,y,width,height"))
+        .action(async (boardId, options) => {
+        try {
+            const result = await createClient().space(resolveSpace(boards)).board(boardId).inspect({
+                include: parseInspectSections(options.include),
+                viewport: parseViewport(options.viewport),
+            });
+            if (jsonRequested(options))
+                return outJson(result);
+            showBoard(result);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(boards.command("capabilities <board-id>")
+        .description("Show supported capabilities"))
+        .action(async (boardId, options) => {
+        try {
+            const result = await createClient().space(resolveSpace(boards)).board(boardId).capabilities();
+            if (jsonRequested(options))
+                return outJson(result);
+            table(result.capabilities.map((capability) => ({
+                ...capability,
+                renderers: capability.renderers?.join(", ") ?? "",
+            })), [
+                { key: "kind", label: "Kind" },
+                { key: "id", label: "ID" },
+                { key: "version", label: "Version" },
+                { key: "renderers", label: "Renderers" },
+                { key: "digest", label: "Digest" },
+            ]);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    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")
+        .option("--time-scale <scale>", "Playback speed from 0 to 4")
+        .option("--seed <seed>", "Deterministic playback seed")
+        .option("--command-id <id>", "Idempotency command ID"))
+        .action(async (boardId, sequenceId, options) => {
+        try {
+            const result = await createClient().space(resolveSpace(boards)).board(boardId).play({
+                commandId: commandId(options),
+                type: "play",
+                sequenceId,
+                shared: true,
+                ...(options.position === undefined ? {} : { position: parseNumber(options.position, "position", { min: 0 }) }),
+                ...(options.timeScale === undefined ? {} : { timeScale: parseNumber(options.timeScale, "timeScale", { min: Number.EPSILON, max: 4 }) }),
+                ...(options.seed ? { seed: options.seed } : {}),
+            });
+            if (jsonRequested(options))
+                return outJson(result);
+            showPlayback(result);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    const playbackAction = (type) => async (boardId, playbackId, options) => {
+        try {
+            const board = createClient().space(resolveSpace(boards)).board(boardId);
+            const id = commandId(options);
+            const result = type === "pause"
+                ? await board.pause({ commandId: id, type: "pause", playbackId })
+                : await board.stop({ commandId: id, type: "stop", playbackId });
+            if (jsonRequested(options))
+                return outJson(result);
+            showPlayback(result);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    };
+    withJson(boards.command("pause <board-id> <playback-id>")
+        .description("Pause playback")
+        .option("--command-id <id>", "Idempotency command ID"))
+        .action(playbackAction("pause"));
+    withJson(boards.command("seek <board-id> <playback-id> <position>")
+        .description("Seek playback")
+        .option("--command-id <id>", "Idempotency command ID"))
+        .action(async (boardId, playbackId, position, options) => {
+        try {
+            const result = await createClient().space(resolveSpace(boards)).board(boardId).seek({
+                commandId: commandId(options),
+                type: "seek",
+                playbackId,
+                position: parseNumber(position, "position", { min: 0 }),
+            });
+            if (jsonRequested(options))
+                return outJson(result);
+            showPlayback(result);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(boards.command("stop <board-id> <playback-id>")
+        .description("Stop playback")
+        .option("--command-id <id>", "Idempotency command ID"))
+        .action(playbackAction("stop"));
+    withJson(boards.command("watch <board-id>")
+        .description("Stream Board events"))
+        .action((boardId, options) => {
+        try {
+            const board = createRealtimeClient().space(resolveSpace(boards)).board(boardId);
+            if (!jsonRequested(options))
+                process.stderr.write(`Listening for Board ${boardId} events...\n`);
+            board.subscribe({
+                event(event) {
+                    if (jsonRequested(options)) {
+                        process.stdout.write(`${JSON.stringify(event)}\n`);
+                        return;
+                    }
+                    if (event.type === "board.transaction.applied") {
+                        process.stdout.write(`version ${event.payload.version}  transaction ${event.payload.txId}  operations ${event.payload.operations.length}\n`);
+                    }
+                    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`);
+                    }
+                },
+            });
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    return boards;
+}

package/dist/commands/spaces.js

@@ -381,16 +381,30 @@ export function registerSpaces(program) {
         .command("ls")
         .alias("list")
         .description("List all spaces")
+        .option("--mine", "Only spaces you own")
+        .option("--pinned", "Only pinned spaces")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
         const client = createClient();
         try {
-            const items = await client.spaces.list();
+            const [items, me] = await Promise.all([
+                client.spaces.list(),
+                opts.mine ? client.user.getMe() : Promise.resolve(null),
+            ]);
+            const myUuid = me?.uuid ?? null;
+            const filtered = items.filter((item) => {
+                if (opts.mine && myUuid && item.userUuid !== myUuid)
+                    return false;
+                if (opts.pinned && !item.isPinned)
+                    return false;
+                return true;
+            });
             if (jsonRequested(opts))
-                return outJson(items);
-            table(items, [
+                return outJson(filtered);
+            table(filtered, [
                 { key: "id", label: "ID" },
                 { key: "name", label: "Name" },
+                { key: "isPinned", label: "Pinned" },
                 { key: "createdAt", label: "Created" },
             ]);
         }
@@ -605,6 +619,33 @@ export function registerSpaces(program) {
     registerMods(spacesCmd);
     // ── spaces labels ──
     registerLabels(spacesCmd);
+    // ── spaces pin / unpin (user-scope label convenience) ──
+    spacesCmd
+        .command("pin <id>")
+        .description("Pin a space (add the Pinned user label)")
+        .action(async (id) => {
+        const client = createClient();
+        try {
+            await client.user.labels.patchResourceLabels("space", id.trim(), { addLabelRefs: ["Pinned"] });
+            ok("Space pinned");
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    spacesCmd
+        .command("unpin <id>")
+        .description("Unpin a space (remove the Pinned user label)")
+        .action(async (id) => {
+        const client = createClient();
+        try {
+            await client.user.labels.patchResourceLabels("space", id.trim(), { removeLabelRefs: ["Pinned"] });
+            ok("Space unpinned");
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
     // ── spaces commerce ──
     registerSpaceCommerce(spacesCmd);
     // ── spaces usage ──

package/dist/index.js

@@ -2,6 +2,7 @@
 import { Command } from "commander";
 import { readFileSync } from "node:fs";
 import { registerAuth } from "./commands/auth.js";
+import { registerBoards } from "./commands/boards.js";
 import { registerChannels } from "./commands/channels.js";
 import { registerCronJobs } from "./commands/cron-jobs.js";
 import { registerGenerations } from "./commands/generations.js";
@@ -48,6 +49,7 @@ Common commands:
   cohub -s <space-id> run -- git status
   cohub sandbox up ./my-project
   cohub search "release notes"
+  cohub -s <space-id> boards inspect <board-id>
   cohub -s <space-id> spaces sessions turns ls <session-id>
   cohub -s <space-id> spaces files ls
   cohub -s <space-id> works publish demo --file dist/index.html
@@ -61,6 +63,7 @@ Environment:
   ENV=dev                Use the development Cohub environment
 `);
 registerAuth(program);
+registerBoards(program);
 registerProfile(program);
 registerMe(program);
 registerPrompt(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "2.7.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": "2.15.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"