Canvas Populate

Node Operations

add image (/canvas add image [path or url])

Resolve the image:

• If URL (starts with http): download with curl -sL [url] -o [media_dir]/[filename]. Derive filename from URL path, or use img-[timestamp].jpg if unclear.
• If local path outside canvas dir: cp [path] [media_dir]/
• If already canvas-relative: use as-is.

Detect aspect ratio:

python3 -c "from PIL import Image; img=Image.open('[path]'); print(img.width, img.height)"
# or fallback
identify -format '%w %h' [path]

Map to the sizing table in ../canvas/references/canvas-spec.md (7 ratios + PDF + fallback).

Create file node with calculated dimensions. Position using auto-layout.

add text (/canvas add text [content])

{
  "id": "text-[slug]-[timestamp]",
  "type": "text",
  "text": "[content]",
  "x": 0, "y": 0,
  "width": 300, "height": 120
}

For multi-line content, estimate height: count newlines, multiply by 24, add 40px padding. Minimum 120px.

add pdf (/canvas add pdf [path])

Copy to [media_dir]/ if outside canvas dir. Fixed size: width=400, height=520.

add note (/canvas add note [wiki-page])

1. Search for a file matching the page name (case-insensitive, partial match).
2. Use "type": "file" with vault-relative path. Not "type": "link" — that's for URLs only.
3. Default size: width=300, height=100.

add link (/canvas add link [url])

{
  "id": "link-[slug]-[timestamp]",
  "type": "link",
  "url": "[url]",
  "x": 0, "y": 0,
  "width": 400, "height": 120
}

Obsidian fetches Open Graph preview automatically.

add mermaid (/canvas add mermaid [code])

Mermaid renders natively in Obsidian text nodes. Wrap in a fenced code block:

{
  "id": "text-mermaid-[timestamp]",
  "type": "text",
  "text": "```mermaid\n[code]\n```",
  "x": 0, "y": 0,
  "width": 500, "height": 400,
  "color": "5"
}

Wider text nodes work better for Mermaid (min 400px wide, 300px tall).

add svg (/canvas add svg [description or path])

• If path: copy SVG to media dir, add as file node. Width=400, height based on viewBox aspect ratio.
• If description: delegate to /svg skill to generate, then add the output file.
• SVGs render as <img> — no interactivity. Must have viewBox attribute.

add gif (/canvas add gif [description or path])

• If path: copy GIF to media dir, add as file node.
• If description: delegate to /claude-gif-generate skill, then add the output.
• Performance limit: max 3 GIFs per canvas, max 480px width. Warn if exceeded.

add banana (/canvas add banana [prompt])

1. Check if banana skill is available. If not: "Install the banana skill for AI image generation."
2. Delegate to banana skill with the prompt.
3. Wait for image generation.
4. Add the generated image as a file node (detect aspect ratio, auto-size).
5. Log the path to .recent-images.txt in the canvas directory.

Zone Operations

zone (/canvas zone [name] [color])

1. Read canvas JSON.
2. Find max_y of all existing nodes. Use -80 if canvas is empty (consistent with starter canvas layout where title is at y=-300 and default zone at y=-140):

   if not canvas_nodes:
       max_y = -80
   else:
       max_y = max(n["y"] + n.get("height", 0) for n in canvas_nodes) + 60
   

3. Create group node:

{
  "id": "zone-[slug]-[timestamp]",
  "type": "group",
  "label": "[name]",
  "x": -400,
  "y": "[max_y]",
  "width": 1000,
  "height": 400,
  "color": "[color or '4']"
}

Valid colors: "1"=red "2"=orange "3"=yellow "4"=green "5"=cyan "6"=purple

4. Insert the group node BEFORE content nodes in the array (z-index: groups render behind).
5. Write and report.

Edge Operations

connect (/canvas connect [from] [to] [label])

1. Read canvas JSON.
2. Find from and to nodes by ID, label text, or partial match.
3. If ambiguous, list matches and ask the user to clarify.
4. Create edge:

{
  "id": "e-[from-slug]-[to-slug]-[timestamp]",
  "fromNode": "[from-id]",
  "toNode": "[to-id]",
  "toEnd": "arrow"
}

5. Omit fromSide/toSide for auto-routing (better results).
6. Add optional label if provided.
7. Write and report.

Banana Import

from banana (/canvas from banana)

1. Check [canvas_dir]/.recent-images.txt for recently logged image paths.
2. If not found or empty: search for images modified in the last 10 minutes:

   find [media_dir] -name "*.png" -o -name "*.jpg" -newer /tmp/ten-min-ago
   

3. If still none: show the 5 most recently modified images.
4. Present list: "Found N recent images. Add to canvas? Which zone?"
5. On confirmation: add each using the add image logic.

Media Directory

• Vault mode: _attachments/images/canvas/
• Standalone mode: .canvases/assets/
• Create if it doesn't exist.
• All file node paths must be relative to the vault/project root.