@clearlysh/beehaven 0.8.16

package/dist/commands/canvas.js

@@ -0,0 +1,932 @@
+/**
+ * `beehaven canvas` — edit the Clearly editor canvas from the CLI.
+ *
+ * Wraps the Home DO's `ui-open`, `canvas-invoke`, `device-record-start/stop`
+ * actions with a friendlier surface. Auto-fills `deviceId` from the pinned
+ * device (see `beehaven devices pin <clientId>`).
+ *
+ *   beehaven canvas open <noteId>                    # open the composition on the pinned device
+ *   beehaven canvas invoke <action> [json-args]      # run a registered editor action
+ *   beehaven canvas query <action>                   # alias for `invoke` on `*.snapshot` actions
+ *   beehaven canvas actions                          # list all action ids registered on the client
+ *   beehaven canvas record start [sessionId]         # start recording on pinned device
+ *   beehaven canvas record stop                      # stop recording
+ *
+ * Flags:
+ *   --device <clientId>       override the pinned device for this call
+ *   --client-type <type>      restrict to mac-app / web / ios-app
+ *   --note <noteId>           stamp the noteId on the envelope (useful in logs)
+ *   --json                    output raw JSON
+ */
+import { execFile } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { rpcOnce } from '../ipc-client.js';
+import { getPinnedDevice } from './devices.js';
+import { withUtm } from '../utm.js';
+// ⚠ The ONE origin resolver — see `canvasUrl`. This module is dependency-free by design.
+import { resolveRelaySelection, appOriginForEnv } from '../relay-presets.js';
+/** Build the web canvas URL for a composition. `--url <base>` overrides the origin entirely;
+ *  `--dev` forces localhost; otherwise it follows the env the daemon is dialling.
+ *
+ *  ⚠⚠ THIS WAS THE THIRD SPELLING OF THE ORIGIN IN THE TREE (CBH-45), and the odd one out: it
+ *  said `https://clearly.sh` — the APEX — while `open` said `https://www.clearly.sh`. The apex
+ *  301s to www, so every canvas link handed out from here carried a redirect, and reading the two
+ *  side by side gave no way to tell which was authoritative.
+ *
+ *  ⚠ IT ALSO IGNORED `beehaven env`: a daemon pointed at a local relay still printed a production
+ *  URL unless the caller happened to remember `--dev`. `appOriginForEnv` is the one resolver now,
+ *  so a link's origin follows the workspace it came from. `--dev` / `CLEARLY_DEV` still win, since
+ *  that is an explicit statement about where the reader is. */
+function canvasUrl(noteId, values) {
+    if (values.url)
+        return withUtm(`${String(values.url).replace(/\/+$/, '')}/c/${noteId}`);
+    if (values.dev || process.env.CLEARLY_DEV)
+        return withUtm(`https://localhost:3000/c/${noteId}`);
+    let base = 'https://www.clearly.sh';
+    try {
+        // ⚠ STATIC IMPORTS, not `require` — this package is ESM ("type": "module"), where `require` is
+        //   not defined, and `canvasUrl` is sync so `await import` is unavailable. `relay-presets` is
+        //   deliberately dependency-free precisely so every surface can import it directly.
+        const p = join(homedir(), '.beehaven', 'config.json');
+        const cfg = existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : {};
+        base = appOriginForEnv(resolveRelaySelection(cfg).envName) ?? base;
+    }
+    catch { /* an unreadable config means production, which is what it always was */ }
+    return withUtm(`${base}/c/${noteId}`);
+}
+/** Open a URL in the user's default browser (a fresh live client). Cross-platform. */
+function launchInBrowser(url) {
+    try {
+        if (process.platform === 'darwin')
+            execFile('open', [url], () => { });
+        else if (process.platform === 'win32')
+            execFile('cmd', ['/c', 'start', '', url], () => { });
+        else
+            execFile('xdg-open', [url], () => { });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseJsonOrBail(raw, fallback = {}) {
+    if (!raw)
+        return fallback;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            return parsed;
+        return fallback;
+    }
+    catch {
+        console.error(`  Invalid JSON: ${raw}`);
+        process.exit(1);
+    }
+}
+function resolveTarget(values) {
+    const cliDevice = values.device;
+    const cliType = values['client-type'];
+    if (cliDevice || cliType)
+        return { deviceId: cliDevice, clientType: cliType };
+    const pinned = getPinnedDevice();
+    if (!pinned)
+        return {};
+    return { deviceId: pinned.clientId, clientType: pinned.clientType };
+}
+export async function cmdCanvas(sub, positionals, values) {
+    switch (sub) {
+        case 'open':
+            return cmdCanvasOpen(positionals, values);
+        case 'invoke':
+        case 'run':
+            return cmdCanvasInvoke(positionals, values);
+        case 'query':
+        case 'snapshot':
+            return cmdCanvasQuery(positionals, values);
+        case 'actions':
+        case 'list':
+            return cmdCanvasActions(values);
+        // ── review + verify (read the canvas, self-test every action) ──────────
+        case 'perceive':
+        case 'look':
+            return cmdCanvasPerceive(positionals, values);
+        case 'status':
+            return cmdCanvasStatus(positionals, values);
+        case 'verify':
+        case 'selftest':
+            return cmdCanvasVerify(positionals, values);
+        case 'prompt':
+        case 'ask':
+            return cmdCanvasPrompt(positionals, values);
+        case 'goto':
+        case 'nav':
+        case 'navigate':
+            return cmdCanvasGoto(positionals, values);
+        case 'help':
+        case 'catalog':
+            return cmdCanvasCatalog(positionals, values);
+        case 'record':
+            return cmdCanvasRecord(positionals, values);
+        // ── Composition-level verbs (task #84) ────────────────────
+        // Thin wrappers over the workspace RPCs so agents and humans
+        // can manage compositions without remembering the RPC names.
+        // Each verb maps to one cloud-side action; the canonical
+        // catalog is `beehaven canvas help --search composition`.
+        case 'new':
+        case 'create':
+            return cmdCompositionCreate(positionals, values);
+        case 'rename':
+            return cmdCompositionRename(positionals, values);
+        case 'delete':
+        case 'rm':
+            return cmdCompositionDelete(positionals, values);
+        case 'detail':
+        case 'get':
+            return cmdCompositionDetail(positionals, values);
+        case 'export':
+            return cmdCompositionExport(positionals, values);
+        // ── Quick text-onto-canvas (companion to teleport --as text) ──
+        // `beehaven canvas paste-text "string..."` or stdin pipe:
+        //   cat note.md | beehaven canvas paste-text --composition <id>
+        // Drops a text block on the canvas without needing a file path.
+        // Useful for one-shot agent dictation, LLM scratch, etc.
+        case 'paste-text':
+        case 'text':
+            return cmdCanvasPasteText(positionals, values);
+        // ── publish-landing — built site dir → site comp → embed block ─
+        // `beehaven canvas publish-landing ./dist --composition <id>`
+        // composes compose-create + compose-push + canvas-invoke into one
+        // shot. Closes the loop on "Claude generates landing → lands on
+        // user's pasteboard as a live, interactive iframe block".
+        case 'publish-landing':
+        case 'publish-site':
+            return cmdCanvasPublishLanding(positionals, values);
+        default:
+            printHelp();
+            return;
+    }
+}
+async function cmdCanvasPublishLanding(positionals, values) {
+    const dir = positionals[0];
+    if (!dir) {
+        console.error('  Usage: beehaven canvas publish-landing <dist-dir> --composition <id>');
+        console.error('  Takes a pre-built static-site directory (Vite dist/, Next out/,');
+        console.error('  Astro dist/, SvelteKit build/, or plain HTML), creates a site');
+        console.error('  composition, pushes the bundle, and embeds the served URL as a');
+        console.error('  website block on the target pasteboard.');
+        process.exit(1);
+    }
+    const targetCompositionId = values.composition;
+    if (!targetCompositionId) {
+        console.error('  --composition <id> required (the pasteboard to embed the landing on).');
+        process.exit(1);
+    }
+    const { resolve } = await import('path');
+    const { statSync } = await import('fs');
+    const absDir = resolve(dir);
+    try {
+        const s = statSync(absDir);
+        if (!s.isDirectory()) {
+            console.error(`  Not a directory: ${absDir}`);
+            process.exit(1);
+        }
+    }
+    catch {
+        console.error(`  Directory not found: ${absDir}`);
+        process.exit(1);
+    }
+    const title = values.title || 'Landing — published from CLI';
+    console.log(`  Publishing landing from ${absDir}…`);
+    console.log(`    Target pasteboard: ${targetCompositionId}`);
+    // Step 1 — create a fresh site composition. The site bundle lives
+    // here; the target pasteboard just embeds the served URL.
+    console.log('  [1/3] Creating site composition…');
+    const create = await rpcOnce('composition-create', { title, type: 'site' }, 30_000);
+    const siteCompositionId = create?.id ?? create?.result?.id;
+    if (!siteCompositionId) {
+        console.error(`  composition-create failed: ${create?.error ?? JSON.stringify(create)}`);
+        process.exit(1);
+    }
+    console.log(`    → site comp: ${siteCompositionId}`);
+    // Step 2 — delegate to the existing compose-push flow. The push
+    // command was extended (this round) to accept `dir` + `composition`
+    // overrides so we don't need to chdir or write a .beehaven.json
+    // link file first.
+    console.log('  [2/3] Building + pushing bundle…');
+    const { cmdComposePush } = await import('./compose.js');
+    await cmdComposePush({
+        ...values,
+        dir: absDir,
+        composition: siteCompositionId,
+    });
+    // Step 3 — embed the served URL as a website block on the target.
+    // iframe-embed RPC resolves siteCompositionId → relay URL, sandboxed.
+    console.log('  [3/3] Embedding on target pasteboard…');
+    const embed = await rpcOnce('iframe-embed', {
+        siteCompositionId,
+        targetCompositionId,
+        title,
+    }, 30_000);
+    if (embed?.error) {
+        // Fall back to a direct canvas-invoke that adds a website block.
+        // Saves the user from needing to redo step 1 + 2.
+        console.error(`  iframe-embed failed: ${embed.error}`);
+        console.error('  Manual fallback:');
+        console.error(`    beehaven call composition-detail '{"id":"${siteCompositionId}"}'   # gets the served URL`);
+        process.exit(1);
+    }
+    const block = embed?.block ?? embed?.result?.block;
+    console.log(`  ✓ Published: site comp ${siteCompositionId} embedded as block ${block?.id ?? '?'} on pasteboard ${targetCompositionId}`);
+    console.log(`  ✓ Open it: https://clearly.sh/c/${targetCompositionId}`);
+    return print(embed, values);
+}
+async function cmdCanvasPasteText(positionals, values) {
+    // Read text from positional or stdin. Stdin is the natural pipe
+    // path for `cat file | beehaven canvas paste-text`; positional is
+    // the natural ad-hoc form for `beehaven canvas paste-text "hi"`.
+    // Args override stdin if both are supplied so the explicit form
+    // wins.
+    let text = positionals[0] ?? '';
+    if (!text && !process.stdin.isTTY) {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        text = Buffer.concat(chunks).toString('utf-8');
+    }
+    text = text.trim();
+    if (!text) {
+        console.error('  Usage: beehaven canvas paste-text "your text" [--composition <id>]');
+        console.error('         or: cat file.md | beehaven canvas paste-text [--composition <id>]');
+        process.exit(1);
+    }
+    const compositionId = values.composition;
+    if (!compositionId) {
+        console.error('  --composition <id> required (the pasteboard to land the text on).');
+        console.error('  List compositions: beehaven sql "SELECT id, title FROM compositions ORDER BY updated_at DESC LIMIT 10"');
+        process.exit(1);
+    }
+    const lines = text.split(/\r?\n/).length;
+    // Same placement heuristic as teleport --as text (workspace.ts).
+    // Keeps the two paths visually consistent.
+    const x = 80, y = 80;
+    const width = 720;
+    const height = Math.max(120, Math.min(2400, lines * 22 + 60));
+    const out = await rpcOnce('canvas-add-text', {
+        compositionId,
+        text,
+        x,
+        y,
+        width,
+        height,
+        source: 'paste-text',
+    }, 15_000);
+    return print(out, values);
+}
+function printHelp() {
+    console.log(`Usage:
+  beehaven canvas open <noteId>
+  beehaven canvas invoke <action> [json-args]
+  beehaven canvas query <snapshot-action>
+  beehaven canvas actions [--archetype X] [--status X] [--runtime X] [--scope X] [--callable-only]
+  beehaven canvas perceive [id] [--format json] [--pixels] [--max N]   # read the live "room"
+  beehaven canvas status [id]                    # compact canvas health summary
+  beehaven canvas verify [--composition id] [--keep] [--image-url url] # self-test every canvas action
+  beehaven canvas prompt "draw a robot" [--composition id]            # send a prompt (= bottom-bar prompt tool)
+  beehaven canvas goto recents | <id>                                 # navigate the app (router.push) — verify reload
+  beehaven canvas new "Title"                   # create empty pasteboard
+  beehaven canvas rename <id> "New title"       # rename a pasteboard
+  beehaven canvas detail <id>                   # full pasteboard payload
+  beehaven canvas delete <id>                   # soft-delete a pasteboard
+  beehaven canvas export <id> [--format pdf|svg|png|json]
+  beehaven canvas paste-text "..." --composition <id>   # text → text block (or pipe stdin)
+  beehaven canvas help [domain]                 # workspace RPC catalog (cloud), grouped
+  beehaven canvas help --search <q>             # keyword search the catalog
+  beehaven canvas record start [sessionId]
+  beehaven canvas record stop
+
+Flags:
+  --device <clientId>    target a specific connected device
+  --client-type <type>   restrict to mac-app | web | ios-app
+  --note <noteId>        stamp noteId on the envelope
+  --json                 output raw JSON
+
+Canvas-actions filters:
+  --archetype <kind>     image | text | link | pdf | media
+  --status <state>       live | partial | pending | mcp
+  --runtime <where>      local | worker | do | mcp
+  --scope <which>        all (default) | block | composition
+  --callable-only        drop status=pending rows
+
+Note: 'canvas actions' lists what the EDITOR CLIENT can do locally
+(open palette, focus block, etc.). 'canvas help' lists what the
+WORKSPACE DO exposes as RPCs (add-text, add-document, time-travel, ...).
+
+Run 'beehaven devices' to see connected devices, and 'beehaven devices pin <id>'
+to pin one as the default target.`);
+}
+// ── open ────────────────────────────────────────────────────────────────────
+async function cmdCanvasOpen(positionals, values) {
+    const noteId = positionals[0];
+    if (!noteId) {
+        console.error('  Usage: beehaven canvas open <noteId> [--launch] [--dev]');
+        process.exit(1);
+    }
+    const url = canvasUrl(noteId, values);
+    // --launch / --browser → open a REAL browser window (a fresh live client).
+    // Use this when nothing is connected (canvas-perceive shows delivered:0).
+    if (values.launch || values.browser) {
+        const ok = launchInBrowser(url);
+        console.log(ok ? `  🌐 Opening ${url}` : `  Open this URL in a browser: ${url}`);
+        try {
+            await rpcOnce('ui-open', { window: 'canvas', noteId, title: values.title }, 6_000);
+        }
+        catch {
+            /* no client yet — the new tab will load it */
+        }
+        return ok ? undefined : process.exit(1);
+    }
+    const target = resolveTarget(values);
+    // `ui-open` is a broadcast — when targeting is required, invoke the
+    // `device.open` alias via canvas-invoke so only the chosen device reacts.
+    if (target.deviceId || target.clientType) {
+        const out = await rpcOnce('canvas-invoke', {
+            action: 'composition.open',
+            args: { noteId, title: values.title },
+            deviceId: target.deviceId,
+            clientType: target.clientType,
+            noteId,
+        }, 15_000);
+        return print(out, values);
+    }
+    const out = await rpcOnce('ui-open', { window: 'canvas', noteId, title: values.title }, 15_000);
+    const delivered = out?.delivered ?? out?.result?.delivered;
+    if (delivered === 0)
+        console.log(`  No browser connected. Launch one:  beehaven canvas open ${noteId} --launch   →  ${url}`);
+    return print(out, values);
+}
+// ── invoke ──────────────────────────────────────────────────────────────────
+async function cmdCanvasInvoke(positionals, values) {
+    const action = positionals[0];
+    const argsRaw = positionals[1];
+    if (!action) {
+        console.error('  Usage: beehaven canvas invoke <action> [json-args]');
+        process.exit(1);
+    }
+    const args = parseJsonOrBail(argsRaw, {});
+    const target = resolveTarget(values);
+    // awaitResult routes the handler's return value back through
+    // _canvasInvokeWaiters in the worker DO (task #81). Default ON for
+    // the CLI so `beehaven canvas invoke` actually shows what the
+    // action did — agents need that. Opt out with --no-await for the
+    // legacy fire-and-forget shape (delivery ack only).
+    const wait = values['no-await'] ? false : true;
+    const out = await rpcOnce('canvas-invoke', {
+        action,
+        args,
+        deviceId: target.deviceId,
+        clientType: target.clientType,
+        noteId: values.note,
+        awaitResult: wait,
+        timeoutMs: wait ? 7500 : undefined,
+    }, wait ? 30_000 : 10_000);
+    return print(out, values);
+}
+// ── query ───────────────────────────────────────────────────────────────────
+// Alias for invoke on *.snapshot actions. Since the client snapshot actions
+// currently write state back into the composition row via deltas (not a
+// direct reply), `query` is equivalent to `invoke` today. Kept as a separate
+// sub-command so when an awaitResult channel lands, agents can switch sub
+// without rewriting scripts.
+async function cmdCanvasQuery(positionals, values) {
+    const action = positionals[0];
+    if (!action) {
+        console.error('  Usage: beehaven canvas query <snapshot-action>');
+        process.exit(1);
+    }
+    const suggested = action.endsWith('.snapshot') ? action : `${action}.snapshot`;
+    return cmdCanvasInvoke([suggested, positionals[1] ?? ''], values);
+}
+// ── actions ─────────────────────────────────────────────────────────────────
+// Asks the client to dump its action registry by invoking a reserved
+// `editor.list-actions` action; the handler is registered by the editor on
+// mount and responds via the sql:delta stream. If the editor isn't open,
+// the call times out — that's the signal agents should `open` first.
+async function cmdCanvasActions(values) {
+    const target = resolveTarget(values);
+    // Forward filter flags to the registered editor.list-actions handler
+    // (registered by FloatingWindowsManager — closes the LLM-on-canvas
+    // framework gap so the CLI can discover what verbs are callable
+    // without bundling its own copy of the manifest).
+    const filterArgs = {};
+    if (values.archetype)
+        filterArgs.archetype = values.archetype;
+    if (values.status)
+        filterArgs.status = values.status;
+    if (values.runtime)
+        filterArgs.runtime = values.runtime;
+    if (values['callable-only'])
+        filterArgs.callableOnly = true;
+    if (values.scope)
+        filterArgs.scope = values.scope;
+    const out = await rpcOnce('canvas-invoke', {
+        action: 'editor.list-actions',
+        args: filterArgs,
+        deviceId: target.deviceId,
+        clientType: target.clientType,
+        awaitResult: true,
+        timeoutMs: 7500,
+    }, 15_000);
+    // If the result envelope arrived with a `value` (handler return),
+    // render the manifest in tabular form. Otherwise fall through to
+    // the legacy ack pretty-printer.
+    if (values.json || values.format === 'json') {
+        console.log(JSON.stringify(out, null, 2));
+        return;
+    }
+    const v = out?.value ?? out?.result?.value;
+    if (v && (v.blocks || v.compositions)) {
+        printManifest(v, filterArgs);
+        return;
+    }
+    // editor.list-actions returns { actions: [{ id, label, group, shortcut, description }] }
+    if (v && Array.isArray(v.actions)) {
+        const acts = v.actions;
+        if (values.scope && values.scope !== 'all') {
+            /* scope filter is client-side already */
+        }
+        let lastGroup = '';
+        for (const a of acts.sort((x, y) => (x.group || '').localeCompare(y.group || '') || x.id.localeCompare(y.id))) {
+            if ((a.group || '') !== lastGroup) {
+                lastGroup = a.group || '';
+                console.log(`\n  ${lastGroup || 'other'}`);
+            }
+            console.log(`    ${a.id}${a.shortcut ? ` (${a.shortcut})` : ''}${a.description ? ` — ${a.description}` : a.label ? ` — ${a.label}` : ''}`);
+        }
+        console.log(`\n  ${acts.length} actions. Call one: beehaven canvas invoke <id> '<json-args>'`);
+        return;
+    }
+    return print(out, values);
+}
+function printManifest(value, filters) {
+    const blocks = Array.isArray(value.blocks) ? value.blocks : [];
+    const comps = Array.isArray(value.compositions) ? value.compositions : [];
+    const filterDesc = Object.entries(filters)
+        .filter(([, v]) => v !== undefined && v !== false)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(' ');
+    if (blocks.length) {
+        console.log(`\n  Block actions${filterDesc ? ` [${filterDesc}]` : ''} — ${blocks.length}\n`);
+        for (const a of blocks) {
+            const arch = Array.isArray(a.archetypes) ? a.archetypes.join(',') : a.archetypes;
+            console.log(`    ${String(a.id).padEnd(34)} ${String(a.status).padEnd(8)} ${String(a.runtime).padEnd(7)} ${arch}`);
+        }
+    }
+    if (comps.length) {
+        console.log(`\n  Composition actions — ${comps.length}\n`);
+        for (const a of comps) {
+            console.log(`    ${String(a.id).padEnd(34)} ${String(a.status).padEnd(8)} ${String(a.runtime).padEnd(7)}`);
+        }
+    }
+    if (!blocks.length && !comps.length) {
+        console.log('  (no actions matched)');
+    }
+}
+// ── perceive / status / verify (review the canvas + self-test actions) ───────
+// perceive → the read RPC (room: gaze / contents / focus / instruments /
+//            prepress). status → a compact health summary built from it.
+// verify   → drives every canvas.* action against the live tab on SCRATCH
+//            nodes, then deletes everything it created (baseline node diff) and
+//            restores print settings. Safe + self-cleaning; never touches
+//            pre-existing user content.
+async function cmdCanvasPerceive(positionals, values) {
+    const compositionId = positionals[0] || values.composition;
+    const wantJson = !!values.json || values.format === 'json';
+    const input = { format: wantJson ? 'json' : 'text' };
+    if (compositionId)
+        input.compositionId = compositionId;
+    if (values.pixels)
+        input.includePixels = true;
+    if (values.max)
+        input.maxObjects = Number(values.max);
+    const out = await rpcOnce('canvas-perceive', input, 20_000);
+    const r = out?.result ?? out;
+    if (wantJson) {
+        console.log(JSON.stringify(r, null, 2));
+        return;
+    }
+    if (typeof r?.text === 'string') {
+        console.log(r.text);
+        if (r.live === false)
+            console.log('\n  (live:false — no open tab; showing persisted scene. Open one:  beehaven canvas open <id> --launch)');
+        return;
+    }
+    console.log(JSON.stringify(r, null, 2));
+}
+async function cmdCanvasStatus(positionals, values) {
+    const compositionId = positionals[0] || values.composition;
+    const input = { format: 'json' };
+    if (compositionId)
+        input.compositionId = compositionId;
+    const out = await rpcOnce('canvas-perceive', input, 20_000);
+    const r = out?.result ?? out;
+    if (values.json || values.format === 'json') {
+        console.log(JSON.stringify(r, null, 2));
+        return;
+    }
+    const delivered = Number(r?.delivered ?? 0);
+    const live = !!r?.live;
+    const room = r?.room;
+    console.log('  Canvas status');
+    console.log(`    Tab connected : ${delivered > 0 ? `yes · ${delivered} client${delivered === 1 ? '' : 's'}` : 'NO  (open one:  beehaven canvas open <id> --launch)'}`);
+    console.log(`    State         : ${live ? 'LIVE — reading the open tab' : 'persisted scene (no live tab)'}`);
+    if (room) {
+        const contents = Array.isArray(room.contents) ? room.contents.length : 0;
+        const sel = Array.isArray(room.focus?.selected) ? room.focus.selected.length : 0;
+        const tool = room.focus?.tool ?? room.focus?.mode ?? '—';
+        console.log(`    Composition   : ${room.room?.title ?? room.room?.id ?? compositionId ?? '—'}`);
+        console.log(`    Objects       : ${contents}`);
+        console.log(`    Selection     : ${sel}`);
+        console.log(`    Active tool   : ${tool}`);
+        if (room.gaze?.zoomPct != null)
+            console.log(`    Zoom          : ${room.gaze.zoomPct}%`);
+        const pp = room.prepress;
+        if (pp)
+            console.log(`    Prepress      : ${pp.dpi ?? '?'}dpi · bleed ${pp.bleedMm ?? 0}mm · safe ${pp.safeMm ?? 0}mm${pp.cropMarks ? ' · crop-marks' : ''}${pp.mirror ? ' · mirror' : ''}`);
+    }
+    else if (delivered === 0) {
+        console.log('    (no live room — open a tab to inspect gaze / selection / tool)');
+    }
+    console.log(`\n    Review:  beehaven canvas perceive${compositionId ? ` ${compositionId}` : ''}`);
+    console.log(`    Verify:  beehaven canvas verify${compositionId ? ` --composition ${compositionId}` : ''}`);
+}
+async function cmdCanvasPrompt(positionals, values) {
+    const text = positionals.join(' ').trim() || String(values.text || '').trim();
+    if (!text) {
+        console.error('  Usage: beehaven canvas prompt "draw a robot" [--composition <id>]');
+        process.exit(1);
+    }
+    const target = resolveTarget(values);
+    // The SAME action as the bottom-bar Prompt tool — drives `canvas.prompt` on the
+    // live web tab (the composer is a web surface) → submitPromptText → the
+    // Librarian. Watch the result: `beehaven canvas perceive` shows "Prompt tool:
+    // THINKING (generating…)", then the generated node appears in contents.
+    const out = await rpcOnce('canvas-invoke', {
+        action: 'canvas.prompt',
+        args: { text },
+        deviceId: target.deviceId,
+        clientType: target.clientType ?? (target.deviceId ? undefined : 'web'),
+        noteId: values.composition,
+        awaitResult: true,
+        timeoutMs: 7500,
+    }, 15_000);
+    return print(out, values);
+}
+async function cmdCanvasGoto(positionals, values) {
+    const dest = (positionals[0] || '').trim();
+    if (!dest) {
+        console.error('  Usage: beehaven canvas goto recents | <compositionId>');
+        process.exit(1);
+    }
+    const path = dest === 'recents' ? '/recents' : dest.startsWith('/') ? dest : `/c/${dest}`;
+    // Drives the app router via ui-navigate (router.push). `goto recents` then
+    // `goto <id>` round-trips the composition → a fresh load from PERSISTED data,
+    // so you can verify generated artwork survives reload.
+    const out = await rpcOnce('ui-navigate', { path }, 15_000);
+    if (!(values.json || values.format === 'json'))
+        console.log(`  → navigated connected client(s) to ${path}`);
+    return print(out, values);
+}
+async function cmdCanvasVerify(positionals, values) {
+    const compositionId = positionals[0] || values.composition;
+    const target = resolveTarget(values);
+    const wantJson = !!values.json || values.format === 'json';
+    // A MUTATING sweep must hit ONE editor surface, never broadcast to every
+    // connected client (mac-app + web + daemon would each run the action →
+    // duplicate scratch nodes). The canvas editor is a web surface, so default
+    // to clientType:'web' unless an explicit --device / --client-type was given.
+    const invTarget = {
+        deviceId: target.deviceId,
+        clientType: target.clientType ?? (target.deviceId ? undefined : 'web'),
+    };
+    // Drive one editor action on the live tab; return the normalized envelope
+    // { ok, value, error, delivered } (see canvas-rpcs.ts canvas-invoke).
+    async function invoke(action, args = {}, timeoutMs = 7500) {
+        const out = await rpcOnce('canvas-invoke', {
+            action,
+            args,
+            deviceId: invTarget.deviceId,
+            clientType: invTarget.clientType,
+            noteId: compositionId,
+            awaitResult: true,
+            timeoutMs,
+        }, timeoutMs + 8000);
+        return out?.result ?? out;
+    }
+    // 1. Require a live tab — list-nodes both proves connectivity and gives the
+    //    baseline node set used for cleanup.
+    const baseEnv = await invoke('canvas.list-nodes');
+    if (!baseEnv || baseEnv.ok === false || !baseEnv.value) {
+        const reason = baseEnv?.error || 'no-client-connected';
+        console.error(`  ✗ No live canvas tab (${reason}).`);
+        console.error(`    Open one:  beehaven canvas open ${compositionId || '<id>'} --launch`);
+        console.error('    Verify drives the real editor, so a tab must be open.');
+        process.exit(1);
+    }
+    const baselineIds = new Set((baseEnv.value.nodes || []).map((n) => String(n.id)));
+    // Capture baseline print settings — restored at the end so set-print is non-destructive.
+    let basePrepress = null;
+    try {
+        const pr = await rpcOnce('canvas-perceive', { format: 'json', compositionId }, 15_000);
+        basePrepress = (pr?.result ?? pr)?.room?.prepress ?? null;
+    }
+    catch {
+        /* perceive optional */
+    }
+    const rows = [];
+    const ids = {};
+    let failed = 0;
+    async function step(action, args, opts = {}) {
+        try {
+            const env = await invoke(action, args);
+            const ok = !!env && env.ok !== false && env.error == null && (!opts.assert || opts.assert(env.value));
+            if (ok && opts.capture && env.value?.id)
+                ids[opts.capture] = String(env.value.id);
+            rows.push({
+                action,
+                status: ok ? 'PASS' : 'FAIL',
+                note: ok ? opts.note : env?.error || 'assertion failed',
+            });
+            if (!ok)
+                failed++;
+        }
+        catch (e) {
+            rows.push({ action, status: 'FAIL', note: e?.message || String(e) });
+            failed++;
+        }
+    }
+    const skip = (action, note) => rows.push({ action, status: 'SKIP', note });
+    // 2. Sweep — every canvas.* action, on scratch nodes.
+    rows.push({
+        action: 'canvas.list-nodes',
+        status: 'PASS',
+        note: `${baselineIds.size} nodes baseline`,
+    });
+    await step('canvas.perceive', { format: 'text' }, { assert: (v) => v != null });
+    await step('canvas.create-node', { type: 'rect', x: 60, y: 60, w: 80, h: 80, fill: '#7CC0F5' }, { capture: 'A', assert: (v) => !!v?.id });
+    await step('canvas.create-node', { type: 'ellipse', x: 180, y: 60, w: 80, h: 80, fill: '#F59E0B' }, { capture: 'B', assert: (v) => !!v?.id });
+    await step('canvas.create-node', { type: 'text', x: 60, y: 180, text: '__verify__', size: 18 }, { capture: 'C', assert: (v) => !!v?.id });
+    if (ids.A)
+        await step('canvas.update-nodes', { ids: [ids.A], patch: { x: 100, y: 100, fill: '#22C55E', name: '__verify__A' } }, { assert: (v) => (v?.updated ?? 0) >= 1 });
+    if (ids.A && ids.B)
+        await step('canvas.set-selection', { ids: [ids.A, ids.B] }, {});
+    if (ids.A && ids.B)
+        await step('canvas.arrange', { op: 'align-left', ids: [ids.A, ids.B] }, {});
+    if (ids.A)
+        await step('canvas.order', { op: 'front', ids: [ids.A] }, {});
+    if (ids.A)
+        await step('canvas.duplicate', { ids: [ids.A] }, {});
+    if (ids.A)
+        await step('canvas.effects', { op: 'shadow', ids: [ids.A] }, {});
+    await step('canvas.set-tool', { mode: 'move' }, {});
+    await step('canvas.viewport', { op: 'zoom-in' }, { assert: (v) => v?.zoomPct != null });
+    await invoke('canvas.viewport', { op: 'reset' }); // restore zoom (not scored)
+    if (ids.B)
+        await step('canvas.clipboard', { op: 'copy', ids: [ids.B] }, {});
+    await step('canvas.clipboard', { op: 'paste' }, {});
+    if (ids.C)
+        await step('canvas.component', { op: 'create', ids: [ids.C] }, {});
+    await step('canvas.select', { op: 'all' }, {});
+    await invoke('canvas.select', { op: 'none' }); // deselect (not scored)
+    await step('canvas.snapshot', {}, {});
+    await step('canvas.set-print', { dpi: 300, bleedMm: 3 }, {});
+    await step('canvas.preflight', {}, { assert: (v) => v != null });
+    await step('canvas.add-artboard', { wMm: 76, hMm: 76 }, {});
+    await step('canvas.add-document', { x: 320, y: 60, title: '__verify__doc' }, { assert: (v) => !!v?.id });
+    await step('canvas.history', { op: 'undo' }, { assert: (v) => v != null });
+    await invoke('canvas.history', { op: 'redo' }); // restore (not scored)
+    if (values['image-url'])
+        await step('canvas.add-image', { src: String(values['image-url']), x: 320, y: 200 }, { assert: (v) => !!v?.id });
+    else
+        skip('canvas.add-image', 'pass --image-url <url> to test (no scratch asset)');
+    skip('canvas.export-bundle', 'triggers a file download in the tab — run manually');
+    skip('canvas.add-comment', 'comment pins have no programmatic removal yet');
+    // 3. Cleanup — delete every node that did NOT exist before the sweep, restore print.
+    let cleaned = 0;
+    if (!values.keep) {
+        try {
+            const afterEnv = await invoke('canvas.list-nodes');
+            const afterIds = (afterEnv?.value?.nodes || []).map((n) => String(n.id));
+            const scratch = afterIds.filter((id) => !baselineIds.has(id));
+            if (scratch.length) {
+                const del = await invoke('canvas.delete', { ids: scratch });
+                cleaned = del?.value?.deleted ?? scratch.length;
+            }
+            if (basePrepress)
+                await invoke('canvas.set-print', {
+                    dpi: basePrepress.dpi,
+                    bleedMm: basePrepress.bleedMm,
+                    safeMm: basePrepress.safeMm,
+                    cropMarks: !!basePrepress.cropMarks,
+                    regMarks: !!basePrepress.regMarks,
+                    mirror: !!basePrepress.mirror,
+                });
+        }
+        catch (e) {
+            rows.push({ action: 'cleanup', status: 'FAIL', note: e?.message || String(e) });
+            failed++;
+        }
+    }
+    rows.push({
+        action: 'canvas.delete',
+        status: cleaned > 0 || values.keep ? 'PASS' : 'SKIP',
+        note: values.keep ? '--keep: scratch left in place' : `cleaned ${cleaned} scratch node(s)`,
+    });
+    // 4. Report.
+    if (wantJson) {
+        console.log(JSON.stringify({ ok: failed === 0, failed, rows }, null, 2));
+        return;
+    }
+    const pass = rows.filter((r) => r.status === 'PASS').length;
+    const skipped = rows.filter((r) => r.status === 'SKIP').length;
+    console.log(`\n  Canvas action verification — ${compositionId || '(pinned tab)'}\n`);
+    for (const r of rows) {
+        const mark = r.status === 'PASS' ? '✓' : r.status === 'FAIL' ? '✗' : '·';
+        console.log(`    ${mark} ${r.action.padEnd(22)} ${r.status}${r.note ? `  — ${r.note}` : ''}`);
+    }
+    console.log(`\n  ${pass} passed · ${failed} failed · ${skipped} skipped${values.keep ? ' · scratch KEPT (--keep)' : ' · scratch cleaned'}`);
+    if (failed > 0)
+        process.exit(1);
+}
+// ── catalog (#113) ──────────────────────────────────────────────────────────
+// Calls the workspace's `canvas:actions` virtual RPC and pretty-prints
+// the grouped result. Single source of truth for canvas capabilities —
+// agents AND humans use the same lookup. The actual catalog lives in
+// the cloudflare worker at apps/cloudflare/src/agent/canvas-rpc-catalog.ts.
+async function cmdCanvasCatalog(positionals, values) {
+    const domain = positionals[0];
+    const search = values.search;
+    const compact = !!values.compact;
+    const wantJson = !!values.json || values.format === 'json';
+    const input = {};
+    if (wantJson) {
+        input.format = 'json';
+        if (search)
+            input.q = search;
+        else if (domain)
+            input.domain = domain;
+    }
+    else {
+        input.format = 'markdown';
+        input.compact = compact;
+        if (search) {
+            input.format = 'json';
+            input.q = search;
+        }
+        else if (domain) {
+            input.format = 'json';
+            input.domain = domain;
+        }
+    }
+    const raw = await rpcOnce('canvas:actions', input, 15_000);
+    if (wantJson) {
+        console.log(JSON.stringify(raw, null, 2));
+        return;
+    }
+    const result = raw?.result ?? raw;
+    if (result?.format === 'markdown' && typeof result.text === 'string') {
+        console.log(result.text);
+        return;
+    }
+    // JSON path (search or domain filter) — render to a friendly list.
+    if (result?.hits && Array.isArray(result.hits)) {
+        console.log(`Matches for "${search}":\n`);
+        for (const e of result.hits) {
+            console.log(`  ${e.id.padEnd(36)} ${e.summary}`);
+        }
+        return;
+    }
+    if (result?.entries && Array.isArray(result.entries)) {
+        console.log(`${result.domain}:\n`);
+        for (const e of result.entries) {
+            console.log(`  ${e.id.padEnd(36)} ${e.summary}`);
+        }
+        return;
+    }
+    console.log(JSON.stringify(raw, null, 2));
+}
+// ── composition lifecycle (#84) ─────────────────────────────────────────────
+// Thin wrappers over the workspace RPCs (composition-create, -patch,
+// -delete, -detail, -export-print-pdf). Composition is the canvas
+// document; these verbs are the agent-friendly shape of that catalog.
+async function cmdCompositionCreate(positionals, values) {
+    const title = positionals[0] || values.title || 'Untitled';
+    // composition-create accepts { title, data?, projectId?, teamId?, frameWidth?, frameHeight? }
+    // — keep the CLI surface minimal; the agent path uses the full RPC.
+    const out = await rpcOnce('composition-create', { title }, 30_000);
+    return print(out, values);
+}
+async function cmdCompositionRename(positionals, values) {
+    const id = positionals[0];
+    const title = positionals[1];
+    if (!id || !title) {
+        console.error('  Usage: beehaven canvas rename <id> "New title"');
+        process.exit(1);
+    }
+    // composition-patch is the canonical rename path — passes `{ id, patch: { title } }`.
+    // It also dispatches a canvas-invoke composition.rename behind the
+    // scenes so any open editor tab refreshes its header live.
+    const out = await rpcOnce('composition-patch', { id, patch: { title } }, 30_000);
+    return print(out, values);
+}
+async function cmdCompositionDelete(positionals, values) {
+    const id = positionals[0];
+    if (!id) {
+        console.error('  Usage: beehaven canvas delete <id>');
+        process.exit(1);
+    }
+    if (!values.yes) {
+        console.error('  Refusing without --yes. (Soft-delete; recoverable from time capsules.)');
+        process.exit(1);
+    }
+    const out = await rpcOnce('composition-delete', { id }, 30_000);
+    return print(out, values);
+}
+async function cmdCompositionDetail(positionals, values) {
+    const id = positionals[0];
+    if (!id) {
+        console.error('  Usage: beehaven canvas detail <id>');
+        process.exit(1);
+    }
+    const out = await rpcOnce('composition-detail', { id }, 30_000);
+    return print(out, values);
+}
+async function cmdCompositionExport(positionals, values) {
+    const id = positionals[0];
+    if (!id) {
+        console.error('  Usage: beehaven canvas export <id> [--format pdf|svg|png|json]');
+        process.exit(1);
+    }
+    const format = values.format || 'pdf';
+    // Only PDF has a server-side worker today (composition-export-print-pdf).
+    // svg / png / json are local-only — they require an open browser tab
+    // running the export pipeline. Route them through canvas-invoke
+    // composition.export so the editor tab handles it; PDF goes direct.
+    if (format === 'pdf') {
+        const out = await rpcOnce('composition-export-print-pdf', { id }, 60_000);
+        return print(out, values);
+    }
+    const target = resolveTarget(values);
+    const out = await rpcOnce('canvas-invoke', {
+        action: 'composition.export',
+        args: { compositionId: id, format },
+        deviceId: target.deviceId,
+        clientType: target.clientType,
+        noteId: id,
+    }, 60_000);
+    return print(out, values);
+}
+// ── record ──────────────────────────────────────────────────────────────────
+async function cmdCanvasRecord(positionals, values) {
+    const verb = positionals[0];
+    const target = resolveTarget(values);
+    if (verb === 'start') {
+        const sessionId = positionals[1];
+        const out = await rpcOnce('device-record-start', {
+            sessionId,
+            deviceId: target.deviceId,
+            clientType: target.clientType,
+        }, 15_000);
+        return print(out, values);
+    }
+    if (verb === 'stop') {
+        const out = await rpcOnce('device-record-stop', {
+            deviceId: target.deviceId,
+            clientType: target.clientType,
+        }, 15_000);
+        return print(out, values);
+    }
+    console.error('  Usage: beehaven canvas record start|stop');
+    process.exit(1);
+}
+// ── output ──────────────────────────────────────────────────────────────────
+function print(value, values) {
+    if (values.json || values.format === 'json') {
+        console.log(JSON.stringify(value, null, 2));
+        return;
+    }
+    if (!value || typeof value !== 'object') {
+        console.log(value);
+        return;
+    }
+    const v = value;
+    if ('delivered' in v && 'ok' in v) {
+        const ok = v.ok ? 'ok' : 'no-target';
+        console.log(`  → ${ok} · delivered to ${v.delivered} device${v.delivered === 1 ? '' : 's'}${v.action ? ` · ${v.action}` : ''}`);
+        if (!v.ok)
+            console.log(`  Hint: run 'beehaven devices' to verify a session is connected.`);
+        return;
+    }
+    console.log(JSON.stringify(value, null, 2));
+}