@neta-art/cohub-cli 3.10.2 → 3.12.0

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/commands/ui.js

@@ -1,8 +1,38 @@
 import { readFileSync } from "node:fs";
+import { HttpError, } from "@neta-art/cohub";
 import { parseWorkRef, UI_COMMAND_DEFAULT_TIMEOUT_MS, UI_COMMAND_MAX_TIMEOUT_MS, } from "@neta-art/cohub";
 import { createClient } from "../client.js";
 import { error, handleHttp, json as outJson, jsonRequested, ok } from "../output.js";
 import { getWorkByRef } from "../work-ref.js";
+const FILE_SCHEME = "file://";
+const WORK_SCHEME = "work://";
+function optionalSpaceId(command) {
+    let current = command;
+    while (current) {
+        const opts = current.opts();
+        if (typeof opts.space === "string" && opts.space.trim())
+            return opts.space.trim();
+        current = current.parent ?? null;
+    }
+    return process.env.COHUB_SPACE_ID?.trim() || undefined;
+}
+function parseFilePath(value) {
+    const path = value.slice(FILE_SCHEME.length).trim();
+    if (!path ||
+        path.startsWith("/") ||
+        path.includes("\0") ||
+        path.split("/").some((segment) => segment === "..") ||
+        path.includes("\\")) {
+        return error("Invalid file path", "Use a relative Space path after file://.");
+    }
+    return path;
+}
+function hasFileScheme(value) {
+    return value.toLowerCase().startsWith(FILE_SCHEME);
+}
+function hasWorkScheme(value) {
+    return value.toLowerCase().startsWith(WORK_SCHEME);
+}
 function readCallInput(opts) {
     if (opts.data !== undefined && opts.input !== undefined) {
         return error("Conflicting input", "Use either --data or --input, not both.");
@@ -33,9 +63,11 @@ function parseTimeout(value) {
     return parsed;
 }
 async function resolveWorkTarget(client, ref) {
-    const parsed = parseWorkRef(ref);
-    const detail = await getWorkByRef(client, ref);
+    const normalized = hasWorkScheme(ref) ? ref.slice(WORK_SCHEME.length) : ref;
+    const parsed = parseWorkRef(normalized);
+    const detail = await getWorkByRef(client, normalized);
     return {
+        kind: "work",
         workId: detail.work.id,
         label: detail.work.slug,
         launch: {
@@ -44,6 +76,24 @@ async function resolveWorkTarget(client, ref) {
         },
     };
 }
+async function resolvePreviewTarget(client, command, value) {
+    if (hasFileScheme(value))
+        return { kind: "file", path: parseFilePath(value) };
+    if (hasWorkScheme(value))
+        return resolveWorkTarget(client, value);
+    const spaceId = optionalSpaceId(command);
+    if (spaceId) {
+        try {
+            await client.space(spaceId).files.read(value);
+            return { kind: "file", path: value };
+        }
+        catch (cause) {
+            if (!(cause instanceof HttpError) || cause.status !== 404)
+                throw cause;
+        }
+    }
+    return resolveWorkTarget(client, value);
+}
 function reportDispatch(record) {
     if (record.status !== "pending") {
         reportOutcome(record, Boolean(record.command.request));
@@ -53,7 +103,7 @@ function reportDispatch(record) {
 }
 function reportOutcome(record, called) {
     if (record.status === "applied") {
-        ok(called ? "Work preview shown and method called" : "Work preview shown");
+        ok(called ? "Work preview shown and method called" : "Preview shown");
         if (record.result !== undefined) {
             console.log(typeof record.result === "string" ? record.result : JSON.stringify(record.result, null, 2));
         }
@@ -70,15 +120,17 @@ Commands reach only the frontend instance that originated the current chat,
 resolved from request provenance. Nothing else can be targeted.
 
 Examples:
-  cohub ui preview <work-id>
+  cohub ui preview <work-or-file>
+  cohub ui preview file://src/main.ts
+  cohub ui preview work://alice/studio/launch
   cohub ui preview alice/studio/launch
   cohub ui preview https://cohub.live/alice/studio/w/launch?view=timeline
   cohub ui preview <work-id> --call selection.get
   cohub ui preview <work-id> --call board.focus --data '{"nodeId":"n1"}'
 `);
     const preview = ui
-        .command("preview <work>")
-        .description("Show a Work preview tab, optionally calling a method it exposes")
+        .command("preview <work-or-file>")
+        .description("Show a file or Work preview tab, optionally calling a Work method")
         .option("--call <method>", "Method the Work registered via client.work.surface.handle()")
         .option("--data <json>", "Inline JSON input for --call")
         .option("-i, --input <file>", "JSON input file for --call; use - for stdin")
@@ -98,19 +150,24 @@ Examples:
         const timeoutMs = parseTimeout(opts.timeoutMs);
         const client = createClient();
         try {
-            const target = await resolveWorkTarget(client, work);
+            const target = await resolvePreviewTarget(client, preview, work);
+            if (target.kind === "file" && opts.call) {
+                return error("Unsupported option", "--call only applies to Work previews.");
+            }
             const request = opts.call
                 ? { method: opts.call, ...(callInput === undefined ? {} : { input: callInput }) }
                 : undefined;
             const input = {
                 command: {
                     type: "preview.show",
-                    preview: {
-                        kind: "work",
-                        workId: target.workId,
-                        label: target.label,
-                        ...(target.launch.search || target.launch.hash ? { launch: target.launch } : {}),
-                    },
+                    preview: target.kind === "file"
+                        ? target
+                        : {
+                            kind: "work",
+                            workId: target.workId,
+                            label: target.label,
+                            ...(target.launch.search || target.launch.hash ? { launch: target.launch } : {}),
+                        },
                     ...(request ? { request } : {}),
                 },
                 ...(opts.client ? { targetClientId: opts.client } : {}),
@@ -133,6 +190,8 @@ Examples:
     });
     preview.addHelpText("after", `
 Notes:
+  - Use file:// and work:// to make the target explicit.
+  - A plain target checks the current Space for a file before resolving a Work.
   - Showing a preview is idempotent; repeating it re-activates the same tab.
   - --call waits for the Work to announce readiness, then invokes the method.
   - Which methods exist is up to the Work author.

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 {};