canvas-populate

canvas-populate: Add Content to Canvases

Read ../canvas/references/canvas-spec.md for the full JSON format before any edit. Read ../canvas/references/performance-guide.md for node limits and constraints.

---

General Workflow

For every add operation:

1. Read the target canvas JSON. Parse nodes and edges arrays.
2. Collect existing IDs to prevent collisions.
3. Generate a new ID: [type]-[slug]-[unix-timestamp].
4. Calculate position using the auto-positioning algorithm (see canvas orchestrator).
5. Spacing check: Verify the calculated position has at least 80px horizontal and 60px vertical gap from ALL existing content nodes. If not, shift the position until spacing is clear.
6. Append the new node to the nodes array (after any groups — z-index ordering).
7. Validate: Run python3 scripts/canvas_validate.py <path> — check for overlaps and node count.
8. Write the updated canvas JSON.
9. Report: "Added [description] to [zone] zone at position ([x], [y])."

---

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.