@neta-art/cohub-cli 3.11.0 → 3.12.0

package/dist/board-command-support.d.ts

@@ -0,0 +1,7 @@
+export declare const BOARD_TRANSACTION_INPUT_MAX_BYTES: number;
+export declare const BOARD_CREATE_INPUT_MAX_BYTES: number;
+export declare const BOARD_DOMAIN_INPUT_MAX_BYTES: number;
+export declare function parseBoardJsonObject(text: string, source?: string): Record<string, unknown>;
+export declare function readBoardJsonObject(source: string, maxBytes?: number): Promise<Record<string, unknown>>;
+export declare function resolveBoardId(spaceId: string, target: string): Promise<string>;
+export declare function writeBoardOutput(path: string, bytes: Uint8Array, force?: boolean): Promise<void>;

package/dist/board-command-support.js

@@ -0,0 +1,99 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, link, open, rename, unlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { isBoardPath, parseBoardManifest, } from "@neta-art/cohub/board";
+import { createClient } from "./client.js";
+export const BOARD_TRANSACTION_INPUT_MAX_BYTES = 16 * 1024 * 1024;
+export const BOARD_CREATE_INPUT_MAX_BYTES = 32 * 1024 * 1024;
+export const BOARD_DOMAIN_INPUT_MAX_BYTES = 1024 * 1024;
+export function parseBoardJsonObject(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 (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${source} must contain a JSON object`);
+    }
+    return value;
+}
+async function readStdinBounded(maxBytes) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.byteLength;
+        if (size > maxBytes)
+            throw new Error(`stdin exceeds the ${maxBytes} byte input limit`);
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function readBoardJsonObject(source, maxBytes = BOARD_DOMAIN_INPUT_MAX_BYTES) {
+    if (source === "-")
+        return parseBoardJsonObject(await readStdinBounded(maxBytes), "stdin");
+    const handle = await open(source, constants.O_RDONLY | constants.O_NONBLOCK);
+    try {
+        const info = await handle.stat();
+        if (!info.isFile())
+            throw new Error(`${source} must be a regular file`);
+        if (info.size > maxBytes)
+            throw new Error(`${source} exceeds the ${maxBytes} byte input limit`);
+        const chunks = [];
+        const buffer = Buffer.allocUnsafe(Math.max(1, Math.min(64 * 1024, maxBytes + 1)));
+        let size = 0;
+        for (;;) {
+            const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, null);
+            if (bytesRead === 0)
+                break;
+            size += bytesRead;
+            if (size > maxBytes)
+                throw new Error(`${source} exceeds the ${maxBytes} byte input limit`);
+            chunks.push(Buffer.from(buffer.subarray(0, bytesRead)));
+        }
+        return parseBoardJsonObject(Buffer.concat(chunks).toString("utf8"), source);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function resolveBoardId(spaceId, target) {
+    if (!isBoardPath(target))
+        return target;
+    const file = await createClient().space(spaceId).files.read(target);
+    if (!("content" in file) || typeof file.content !== "string") {
+        throw new Error(`${target} is not a readable Board manifest`);
+    }
+    return parseBoardManifest(file.content).boardId;
+}
+export async function writeBoardOutput(path, bytes, force = false) {
+    if (!force) {
+        await access(path).then(() => { throw new Error(`Output already exists: ${path}; use --force to replace it`); }, () => undefined);
+    }
+    const temp = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    try {
+        const handle = await open(temp, "wx");
+        try {
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        if (force)
+            await rename(temp, path);
+        else {
+            await link(temp, path);
+            await unlink(temp);
+        }
+    }
+    catch (cause) {
+        await unlink(temp).catch(() => undefined);
+        throw cause;
+    }
+}

package/dist/board-export.js

@@ -9,9 +9,11 @@
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
-import { boardBootstrapToDocument, boardImageKeySource, imageAssetKey, isBoardPath, parseBoardManifest, planBoardExport, selectBoardExportAssets, } from "@neta-art/cohub/board";
+import { boardBootstrapToDocument, boardImageKeySource, imageAssetKey, planBoardExport, selectBoardExportAssets, } from "@neta-art/cohub/board";
 import { createBoardHeadlessRenderer, exportBoardImageBytes, } from "@neta-art/cohub/board/headless";
+import { resolveBoardId } from "./board-command-support.js";
 import { createClient } from "./client.js";
+import { downloadPublicImage } from "./safe-remote-image.js";
 export const BOARD_EXPORT_FORMATS = ["png", "jpeg", "webp"];
 /** Infer the output format from the file extension, defaulting to PNG. */
 export function formatFromPath(path) {
@@ -61,9 +63,7 @@ export function resolveBundledFonts() {
  */
 export async function loadBoardDocument(spaceId, target) {
     const client = createClient();
-    const boardId = isBoardPath(target)
-        ? await resolveManifestBoardId(spaceId, target)
-        : target;
+    const boardId = await resolveBoardId(spaceId, target);
     const bootstrap = await client.space(spaceId).board(boardId).inspect({ include: ["nodes"] });
     return {
         document: boardBootstrapToDocument(bootstrap),
@@ -71,13 +71,6 @@ export async function loadBoardDocument(spaceId, target) {
         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.
  *
@@ -92,7 +85,7 @@ export async function loadBoardTextures(headless, spaceId, items, options = {})
     const textures = new Map();
     const failed = [];
     const pending = [...selection.keys];
-    const concurrency = Math.max(1, Math.min(options.concurrency ?? 6, 16));
+    const concurrency = Math.max(1, Math.min(options.concurrency ?? 4, 16));
     const client = createClient();
     async function worker() {
         for (;;) {
@@ -107,7 +100,7 @@ export async function loadBoardTextures(headless, spaceId, items, options = {})
             try {
                 const { bytes, mimeType } = source.kind === "file"
                     ? await readSpaceFileBytes(client, spaceId, source.value)
-                    : await readUrlBytes(source.value);
+                    : await downloadPublicImage(source.value);
                 const texture = await headless.decodeImage(bytes, mimeType);
                 textures.set(key, texture);
             }
@@ -123,15 +116,6 @@ 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);
@@ -149,6 +133,7 @@ export async function runBoardExport(options) {
     try {
         const warnings = [];
         let textures;
+        let backgroundTexture;
         let omittedKeys = new Set();
         if (options.withImages) {
             const loaded = await loadBoardTextures(headless, options.spaceId, plan.items);
@@ -161,6 +146,19 @@ export async function runBoardExport(options) {
                 warnings.push(`${loaded.omitted.length} previews were drawn as placeholders to stay within the export texture limit.`);
             }
         }
+        const declaredBackground = document.appearance.background;
+        if (options.withImages &&
+            options.background === "paper" &&
+            declaredBackground.kind === "image" &&
+            declaredBackground.imageUrl) {
+            try {
+                const { bytes, mimeType } = await downloadPublicImage(declaredBackground.imageUrl);
+                backgroundTexture = await headless.decodeImage(bytes, mimeType);
+            }
+            catch {
+                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 (videoCount > 0) {
             warnings.push(`${videoCount} video preview${videoCount === 1 ? " was" : "s were"} drawn as placeholders; headless video decoding is unavailable.`);
@@ -172,6 +170,14 @@ export async function runBoardExport(options) {
             colorScheme: options.colorScheme,
             background: options.background,
             textures,
+            backgroundImage: backgroundTexture
+                ? {
+                    texture: backgroundTexture,
+                    fit: declaredBackground.fit ?? "cover",
+                    position: declaredBackground.position ?? "center",
+                    opacity: declaredBackground.opacity ?? 1,
+                }
+                : undefined,
             ...(options.withImages
                 ? {
                     assetKey: (item) => {

package/dist/commands/board-domain.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerBoardDomainCommands(boards: Command): void;

package/dist/commands/board-domain.js

@@ -0,0 +1,8 @@
+import { registerBoardAnimationCommands } from "./boards/animation.js";
+import { registerBoardAppearanceCommands } from "./boards/appearance.js";
+import { registerBoardNodeCommands } from "./boards/nodes.js";
+export function registerBoardDomainCommands(boards) {
+    registerBoardAppearanceCommands(boards);
+    registerBoardNodeCommands(boards);
+    registerBoardAnimationCommands(boards);
+}

package/dist/commands/boards/animation.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerBoardAnimationCommands(boards: Command): void;

package/dist/commands/boards/animation.js

@@ -0,0 +1,227 @@
+import { randomUUID } from "node:crypto";
+import { BoardCameraFocusParamsSchema, boardEffectDeleteOperation, boardEffectUpsertOperation, boardSequenceDeleteOperation, boardSequenceUpsertOperation, } from "@neta-art/cohub/board";
+import { BOARD_DOMAIN_INPUT_MAX_BYTES, readBoardJsonObject, } from "../../board-command-support.js";
+import { handleHttp, json, jsonRequested, table } from "../../output.js";
+import { finite, resolvedBoard, showUpdated, withJson, } from "./context.js";
+function rect(value) {
+    const parts = value.split(",").map(Number);
+    if (parts.length !== 4 || parts.some((part) => !Number.isFinite(part))) {
+        throw new Error("--rect must be x,y,width,height");
+    }
+    const [x, y, width, height] = parts;
+    if (width <= 0 || height <= 0)
+        throw new Error("--rect width and height must be positive");
+    return { x, y, width, height };
+}
+export function registerBoardAnimationCommands(boards) {
+    const effects = boards.command("effects").description("Manage Board effects");
+    withJson(effects.command("list <board>").alias("ls").description("List effects"))
+        .action(async (target, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            const result = await board.inspect({ include: ["effects"] });
+            if (jsonRequested(options))
+                return json(result.effects);
+            table(result.effects, [
+                { key: "id", label: "ID" },
+                { key: "kind", label: "KIND" },
+                { key: "enabled", label: "ENABLED" },
+                { key: "layer", label: "LAYER" },
+            ]);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(effects.command("upsert <board>")
+        .description("Create or replace an effect")
+        .requiredOption("-i, --input <file>", "Board effect JSON; use - for stdin")
+        .addHelpText("after", `
+Minimal pulse effect:
+  {"id":"pulse-title","target":{"type":"node","nodeId":"title"},"kind":"effects.pulse","kindVersion":1,"lifecycle":"when-visible","timeOrigin":"visible","seed":"pulse-title"}
+
+Run boards capabilities <board> to discover supported effect kinds.`))
+        .action(async (target, options) => {
+        try {
+            const effect = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({ build: () => [boardEffectUpsertOperation(effect)] }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(effects.command("delete <board> <effect-id>").alias("rm").description("Delete an effect"))
+        .action(async (target, effectId, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({ build: () => [boardEffectDeleteOperation(effectId)] }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    const sequences = boards.command("sequences").description("Manage Board sequences");
+    withJson(sequences.command("list <board>").alias("ls").description("List sequences"))
+        .action(async (target, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            const result = await board.inspect({ include: ["sequences"] });
+            if (jsonRequested(options))
+                return json(result.sequences);
+            table(result.sequences, [
+                { key: "id", label: "ID" },
+                { key: "name", label: "NAME" },
+                { key: "duration", label: "DURATION" },
+                { key: "revision", label: "REVISION" },
+            ]);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(sequences.command("get <board> <sequence-id>").description("Get a sequence and its clips"))
+        .action(async (target, sequenceId, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            const result = await board.inspect({ include: ["sequences", "clips"] });
+            const sequence = result.sequences.find((item) => item.id === sequenceId);
+            if (!sequence)
+                throw new Error(`Sequence not found: ${sequenceId}`);
+            const output = {
+                sequence,
+                clips: result.clips.filter((clip) => clip.sequenceId === sequenceId),
+            };
+            if (jsonRequested(options))
+                return json(output);
+            table([sequence], [
+                { key: "id", label: "ID" },
+                { key: "name", label: "NAME" },
+                { key: "duration", label: "DURATION" },
+                { key: "revision", label: "REVISION" },
+            ]);
+            table(output.clips, [
+                { key: "id", label: "CLIP" },
+                { key: "kind", label: "KIND" },
+                { key: "start", label: "START" },
+                { key: "duration", label: "DURATION" },
+            ]);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(sequences.command("upsert <board>")
+        .description("Create or replace a sequence and clips")
+        .requiredOption("-i, --input <file>", "{ sequence, clips } JSON; use - for stdin")
+        .addHelpText("after", `
+Minimal sequence with one clip:
+  {"sequence":{"id":"intro","name":"Intro","duration":1200,"seed":"intro"},"clips":[{"id":"reveal-title","kind":"text.reveal","kindVersion":1,"target":{"type":"node","nodeId":"title"},"start":0,"duration":600,"seed":"reveal-title"}]}
+
+Coordinate rules:
+  node motion x/y and path points are Board-world offsets; camera.pan x/y are screen-pixel offsets.
+
+Edit an existing sequence:
+  cohub boards sequences get <board> intro --json > intro.json
+  cohub boards sequences upsert <board> -i intro.json`))
+        .action(async (target, options) => {
+        try {
+            const input = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({ build: () => [boardSequenceUpsertOperation(input)] }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(sequences.command("camera-focus <board> <sequence-id>")
+        .description("Add or replace a semantic camera focus clip")
+        .option("--id <id>", "Stable clip id")
+        .option("--node <id>", "Focus one node")
+        .option("--nodes <ids>", "Focus comma-separated nodes")
+        .option("--frame <id>", "Focus a frame")
+        .option("--rect <rect>", "Board world rect as x,y,width,height")
+        .requiredOption("--at <ms>", "Clip start time")
+        .option("--duration <ms>", "Transition duration", "700")
+        .option("--padding <px>", "Screen padding in CSS pixels", "32")
+        .option("--fit <mode>", "contain or cover", "contain")
+        .option("--min-zoom <zoom>", "Minimum zoom multiplier")
+        .option("--max-zoom <zoom>", "Maximum zoom multiplier")
+        .option("--easing <name>", "Easing", "ease-out-cubic")
+        .addHelpText("after", `
+Examples:
+  cohub boards sequences camera-focus plan.board intro --node hero --at 1200
+  cohub boards sequences camera-focus plan.board intro --rect 120,80,640,360 --at 2000 --duration 800`))
+        .action(async (target, sequenceId, options) => {
+        try {
+            const selected = [options.node, options.nodes, options.frame, options.rect].filter(Boolean);
+            if (selected.length !== 1)
+                throw new Error("Choose one of --node, --nodes, --frame, or --rect");
+            const focus = options.node
+                ? { type: "node", nodeId: options.node }
+                : options.nodes
+                    ? { type: "nodes", nodeIds: options.nodes.split(",").map((id) => id.trim()).filter(Boolean) }
+                    : options.frame
+                        ? { type: "frame", frameId: options.frame }
+                        : { type: "rect", rect: rect(options.rect) };
+            const params = BoardCameraFocusParamsSchema.parse({
+                focus,
+                fit: options.fit,
+                padding: finite(options.padding, "padding"),
+                ...(options.minZoom === undefined ? {} : { minZoom: finite(options.minZoom, "min zoom") }),
+                ...(options.maxZoom === undefined ? {} : { maxZoom: finite(options.maxZoom, "max zoom") }),
+            });
+            const start = finite(options.at, "start");
+            const duration = finite(options.duration, "duration");
+            if (start < 0 || duration <= 0)
+                throw new Error("start must be non-negative and duration must be positive");
+            const clipId = options.id ?? randomUUID();
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({
+                include: ["sequences", "clips"],
+                build(current) {
+                    const currentSequence = current.sequences.find((sequence) => sequence.id === sequenceId);
+                    if (!currentSequence)
+                        throw new Error(`Sequence not found: ${sequenceId}`);
+                    const { boardId: _boardId, revision: _revision, ...sequence } = currentSequence;
+                    const clips = current.clips
+                        .filter((clip) => clip.sequenceId === sequenceId && clip.id !== clipId)
+                        .map(({ sequenceId: _sequenceId, ...clip }) => clip);
+                    clips.push({
+                        id: clipId,
+                        kind: "camera.focus",
+                        kindVersion: 1,
+                        target: { type: "camera" },
+                        start,
+                        duration,
+                        layer: "screen",
+                        fill: "forwards",
+                        easing: options.easing,
+                        params,
+                        keyframes: [],
+                        assetRefs: [],
+                        seed: clipId,
+                        metadata: {},
+                    });
+                    return [boardSequenceUpsertOperation({
+                            sequence: { ...sequence, duration: Math.max(sequence.duration, start + duration) },
+                            clips,
+                        })];
+                },
+            }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(sequences.command("delete <board> <sequence-id>").alias("rm").description("Delete a sequence and its clips"))
+        .action(async (target, sequenceId, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({ build: () => [boardSequenceDeleteOperation(sequenceId)] }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+}

package/dist/commands/boards/appearance.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerBoardAppearanceCommands(boards: Command): void;

package/dist/commands/boards/appearance.js

@@ -0,0 +1,93 @@
+import { BoardAppearanceSchema, DEFAULT_BOARD_APPEARANCE, boardAppearanceOperation, boardPlaybackPolicyOperation, boardTitleOperation, patchBoardAppearance, } from "@neta-art/cohub/board";
+import { handleHttp } from "../../output.js";
+import { finite, resolvedBoard, showUpdated, withJson, } from "./context.js";
+function appearanceFrom(metadata) {
+    const parsed = BoardAppearanceSchema.safeParse(metadata.appearance);
+    return parsed.success ? parsed.data : DEFAULT_BOARD_APPEARANCE;
+}
+export function registerBoardAppearanceCommands(boards) {
+    withJson(boards.command("rename <board> <title>").description("Rename a Board"))
+        .action(async (target, title, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({ build: () => [boardTitleOperation(title)] }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(boards.command("background <board>")
+        .description("Configure the Board background")
+        .option("--color <color>", "Solid CSS color")
+        .option("--image <url>", "Public image URL")
+        .option("--fit <mode>", "cover, contain, or repeat", "cover")
+        .option("--position <position>", "center, top, bottom, left, or right", "center")
+        .option("--opacity <value>", "Image opacity from 0 to 1", "1")
+        .option("--reset", "Restore the default background")
+        .addHelpText("after", `
+Examples:
+  cohub boards background plan.board --color "#123456"
+  cohub boards background plan.board --image https://example.com/bg.webp --fit cover --opacity 0.8`))
+        .action(async (target, options) => {
+        try {
+            const selected = [options.color, options.image, options.reset ? "reset" : undefined].filter(Boolean);
+            if (selected.length !== 1)
+                throw new Error("Choose one of --color, --image, or --reset");
+            if (!["cover", "contain", "repeat"].includes(options.fit))
+                throw new Error("--fit must be cover, contain, or repeat");
+            if (!["center", "top", "bottom", "left", "right"].includes(options.position))
+                throw new Error("--position must be center, top, bottom, left, or right");
+            const opacity = finite(options.opacity, "opacity");
+            if (opacity < 0 || opacity > 1)
+                throw new Error("opacity must be between 0 and 1");
+            const board = await resolvedBoard(boards, target);
+            const result = await board.mutate({
+                build(current) {
+                    const appearance = appearanceFrom(current.board.metadata);
+                    const background = options.reset
+                        ? { kind: "solid" }
+                        : options.color
+                            ? { kind: "solid", color: options.color }
+                            : {
+                                kind: "image",
+                                imageUrl: options.image,
+                                fit: options.fit,
+                                position: options.position,
+                                opacity,
+                                color: appearance.background.color,
+                            };
+                    return [boardAppearanceOperation(patchBoardAppearance(appearance, { background }))];
+                },
+            });
+            showUpdated(result, options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(boards.command("playback-policy <board>")
+        .description("Configure automatic Board playback")
+        .option("--sequence <id>", "Sequence to play")
+        .option("--delay <ms>", "Delay before playback", "0")
+        .option("--loop", "Loop the sequence")
+        .option("--clear", "Remove the playback policy"))
+        .action(async (target, options) => {
+        try {
+            if (options.clear === Boolean(options.sequence))
+                throw new Error("Use --sequence or --clear");
+            const delayMs = finite(options.delay, "delay");
+            if (delayMs < 0)
+                throw new Error("delay must be non-negative");
+            const policy = options.clear
+                ? null
+                : { sequenceId: options.sequence, delayMs, loop: Boolean(options.loop) };
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({
+                build: (current) => [boardPlaybackPolicyOperation(current.board.metadata, policy)],
+            }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+}

package/dist/commands/boards/context.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from "commander";
+export type JsonOptions = {
+    json?: boolean;
+};
+export declare function withJson(command: Command): Command;
+export declare function finite(value: string | undefined, name: string, fallback?: number): number;
+export declare function resolvedBoard(boards: Command, target: string): Promise<import("@neta-art/cohub").BoardClient>;
+export declare function showUpdated(result: {
+    board: {
+        version: number;
+    };
+}, options: JsonOptions): void;

package/dist/commands/boards/context.js

@@ -0,0 +1,25 @@
+import { createClient } from "../../client.js";
+import { resolveBoardId } from "../../board-command-support.js";
+import { json, jsonRequested, ok } from "../../output.js";
+import { resolveSpace } from "../../space.js";
+export function withJson(command) {
+    return command.option("--json", "Output as JSON");
+}
+export function finite(value, name, fallback) {
+    if (value === undefined && fallback !== undefined)
+        return fallback;
+    const result = Number(value);
+    if (!Number.isFinite(result))
+        throw new Error(`${name} must be a finite number`);
+    return result;
+}
+export async function resolvedBoard(boards, target) {
+    const spaceId = resolveSpace(boards);
+    const boardId = await resolveBoardId(spaceId, target);
+    return createClient().space(spaceId).board(boardId);
+}
+export function showUpdated(result, options) {
+    if (jsonRequested(options))
+        return json(result);
+    ok(`Board updated to version ${result.board.version}`);
+}

package/dist/commands/boards/nodes.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerBoardNodeCommands(boards: Command): void;

package/dist/commands/boards/nodes.js

@@ -0,0 +1,110 @@
+import { randomUUID } from "node:crypto";
+import { boardNodeCreateOperation, boardNodeDeleteOperations, boardNodePatchOperation, createBoardConnection, createBoardNode, } from "@neta-art/cohub/board";
+import { BOARD_DOMAIN_INPUT_MAX_BYTES, readBoardJsonObject, } from "../../board-command-support.js";
+import { handleHttp } from "../../output.js";
+import { resolvedBoard, showUpdated, withJson, } from "./context.js";
+export function registerBoardNodeCommands(boards) {
+    const nodes = boards.command("nodes").description("Create and update Board nodes");
+    withJson(nodes.command("add <board>")
+        .description("Add a node")
+        .requiredOption("-i, --input <file>", "BoardNodeSpec JSON; use - for stdin")
+        .addHelpText("after", `
+Frame x/y/width/height use Board world units. Draw points and arrow endpoints are also world input.
+Minimal text node:
+  {"id":"title","type":"text","frame":{"x":120,"y":80,"width":320,"height":48},"text":"Launch plan"}`))
+        .action(async (target, options) => {
+        try {
+            const input = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            const node = createBoardNode(input);
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({ build: () => [boardNodeCreateOperation(node)] }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(nodes.command("patch <board> <node-id>")
+        .description("Patch a node")
+        .requiredOption("-i, --input <file>", "BoardNodeInput field patch; use - for stdin")
+        .addHelpText("after", `
+x/y are absolute Board world coordinates.
+Move a node without changing its content:
+  {"x":160,"y":120}
+
+Nested view, style, and data fields replace their complete stored object.`))
+        .action(async (target, nodeId, options) => {
+        try {
+            const patch = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            if ("nodeId" in patch)
+                throw new Error("node patch must not contain nodeId");
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({
+                build: () => [boardNodePatchOperation(nodeId, patch)],
+            }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(nodes.command("remove <board> <node-id>")
+        .alias("rm")
+        .description("Remove a node and its connections"))
+        .action(async (target, nodeId, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({
+                include: ["connections"],
+                build: (current) => boardNodeDeleteOperations(nodeId, current.connections),
+            }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(boards.command("connect <board> <source> <target>")
+        .description("Connect two Board nodes")
+        .option("--id <id>", "Connection id")
+        .option("--relation <relation>", "Relation type")
+        .option("--direction <direction>", "none, forward, backward, or both", "forward")
+        .option("--label <label>", "Connection label")
+        .option("--source-port <id>", "Source port id")
+        .option("--target-port <id>", "Target port id"))
+        .action(async (target, source, destination, options) => {
+        try {
+            const direction = options.direction ?? "forward";
+            if (!["none", "forward", "backward", "both"].includes(direction)) {
+                throw new Error("--direction must be none, forward, backward, or both");
+            }
+            const board = await resolvedBoard(boards, target);
+            const connection = createBoardConnection({
+                id: options.id ?? randomUUID(),
+                sourceNodeId: source,
+                targetNodeId: destination,
+                relation: options.relation,
+                direction: direction,
+                label: options.label,
+                sourcePortId: options.sourcePort,
+                targetPortId: options.targetPort,
+            });
+            showUpdated(await board.mutate({
+                build: () => [{ type: "connection.create", payload: { connection } }],
+            }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(boards.command("disconnect <board> <connection-id>")
+        .description("Remove a Board connection"))
+        .action(async (target, connectionId, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({
+                build: () => [{ type: "connection.delete", payload: { connectionId } }],
+            }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+}

package/dist/commands/boards.d.ts

@@ -1,9 +1,10 @@
 import type { BoardInspectInput, BoardTransactionInput } from "@neta-art/cohub";
 import type { Command } from "commander";
+import { parseBoardJsonObject } from "../board-command-support.js";
 declare const INSPECT_SECTIONS: readonly ["nodes", "connections", "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 const parseJsonObject: typeof parseBoardJsonObject;
+export declare function readJsonObject(source: string, maxBytes?: number): 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: {

package/dist/commands/boards.js

@@ -1,36 +1,14 @@
 import { randomUUID } from "node:crypto";
-import { readFile, writeFile } from "node:fs/promises";
+import { BOARD_CREATE_INPUT_MAX_BYTES, BOARD_TRANSACTION_INPUT_MAX_BYTES, parseBoardJsonObject, readBoardJsonObject, resolveBoardId, writeBoardOutput, } from "../board-command-support.js";
 import { BOARD_EXPORT_FORMATS, formatFromPath, runBoardExport } from "../board-export.js";
+import { registerBoardDomainCommands } from "./board-domain.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", "connections", "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);
+export const parseJsonObject = parseBoardJsonObject;
+export async function readJsonObject(source, maxBytes = BOARD_TRANSACTION_INPUT_MAX_BYTES) {
+    return readBoardJsonObject(source, maxBytes);
 }
 function parseNumber(value, name, options = {}) {
     if (!value.trim())
@@ -116,6 +94,27 @@ function showBoard(result) {
         { key: "clips", label: "Clips" },
     ]);
 }
+function showSummary(result) {
+    const background = result.board.metadata.appearance;
+    table([{
+            id: result.board.id,
+            title: result.board.title,
+            version: result.board.version,
+            ...result.counts,
+            background: background?.background?.kind ?? "default",
+            updatedAt: result.board.updatedAt,
+        }], [
+        { key: "id", label: "ID" },
+        { key: "title", label: "TITLE" },
+        { key: "version", label: "VERSION" },
+        { key: "nodes", label: "NODES" },
+        { key: "connections", label: "CONNECTIONS" },
+        { key: "effects", label: "EFFECTS" },
+        { key: "sequences", label: "SEQUENCES" },
+        { key: "background", label: "BACKGROUND" },
+        { key: "updatedAt", label: "UPDATED" },
+    ]);
+}
 function showValidation(result) {
     table([{ valid: result.valid, diagnostics: result.diagnostics.length }], [
         { key: "valid", label: "Valid" },
@@ -145,16 +144,37 @@ function showPlayback(result) {
 function withJson(command) {
     return command.option("--json", "Output as JSON");
 }
+function capabilityUnits(schema) {
+    const params = schema?.params;
+    if (!params || typeof params !== "object" || Array.isArray(params))
+        return "";
+    return Object.entries(params).flatMap(([field, value]) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return [];
+        const meta = value;
+        const detail = [meta.coordinateSpace, meta.unit]
+            .filter((item) => typeof item === "string")
+            .join("/");
+        return detail ? [`${field}:${detail}`] : [];
+    }).join(", ");
+}
 function registerTransactionCommand(boards, name) {
-    withJson(boards.command(`${name} <board-id>`)
+    withJson(boards.command(`${name} <board>`)
         .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) => {
+        .option("--base-version <version>", "Override baseVersion")
+        .addHelpText("after", `
+Input example:
+  {"baseVersion":12,"operations":[{"type":"board.patch","payload":{"patch":{"title":"Launch plan"}}}]}
+
+Prefer semantic commands such as boards background, nodes, effects, or sequences for common edits.`))
+        .action(async (target, options) => {
         try {
-            const transaction = createTransactionInput(await readJsonObject(options.input), options);
-            const board = createClient().space(resolveSpace(boards)).board(boardId);
+            const transaction = createTransactionInput(await readJsonObject(options.input, BOARD_TRANSACTION_INPUT_MAX_BYTES), options);
+            const spaceId = resolveSpace(boards);
+            const boardId = await resolveBoardId(spaceId, target);
+            const board = createClient().space(spaceId).board(boardId);
             const result = await board[name](transaction);
             if (jsonRequested(options))
                 return outJson(result);
@@ -240,7 +260,8 @@ function registerExportCommand(boards) {
         .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"))
+        .option("--no-images", "Skip image downloads and draw placeholders")
+        .option("--force", "Replace an existing output file"))
         .action(async (board, options) => {
         try {
             const out = options.out;
@@ -263,7 +284,7 @@ function registerExportCommand(boards) {
             if (!result) {
                 return error("Nothing to export", "The selected region contains no items.");
             }
-            await writeFile(out, result.bytes);
+            await writeBoardOutput(out, result.bytes, Boolean(options.force));
             if (jsonRequested(options)) {
                 return outJson({
                     path: out,
@@ -293,14 +314,26 @@ export function registerBoards(program) {
     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"))
+        .option("--mutation-id <id>", "Stable id for safe retries")
+        .option("-i, --input <file>", "BoardCreateInput fields; use - for stdin")
+        .addHelpText("after", `
+For normal use, create an empty Board and add content with boards nodes, effects, and sequences.
+--input is intended for bulk creation and accepts BoardCreateInput fields except path and title.`))
         .action(async (path, options) => {
         try {
-            const content = options.input ? await readJsonObject(options.input) : {};
+            const content = options.input
+                ? await readJsonObject(options.input, BOARD_CREATE_INPUT_MAX_BYTES)
+                : {};
             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 input = {
+                ...content,
+                path,
+                mutationId: options.mutationId ??
+                    (typeof content.mutationId === "string" ? content.mutationId : randomUUID()),
+                ...(options.title ? { title: options.title } : {}),
+            };
             const result = await createClient().space(resolveSpace(boards)).boards.create(input);
             if (jsonRequested(options))
                 return outJson(result);
@@ -311,14 +344,20 @@ export function registerBoards(program) {
             handleHttp(cause);
         }
     });
-    withJson(boards.command("inspect <board-id>")
+    withJson(boards.command("inspect <board>")
         .alias("get")
         .description("Inspect a Board")
         .option("--include <sections>", "Comma-separated nodes,connections,effects,sequences,clips,playback")
         .option("--viewport <rect>", "Viewport as x,y,width,height"))
-        .action(async (boardId, options) => {
+        .action(async (target, options) => {
         try {
-            const result = await createClient().space(resolveSpace(boards)).board(boardId).inspect({
+            const spaceId = resolveSpace(boards);
+            const boardId = await resolveBoardId(spaceId, target);
+            const board = createClient().space(spaceId).board(boardId);
+            if (!jsonRequested(options) && !options.include && !options.viewport) {
+                return showSummary(await board.summary());
+            }
+            const result = await board.inspect({
                 include: parseInspectSections(options.include),
                 viewport: parseViewport(options.viewport),
             });
@@ -330,21 +369,25 @@ export function registerBoards(program) {
             handleHttp(cause);
         }
     });
-    withJson(boards.command("capabilities <board-id>")
+    withJson(boards.command("capabilities <board>")
         .description("Show supported capabilities"))
-        .action(async (boardId, options) => {
+        .action(async (target, options) => {
         try {
-            const result = await createClient().space(resolveSpace(boards)).board(boardId).capabilities();
+            const spaceId = resolveSpace(boards);
+            const boardId = await resolveBoardId(spaceId, target);
+            const result = await createClient().space(spaceId).board(boardId).capabilities();
             if (jsonRequested(options))
                 return outJson(result);
             table(result.capabilities.map((capability) => ({
                 ...capability,
                 renderers: capability.renderers?.join(", ") ?? "",
+                coordinates: capabilityUnits(capability.schema),
             })), [
                 { key: "kind", label: "Kind" },
                 { key: "id", label: "ID" },
                 { key: "version", label: "Version" },
                 { key: "renderers", label: "Renderers" },
+                { key: "coordinates", label: "Coordinates / units" },
                 { key: "digest", label: "Digest" },
             ]);
             const nodes = result.nodes;
@@ -371,16 +414,19 @@ export function registerBoards(program) {
     });
     registerTransactionCommand(boards, "validate");
     registerTransactionCommand(boards, "apply");
+    registerBoardDomainCommands(boards);
     registerExportCommand(boards);
-    withJson(boards.command("play <board-id> <sequence-id>")
+    withJson(boards.command("play <board> <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) => {
+        .action(async (target, sequenceId, options) => {
         try {
-            const result = await createClient().space(resolveSpace(boards)).board(boardId).play({
+            const spaceId = resolveSpace(boards);
+            const boardId = await resolveBoardId(spaceId, target);
+            const result = await createClient().space(spaceId).board(boardId).play({
                 commandId: commandId(options),
                 type: "play",
                 sequenceId,
@@ -397,9 +443,11 @@ export function registerBoards(program) {
             handleHttp(cause);
         }
     });
-    const playbackAction = (type) => async (boardId, playbackId, options) => {
+    const playbackAction = (type) => async (target, playbackId, options) => {
         try {
-            const board = createClient().space(resolveSpace(boards)).board(boardId);
+            const spaceId = resolveSpace(boards);
+            const boardId = await resolveBoardId(spaceId, target);
+            const board = createClient().space(spaceId).board(boardId);
             const id = commandId(options);
             const result = type === "pause"
                 ? await board.pause({ commandId: id, type: "pause", playbackId })
@@ -412,16 +460,18 @@ export function registerBoards(program) {
             handleHttp(cause);
         }
     };
-    withJson(boards.command("pause <board-id> <playback-id>")
+    withJson(boards.command("pause <board> <playback-id>")
         .description("Pause playback")
         .option("--command-id <id>", "Idempotency command ID"))
         .action(playbackAction("pause"));
-    withJson(boards.command("seek <board-id> <playback-id> <position>")
+    withJson(boards.command("seek <board> <playback-id> <position>")
         .description("Seek playback")
         .option("--command-id <id>", "Idempotency command ID"))
-        .action(async (boardId, playbackId, position, options) => {
+        .action(async (target, playbackId, position, options) => {
         try {
-            const result = await createClient().space(resolveSpace(boards)).board(boardId).seek({
+            const spaceId = resolveSpace(boards);
+            const boardId = await resolveBoardId(spaceId, target);
+            const result = await createClient().space(spaceId).board(boardId).seek({
                 commandId: commandId(options),
                 type: "seek",
                 playbackId,
@@ -435,18 +485,32 @@ export function registerBoards(program) {
             handleHttp(cause);
         }
     });
-    withJson(boards.command("stop <board-id> <playback-id>")
+    withJson(boards.command("stop <board> <playback-id>")
         .description("Stop playback")
         .option("--command-id <id>", "Idempotency command ID"))
         .action(playbackAction("stop"));
-    withJson(boards.command("watch <board-id>")
+    withJson(boards.command("watch <board>")
         .description("Stream Board events"))
-        .action((boardId, options) => {
+        .action(async (target, options) => {
         try {
-            const board = createRealtimeClient().space(resolveSpace(boards)).board(boardId);
+            const spaceId = resolveSpace(boards);
+            const boardId = await resolveBoardId(spaceId, target);
+            const client = createRealtimeClient();
+            const board = client.space(spaceId).board(boardId);
             if (!jsonRequested(options))
                 process.stderr.write(`Listening for Board ${boardId} events...\n`);
-            board.subscribe({
+            const offConnection = client.onConnection((state) => {
+                if (jsonRequested(options)) {
+                    process.stdout.write(`${JSON.stringify({ type: "connection", ...state })}\n`);
+                }
+                else {
+                    const detail = state.state === "reconnecting" && state.attempt
+                        ? ` (attempt ${state.attempt})`
+                        : "";
+                    process.stderr.write(`${state.state}${detail}\n`);
+                }
+            });
+            const offBoard = board.subscribe({
                 event(event) {
                     if (jsonRequested(options)) {
                         process.stdout.write(`${JSON.stringify(event)}\n`);
@@ -463,6 +527,11 @@ export function registerBoards(program) {
                     }
                 },
             });
+            process.once("SIGINT", () => {
+                offBoard();
+                offConnection();
+                process.exit(0);
+            });
         }
         catch (cause) {
             handleHttp(cause);

package/dist/safe-remote-image.d.ts

@@ -0,0 +1,24 @@
+export declare const REMOTE_IMAGE_MAX_BYTES: number;
+export declare const REMOTE_IMAGE_TIMEOUT_MS = 15000;
+type ResolvedAddress = {
+    address: string;
+    family: 4 | 6;
+};
+type Lookup = (hostname: string) => Promise<readonly ResolvedAddress[]>;
+type RemoteResponse = {
+    status: number;
+    headers: Headers;
+    bytes: Uint8Array;
+};
+type Requester = (url: URL, address: ResolvedAddress, timeoutMs: number, maxBytes: number) => Promise<RemoteResponse>;
+export type RemoteImageDownloadOptions = {
+    lookup?: Lookup;
+    requester?: Requester;
+    maxBytes?: number;
+    timeoutMs?: number;
+};
+export declare function downloadPublicImage(input: string, options?: RemoteImageDownloadOptions): Promise<{
+    bytes: Uint8Array;
+    mimeType: string;
+}>;
+export {};

package/dist/safe-remote-image.js

@@ -0,0 +1,160 @@
+import dns from "node:dns/promises";
+import http from "node:http";
+import https from "node:https";
+import { isIP } from "node:net";
+import { isPublicBoardRemoteAddress, normalizeBoardRemoteUrl, } from "@neta-art/cohub/board";
+export const REMOTE_IMAGE_MAX_BYTES = 16 * 1024 * 1024;
+export const REMOTE_IMAGE_TIMEOUT_MS = 15_000;
+const MAX_REDIRECTS = 3;
+const IMAGE_MIME_TYPES = new Set([
+    "image/avif",
+    "image/gif",
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+]);
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+async function defaultLookup(hostname) {
+    const records = await dns.lookup(hostname, { all: true, verbatim: true });
+    return records.map((record) => ({
+        address: record.address,
+        family: record.family,
+    }));
+}
+function responseHeaders(input) {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(input)) {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                headers.append(key, item);
+        }
+        else if (value !== undefined) {
+            headers.set(key, value);
+        }
+    }
+    return headers;
+}
+function requestPinned(url, address, timeoutMs, maxBytes) {
+    return new Promise((resolve, reject) => {
+        const client = url.protocol === "https:" ? https : http;
+        const request = client.request(url, {
+            agent: false,
+            headers: { Accept: "image/avif,image/webp,image/png,image/jpeg,image/gif" },
+            lookup: (_hostname, _options, callback) => {
+                callback(null, address.address, address.family);
+            },
+        }, (response) => {
+            const status = response.statusCode ?? 0;
+            const headers = responseHeaders(response.headers);
+            if (REDIRECT_STATUSES.has(status)) {
+                response.resume();
+                resolve({ status, headers, bytes: new Uint8Array() });
+                return;
+            }
+            const declaredLength = Number(headers.get("content-length") ?? 0);
+            if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+                response.destroy();
+                reject(new Error(`Image exceeds the ${maxBytes} byte download limit`));
+                return;
+            }
+            const chunks = [];
+            let total = 0;
+            response.on("data", (chunk) => {
+                total += chunk.byteLength;
+                if (total > maxBytes) {
+                    response.destroy(new Error(`Image exceeds the ${maxBytes} byte download limit`));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            response.once("error", reject);
+            response.once("end", () => {
+                const bytes = new Uint8Array(total);
+                let offset = 0;
+                for (const chunk of chunks) {
+                    bytes.set(chunk, offset);
+                    offset += chunk.byteLength;
+                }
+                resolve({ status, headers, bytes });
+            });
+        });
+        request.setTimeout(timeoutMs, () => {
+            request.destroy(new Error(`Image download timed out after ${timeoutMs}ms`));
+        });
+        request.once("error", reject);
+        request.end();
+    });
+}
+function remainingMs(deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw new Error("Image download timed out");
+    return remaining;
+}
+async function withDeadline(promise, deadline) {
+    const timeoutMs = remainingMs(deadline);
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Image download timed out after ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function resolvePublicUrl(value, lookup, deadline) {
+    const normalized = normalizeBoardRemoteUrl(value);
+    if (!normalized)
+        throw new Error("Image URL must be a public HTTP(S) URL");
+    const url = new URL(normalized);
+    const hostname = url.hostname.replace(/^\[|\]$/g, "");
+    const addresses = isIP(hostname)
+        ? [{ address: hostname, family: isIP(hostname) }]
+        : await withDeadline(lookup(hostname), deadline);
+    if (addresses.length === 0 ||
+        addresses.some((entry) => !isPublicBoardRemoteAddress(entry.address))) {
+        throw new Error("Image URL resolves to a private address");
+    }
+    return { url, address: addresses[0] };
+}
+export async function downloadPublicImage(input, options = {}) {
+    const lookup = options.lookup ?? defaultLookup;
+    const requester = options.requester ?? requestPinned;
+    const maxBytes = options.maxBytes ?? REMOTE_IMAGE_MAX_BYTES;
+    const deadline = Date.now() + (options.timeoutMs ?? REMOTE_IMAGE_TIMEOUT_MS);
+    let current = input;
+    for (let redirect = 0; redirect <= MAX_REDIRECTS; redirect += 1) {
+        const { url, address } = await resolvePublicUrl(current, lookup, deadline);
+        const response = await withDeadline(requester(url, address, remainingMs(deadline), maxBytes), deadline);
+        if (REDIRECT_STATUSES.has(response.status)) {
+            const location = response.headers.get("location");
+            if (!location)
+                throw new Error("Image redirect is missing a location");
+            if (redirect === MAX_REDIRECTS)
+                throw new Error("Too many image redirects");
+            current = new URL(location, url).toString();
+            continue;
+        }
+        if (response.status < 200 || response.status >= 300) {
+            throw new Error(`HTTP ${response.status}`);
+        }
+        if (response.bytes.byteLength > maxBytes) {
+            throw new Error(`Image exceeds the ${maxBytes} byte download limit`);
+        }
+        const mimeType = response.headers
+            .get("content-type")
+            ?.split(";", 1)[0]
+            ?.trim()
+            .toLowerCase();
+        if (!mimeType || !IMAGE_MIME_TYPES.has(mimeType)) {
+            throw new Error("Remote background must be a supported raster image");
+        }
+        return { bytes: response.bytes, mimeType };
+    }
+    throw new Error("Too many image redirects");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "license": "Apache-2.0",
@@ -19,7 +19,7 @@
     "commander": "^15.0.0",
     "pixi.js": "^8.19.0",
     "sharp": "^0.35.3",
-    "@neta-art/cohub": "5.9.0"
+    "@neta-art/cohub": "5.10.0"
   },
   "publishConfig": {
     "access": "public"