🗺️ CanvasGuru

Build valid, crop-free .canvas knowledge maps for this fork’s canvas-page plugin. Canon: 📜 SSOT Bible. Live example: 🗺️ Site Map.

1. 🎯 When

Use a canvas when layout carries meaning — module maps, dependency graphs, mind maps, migration funnels, kanban boards. For inline flow inside a doc, prefer 🧜 MermaidGuru.

2. 🧩 Nodes

Document is { "nodes": [...], "edges": [...] }. Four node types, all need id, x, y, width, height:

Type	Extra field	Renders as
text	text	Inline GFM markdown
file	file	Clickable page + hover popover
link	url	Card (this fork — no iframe)
group	label, background?	Dashed container

• 📁 file paths are CONTENT-ROOT-RELATIVE: "file": "skills/gurus/MermaidGuru.md", never absolute, never vault-root. Label = filename minus extension.
• 🔗 External link nodes render as cards in this fork (the old iframe embed is gone), so they no longer need 300px of iframe height — size them like a wide text node.

3. 📏 Sizing

Crop is invisible in JSON and only shows in the viewport — oversize on purpose.

Node	Width	Height
File	400–460	60–80
Text (multi-line)	250–500	80–200, scale to content
Link (card)	400	120–160
Group	content + 80	content + 120

• ↕️ ≥100px vertical pitch between stacked nodes (node height + ≥20px gap; 100px grid for groups).
• 🔲 All coordinates snap to multiples of 20; groups round to 100.
• 🧱 First node inside a group sits at group_y + 40 (pad) + 60 (label area) — skipping the label area overlaps the title.
• ↔️ Groups ≥200px apart; never nest groups (spec 1.0 has no nesting).

4. 🎨 Colors

Preset 1–6 (or #hex) — assign meaning, not aesthetics:

#	Color	Meaning
1 🔴	Red	Critical / deprecated
2 🟠	Orange	Reference / outputs
3 🟡	Yellow	In-progress / plans
4 🟢	Green	Stable / infra
5 🔵	Cyan	Core / hub
6 🟣	Purple	Knowledge / skills

5. 🧷 Edges & Order

• 🧭 Always set fromSide/toSide facing the target; add toEnd: "arrow" for direction; labels 1–2 verb words.
• 🪜 Z-order = array order: groups FIRST (background), then text, then file/link (foreground, clickable). Containment is geometry-only — a node belongs to a group when it falls fully inside its bounds.
• 🆔 IDs kebab-case: grp-*, f-*, txt-*, lnk-*, e-from-to.

6. ✅ Verify

• Every fromNode/toNode references a real node id.
• Groups precede their contained nodes in the array.
• Coordinates are multiples of 20; no unintended overlap.
• file paths are content-root-relative and exist.
• Colors encode meaning; JSON valid, 2-space indent, no // comments.

The deploy → screenshot → evaluate loop is the main agent’s job; author the JSON to pass it first time. Diagram form instead → 🧜 MermaidGuru.