beehaven 0.8.18 → 0.8.19

package/dist/build-channel.js

@@ -53,9 +53,9 @@ export const PUBLIC_BUILD = true;
  * ⚠ REWRITTEN IN `dist/` AT BUILD TIME, like `PUBLIC_BUILD`. `unstamped` is what a source checkout
  * carries and what `tsx`/`vitest` see, and it is honest: nothing has stamped them.
  */
-export const BUILD_SHA = 'cea58c529fe1';
+export const BUILD_SHA = '42cf394385d8';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-09-27T07:47Z';
+export const BUILD_TIME = '2026-09-27T18:08Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/cli.js

@@ -1598,6 +1598,8 @@ async function run() {
             svg: { type: 'string' },
             x: { type: 'string' },
             y: { type: 'string' },
+            width: { type: 'string' },
+            height: { type: 'string' },
             w: { type: 'string' },
             h: { type: 'string' },
             // `as` is also used by teleport (text | attachment |

package/dist/commands/canvas-image.js

@@ -0,0 +1,101 @@
+/** Upload a local raster and place it on a composition without sending base64 over the relay. */
+import { readFileSync, statSync, existsSync } from 'node:fs';
+import { basename, extname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { rpcOnce } from '../ipc-client.js';
+const IMAGE_MIME = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp', '.gif': 'image/gif', '.avif': 'image/avif',
+};
+const MAX_BYTES = 100 * 1024 * 1024;
+function positiveFlag(raw, label) {
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0)
+        throw new Error(`${label} must be a positive number`);
+    return value;
+}
+function coordinateFlag(raw, label) {
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value))
+        throw new Error(`${label} must be a number`);
+    return value;
+}
+function absoluteRelayUrl(url) {
+    if (!url.startsWith('/'))
+        return url;
+    const configPath = join(homedir(), '.beehaven', 'config.json');
+    let endpoint = 'wss://relay.clearly.sh';
+    if (existsSync(configPath)) {
+        const config = JSON.parse(readFileSync(configPath, 'utf8'));
+        if (config.endpoint)
+            endpoint = String(config.endpoint);
+    }
+    return endpoint.replace(/^wss:/, 'https:').replace(/^ws:/, 'http:').replace(/\/$/, '') + url;
+}
+export async function cmdCanvasAddImage(positionals, values) {
+    const input = positionals[0];
+    const compositionId = String(values.composition ?? values.comp ?? values.c ?? '').trim();
+    if (!input || !compositionId) {
+        throw new Error('Usage: beehaven canvas add-image <local.png|jpg|webp|gif|avif> --composition <id> [--x N --y N --width N --height N]');
+    }
+    const path = resolve(input);
+    const mimeType = IMAGE_MIME[extname(path).toLowerCase()];
+    if (!mimeType)
+        throw new Error('Supported image formats: PNG, JPEG, WebP, GIF, AVIF');
+    const stat = statSync(path);
+    if (!stat.isFile())
+        throw new Error(`Not a file: ${path}`);
+    if (!stat.size || stat.size > MAX_BYTES)
+        throw new Error(`Image must be 1 byte to 100 MB (${stat.size} bytes given)`);
+    const x = coordinateFlag(values.x, '--x');
+    const y = coordinateFlag(values.y, '--y');
+    const width = positiveFlag(values.width, '--width');
+    const height = positiveFlag(values.height, '--height');
+    if ((x === undefined) !== (y === undefined))
+        throw new Error('Pass --x and --y together');
+    if ((width === undefined) !== (height === undefined))
+        throw new Error('Pass --width and --height together');
+    // Refuse an unknown target before putting bytes in storage for a canvas that cannot use them.
+    const target = await rpcOnce('composition-detail', { id: compositionId }, 30_000);
+    if (target?.error || target?.composition?.id !== compositionId) {
+        throw new Error(`Canvas not found or not accessible: ${compositionId}`);
+    }
+    const name = basename(path);
+    const safeName = name.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 64);
+    const key = `compositions/${compositionId}/images/${randomUUID()}-${safeName}`;
+    const intent = await rpcOnce('get-upload-url', {
+        key, contentType: mimeType, maxSize: stat.size, size: stat.size,
+    }, 30_000);
+    if (intent?.error || !intent?.uploadUrl || !intent?.publicUrl) {
+        throw new Error(`Could not prepare image upload: ${intent?.error ?? 'missing upload or image URL'}`);
+    }
+    const uploaded = await fetch(absoluteRelayUrl(String(intent.uploadUrl)), {
+        method: 'PUT', headers: { 'Content-Type': mimeType }, body: readFileSync(path),
+    });
+    if (!uploaded.ok)
+        throw new Error(`Image upload failed: HTTP ${uploaded.status}`);
+    const recorded = await rpcOnce('file-uploaded', {
+        key, name, mimeType, size: stat.size, composition: true,
+    }, 30_000);
+    if (recorded?.ok === false || recorded?.error) {
+        throw new Error(`Image uploaded but could not be registered: ${recorded?.error ?? 'unknown error'}`);
+    }
+    const placed = await rpcOnce('canvas-add-image', {
+        compositionId, imageUrl: absoluteRelayUrl(String(intent.publicUrl)),
+        ...(x !== undefined ? { x, y } : {}),
+        ...(width !== undefined ? { width, height } : {}),
+    }, 30_000);
+    if (placed?.ok !== true || !placed?.nodeId && !placed?.blockId) {
+        throw new Error(`Image uploaded but could not be placed: ${placed?.error ?? 'unknown error'}. Asset key: ${key}`);
+    }
+    const result = { ok: true, compositionId, nodeId: placed.nodeId ?? placed.blockId, imageFileId: recorded?.id, name };
+    if (values.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(`  Added ${name} to canvas ${compositionId} (node ${result.nodeId})`);
+}

package/dist/commands/canvas.js

@@ -155,6 +155,10 @@ export async function cmdCanvas(sub, positionals, values) {
         case 'paste-text':
         case 'text':
             return cmdCanvasPasteText(positionals, values);
+        case 'add-image': {
+            const { cmdCanvasAddImage } = await import('./canvas-image.js');
+            return cmdCanvasAddImage(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
@@ -301,6 +305,7 @@ function printHelp() {
   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 add-image ./photo.png --composition <id> [--x N --y N --width N --height N]
   beehaven canvas help [domain]                 # workspace RPC catalog (cloud), grouped
   beehaven canvas help --search <q>             # keyword search the catalog
   beehaven canvas record start [sessionId]

package/dist/commands/help.js

@@ -535,13 +535,15 @@ const PAGES = {
         related: ['cd', 'status', 'actions', 'workspaces'],
     },
     canvas: {
-        synopsis: 'beehaven canvas <open|invoke|query|actions|help|record> [args]',
+        synopsis: 'beehaven canvas <open|add-image|invoke|query|actions|help|record> [args]',
         description: `Interact with the FAB canvas (notes editor) from the CLI.
 
     Subcommands:
       open <noteId>          Open a note in the canvas editor
       invoke <action> [json] Call an editor-client action (local UI ops)
       query <action>         Read editor-client state
+      add-image <file>       Upload a local image and place it on a composition
+                             (--composition <id>, optional x/y/width/height)
       actions / list          List editor-client UI actions (LOCAL — what the
                              canvas UI can do)
       help [domain]          Show the workspace RPC catalog (CLOUD — what
@@ -563,6 +565,7 @@ const PAGES = {
             { cmd: 'beehaven canvas actions', note: 'editor UI actions (local)' },
             { cmd: 'beehaven canvas help', note: 'workspace RPC catalog (cloud)' },
             { cmd: 'beehaven canvas help --search "image"', note: 'find image-related RPCs' },
+            { cmd: 'beehaven canvas add-image ./photo.png --composition <id>', note: 'upload a local image and place it on the canvas' },
             { cmd: 'beehaven canvas invoke insert-block \'{"type":"text","text":"hi"}\'' },
         ],
         related: ['conversations', 'call', 'actions'],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "beehaven",
-  "version": "0.8.18",
-  "description": "Beehaven CLI \u2014 command your Clearly workspace, agents, and canvas from the terminal",
+  "version": "0.8.19",
+  "description": "Beehaven CLI — command your Clearly workspace, agents, and canvas from the terminal",
   "private": false,
   "type": "module",
   "bin": {

package/skills/clearly-canvas/SKILL.md

@@ -142,7 +142,10 @@ matches the chosen direction, then adapt and inspect it. It is not an art direct
 a quality guarantee. Custom compositions should use native nodes and your own builder.
 
 Read [authoring.md](authoring.md) before building. It covers the exact coordinate,
-batch, text, asset and MCP contracts. Consult `canvas-catalog` for action schemas
+batch, text, image-upload and MCP contracts. For a local image, use
+`beehaven canvas add-image <file> --composition <id>` when the installed CLI supports
+it; read authoring.md for the current CLI fallback and the MCP URL-only path.
+Consult `canvas-catalog` for action schemas
 instead of loading an exhaustive reference.
 
 ## 4. Build a representative surface, then complete the artifact

package/skills/clearly-canvas/authoring.md

@@ -105,11 +105,62 @@ Use `canvas.place {kind,id,x,y,w,h,name,parentId?}` to put a workspace object (d
 deck, sheet, board, ticket, project, site or file) on the canvas as a live card. With
 `parentId`, `x/y` are relative to that frame, like `canvas.create-node`. See
 [project-plans.md](project-plans.md).
-Use `canvas.list-sources`/`canvas.place-source` for library assets. A native image
-node accepts `src`. Upload local media using `canvas-upload-image` (discover its current
-schema), then place its returned URL. Inspect the actual asset before using it. Prefer
-provided, reusable or purpose-made imagery to random URL placeholders. Label temporary
-assets in the handoff and replace them when final assets are part of the request.
+Use `canvas.list-sources`/`canvas.place-source` for an existing library asset. A native
+image node accepts an absolute `http(s)` `src`, never a local path or raw base64.
+Inspect the actual asset before placing it. Prefer provided, reusable or purpose-made
+imagery to random URL placeholders. Label temporary assets in the handoff.
+
+### Local images from the CLI
+
+`beehaven canvas add-image` uploads a PNG, JPEG, WebP, GIF or AVIF from disk through
+`get-upload-url` → binary PUT → `file-uploaded {composition:true}`, then appends an
+image node with `canvas-add-image`. The binary does not cross the relay WebSocket.
+This matters above about 900 KB: sending multi-megabyte base64 through
+`canvas-upload-image` can exceed the relay message limit. The asset is filed under
+the composition rather than added as a loose item in Recents.
+
+```sh
+beehaven canvas add-image ./photo.png --composition <id> \
+  --x 120 --y 160 --width 600 --height 400 --json
+```
+
+The command reports `nodeId` and `imageFileId`. Coordinates are world coordinates;
+omit both `--x`/`--y` to use canvas auto-placement, and omit both size flags to use
+the image's native dimensions. Check `beehaven canvas` help on the installed CLI:
+older versions do not have this command. On one of those, use the documented
+`get-upload-url` → binary PUT → `file-uploaded` sequence, then
+`canvas-act {action:"canvas.create-node",args:{type:"image",src:<absolute URL>,x,y,w,h}}`.
+The upload intent's `publicUrl` may be `/f/...`; prefix the active relay's HTTPS
+origin before storing it as `src`. `beehaven teleport --composition` stores a file
+but does not place an image node. `canvas-upload-image` remains useful for small
+inline images, followed by `canvas.create-node` or `canvas-add-image` using its `url`.
+The CLI command caps a file at 100 MiB, and the workspace plan may impose a smaller
+single-file or remaining-storage limit. Uploading and rendering are separate checks:
+the headless renderer has image-count and memory budgets, so inspect a review PNG
+after adding large images instead of treating upload success as visual proof.
+In the editor, paste/drop also uses presigned binary PUT. Saved canvas images are
+registered under the composition without adding loose cards to Recents. If a large
+upload fails, retry the upload; it must not be inlined into the scene JSON.
+
+For a composed artboard, nest the image with `canvas.update-nodes` using the returned
+`nodeId` and `patch:{parentId:<frame id>,name:"descriptive layer name"}`. The
+membership-only patch keeps its world position. Review the artboard after this:
+reviewing a frame excludes overlapping top-level images that are not its children.
+Image nodes are square-edged by default. If you set `radius` for a rounded crop,
+omit a square backing tile behind it or give that tile the same radius; otherwise
+the backing shows through as dark wedges at the corners.
+
+### Images from MCP
+
+The seven artifact MCP tools do not upload local binary files or dispatch `canvas-act`.
+For an image already reachable by an absolute URL, read the composition with
+`clearly_read {type:"composition",target:<id>}`; append an image node
+`{id,type:"image",src,x,y,w,h,fit:"contain",parentId?}` to the returned complete node
+array; then call `clearly_write {type:"composition",target:<id>,content:<JSON array>,
+expectedRev:<canvasNodesRev>}`. Preserve every existing node. A stale revision is a
+merge prompt, never a reason to drop `expectedRev`. `clearly_edit` can change an
+existing image's `src`, `fit` or geometry, but cannot create a node. For a local file,
+use the CLI upload path first; an MCP-only client needs a URL it can already access.
 
 Current headless rendering can resolve images, including workspace media. A blank image
 can indicate fetch, decoding or budget failure; check its source and inspect a live view.

package/skills/index.json

@@ -17,7 +17,7 @@
       "project-plans.md",
       "review.mjs"
     ],
-    "sha": "fe0256c5ce9dea7c"
+    "sha": "21faa5f8d14beefe"
   },
   {
     "name": "agent-home",