@neta-art/cohub-cli 3.10.2 → 3.12.0

package/README.md

@@ -329,17 +329,21 @@ through `client.work.realtime` in the SDK rather than as CLI commands.
 
 ## Drive the Cohub UI
 
-Show a Work preview in the Cohub tab that started the current work, and call
+Show a file or Work preview in the Cohub tab that started the current work, and call
 methods the Work exposes.
 
 ```bash
-cohub ui preview <workId|url|cohub://works/...|username/space/work>
-cohub ui preview <work> --call selection.get
+cohub ui preview <workId|url|cohub://works/...|username/space/work|file://path>
+cohub ui preview file://src/main.ts
+cohub ui preview work://alice/studio/launch
+cohub ui preview <work-or-file> --call selection.get
 cohub ui preview <work> --call board.focus --data '{"nodeId":"n1"}'
 cohub ui preview <work> --call report.build --input payload.json --json
 ```
 
-`ui preview` accepts the same Work references as `works get`. Showing a preview is
+`ui preview` accepts `file://` Space-relative paths, `work://` Work references, and
+legacy bare targets. A bare target checks the current Space for a file first, then
+falls back to the same Work references as `works get`. Showing a preview is
 idempotent: repeating it re-activates the same tab and refreshes any launch state
 carried by the reference. With `--call`, the command waits for the Work to announce readiness, invokes the method,
 and waits for the Work to complete the same UI command with `client.ui.reportResult()`.

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;