From cf67df2f8c1f2f981217cffdd504c12cd52b7182 Mon Sep 17 00:00:00 2001
From: Legacynnn <danmelomour@gmail.com>
Date: Thu, 25 Jun 2026 21:49:00 -0300
Subject: [PATCH] feat(plan-canvas): freeform figma-style prototyping surface +
 resilient parsing

Rework <PlanCanvas> from an auto-laid mind-map into a pan/zoom figma board:
agent-positioned frames embedding live previews, greyscale wireframes, and
sticky notes, wired with labeled <CanvasFlow> arrows and grouped via
<CanvasGroup>. Legacy connects=-only plans still render via auto-layout.

Also harden plan MDX parsing: strip leaked agent tool-call wrapper tags
(e.g. a stray trailing </content></invoke> from a Write call) before parsing,
so one stray closing tag no longer drops the whole plan to plain Markdown and
blanks the canvas.
---
 .changeset/figma-plan-canvas.md               |   8 +
 src-tauri/src/agents/system_prompt.rs         |   8 +-
 .../components/canvas/auto-layout.test.ts     |  84 ++++++
 .../components/canvas/auto-layout.ts          | 125 +++++++++
 .../components/canvas/build-graph.test.ts     | 217 +++++++++++-----
 .../components/canvas/build-graph.ts          | 240 +++++++++++++-----
 .../components/canvas/canvas-node.tsx         |  73 ------
 .../components/canvas/design-toolbar.tsx      |  34 +++
 .../components/canvas/flow-edge.tsx           | 113 +++++++++
 .../components/canvas/frame-kinds.test.ts     |  60 +++++
 .../components/canvas/frame-kinds.ts          |  75 ++++++
 .../components/canvas/frames/frame-chrome.tsx |  67 +++++
 .../components/canvas/frames/group-node.tsx   |  39 +++
 .../components/canvas/frames/note-frame.tsx   |  26 ++
 .../canvas/frames/preview-frame.test.tsx      |  37 +++
 .../canvas/frames/preview-frame.tsx           |  20 ++
 .../canvas/frames/wireframe-frame.tsx         |  30 +++
 .../plan-viewer/components/canvas/index.tsx   |  19 +-
 .../components/canvas/layout.test.ts          |  74 ------
 .../plan-viewer/components/canvas/layout.ts   |  42 ---
 .../components/canvas/node-kinds.test.ts      |  20 --
 .../components/canvas/node-kinds.ts           |  35 ---
 .../canvas/plan-canvas-render.test.tsx        |  59 +++++
 .../components/canvas/plan-canvas-surface.tsx | 158 ++++++++++--
 .../components/canvas/plan-canvas.test.tsx    |  12 +-
 .../components/canvas/theme-modes.test.ts     |  33 +++
 .../components/canvas/theme-modes.ts          |  96 +++++++
 src/features/plan-viewer/mdx/parse.test.ts    | 134 ++++++++++
 src/features/plan-viewer/mdx/parse.ts         |  10 +-
 src/features/plan-viewer/mdx/registry.tsx     |   8 +
 .../plan-viewer/mdx/strip-leaked-tags.test.ts |  71 ++++++
 .../plan-viewer/mdx/strip-leaked-tags.ts      |  57 +++++
 32 files changed, 1675 insertions(+), 409 deletions(-)
 create mode 100644 .changeset/figma-plan-canvas.md
 create mode 100644 src/features/plan-viewer/components/canvas/auto-layout.test.ts
 create mode 100644 src/features/plan-viewer/components/canvas/auto-layout.ts
 delete mode 100644 src/features/plan-viewer/components/canvas/canvas-node.tsx
 create mode 100644 src/features/plan-viewer/components/canvas/design-toolbar.tsx
 create mode 100644 src/features/plan-viewer/components/canvas/flow-edge.tsx
 create mode 100644 src/features/plan-viewer/components/canvas/frame-kinds.test.ts
 create mode 100644 src/features/plan-viewer/components/canvas/frame-kinds.ts
 create mode 100644 src/features/plan-viewer/components/canvas/frames/frame-chrome.tsx
 create mode 100644 src/features/plan-viewer/components/canvas/frames/group-node.tsx
 create mode 100644 src/features/plan-viewer/components/canvas/frames/note-frame.tsx
 create mode 100644 src/features/plan-viewer/components/canvas/frames/preview-frame.test.tsx
 create mode 100644 src/features/plan-viewer/components/canvas/frames/preview-frame.tsx
 create mode 100644 src/features/plan-viewer/components/canvas/frames/wireframe-frame.tsx
 delete mode 100644 src/features/plan-viewer/components/canvas/layout.test.ts
 delete mode 100644 src/features/plan-viewer/components/canvas/layout.ts
 delete mode 100644 src/features/plan-viewer/components/canvas/node-kinds.test.ts
 delete mode 100644 src/features/plan-viewer/components/canvas/node-kinds.ts
 create mode 100644 src/features/plan-viewer/components/canvas/plan-canvas-render.test.tsx
 create mode 100644 src/features/plan-viewer/components/canvas/theme-modes.test.ts
 create mode 100644 src/features/plan-viewer/components/canvas/theme-modes.ts
 create mode 100644 src/features/plan-viewer/mdx/strip-leaked-tags.test.ts
 create mode 100644 src/features/plan-viewer/mdx/strip-leaked-tags.ts

diff --git a/.changeset/figma-plan-canvas.md b/.changeset/figma-plan-canvas.md
new file mode 100644
index 000000000..636d597fe
--- /dev/null
+++ b/.changeset/figma-plan-canvas.md
@@ -0,0 +1,8 @@
+---
+"helmor": minor
+---
+
+Reworked the plan canvas into a freeform, figma-style prototyping surface and hardened plan parsing against leaked tool-call tags.
+
+- `<PlanCanvas>` is now a pan/zoom board of agent-positioned frames that embed live previews, greyscale wireframes, and sticky notes, wired together with labeled flow arrows and grouped into labeled sections. Older `connects=`-only mind-map plans still render via an auto-layout fallback, so nothing breaks.
+- Plans that accidentally contain leaked agent tool-call wrapper tags (e.g. a stray trailing `</content></invoke>` from a Write call) no longer collapse to plain text. The parser strips the stray tags before parsing so the canvas and other rich plan components keep rendering.
diff --git a/src-tauri/src/agents/system_prompt.rs b/src-tauri/src/agents/system_prompt.rs
index 207f34e0c..27f5d9a2d 100644
--- a/src-tauri/src/agents/system_prompt.rs
+++ b/src-tauri/src/agents/system_prompt.rs
@@ -246,8 +246,10 @@ Allowed components:
   - `<OpenQuestions>` containing a markdown list of decisions that need the user's input.
   - `<AnnotatedCode lang="…" note="…">` … code … `</AnnotatedCode>` for an annotated snippet. PREFER passing the code as the component's children (between the tags) — especially when it contains quotes or `<…>`. Only use a `code="…"` attribute for short, quote-free one-liners. NEVER put backslash-escaped quotes (`\"`) inside an attribute value: JSX attributes have no backslash escaping, so a value like `code="<Foo bar=\"x\">"` is invalid markup and will fail to render.
   - `<Diagram>` containing mermaid diagram source (no code fences) for architecture or data flow.
-  - `<PlanCanvas direction="TB|LR">` containing `<CanvasNode>` children — an interactive node graph shown at the TOP of the plan. ALWAYS lead a non-trivial plan with one. It must map the ACTUAL logic of THIS task — its real subsystems/modules/files/steps and how they genuinely depend on or flow into each other (use `connects` for real edges: what calls/feeds/blocks what, not decorative links). Do NOT emit a generic five-box "overview/structure/visuals/decisions" diagram — that conveys nothing. Pick `kind` to match each node's real role (see below) so the graph is legible. Use `direction="LR"` for a pipeline/flow and `"TB"` for a hierarchy. Keep it focused (roughly 3–8 nodes) but every node and edge should carry real meaning. Do NOT close the graph into a loop — never wire the last node back to the first/overview node just to "complete" it; only add an edge where a real dependency exists. The graph should stay acyclic.
-  - `<CanvasNode id="unique-id" title="Short title" connects="other-id,another-id">` … short markdown … `</CanvasNode>` — one box in the PlanCanvas. `id` must be unique; `connects` is a comma-separated list of other node ids this box links to. Keep the body to a sentence or a short list. Use a self-closing `<CanvasNode ... />` when there is no body. CanvasNode is ONLY valid inside a PlanCanvas. Set `kind` to the node's real role — it drives a coloured badge + icon: `resume` = the overview/summary node, `phase` = a sequenced step/milestone, `option` = an alternative/branch, `wireframe` = a UI/screen node, `note` = plain detail (the default). Choose deliberately so the badges read as a real map.
+  - `<PlanCanvas theme="repo|wireframe" height="640">` containing `<CanvasNode>` / `<CanvasFlow>` / `<CanvasGroup>` children — a freeform, figma-style board shown at the TOP of the plan. ALWAYS lead a non-trivial UI/design plan with one. You place frames at explicit coordinates, fill each with a real live preview, a low-fi wireframe, or a sticky note, and wire the user journey with labeled flow arrows. `theme="repo"` (default) renders polished, accent-colored frames; `theme="wireframe"` renders the whole board greyscale to focus on layout over color. `height` is the board's pixel height (optional, default 720 — go taller for a busy board). Frames float freely on the open canvas (no enclosing card), so lay them out left-to-right along the primary journey — flows enter a frame on its left edge and leave on its right — and leave GENEROUS gaps between frames (roughly 80–160px of empty space, more between groups) so the board reads as a spacious canvas, not a tight cluster. Group related frames with `<CanvasGroup>`. Keep it focused (roughly 3–10 frames) but every frame and arrow should carry real meaning. Cycles ARE allowed here: a real user journey may loop back. (A legacy `<PlanCanvas direction="TB|LR">` with `<CanvasNode connects="…">` and no coordinates still renders via auto-layout, but prefer the coordinate-based board.)
+  - `<CanvasNode id="unique-id" title="Short title" x="40" y="80" w="360" h="420" device="browser|app|mobile|panel|popover" accent="neutral|info|success|warning|danger|highlight">` … one `<Preview>` OR one `<Wireframe>` OR short markdown … `</CanvasNode>` — one frame on the board. `id` must be unique. `x`/`y` set the top-left position and `w`/`h` the size (all optional — omit them to auto-layout, but for a figma board set them so frames sit where you intend). The frame's kind is inferred from its body: a nested `<Preview>` makes a LIVE preview frame (high-fidelity, runs live on the canvas), a nested `<Wireframe>` makes a low-fi wireframe frame, and anything else is a sticky note for rationale. `device` picks the window/device chrome; `accent` colors the frame in `repo` theme. Self-close `<CanvasNode ... />` for an empty placeholder frame. CanvasNode is ONLY valid inside a PlanCanvas.
+  - `<CanvasFlow from="frame-id" to="frame-id" label="Submit" kind="primary|secondary|back" />` — a labeled arrow between two frames marking a user-flow transition. `kind` styles the line: `primary` is a solid accent path (the happy path), `secondary` and `back` are quieter dashed lines (branches / return steps). Self-closing. CanvasFlow is ONLY valid inside a PlanCanvas.
+  - `<CanvasGroup id="auth" title="Onboarding" contains="login,verify" accent="info" />` — a labeled section drawn BEHIND the listed frames to group a flow or area. `contains` is a comma-separated list of frame ids; the section auto-sizes to enclose them. Self-closing. CanvasGroup is ONLY valid inside a PlanCanvas.
   - `<Decision>` containing `<Option title="..." recommended>` … markdown pros/cons … `</Option>` children — present 2–4 candidate approaches as cards and mark the best one with the boolean `recommended` attribute. `<Option>` is ONLY valid inside a `<Decision>`.
   - `<BeforeAfter>` containing exactly one `<Before>` … markdown … `</Before>` and one `<After>` … markdown … `</After>` — a side-by-side comparison of current vs. proposed behavior. `<Before>`/`<After>` are ONLY valid inside a `<BeforeAfter>`.
   - `<Diff lang="...">` whose contents are unified-diff lines: each line starts with `+` (added line), `-` (removed line), or a space (unchanged context). Use it for concrete before/after code changes. `lang` is an optional language label.
@@ -535,6 +537,8 @@ mod tests {
         assert!(prompt.contains("Diagram"));
         assert!(prompt.contains("PlanCanvas"));
         assert!(prompt.contains("CanvasNode"));
+        assert!(prompt.contains("CanvasFlow"));
+        assert!(prompt.contains("CanvasGroup"));
         assert!(prompt.contains("Decision"));
         assert!(prompt.contains("BeforeAfter"));
         assert!(prompt.contains("Diff"));
diff --git a/src/features/plan-viewer/components/canvas/auto-layout.test.ts b/src/features/plan-viewer/components/canvas/auto-layout.test.ts
new file mode 100644
index 000000000..962cb5471
--- /dev/null
+++ b/src/features/plan-viewer/components/canvas/auto-layout.test.ts
@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+import { autoLayoutFrames, computeGroupBounds } from "./auto-layout";
+import type { FlowEdge, FrameNode, GroupSpec } from "./build-graph";
+
+function frame(id: string, position?: { x: number; y: number }): FrameNode {
+	return {
+		id,
+		frameKind: "note",
+		data: {
+			title: id,
+			frameKind: "note",
+			device: "browser",
+			theme: "repo",
+			accent: "neutral",
+			previewCode: "",
+			wireframeSource: "",
+			bodyBlocks: [],
+		},
+		position,
+		width: 200,
+		height: 120,
+	};
+}
+
+const edge: FlowEdge = {
+	id: "a->b",
+	source: "a",
+	target: "b",
+	label: "",
+	kind: "primary",
+};
+
+describe("autoLayoutFrames", () => {
+	it("assigns positions to a fully coordless graph (Dagre fallback)", () => {
+		const out = autoLayoutFrames([frame("a"), frame("b")], [edge], "LR");
+		expect(out.every((f) => f.position != null)).toBe(true);
+		const [a, b] = out;
+		expect(a.position).not.toEqual(b.position);
+	});
+
+	it("leaves a fully positioned graph untouched", () => {
+		const a = frame("a", { x: 10, y: 20 });
+		const b = frame("b", { x: 300, y: 20 });
+		const out = autoLayoutFrames([a, b], [], "LR");
+		expect(out[0].position).toEqual({ x: 10, y: 20 });
+		expect(out[1].position).toEqual({ x: 300, y: 20 });
+	});
+
+	it("fills only the coordless frames in a mixed graph", () => {
+		const a = frame("a", { x: 10, y: 20 });
+		const out = autoLayoutFrames([a, frame("b")], [], "LR");
+		expect(out[0].position).toEqual({ x: 10, y: 20 });
+		expect(out[1].position).toBeDefined();
+	});
+});
+
+describe("computeGroupBounds", () => {
+	it("frames the bounding box of its members", () => {
+		const a = frame("a", { x: 0, y: 0 });
+		const b = frame("b", { x: 300, y: 100 });
+		const group: GroupSpec = {
+			id: "g",
+			title: "Sec",
+			contains: ["a", "b"],
+			accent: "info",
+		};
+		const [bounds] = computeGroupBounds([group], [a, b]);
+		// Encloses both members (a at 0,0 and b ending at 500,220) with padding.
+		expect(bounds.x).toBeLessThan(0);
+		expect(bounds.y).toBeLessThan(0);
+		expect(bounds.width).toBeGreaterThan(500);
+		expect(bounds.height).toBeGreaterThan(220);
+	});
+
+	it("skips a group whose members have no position", () => {
+		const group: GroupSpec = {
+			id: "g",
+			title: "Sec",
+			contains: ["ghost"],
+			accent: "neutral",
+		};
+		expect(computeGroupBounds([group], [frame("a")])).toHaveLength(0);
+	});
+});
diff --git a/src/features/plan-viewer/components/canvas/auto-layout.ts b/src/features/plan-viewer/components/canvas/auto-layout.ts
new file mode 100644
index 000000000..09cc41f90
--- /dev/null
+++ b/src/features/plan-viewer/components/canvas/auto-layout.ts
@@ -0,0 +1,125 @@
+import dagre from "@dagrejs/dagre";
+import type { CanvasGraph, FrameNode, GroupSpec } from "./build-graph";
+
+/** Auto-layout direction, from `<PlanCanvas direction="…">` (legacy coordless). */
+export type CanvasDirection = "TB" | "LR";
+
+export function parseDirection(value: string | undefined): CanvasDirection {
+	return value === "LR" ? "LR" : "TB";
+}
+
+const GROUP_PADDING = 36;
+const GROUP_HEADER = 26;
+const STACK_GAP = 72;
+
+/** Run Dagre over every frame, sizing each by its own width/height. Cycles are
+ * tolerated (Dagre breaks them internally) so user journeys can loop. */
+function dagreLayout(
+	frames: FrameNode[],
+	edges: CanvasGraph["edges"],
+	direction: CanvasDirection,
+): FrameNode[] {
+	const g = new dagre.graphlib.Graph();
+	g.setGraph({ rankdir: direction, nodesep: 110, ranksep: 160 });
+	g.setDefaultEdgeLabel(() => ({}));
+	for (const frame of frames) {
+		g.setNode(frame.id, { width: frame.width, height: frame.height });
+	}
+	for (const edge of edges) {
+		g.setEdge(edge.source, edge.target);
+	}
+	dagre.layout(g);
+	return frames.map((frame) => {
+		const pos = g.node(frame.id);
+		// Dagre returns the node center; React Flow wants the top-left corner.
+		return {
+			...frame,
+			position: { x: pos.x - frame.width / 2, y: pos.y - frame.height / 2 },
+		};
+	});
+}
+
+/** Bounding box of frames that already have a position. */
+function boundsOf(frames: FrameNode[]): {
+	minX: number;
+	minY: number;
+	maxX: number;
+	maxY: number;
+} {
+	let minX = Number.POSITIVE_INFINITY;
+	let minY = Number.POSITIVE_INFINITY;
+	let maxX = Number.NEGATIVE_INFINITY;
+	let maxY = Number.NEGATIVE_INFINITY;
+	for (const f of frames) {
+		if (!f.position) continue;
+		minX = Math.min(minX, f.position.x);
+		minY = Math.min(minY, f.position.y);
+		maxX = Math.max(maxX, f.position.x + f.width);
+		maxY = Math.max(maxY, f.position.y + f.height);
+	}
+	return { minX, minY, maxX, maxY };
+}
+
+/**
+ * Ensure every frame has a position.
+ * - Fully coordless graph (old `connects=` plans): Dagre-layout everything.
+ * - Fully positioned graph (new freeform plans): return as-is.
+ * - Mixed: honor authored coords, stack the coordless frames in a column just
+ *   right of the positioned cluster so nothing overlaps.
+ */
+export function autoLayoutFrames(
+	frames: FrameNode[],
+	edges: CanvasGraph["edges"],
+	direction: CanvasDirection,
+): FrameNode[] {
+	const missing = frames.filter((f) => !f.position);
+	if (missing.length === 0) return frames;
+	if (missing.length === frames.length) {
+		return dagreLayout(frames, edges, direction);
+	}
+	const { maxX, minY } = boundsOf(frames);
+	const startX = Number.isFinite(maxX) ? maxX + STACK_GAP : 0;
+	let cursorY = Number.isFinite(minY) ? minY : 0;
+	return frames.map((frame) => {
+		if (frame.position) return frame;
+		const position = { x: startX, y: cursorY };
+		cursorY += frame.height + STACK_GAP;
+		return { ...frame, position };
+	});
+}
+
+export type GroupBounds = {
+	spec: GroupSpec;
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+};
+
+/**
+ * Compute each group's background rectangle from its member frames' positions
+ * (run AFTER {@link autoLayoutFrames} so every member has a position). Padding
+ * leaves room for the group's title strip above its members.
+ */
+export function computeGroupBounds(
+	groups: GroupSpec[],
+	frames: FrameNode[],
+): GroupBounds[] {
+	const byId = new Map(frames.map((f) => [f.id, f]));
+	const out: GroupBounds[] = [];
+	for (const spec of groups) {
+		const members = spec.contains
+			.map((id) => byId.get(id))
+			.filter((f): f is FrameNode => f != null && f.position != null);
+		if (members.length === 0) continue;
+		const { minX, minY, maxX, maxY } = boundsOf(members);
+		out.push({
+			spec,
+			x: minX - GROUP_PADDING,
+			y: minY - GROUP_PADDING - GROUP_HEADER,
+			width: maxX - minX + GROUP_PADDING * 2,
+			height: maxY - minY + GROUP_PADDING * 2 + GROUP_HEADER,
+		});
+	}
+	return out;
+}
diff --git a/src/features/plan-viewer/components/canvas/build-graph.test.ts b/src/features/plan-viewer/components/canvas/build-graph.test.ts
index 6d3bf1dcf..722fcf900 100644
--- a/src/features/plan-viewer/components/canvas/build-graph.test.ts
+++ b/src/features/plan-viewer/components/canvas/build-graph.test.ts
@@ -2,104 +2,193 @@ import { describe, expect, it } from "vitest";
 import type { PlanBlock } from "../../mdx/parse";
 import { buildCanvasGraph } from "./build-graph";
 
-function node(
-	id: string,
+function comp(
+	name: string,
 	props: Record<string, string>,
+	rawText = "",
 	children: PlanBlock[] = [],
 ): PlanBlock {
 	return {
 		kind: "component",
-		id,
-		name: "CanvasNode",
+		id: `b-${name}-${props.id ?? ""}`,
+		name,
 		props,
-		rawText: "",
+		rawText,
 		childBlocks: children,
 	};
 }
 
+function node(
+	props: Record<string, string>,
+	children: PlanBlock[] = [],
+): PlanBlock {
+	return comp("CanvasNode", props, "", children);
+}
+
 describe("buildCanvasGraph", () => {
-	it("builds nodes from CanvasNode blocks", () => {
-		const { nodes } = buildCanvasGraph([
-			node("b0", { id: "a", title: "A" }),
-			node("b1", { id: "b", title: "B" }),
-		]);
-		expect(nodes.map((n) => n.id)).toEqual(["a", "b"]);
-		expect(nodes[0].data.title).toBe("A");
+	it("builds a frame per CanvasNode, carrying title", () => {
+		const { frames } = buildCanvasGraph(
+			[node({ id: "a", title: "A" }), node({ id: "b", title: "B" })],
+			"repo",
+		);
+		expect(frames.map((f) => f.id)).toEqual(["a", "b"]);
+		expect(frames[0].data.title).toBe("A");
 	});
 
-	it("builds edges from connects and drops dangling targets", () => {
-		const { edges } = buildCanvasGraph([
-			node("b0", { id: "a", title: "A", connects: "b, missing" }),
-			node("b1", { id: "b", title: "B" }),
-		]);
-		expect(edges).toHaveLength(1);
-		expect(edges[0]).toMatchObject({ source: "a", target: "b" });
+	it("honors explicit x/y coordinates and flags hasCoords", () => {
+		const { frames, hasCoords } = buildCanvasGraph(
+			[node({ id: "a", title: "A", x: "40", y: "80" })],
+			"repo",
+		);
+		expect(frames[0].position).toEqual({ x: 40, y: 80 });
+		expect(hasCoords).toBe(true);
 	});
 
-	it("synthesizes an id from the block id when id prop is absent", () => {
-		const { nodes } = buildCanvasGraph([node("b7", { title: "No id" })]);
-		expect(nodes[0].id).toBe("b7");
+	it("leaves position undefined when coords are absent", () => {
+		const { frames, hasCoords } = buildCanvasGraph(
+			[node({ id: "a", title: "A" })],
+			"repo",
+		);
+		expect(frames[0].position).toBeUndefined();
+		expect(hasCoords).toBe(false);
 	});
 
-	it("ignores non-CanvasNode child blocks", () => {
-		const { nodes } = buildCanvasGraph([
-			{ kind: "prose", id: "p0", markdown: "stray" },
-			node("b0", { id: "a", title: "A" }),
-		]);
-		expect(nodes.map((n) => n.id)).toEqual(["a"]);
+	it("infers a preview frame from a nested Preview and lifts its code", () => {
+		const { frames } = buildCanvasGraph(
+			[
+				node({ id: "a", title: "A" }, [
+					comp("Preview", {}, "function App() {}"),
+				]),
+			],
+			"repo",
+		);
+		expect(frames[0].frameKind).toBe("preview");
+		expect(frames[0].data.previewCode).toContain("function App()");
 	});
 
-	it("carries the node body blocks for rendering", () => {
-		const body: PlanBlock = { kind: "prose", id: "p", markdown: "hi" };
-		const { nodes } = buildCanvasGraph([
-			node("b0", { id: "a", title: "A" }, [body]),
-		]);
-		expect(nodes[0].data.bodyBlocks).toEqual([body]);
+	it("infers a wireframe frame from a nested Wireframe and lifts its source", () => {
+		const { frames } = buildCanvasGraph(
+			[
+				node({ id: "a", title: "A" }, [
+					comp("Wireframe", { surface: "mobile" }, "row\n  button Go"),
+				]),
+			],
+			"repo",
+		);
+		expect(frames[0].frameKind).toBe("wireframe");
+		expect(frames[0].data.wireframeSource).toContain("button Go");
+		expect(frames[0].data.device).toBe("mobile");
 	});
 
-	it("deduplicates nodes that share an id", () => {
-		const { nodes } = buildCanvasGraph([
-			node("b0", { id: "a", title: "First" }),
-			node("b1", { id: "a", title: "Second" }),
-		]);
-		expect(nodes).toHaveLength(1);
-		expect(nodes[0].data.title).toBe("First");
+	it("defaults a bodyless / old-kind node to a note frame", () => {
+		const { frames } = buildCanvasGraph(
+			[node({ id: "a", title: "A", kind: "resume" })],
+			"repo",
+		);
+		expect(frames[0].frameKind).toBe("note");
 	});
 
-	it("deduplicates repeated edge targets", () => {
-		const { edges } = buildCanvasGraph([
-			node("b0", { id: "a", title: "A", connects: "b,b" }),
-			node("b1", { id: "b", title: "B" }),
-		]);
+	it("propagates the canvas theme onto frame data", () => {
+		const { frames } = buildCanvasGraph(
+			[node({ id: "a", title: "A" })],
+			"wireframe",
+		);
+		expect(frames[0].data.theme).toBe("wireframe");
+	});
+
+	it("builds labeled flow edges from CanvasFlow blocks", () => {
+		const { edges } = buildCanvasGraph(
+			[
+				node({ id: "a", title: "A" }),
+				node({ id: "b", title: "B" }),
+				comp("CanvasFlow", {
+					from: "a",
+					to: "b",
+					label: "Go",
+					kind: "primary",
+				}),
+			],
+			"repo",
+		);
 		expect(edges).toHaveLength(1);
+		expect(edges[0]).toMatchObject({
+			source: "a",
+			target: "b",
+			label: "Go",
+			kind: "primary",
+		});
 	});
 
-	it("drops self-loop edges", () => {
-		const { edges } = buildCanvasGraph([
-			node("b0", { id: "a", title: "A", connects: "a" }),
-		]);
+	it("keeps back-compat connects as edges", () => {
+		const { edges } = buildCanvasGraph(
+			[
+				node({ id: "a", title: "A", connects: "b,missing" }),
+				node({ id: "b", title: "B" }),
+			],
+			"repo",
+		);
+		expect(edges).toHaveLength(1);
+		expect(edges[0]).toMatchObject({ source: "a", target: "b" });
+	});
+
+	it("drops self-loops and unknown flow ids", () => {
+		const { edges } = buildCanvasGraph(
+			[
+				node({ id: "a", title: "A" }),
+				comp("CanvasFlow", { from: "a", to: "a" }),
+				comp("CanvasFlow", { from: "a", to: "ghost" }),
+			],
+			"repo",
+		);
 		expect(edges).toHaveLength(0);
 	});
 
-	it("drops a back-edge that would close a cycle (last → first clutter)", () => {
-		const { edges } = buildCanvasGraph([
-			node("b0", { id: "a", title: "A", connects: "b" }),
-			node("b1", { id: "b", title: "B", connects: "c" }),
-			node("b2", { id: "c", title: "C", connects: "a" }),
-		]);
-		// a→b and b→c survive; c→a is dropped because a already reaches c.
+	it("preserves cycles (user journeys loop)", () => {
+		const { edges } = buildCanvasGraph(
+			[
+				node({ id: "a", title: "A" }),
+				node({ id: "b", title: "B" }),
+				node({ id: "c", title: "C" }),
+				comp("CanvasFlow", { from: "a", to: "b" }),
+				comp("CanvasFlow", { from: "b", to: "c" }),
+				comp("CanvasFlow", { from: "c", to: "a" }),
+			],
+			"repo",
+		);
 		expect(edges.map((e) => `${e.source}->${e.target}`)).toEqual([
 			"a->b",
 			"b->c",
+			"c->a",
 		]);
 	});
 
-	it("carries the node kind from props, defaulting to note", () => {
-		const { nodes } = buildCanvasGraph([
-			node("b0", { id: "a", title: "A", kind: "resume" }),
-			node("b1", { id: "b", title: "B" }),
-		]);
-		expect(nodes[0].data.kind).toBe("resume");
-		expect(nodes[1].data.kind).toBe("note");
+	it("builds a group from CanvasGroup, keeping only known member ids", () => {
+		const { groups } = buildCanvasGraph(
+			[
+				node({ id: "a", title: "A" }),
+				node({ id: "b", title: "B" }),
+				comp("CanvasGroup", { id: "g", title: "Sec", contains: "a,b,ghost" }),
+			],
+			"repo",
+		);
+		expect(groups).toHaveLength(1);
+		expect(groups[0].contains).toEqual(["a", "b"]);
+	});
+
+	it("drops a group whose members are all unknown", () => {
+		const { groups } = buildCanvasGraph(
+			[comp("CanvasGroup", { id: "g", title: "Sec", contains: "ghost" })],
+			"repo",
+		);
+		expect(groups).toHaveLength(0);
+	});
+
+	it("deduplicates frames that share an id", () => {
+		const { frames } = buildCanvasGraph(
+			[node({ id: "a", title: "First" }), node({ id: "a", title: "Second" })],
+			"repo",
+		);
+		expect(frames).toHaveLength(1);
+		expect(frames[0].data.title).toBe("First");
 	});
 });
diff --git a/src/features/plan-viewer/components/canvas/build-graph.ts b/src/features/plan-viewer/components/canvas/build-graph.ts
index c7ac5a261..ac1ae3334 100644
--- a/src/features/plan-viewer/components/canvas/build-graph.ts
+++ b/src/features/plan-viewer/components/canvas/build-graph.ts
@@ -1,35 +1,76 @@
 import type { PlanBlock } from "../../mdx/parse";
-import { type CanvasNodeKind, normalizeKind } from "./node-kinds";
+import type { PlanAccent } from "../shell/accent";
+import {
+	DEFAULT_FRAME_SIZE,
+	type FrameDevice,
+	type FrameKind,
+	normalizeDevice,
+	parseCoord,
+	parseDimension,
+	resolveFrameKind,
+} from "./frame-kinds";
+import { type CanvasTheme, normalizeAccent } from "./theme-modes";
 
-/** Data carried on each React Flow node (rendered by canvas-node.tsx). */
-export type CanvasNodeData = {
+/** Direction of a user-flow arrow, set via `<CanvasFlow kind="...">`. */
+export type FlowKind = "primary" | "secondary" | "back";
+
+const FLOW_KINDS = new Set<FlowKind>(["primary", "secondary", "back"]);
+
+function normalizeFlowKind(value: string | undefined): FlowKind {
+	return value && FLOW_KINDS.has(value as FlowKind)
+		? (value as FlowKind)
+		: "primary";
+}
+
+/** Data carried on each frame React Flow node (rendered by the frame nodes). */
+export type FrameData = {
 	title: string;
+	frameKind: FrameKind;
+	device: FrameDevice;
+	theme: CanvasTheme;
+	accent: PlanAccent;
+	/** Raw React snippet for a preview frame (empty otherwise). */
+	previewCode: string;
+	/** Raw wireframe-DSL source for a wireframe frame (empty otherwise). */
+	wireframeSource: string;
+	/** Markdown body blocks for a note frame (empty otherwise). */
 	bodyBlocks: PlanBlock[];
-	/** Optional only because nodes may be constructed outside `buildCanvasGraph`
-	 * (e.g. test fixtures); `buildCanvasGraph` always resolves it via
-	 * `normalizeKind`. Consumers should default a missing value to "note". */
-	kind?: CanvasNodeKind;
 };
 
-export type CanvasGraphNode = {
+export type FrameNode = {
 	id: string;
-	type: "canvasNode";
-	data: CanvasNodeData;
-	position: { x: number; y: number };
+	frameKind: FrameKind;
+	data: FrameData;
+	/** Authored top-left position, or `undefined` → auto-layout assigns one. */
+	position?: { x: number; y: number };
+	width: number;
+	height: number;
 };
 
-export type CanvasGraphEdge = {
+export type FlowEdge = {
 	id: string;
 	source: string;
 	target: string;
+	label: string;
+	kind: FlowKind;
+};
+
+export type GroupSpec = {
+	id: string;
+	title: string;
+	contains: string[];
+	accent: PlanAccent;
 };
 
 export type CanvasGraph = {
-	nodes: CanvasGraphNode[];
-	edges: CanvasGraphEdge[];
+	frames: FrameNode[];
+	edges: FlowEdge[];
+	groups: GroupSpec[];
+	/** True when at least one frame carries an explicit position. */
+	hasCoords: boolean;
 };
 
-function splitConnects(value: string | undefined): string[] {
+function splitIds(value: string | undefined): string[] {
 	if (!value) return [];
 	return value
 		.split(",")
@@ -37,82 +78,145 @@ function splitConnects(value: string | undefined): string[] {
 		.filter((s) => s.length > 0);
 }
 
+/** Find the first nested component block with the given name (e.g. Preview). */
+function findChildComponent(
+	block: Extract<PlanBlock, { kind: "component" }>,
+	name: string,
+): Extract<PlanBlock, { kind: "component" }> | undefined {
+	for (const child of block.childBlocks) {
+		if (child.kind === "component" && child.name === name) {
+			return child;
+		}
+	}
+	return undefined;
+}
+
 /**
- * Convert a PlanCanvas component's child blocks into a React Flow graph.
- * Only `CanvasNode` component blocks become nodes; everything else is ignored.
- * Positions are all `{0,0}` here — `layout.ts` assigns real coordinates.
+ * Convert a `<PlanCanvas>`'s child blocks into a freeform frame graph:
+ * - each `<CanvasNode>` → a positioned frame (preview / wireframe / note),
+ * - each `<CanvasFlow>` (plus back-compat `connects=`) → a labeled flow edge,
+ * - each `<CanvasGroup>` → a section spec (bbox computed after layout).
+ * Positions are honored verbatim when authored; `auto-layout.ts` fills the rest.
  */
-export function buildCanvasGraph(childBlocks: PlanBlock[]): CanvasGraph {
-	const nodes: CanvasGraphNode[] = [];
+export function buildCanvasGraph(
+	childBlocks: PlanBlock[],
+	theme: CanvasTheme,
+): CanvasGraph {
+	const frames: FrameNode[] = [];
 	const ids = new Set<string>();
+	let hasCoords = false;
 
 	for (const block of childBlocks) {
-		if (block.kind !== "component" || block.name !== "CanvasNode") {
-			continue;
-		}
+		if (block.kind !== "component" || block.name !== "CanvasNode") continue;
 		const id = block.props.id?.trim() || block.id;
 		if (ids.has(id)) continue;
 		ids.add(id);
-		nodes.push({
+
+		const previewBlock = findChildComponent(block, "Preview");
+		const wireframeBlock = findChildComponent(block, "Wireframe");
+		const frameKind = resolveFrameKind(block.props.kind, {
+			hasPreview: previewBlock != null,
+			hasWireframe: wireframeBlock != null,
+		});
+		const device = normalizeDevice(
+			block.props.device ?? wireframeBlock?.props.surface,
+		);
+		const accent = normalizeAccent(block.props.accent);
+		const defaults = DEFAULT_FRAME_SIZE[frameKind];
+		const width = parseDimension(block.props.w, defaults.width);
+		const height = parseDimension(block.props.h, defaults.height);
+
+		const x = parseCoord(block.props.x);
+		const y = parseCoord(block.props.y);
+		const position = x != null && y != null ? { x, y } : undefined;
+		if (position) hasCoords = true;
+
+		frames.push({
 			id,
-			type: "canvasNode",
+			frameKind,
 			data: {
 				title: block.props.title?.trim() || id,
+				frameKind,
+				device,
+				theme,
+				accent,
+				previewCode: previewBlock?.rawText ?? "",
+				wireframeSource: wireframeBlock?.rawText ?? "",
 				bodyBlocks: block.childBlocks,
-				kind: normalizeKind(block.props.kind),
 			},
-			position: { x: 0, y: 0 },
+			position,
+			width,
+			height,
 		});
 	}
 
-	const edges: CanvasGraphEdge[] = [];
-	const seenEdgeIds = new Set<string>();
-	// Adjacency of edges accepted so far, used to keep the graph acyclic.
-	const adjacency = new Map<string, Set<string>>();
+	const edges = buildEdges(childBlocks, ids);
+	const groups = buildGroups(childBlocks, ids);
+	return { frames, edges, groups, hasCoords };
+}
+
+/** Flow edges from explicit `<CanvasFlow>` blocks AND back-compat `connects=`.
+ * Cycles are kept (user journeys legitimately loop); only self-loops, dangling
+ * ids, and duplicate ids are dropped. */
+function buildEdges(childBlocks: PlanBlock[], ids: Set<string>): FlowEdge[] {
+	const edges: FlowEdge[] = [];
+	const seen = new Set<string>();
+	const push = (
+		source: string,
+		target: string,
+		label: string,
+		kind: FlowKind,
+		id: string,
+	) => {
+		if (!ids.has(source) || !ids.has(target)) return;
+		if (source === target) return;
+		if (seen.has(id)) return;
+		seen.add(id);
+		edges.push({ id, source, target, label, kind });
+	};
+
+	let flowIndex = 0;
 	for (const block of childBlocks) {
-		if (block.kind !== "component" || block.name !== "CanvasNode") {
+		if (block.kind !== "component") continue;
+		if (block.name === "CanvasFlow") {
+			const source = block.props.from?.trim() ?? "";
+			const target = block.props.to?.trim() ?? "";
+			push(
+				source,
+				target,
+				block.props.label?.trim() ?? "",
+				normalizeFlowKind(block.props.kind),
+				`flow-${flowIndex++}-${source}->${target}`,
+			);
 			continue;
 		}
-		const source = block.props.id?.trim() || block.id;
-		for (const target of splitConnects(block.props.connects)) {
-			if (!ids.has(target)) continue; // drop dangling edges
-			if (target === source) continue; // drop self-loops (degenerate layout)
-			const id = `${source}->${target}`;
-			if (seenEdgeIds.has(id)) continue; // dedupe repeated targets (e.g. "b,b")
-			// Drop any edge that would close a loop (e.g. the agent wiring the last
-			// node back to the first). Cycles force dagre into a long edge sweeping
-			// across the whole graph, which reads as clutter — keep it a clean DAG.
-			if (canReach(adjacency, target, source)) continue;
-			seenEdgeIds.add(id);
-			const out = adjacency.get(source) ?? new Set<string>();
-			out.add(target);
-			adjacency.set(source, out);
-			edges.push({ id, source, target });
+		if (block.name === "CanvasNode") {
+			const source = block.props.id?.trim() || block.id;
+			for (const target of splitIds(block.props.connects)) {
+				push(source, target, "", "secondary", `connect-${source}->${target}`);
+			}
 		}
 	}
-
-	return { nodes, edges };
+	return edges;
 }
 
-/** True when `to` is already reachable from `from` via accepted edges — i.e.
- * adding `from → to` would create a cycle. Iterative DFS over the adjacency. */
-function canReach(
-	adjacency: Map<string, Set<string>>,
-	from: string,
-	to: string,
-): boolean {
-	const stack = [from];
+/** Section specs from `<CanvasGroup contains="a,b">` blocks (known ids only). */
+function buildGroups(childBlocks: PlanBlock[], ids: Set<string>): GroupSpec[] {
+	const groups: GroupSpec[] = [];
 	const seen = new Set<string>();
-	while (stack.length > 0) {
-		const current = stack.pop();
-		if (current === undefined) continue;
-		if (current === to) return true;
-		if (seen.has(current)) continue;
-		seen.add(current);
-		const next = adjacency.get(current);
-		if (next) {
-			for (const node of next) stack.push(node);
-		}
+	for (const block of childBlocks) {
+		if (block.kind !== "component" || block.name !== "CanvasGroup") continue;
+		const id = block.props.id?.trim() || block.id;
+		if (seen.has(id)) continue;
+		seen.add(id);
+		const contains = splitIds(block.props.contains).filter((m) => ids.has(m));
+		if (contains.length === 0) continue; // an empty section frames nothing
+		groups.push({
+			id,
+			title: block.props.title?.trim() || "",
+			contains,
+			accent: normalizeAccent(block.props.accent),
+		});
 	}
-	return false;
+	return groups;
 }
diff --git a/src/features/plan-viewer/components/canvas/canvas-node.tsx b/src/features/plan-viewer/components/canvas/canvas-node.tsx
deleted file mode 100644
index 8ff4f25ef..000000000
--- a/src/features/plan-viewer/components/canvas/canvas-node.tsx
+++ /dev/null
@@ -1,73 +0,0 @@
-import { Handle, type NodeProps, Position } from "@xyflow/react";
-import {
-	FlagIcon,
-	GitBranchIcon,
-	LayoutDashboardIcon,
-	LayoutTemplateIcon,
-	type LucideIcon,
-	StickyNoteIcon,
-} from "lucide-react";
-import { cn } from "@/lib/utils";
-import { renderBlocks } from "../../render-blocks";
-import { accentClasses, type PlanAccent } from "../shell/accent";
-import type { CanvasNodeData } from "./build-graph";
-import { type CanvasNodeKind, NODE_SIZE, normalizeKind } from "./node-kinds";
-
-/** Per-kind accent, icon, and short role label so a node's role is legible at a
- * glance — a phase reads differently from an option, an overview from a note. */
-const KIND_META: Record<
-	CanvasNodeKind,
-	{ accent: PlanAccent; icon: LucideIcon; label: string }
-> = {
-	note: { accent: "neutral", icon: StickyNoteIcon, label: "Note" },
-	resume: { accent: "info", icon: LayoutDashboardIcon, label: "Overview" },
-	option: { accent: "success", icon: GitBranchIcon, label: "Option" },
-	phase: { accent: "warning", icon: FlagIcon, label: "Phase" },
-	wireframe: { accent: "highlight", icon: LayoutTemplateIcon, label: "Mockup" },
-};
-
-/** A single card on the canvas. `data` comes from build-graph. */
-export function CanvasNode({ data, selected }: NodeProps) {
-	const d = data as unknown as CanvasNodeData;
-	const kind = normalizeKind(d.kind);
-	const meta = KIND_META[kind];
-	const styles = accentClasses(meta.accent);
-	const Icon = meta.icon;
-	return (
-		<div
-			style={{ width: NODE_SIZE[kind].width }}
-			className={cn(
-				// Flat, bordered surface (no shadow); `styles.container` supplies the
-				// per-kind fill + border so the node never sits white-on-white.
-				"max-h-[240px] overflow-hidden rounded-lg border transition-colors",
-				styles.container,
-				selected ? "border-ring ring-2 ring-ring" : "hover:border-ring/60",
-			)}
-		>
-			<Handle type="target" position={Position.Top} className="!bg-border" />
-			<div
-				className={cn(
-					"flex items-center gap-1.5 border-b border-border/50 px-3 py-2 font-medium text-small",
-					styles.header,
-				)}
-			>
-				<Icon className="size-3.5 shrink-0 opacity-80" strokeWidth={2} />
-				<span className="min-w-0 flex-1 truncate">{d.title}</span>
-				<span
-					className={cn(
-						"shrink-0 rounded border px-1 py-px text-nano uppercase tracking-wide",
-						styles.badge,
-					)}
-				>
-					{meta.label}
-				</span>
-			</div>
-			{d.bodyBlocks.length > 0 ? (
-				<div className="max-h-[180px] overflow-auto px-3 py-2 text-micro text-muted-foreground">
-					{renderBlocks(d.bodyBlocks)}
-				</div>
-			) : null}
-			<Handle type="source" position={Position.Bottom} className="!bg-border" />
-		</div>
-	);
-}
diff --git a/src/features/plan-viewer/components/canvas/design-toolbar.tsx b/src/features/plan-viewer/components/canvas/design-toolbar.tsx
new file mode 100644
index 000000000..30578b2fb
--- /dev/null
+++ b/src/features/plan-viewer/components/canvas/design-toolbar.tsx
@@ -0,0 +1,34 @@
+import { Panel, useReactFlow, useViewport } from "@xyflow/react";
+import { MaximizeIcon } from "lucide-react";
+import { cn } from "@/lib/utils";
+import type { CanvasTheme } from "./theme-modes";
+
+const BTN =
+	"flex cursor-pointer items-center gap-1 rounded px-1.5 py-0.5 text-foreground transition-colors hover:bg-accent hover:text-accent-foreground";
+
+/** Overlay toolbar: live theme pill, current zoom, and fit-to-view. Rendered
+ * inside `<ReactFlow>` so its hooks resolve against the flow instance. */
+export function DesignToolbar({ theme }: { theme: CanvasTheme }) {
+	const { fitView } = useReactFlow();
+	const { zoom } = useViewport();
+	return (
+		<Panel position="top-left">
+			<div className="flex items-center gap-0.5 rounded-md border border-border bg-card/90 p-1 text-mini backdrop-blur">
+				<span className="rounded bg-muted px-1.5 py-0.5 text-nano text-muted-foreground uppercase tracking-wide">
+					{theme}
+				</span>
+				<span className="px-1.5 text-muted-foreground tabular-nums">
+					{Math.round(zoom * 100)}%
+				</span>
+				<button
+					type="button"
+					className={cn(BTN)}
+					onClick={() => fitView({ padding: 0.2, duration: 200 })}
+				>
+					<MaximizeIcon className="size-3.5" />
+					Fit
+				</button>
+			</div>
+		</Panel>
+	);
+}
diff --git a/src/features/plan-viewer/components/canvas/flow-edge.tsx b/src/features/plan-viewer/components/canvas/flow-edge.tsx
new file mode 100644
index 000000000..09e655e03
--- /dev/null
+++ b/src/features/plan-viewer/components/canvas/flow-edge.tsx
@@ -0,0 +1,113 @@
+import {
+	BaseEdge,
+	EdgeLabelRenderer,
+	type EdgeProps,
+	getBezierPath,
+	type InternalNode,
+	type Node,
+	Position,
+	useInternalNode,
+} from "@xyflow/react";
+import type { CSSProperties } from "react";
+import type { FlowKind } from "./build-graph";
+
+/** Per-kind stroke: a solid accent for the primary path, quieter dashed lines
+ * for secondary branches and back/return journeys. */
+const STROKE: Record<FlowKind, CSSProperties> = {
+	primary: { stroke: "var(--primary)", strokeWidth: 1.75 },
+	secondary: {
+		stroke: "var(--muted-foreground)",
+		strokeWidth: 1.5,
+		strokeDasharray: "6 5",
+		opacity: 0.65,
+	},
+	back: {
+		stroke: "var(--muted-foreground)",
+		strokeWidth: 1.5,
+		strokeDasharray: "2 5",
+		opacity: 0.55,
+	},
+};
+
+/** Point where the line from `node`'s center toward `target`'s center crosses
+ * `node`'s border — so edges anchor to the frame edge, never cut into it. */
+function nodeIntersection(
+	node: InternalNode<Node>,
+	target: InternalNode<Node>,
+): { x: number; y: number } {
+	const w = (node.measured?.width ?? 0) / 2;
+	const h = (node.measured?.height ?? 0) / 2;
+	const x2 = node.internals.positionAbsolute.x + w;
+	const y2 = node.internals.positionAbsolute.y + h;
+	const x1 =
+		target.internals.positionAbsolute.x + (target.measured?.width ?? 0) / 2;
+	const y1 =
+		target.internals.positionAbsolute.y + (target.measured?.height ?? 0) / 2;
+	if (w === 0 || h === 0) return { x: x2, y: y2 };
+	const xx1 = (x1 - x2) / (2 * w) - (y1 - y2) / (2 * h);
+	const yy1 = (x1 - x2) / (2 * w) + (y1 - y2) / (2 * h);
+	const a = 1 / (Math.abs(xx1) + Math.abs(yy1) || 1);
+	const xx3 = a * xx1;
+	const yy3 = a * yy1;
+	return { x: w * (xx3 + yy3) + x2, y: h * (-xx3 + yy3) + y2 };
+}
+
+/** Which side of `node` the intersection point sits on (drives bezier tangent). */
+function edgeSide(
+	node: InternalNode<Node>,
+	point: { x: number; y: number },
+): Position {
+	const nx = node.internals.positionAbsolute.x;
+	const ny = node.internals.positionAbsolute.y;
+	const w = node.measured?.width ?? 0;
+	if (point.x <= nx + 1) return Position.Left;
+	if (point.x >= nx + w - 1) return Position.Right;
+	if (point.y <= ny + 1) return Position.Top;
+	return Position.Bottom;
+}
+
+/** A labeled, directional user-flow arrow. Floating: it anchors to the nearest
+ * border of each frame (computed from live node geometry), so the line meets the
+ * frame cleanly from whatever direction it approaches instead of always
+ * left→right — which keeps connections from slicing across the canvas. */
+export function FlowEdge({ id, source, target, markerEnd, data }: EdgeProps) {
+	const sourceNode = useInternalNode(source);
+	const targetNode = useInternalNode(target);
+	if (!sourceNode || !targetNode) return null;
+
+	const sp = nodeIntersection(sourceNode, targetNode);
+	const tp = nodeIntersection(targetNode, sourceNode);
+	const meta = (data ?? {}) as { kind?: FlowKind; label?: string };
+	const kind = meta.kind ?? "primary";
+	const [path, labelX, labelY] = getBezierPath({
+		sourceX: sp.x,
+		sourceY: sp.y,
+		sourcePosition: edgeSide(sourceNode, sp),
+		targetX: tp.x,
+		targetY: tp.y,
+		targetPosition: edgeSide(targetNode, tp),
+		curvature: 0.3,
+	});
+	return (
+		<>
+			<BaseEdge
+				id={id}
+				path={path}
+				markerEnd={markerEnd}
+				style={STROKE[kind]}
+			/>
+			{meta.label ? (
+				<EdgeLabelRenderer>
+					<div
+						className="nodrag nopan absolute rounded border border-border bg-card px-1.5 py-0.5 text-foreground text-nano shadow-sm"
+						style={{
+							transform: `translate(-50%,-50%) translate(${labelX}px,${labelY}px)`,
+						}}
+					>
+						{meta.label}
+					</div>
+				</EdgeLabelRenderer>
+			) : null}
+		</>
+	);
+}
diff --git a/src/features/plan-viewer/components/canvas/frame-kinds.test.ts b/src/features/plan-viewer/components/canvas/frame-kinds.test.ts
new file mode 100644
index 000000000..79c303fce
--- /dev/null
+++ b/src/features/plan-viewer/components/canvas/frame-kinds.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import {
+	DEFAULT_FRAME_SIZE,
+	parseCoord,
+	parseDimension,
+	resolveFrameKind,
+} from "./frame-kinds";
+
+describe("resolveFrameKind", () => {
+	it("prefers embedded content over the kind prop", () => {
+		expect(
+			resolveFrameKind("note", { hasPreview: true, hasWireframe: false }),
+		).toBe("preview");
+		expect(
+			resolveFrameKind("preview", { hasPreview: false, hasWireframe: true }),
+		).toBe("wireframe");
+	});
+
+	it("falls back to note for bodyless or old mind-map kinds", () => {
+		const empty = { hasPreview: false, hasWireframe: false };
+		expect(resolveFrameKind(undefined, empty)).toBe("note");
+		expect(resolveFrameKind("resume", empty)).toBe("note");
+		expect(resolveFrameKind("preview", empty)).toBe("note");
+	});
+});
+
+describe("parseCoord", () => {
+	it("parses finite numbers and rejects garbage", () => {
+		expect(parseCoord("40")).toBe(40);
+		expect(parseCoord(undefined)).toBeUndefined();
+		expect(parseCoord("abc")).toBeUndefined();
+	});
+
+	it("clamps absurd values", () => {
+		expect(parseCoord("99999999")).toBe(100_000);
+		expect(parseCoord("-99999999")).toBe(-100_000);
+	});
+});
+
+describe("parseDimension", () => {
+	it("falls back when absent or unparseable", () => {
+		expect(parseDimension(undefined, 200)).toBe(200);
+		expect(parseDimension("nope", 200)).toBe(200);
+	});
+
+	it("clamps to a sane range", () => {
+		expect(parseDimension("10", 200)).toBe(120);
+		expect(parseDimension("9999", 200)).toBe(2000);
+		expect(parseDimension("400", 200)).toBe(400);
+	});
+});
+
+describe("DEFAULT_FRAME_SIZE", () => {
+	it("sizes every kind, with preview taller than a note", () => {
+		expect(DEFAULT_FRAME_SIZE.note.width).toBeGreaterThan(0);
+		expect(DEFAULT_FRAME_SIZE.preview.height).toBeGreaterThan(
+			DEFAULT_FRAME_SIZE.note.height,
+		);
+	});
+});
diff --git a/src/features/plan-viewer/components/canvas/frame-kinds.ts b/src/features/plan-viewer/components/canvas/frame-kinds.ts
new file mode 100644
index 000000000..82a51c02c
--- /dev/null
+++ b/src/features/plan-viewer/components/canvas/frame-kinds.ts
@@ -0,0 +1,75 @@
+import {
+	normalizeSurface,
+	type WireframeSurface,
+} from "../wireframe/surface-frame";
+
+/**
+ * The visual role of a canvas frame. Unlike the old mind-map `CanvasNodeKind`
+ * (note/resume/option/phase/wireframe), a frame's kind decides which RENDERER
+ * the surface mounts: a live preview, a low-fi wireframe, or a sticky note.
+ * `screen` is an alias resolved by embedded content (see {@link resolveFrameKind}).
+ */
+export type FrameKind = "preview" | "wireframe" | "note" | "screen";
+
+/** The device/window chrome a frame is shown in — same taxonomy as wireframes. */
+export type FrameDevice = WireframeSurface;
+
+/** Resolve a `device=` prop to a known device, defaulting to `browser`. */
+export function normalizeDevice(value: string | undefined): FrameDevice {
+	return normalizeSurface(value);
+}
+
+/**
+ * Decide a frame's kind. Embedded content wins over the authored `kind` prop —
+ * a `<Preview>` child is unambiguously a preview frame, a `<Wireframe>` child a
+ * wireframe frame — so old mind-map kinds (resume/option/phase) and bare
+ * `kind="screen"` fall through to `note`, preserving their markdown body.
+ */
+export function resolveFrameKind(
+	_kindProp: string | undefined,
+	content: { hasPreview: boolean; hasWireframe: boolean },
+): FrameKind {
+	if (content.hasPreview) return "preview";
+	if (content.hasWireframe) return "wireframe";
+	// No embedded content: a bare `kind="preview"`/`"wireframe"` has nothing to
+	// render live, and old mind-map kinds aren't frame kinds — all become notes.
+	return "note";
+}
+
+export type FrameSize = { width: number; height: number };
+
+/** Default frame size by kind — generous so a preview reads near real-screen
+ * and frames have room to breathe across the canvas. */
+export const DEFAULT_FRAME_SIZE: Record<FrameKind, FrameSize> = {
+	preview: { width: 520, height: 600 },
+	screen: { width: 520, height: 600 },
+	wireframe: { width: 420, height: 520 },
+	note: { width: 300, height: 200 },
+};
+
+const COORD_LIMIT = 100_000;
+const MIN_DIM = 120;
+const MAX_DIM = 2000;
+
+/**
+ * Parse a coordinate prop (`x`/`y`) to a finite number, or `undefined` when
+ * absent/unparseable so the caller can fall back to auto-layout. Absurd values
+ * are clamped so one bad number can't fling a frame off the canvas.
+ */
+export function parseCoord(value: string | undefined): number | undefined {
+	if (value == null) return undefined;
+	const n = Number.parseFloat(value);
+	if (!Number.isFinite(n)) return undefined;
+	return Math.max(-COORD_LIMIT, Math.min(COORD_LIMIT, n));
+}
+
+/** Parse a dimension prop (`w`/`h`), clamped to a sane range, or `fallback`. */
+export function parseDimension(
+	value: string | undefined,
+	fallback: number,
+): number {
+	if (value == null) return fallback;
+	const n = Number.parseFloat(value);
+	if (!Number.isFinite(n)) return fallback;
+	return Math.max(MIN_DIM, Math.min(MAX_DIM, n));
+}
diff --git a/src/features/plan-viewer/components/canvas/frames/frame-chrome.tsx b/src/features/plan-viewer/components/canvas/frames/frame-chrome.tsx
new file mode 100644
index 000000000..4fbe6dd7f
--- /dev/null
+++ b/src/features/plan-viewer/components/canvas/frames/frame-chrome.tsx
@@ -0,0 +1,67 @@
+import { Handle, Position } from "@xyflow/react";
+import type { ReactNode } from "react";
+import { cn } from "@/lib/utils";
+import type { FrameDevice } from "../frame-kinds";
+import type { FrameThemeClasses } from "../theme-modes";
+
+/** Hidden connection handles. Flows enter on the left, leave on the right —
+ * which draws clean horizontal arrows for the common left→right journey. */
+const HANDLE =
+	"!h-2 !w-2 !min-h-0 !min-w-0 !rounded-full !border-0 !bg-border opacity-0";
+
+const DEVICE_LABEL: Record<FrameDevice, string> = {
+	browser: "Web",
+	app: "App",
+	mobile: "Mobile",
+	panel: "Panel",
+	popover: "Popover",
+};
+
+/**
+ * Figma-style frame shell. There is intentionally NO card around the frame —
+ * just a small floating title label above the content and hidden edge handles,
+ * so the embedded UI (a live preview, a device wireframe, a sticky note) floats
+ * freely on the canvas and provides its own surface. The greyscale body filter
+ * (wireframe theme) wraps the content.
+ */
+export function FrameChrome({
+	title,
+	device,
+	badge,
+	theme,
+	children,
+}: {
+	title: string;
+	device: FrameDevice;
+	badge?: string;
+	theme: FrameThemeClasses;
+	children: ReactNode;
+}) {
+	return (
+		<div className="relative flex h-full w-full flex-col gap-1.5">
+			<Handle type="target" position={Position.Left} className={HANDLE} />
+			<div className="flex shrink-0 items-center gap-1.5 px-0.5">
+				<span
+					className={cn(
+						"min-w-0 flex-1 truncate font-medium text-mini",
+						theme.header,
+					)}
+				>
+					{title}
+				</span>
+				<span
+					className={cn(
+						"shrink-0 rounded border bg-card px-1 py-px text-nano uppercase tracking-wide",
+						theme.badge,
+					)}
+				>
+					{badge ?? DEVICE_LABEL[device]}
+				</span>
+			</div>
+			<div className={cn("min-h-0 flex-1 overflow-hidden", theme.bodyFilter)}>
+				{children}
+			</div>
+			<Handle type="source" position={Position.Right} className={HANDLE} />
+		</div>
+	);
+}
diff --git a/src/features/plan-viewer/components/canvas/frames/group-node.tsx b/src/features/plan-viewer/components/canvas/frames/group-node.tsx
new file mode 100644
index 000000000..509a35add
--- /dev/null
+++ b/src/features/plan-viewer/components/canvas/frames/group-node.tsx
@@ -0,0 +1,39 @@
+import type { NodeProps } from "@xyflow/react";
+import { cn } from "@/lib/utils";
+import { accentClasses, type PlanAccent } from "../../shell/accent";
+import type { CanvasTheme } from "../theme-modes";
+
+export type GroupData = {
+	title: string;
+	accent: PlanAccent;
+	theme: CanvasTheme;
+};
+
+/** A section background that visually frames a set of member frames. It sits
+ * behind the frames and ignores pointer events so the frames stay interactive. */
+export function GroupNode({ data }: NodeProps) {
+	const d = data as unknown as GroupData;
+	const styles = accentClasses(d.theme === "wireframe" ? "neutral" : d.accent);
+	return (
+		<div
+			className={cn(
+				// No fill — just a faint dashed outline so the section frames its
+				// members without caging them in a solid box.
+				"pointer-events-none relative h-full w-full rounded-2xl border border-dashed",
+				styles.badge,
+				"bg-transparent opacity-70",
+			)}
+		>
+			{d.title ? (
+				<span
+					className={cn(
+						"absolute top-2 left-3 inline-flex items-center font-medium text-nano uppercase tracking-wide",
+						styles.header,
+					)}
+				>
+					{d.title}
+				</span>
+			) : null}
+		</div>
+	);
+}
diff --git a/src/features/plan-viewer/components/canvas/frames/note-frame.tsx b/src/features/plan-viewer/components/canvas/frames/note-frame.tsx
new file mode 100644
index 000000000..1deec2212
--- /dev/null
+++ b/src/features/plan-viewer/components/canvas/frames/note-frame.tsx
@@ -0,0 +1,26 @@
+import type { NodeProps } from "@xyflow/react";
+import { cn } from "@/lib/utils";
+import { renderBlocks } from "../../../render-blocks";
+import type { FrameData } from "../build-graph";
+import { frameTheme, solidSurface } from "../theme-modes";
+import { FrameChrome } from "./frame-chrome";
+
+/** A sticky-note frame: pinned rationale / markdown. Uses a SOLID `bg-card`
+ * surface with an accent border (never translucent) so it reads as a real note
+ * on any theme. Also the back-compat renderer for old mind-map nodes. */
+export function NoteFrame({ data }: NodeProps) {
+	const d = data as unknown as FrameData;
+	const theme = frameTheme(d.theme, d.accent);
+	return (
+		<FrameChrome title={d.title} device={d.device} badge="Note" theme={theme}>
+			<div
+				className={cn(
+					"h-full overflow-auto rounded-md px-3 py-2 text-micro text-muted-foreground",
+					solidSurface(d.theme, d.accent),
+				)}
+			>
+				{d.bodyBlocks.length > 0 ? renderBlocks(d.bodyBlocks) : null}
+			</div>
+		</FrameChrome>
+	);
+}
diff --git a/src/features/plan-viewer/components/canvas/frames/preview-frame.test.tsx b/src/features/plan-viewer/components/canvas/frames/preview-frame.test.tsx
new file mode 100644
index 000000000..2ae5a28e6
--- /dev/null
+++ b/src/features/plan-viewer/components/canvas/frames/preview-frame.test.tsx
@@ -0,0 +1,37 @@
+import { render } from "@testing-library/react";
+import type { ComponentProps } from "react";
+import { describe, expect, it, vi } from "vitest";
+
+// Mock React Flow primitives so the frame renders without a real canvas.
+vi.mock("@xyflow/react", () => ({
+	Handle: () => null,
+	Position: { Left: "left", Right: "right", Top: "top", Bottom: "bottom" },
+}));
+
+import type { FrameData } from "../build-graph";
+import { PreviewFrame } from "./preview-frame";
+
+const data: FrameData = {
+	title: "Home",
+	frameKind: "preview",
+	device: "browser",
+	theme: "repo",
+	accent: "neutral",
+	previewCode: "function App() { return null }",
+	wireframeSource: "",
+	bodyBlocks: [],
+};
+
+function renderFrame() {
+	const props = { data } as unknown as ComponentProps<typeof PreviewFrame>;
+	return render(<PreviewFrame {...props} />);
+}
+
+describe("PreviewFrame", () => {
+	it("mounts the live preview iframe immediately (no run-to-preview gate)", () => {
+		renderFrame();
+		const iframe = document.querySelector("iframe");
+		expect(iframe).not.toBeNull();
+		expect(iframe?.getAttribute("title")).toBe("Live UI preview");
+	});
+});
diff --git a/src/features/plan-viewer/components/canvas/frames/preview-frame.tsx b/src/features/plan-viewer/components/canvas/frames/preview-frame.tsx
new file mode 100644
index 000000000..b9b566f89
--- /dev/null
+++ b/src/features/plan-viewer/components/canvas/frames/preview-frame.tsx
@@ -0,0 +1,20 @@
+import type { NodeProps } from "@xyflow/react";
+import { LiveCodePreview } from "../../preview/live-code-preview";
+import type { FrameData } from "../build-graph";
+import { frameTheme } from "../theme-modes";
+import { FrameChrome } from "./frame-chrome";
+
+/** A frame hosting a live React/Tailwind preview. The preview mounts live —
+ * React Flow's `onlyRenderVisibleElements` keeps off-screen frames from mounting
+ * their sandboxed iframe until they scroll into view, so this stays smooth. */
+export function PreviewFrame({ data }: NodeProps) {
+	const d = data as unknown as FrameData;
+	const theme = frameTheme(d.theme, d.accent);
+	return (
+		<FrameChrome title={d.title} device={d.device} badge="Live" theme={theme}>
+			{d.previewCode.length > 0 ? (
+				<LiveCodePreview code={d.previewCode} />
+			) : null}
+		</FrameChrome>
+	);
+}
diff --git a/src/features/plan-viewer/components/canvas/frames/wireframe-frame.tsx b/src/features/plan-viewer/components/canvas/frames/wireframe-frame.tsx
new file mode 100644
index 000000000..7e053b6dd
--- /dev/null
+++ b/src/features/plan-viewer/components/canvas/frames/wireframe-frame.tsx
@@ -0,0 +1,30 @@
+import type { NodeProps } from "@xyflow/react";
+import { parseWireframe } from "../../wireframe/parse-wireframe";
+import { renderChildren } from "../../wireframe/primitives";
+import { WireframeFrame as WireframeDeviceFrame } from "../../wireframe/surface-frame";
+import type { FrameData } from "../build-graph";
+import { frameTheme } from "../theme-modes";
+import { FrameChrome } from "./frame-chrome";
+
+/** A frame holding a low-fidelity wireframe. Reuses the existing wireframe DSL
+ * parser + primitive renderer inside the existing device/window chrome — that
+ * chrome IS the frame's surface, so the frame itself stays card-less. */
+export function WireframeFrame({ data }: NodeProps) {
+	const d = data as unknown as FrameData;
+	const nodes = parseWireframe(d.wireframeSource);
+	const theme = frameTheme(d.theme, d.accent);
+	return (
+		<FrameChrome
+			title={d.title}
+			device={d.device}
+			badge="Wireframe"
+			theme={theme}
+		>
+			<div className="h-full overflow-auto">
+				<WireframeDeviceFrame surface={d.device}>
+					{renderChildren(nodes, false, true)}
+				</WireframeDeviceFrame>
+			</div>
+		</FrameChrome>
+	);
+}
diff --git a/src/features/plan-viewer/components/canvas/index.tsx b/src/features/plan-viewer/components/canvas/index.tsx
index 7d23104c9..d5e5781e8 100644
--- a/src/features/plan-viewer/components/canvas/index.tsx
+++ b/src/features/plan-viewer/components/canvas/index.tsx
@@ -6,17 +6,30 @@ const PlanCanvasSurface = lazy(() => import("./plan-canvas-surface"));
 export type PlanCanvasProps = {
 	childBlocks?: PlanBlock[];
 	direction?: string;
+	theme?: string;
+	height?: string;
 };
 
-/** Entry registered in the plan component registry (structured child mode). */
-export function PlanCanvas({ childBlocks = [], direction }: PlanCanvasProps) {
+/** Entry registered in the plan component registry (structured child mode). A
+ * freeform figma-style board of positioned frames, flow arrows, and sections. */
+export function PlanCanvas({
+	childBlocks = [],
+	direction,
+	theme,
+	height,
+}: PlanCanvasProps) {
 	return (
 		<Suspense
 			fallback={
 				<div className="h-[460px] w-full animate-pulse border-border border-b bg-background" />
 			}
 		>
-			<PlanCanvasSurface childBlocks={childBlocks} direction={direction} />
+			<PlanCanvasSurface
+				childBlocks={childBlocks}
+				direction={direction}
+				theme={theme}
+				height={height}
+			/>
 		</Suspense>
 	);
 }
diff --git a/src/features/plan-viewer/components/canvas/layout.test.ts b/src/features/plan-viewer/components/canvas/layout.test.ts
deleted file mode 100644
index edc36c60c..000000000
--- a/src/features/plan-viewer/components/canvas/layout.test.ts
+++ /dev/null
@@ -1,74 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { CanvasGraph } from "./build-graph";
-import { layoutCanvasGraph } from "./layout";
-
-const graph: CanvasGraph = {
-	nodes: [
-		{
-			id: "a",
-			type: "canvasNode",
-			data: { title: "A", bodyBlocks: [] },
-			position: { x: 0, y: 0 },
-		},
-		{
-			id: "b",
-			type: "canvasNode",
-			data: { title: "B", bodyBlocks: [] },
-			position: { x: 0, y: 0 },
-		},
-	],
-	edges: [{ id: "a->b", source: "a", target: "b" }],
-};
-
-describe("layoutCanvasGraph", () => {
-	it("assigns distinct positions to connected nodes", () => {
-		const out = layoutCanvasGraph(graph, "TB");
-		const a = out.nodes.find((n) => n.id === "a");
-		const b = out.nodes.find((n) => n.id === "b");
-		expect(a && b).toBeTruthy();
-		expect((b as { position: { y: number } }).position.y).toBeGreaterThan(
-			(a as { position: { y: number } }).position.y,
-		);
-	});
-
-	it("returns finite coordinates", () => {
-		const out = layoutCanvasGraph(graph, "LR");
-		for (const n of out.nodes) {
-			expect(Number.isFinite(n.position.x)).toBe(true);
-			expect(Number.isFinite(n.position.y)).toBe(true);
-		}
-	});
-
-	it("handles a single node with no edges", () => {
-		const out = layoutCanvasGraph({ nodes: [graph.nodes[0]], edges: [] }, "TB");
-		expect(out.nodes).toHaveLength(1);
-		expect(Number.isFinite(out.nodes[0].position.x)).toBe(true);
-	});
-
-	it("spaces a taller node kind further from its successor", () => {
-		// A taller source node ("wireframe", h=160) pushes its TB successor lower
-		// than a short one ("note", h=96) does — proving layout consults the
-		// per-kind size, not a fixed height.
-		const make = (sourceKind: "note" | "wireframe"): CanvasGraph => ({
-			nodes: [
-				{
-					id: "a",
-					type: "canvasNode",
-					data: { title: "A", bodyBlocks: [], kind: sourceKind },
-					position: { x: 0, y: 0 },
-				},
-				{
-					id: "b",
-					type: "canvasNode",
-					data: { title: "B", bodyBlocks: [] },
-					position: { x: 0, y: 0 },
-				},
-			],
-			edges: [{ id: "a->b", source: "a", target: "b" }],
-		});
-		const yOfB = (g: CanvasGraph) =>
-			layoutCanvasGraph(g, "TB").nodes.find((n) => n.id === "b")?.position.y ??
-			0;
-		expect(yOfB(make("wireframe"))).toBeGreaterThan(yOfB(make("note")));
-	});
-});
diff --git a/src/features/plan-viewer/components/canvas/layout.ts b/src/features/plan-viewer/components/canvas/layout.ts
deleted file mode 100644
index 4c0b7e9e6..000000000
--- a/src/features/plan-viewer/components/canvas/layout.ts
+++ /dev/null
@@ -1,42 +0,0 @@
-import dagre from "@dagrejs/dagre";
-import type { CanvasGraph } from "./build-graph";
-import { NODE_SIZE, normalizeKind } from "./node-kinds";
-
-export type CanvasDirection = "TB" | "LR";
-
-/** Position every node with dagre, sizing each by its kind. Pure: returns a new
- * graph; input untouched. */
-export function layoutCanvasGraph(
-	graph: CanvasGraph,
-	direction: CanvasDirection,
-): CanvasGraph {
-	const g = new dagre.graphlib.Graph();
-	g.setGraph({ rankdir: direction, nodesep: 48, ranksep: 64 });
-	g.setDefaultEdgeLabel(() => ({}));
-
-	for (const node of graph.nodes) {
-		const size = NODE_SIZE[normalizeKind(node.data.kind)];
-		g.setNode(node.id, { width: size.width, height: size.height });
-	}
-	for (const edge of graph.edges) {
-		g.setEdge(edge.source, edge.target);
-	}
-
-	dagre.layout(g);
-
-	const nodes = graph.nodes.map((node) => {
-		const pos = g.node(node.id);
-		const size = NODE_SIZE[normalizeKind(node.data.kind)];
-		// dagre returns the node center; React Flow wants the top-left corner.
-		return {
-			...node,
-			position: { x: pos.x - size.width / 2, y: pos.y - size.height / 2 },
-		};
-	});
-
-	return { nodes, edges: graph.edges };
-}
-
-export function parseDirection(value: string | undefined): CanvasDirection {
-	return value === "LR" ? "LR" : "TB";
-}
diff --git a/src/features/plan-viewer/components/canvas/node-kinds.test.ts b/src/features/plan-viewer/components/canvas/node-kinds.test.ts
deleted file mode 100644
index bb0f4a2a0..000000000
--- a/src/features/plan-viewer/components/canvas/node-kinds.test.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { NODE_SIZE, normalizeKind } from "./node-kinds";
-
-describe("normalizeKind", () => {
-	it("passes through a known kind", () => {
-		expect(normalizeKind("resume")).toBe("resume");
-	});
-
-	it("defaults unknown or undefined to note", () => {
-		expect(normalizeKind("bogus")).toBe("note");
-		expect(normalizeKind(undefined)).toBe("note");
-	});
-});
-
-describe("NODE_SIZE", () => {
-	it("sizes every kind, with resume wider than note", () => {
-		expect(NODE_SIZE.note.width).toBeGreaterThan(0);
-		expect(NODE_SIZE.resume.width).toBeGreaterThan(NODE_SIZE.note.width);
-	});
-});
diff --git a/src/features/plan-viewer/components/canvas/node-kinds.ts b/src/features/plan-viewer/components/canvas/node-kinds.ts
deleted file mode 100644
index bc43e0039..000000000
--- a/src/features/plan-viewer/components/canvas/node-kinds.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-/** The visual role of a canvas node, set via `<CanvasNode kind="...">`. */
-export type CanvasNodeKind =
-	| "note"
-	| "resume"
-	| "option"
-	| "phase"
-	| "wireframe";
-
-const KINDS = new Set<CanvasNodeKind>([
-	"note",
-	"resume",
-	"option",
-	"phase",
-	"wireframe",
-]);
-
-/** Resolve a kind string to a known kind, defaulting to `note`. */
-export function normalizeKind(value: string | undefined): CanvasNodeKind {
-	return value && KINDS.has(value as CanvasNodeKind)
-		? (value as CanvasNodeKind)
-		: "note";
-}
-
-/** Per-kind nominal node size (used by dagre layout AND the rendered node so
- * they stay in sync). */
-export const NODE_SIZE: Record<
-	CanvasNodeKind,
-	{ width: number; height: number }
-> = {
-	note: { width: 220, height: 96 },
-	resume: { width: 300, height: 120 },
-	option: { width: 230, height: 110 },
-	phase: { width: 200, height: 90 },
-	wireframe: { width: 260, height: 160 },
-};
diff --git a/src/features/plan-viewer/components/canvas/plan-canvas-render.test.tsx b/src/features/plan-viewer/components/canvas/plan-canvas-render.test.tsx
new file mode 100644
index 000000000..d504e5f63
--- /dev/null
+++ b/src/features/plan-viewer/components/canvas/plan-canvas-render.test.tsx
@@ -0,0 +1,59 @@
+import { render } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { parsePlanMdx } from "../../mdx/parse";
+import PlanCanvasSurface from "./plan-canvas-surface";
+
+// Renders the REAL surface against real @xyflow/react (jsdom polyfills
+// ResizeObserver/matchMedia in src/test/setup.ts) to catch runtime regressions
+// the heavily-mocked plan-canvas.test.tsx can't see (floating edges via
+// useInternalNode, MiniMap props, etc.).
+const SRC = [
+	"---",
+	'title: "T"',
+	"status: draft",
+	'summary: "S"',
+	"---",
+	"",
+	'<PlanCanvas theme="repo" height="640">',
+	'<CanvasGroup id="auth" title="Onboarding" contains="login,verify" accent="info" />',
+	'<CanvasNode id="login" title="Sign in" x="40" y="80" device="mobile" accent="info">',
+	"<Wireframe>",
+	"section",
+	"  heading Welcome",
+	"  button Continue",
+	"</Wireframe>",
+	"</CanvasNode>",
+	'<CanvasNode id="verify" title="Verify" x="520" y="80" device="mobile" accent="info" />',
+	'<CanvasNode id="note" title="NOTE" x="520" y="600" accent="warning">',
+	"A pinned note.",
+	"</CanvasNode>",
+	'<CanvasFlow from="login" to="verify" label="Submit" kind="primary" />',
+	'<CanvasFlow from="verify" to="login" label="Back" kind="back" />',
+	"</PlanCanvas>",
+	"",
+].join("\n");
+
+function canvasChildBlocks() {
+	const { blocks } = parsePlanMdx(SRC);
+	const canvas = blocks.find(
+		(b) => b.kind === "component" && b.name === "PlanCanvas",
+	);
+	if (canvas?.kind !== "component") throw new Error("no PlanCanvas parsed");
+	return canvas.childBlocks;
+}
+
+describe("PlanCanvasSurface (real xyflow render)", () => {
+	it("mounts the React Flow surface without throwing", () => {
+		const { container } = render(
+			<PlanCanvasSurface childBlocks={canvasChildBlocks()} theme="repo" />,
+		);
+		expect(container.querySelector(".react-flow")).not.toBeNull();
+	});
+
+	it("renders the MiniMap", () => {
+		const { container } = render(
+			<PlanCanvasSurface childBlocks={canvasChildBlocks()} theme="repo" />,
+		);
+		expect(container.querySelector(".react-flow__minimap")).not.toBeNull();
+	});
+});
diff --git a/src/features/plan-viewer/components/canvas/plan-canvas-surface.tsx b/src/features/plan-viewer/components/canvas/plan-canvas-surface.tsx
index 996d0c1b7..c4a3848f7 100644
--- a/src/features/plan-viewer/components/canvas/plan-canvas-surface.tsx
+++ b/src/features/plan-viewer/components/canvas/plan-canvas-surface.tsx
@@ -2,40 +2,139 @@ import {
 	Background,
 	BackgroundVariant,
 	Controls,
+	MarkerType,
+	MiniMap,
 	ReactFlow,
 	useEdgesState,
 	useNodesState,
+	useReactFlow,
 } from "@xyflow/react";
 import "@xyflow/react/dist/style.css";
 import { type CSSProperties, useEffect, useMemo } from "react";
 import type { PlanBlock } from "../../mdx/parse";
+import {
+	autoLayoutFrames,
+	computeGroupBounds,
+	parseDirection,
+} from "./auto-layout";
 import { buildCanvasGraph } from "./build-graph";
-import { CanvasNode } from "./canvas-node";
-import { layoutCanvasGraph, parseDirection } from "./layout";
+import { DesignToolbar } from "./design-toolbar";
+import { FlowEdge } from "./flow-edge";
+import type { FrameKind } from "./frame-kinds";
+import { GroupNode } from "./frames/group-node";
+import { NoteFrame } from "./frames/note-frame";
+import { PreviewFrame } from "./frames/preview-frame";
+import { WireframeFrame } from "./frames/wireframe-frame";
+import { normalizeTheme } from "./theme-modes";
+
+const nodeTypes = {
+	previewFrame: PreviewFrame,
+	wireframeFrame: WireframeFrame,
+	noteFrame: NoteFrame,
+	// NOT "group": React Flow ships default grey fill + border CSS for the
+	// reserved `group` type (`.react-flow__node-group`). A custom name avoids it
+	// so only our faint dashed outline shows.
+	sectionGroup: GroupNode,
+};
+const edgeTypes = { flow: FlowEdge };
 
-const nodeTypes = { canvasNode: CanvasNode };
+/** Frame kind → registered React Flow node type. */
+const NODE_TYPE: Record<FrameKind, string> = {
+	preview: "previewFrame",
+	wireframe: "wireframeFrame",
+	note: "noteFrame",
+	screen: "noteFrame",
+};
+
+const CONTROLS_STYLE = {
+	"--xy-controls-button-background-color": "var(--card)",
+	"--xy-controls-button-background-color-hover": "var(--accent)",
+	"--xy-controls-button-color": "var(--foreground)",
+	"--xy-controls-button-color-hover": "var(--accent-foreground)",
+	"--xy-controls-button-border-color": "var(--border)",
+} as CSSProperties;
 
 export type PlanCanvasSurfaceProps = {
 	childBlocks: PlanBlock[];
 	direction?: string;
+	theme?: string;
+	height?: string;
 };
 
+/** Re-fit the viewport whenever the authored graph changes (e.g. the agent
+ * edits the plan and the watcher pushes a fresh parse). */
+function FitView({ dep }: { dep: unknown }) {
+	const { fitView } = useReactFlow();
+	useEffect(() => {
+		fitView({ padding: 0.2 });
+	}, [dep, fitView]);
+	return null;
+}
+
+function parseHeight(value: string | undefined): number {
+	const n = value ? Number.parseFloat(value) : Number.NaN;
+	if (!Number.isFinite(n)) return 720;
+	return Math.max(360, Math.min(1600, n));
+}
+
 export default function PlanCanvasSurface({
 	childBlocks,
 	direction,
+	theme: themeProp,
+	height,
 }: PlanCanvasSurfaceProps) {
+	const theme = normalizeTheme(themeProp);
 	const graph = useMemo(() => {
-		const built = buildCanvasGraph(childBlocks);
-		return layoutCanvasGraph(built, parseDirection(direction));
-	}, [childBlocks, direction]);
+		const built = buildCanvasGraph(childBlocks, theme);
+		const positioned = autoLayoutFrames(
+			built.frames,
+			built.edges,
+			parseDirection(direction),
+		);
+		const groups = computeGroupBounds(built.groups, positioned);
+
+		const groupNodes = groups.map((g) => ({
+			id: `group-${g.spec.id}`,
+			type: "sectionGroup",
+			position: { x: g.x, y: g.y },
+			width: g.width,
+			height: g.height,
+			data: { title: g.spec.title, accent: g.spec.accent, theme },
+			// Neutralize any base node chrome so only the component's outline shows.
+			style: { background: "transparent", border: "none", padding: 0 },
+			selectable: false,
+			draggable: false,
+			zIndex: 0,
+		}));
+		const frameNodes = positioned.map((f) => ({
+			id: f.id,
+			type: NODE_TYPE[f.frameKind],
+			position: f.position ?? { x: 0, y: 0 },
+			width: f.width,
+			height: f.height,
+			data: f.data,
+			zIndex: 1,
+		}));
+		const edges = built.edges.map((e) => ({
+			id: e.id,
+			source: e.source,
+			target: e.target,
+			type: "flow",
+			markerEnd: {
+				type: MarkerType.ArrowClosed,
+				color:
+					e.kind === "primary" ? "var(--primary)" : "var(--muted-foreground)",
+			},
+			data: { kind: e.kind, label: e.label },
+		}));
+		// Group backgrounds first so they paint behind the frames.
+		return { nodes: [...groupNodes, ...frameNodes], edges };
+	}, [childBlocks, direction, theme]);
 
 	const [nodes, setNodes, onNodesChange] = useNodesState(graph.nodes);
 	const [edges, setEdges, onEdgesChange] = useEdgesState(graph.edges);
 
-	// `useNodesState`/`useEdgesState` only seed initial state, so re-sync when the
-	// authored graph changes (e.g. the agent edits the plan and the watcher pushes
-	// a fresh parse, or content streams in). Ephemeral user drags are intentionally
-	// reset to the authored layout on such updates.
+	// Re-seed when the authored graph changes (ephemeral drags reset to authored).
 	useEffect(() => {
 		setNodes(graph.nodes);
 		setEdges(graph.edges);
@@ -46,13 +145,17 @@ export default function PlanCanvasSurface({
 	}
 
 	return (
-		<div className="h-[460px] w-full overflow-hidden border-border border-b bg-background">
+		<div
+			className="w-full overflow-hidden border-border border-b bg-background"
+			style={{ height: parseHeight(height) }}
+		>
 			<ReactFlow
 				nodes={nodes}
 				edges={edges}
 				onNodesChange={onNodesChange}
 				onEdgesChange={onEdgesChange}
 				nodeTypes={nodeTypes}
+				edgeTypes={edgeTypes}
 				fitView
 				fitViewOptions={{ padding: 0.2 }}
 				minZoom={0.2}
@@ -60,22 +163,27 @@ export default function PlanCanvasSurface({
 				proOptions={{ hideAttribution: true }}
 				nodesConnectable={false}
 				edgesFocusable={false}
+				// Keep off-screen frames from mounting their live preview iframe until
+				// they scroll into view — lets every preview run live without paying
+				// for all of them at once.
+				onlyRenderVisibleElements
 			>
-				<Background variant={BackgroundVariant.Dots} gap={20} size={1} />
-				<Controls
-					showInteractive={false}
-					// Theme React Flow's default light-on-white control buttons with
-					// Helmor tokens (icon uses `fill: currentColor`, driven by `color`).
-					style={
-						{
-							"--xy-controls-button-background-color": "var(--card)",
-							"--xy-controls-button-background-color-hover": "var(--accent)",
-							"--xy-controls-button-color": "var(--foreground)",
-							"--xy-controls-button-color-hover": "var(--accent-foreground)",
-							"--xy-controls-button-border-color": "var(--border)",
-						} as CSSProperties
-					}
+				<Background variant={BackgroundVariant.Dots} gap={22} size={1} />
+				<MiniMap
+					pannable
+					zoomable
+					// Small + theme-matched. Sized via Tailwind; panel bg follows --card;
+					// the out-of-view mask is a plain translucent black so it reads as a
+					// dimmed canvas on the dark theme rather than RF's default bright-grey
+					// patch. Values kept to rgba / CSS vars that WebKit accepts as fills.
+					className="!h-[92px] !w-[132px] overflow-hidden !rounded-md border border-border !bg-card"
+					maskColor="rgba(0, 0, 0, 0.55)"
+					nodeColor="var(--muted-foreground)"
+					nodeStrokeColor="var(--border)"
 				/>
+				<Controls showInteractive={false} style={CONTROLS_STYLE} />
+				<DesignToolbar theme={theme} />
+				<FitView dep={graph} />
 			</ReactFlow>
 		</div>
 	);
diff --git a/src/features/plan-viewer/components/canvas/plan-canvas.test.tsx b/src/features/plan-viewer/components/canvas/plan-canvas.test.tsx
index 1ac8dd452..aa8b5a048 100644
--- a/src/features/plan-viewer/components/canvas/plan-canvas.test.tsx
+++ b/src/features/plan-viewer/components/canvas/plan-canvas.test.tsx
@@ -7,7 +7,7 @@ vi.mock("@xyflow/react", () => ({
 	ReactFlow: ({
 		nodes,
 	}: {
-		nodes: Array<{ id: string; data: { title: string } }>;
+		nodes: Array<{ id: string; data: { title?: string } }>;
 	}) => (
 		<div data-testid="rf">
 			{nodes.map((n) => (
@@ -17,11 +17,19 @@ vi.mock("@xyflow/react", () => ({
 	),
 	Background: () => null,
 	Controls: () => null,
+	MiniMap: () => null,
+	Panel: () => null,
+	BaseEdge: () => null,
+	EdgeLabelRenderer: () => null,
+	getBezierPath: () => ["", 0, 0],
 	BackgroundVariant: { Dots: "dots" },
+	MarkerType: { ArrowClosed: "arrowclosed" },
 	Handle: () => null,
-	Position: { Top: "top", Bottom: "bottom" },
+	Position: { Top: "top", Bottom: "bottom", Left: "left", Right: "right" },
 	useNodesState: (init: unknown) => [init, vi.fn(), vi.fn()],
 	useEdgesState: (init: unknown) => [init, vi.fn(), vi.fn()],
+	useReactFlow: () => ({ fitView: vi.fn() }),
+	useViewport: () => ({ x: 0, y: 0, zoom: 1 }),
 }));
 
 import PlanCanvasSurface from "./plan-canvas-surface";
diff --git a/src/features/plan-viewer/components/canvas/theme-modes.test.ts b/src/features/plan-viewer/components/canvas/theme-modes.test.ts
new file mode 100644
index 000000000..29e104480
--- /dev/null
+++ b/src/features/plan-viewer/components/canvas/theme-modes.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { frameTheme, normalizeAccent, normalizeTheme } from "./theme-modes";
+
+describe("normalizeTheme", () => {
+	it("defaults unknown/absent to repo", () => {
+		expect(normalizeTheme(undefined)).toBe("repo");
+		expect(normalizeTheme("bogus")).toBe("repo");
+		expect(normalizeTheme("wireframe")).toBe("wireframe");
+	});
+});
+
+describe("normalizeAccent", () => {
+	it("passes through known accents, defaults to neutral", () => {
+		expect(normalizeAccent("success")).toBe("success");
+		expect(normalizeAccent("nope")).toBe("neutral");
+		expect(normalizeAccent(undefined)).toBe("neutral");
+	});
+});
+
+describe("frameTheme", () => {
+	it("greyscales the body and ignores accent in wireframe mode", () => {
+		const t = frameTheme("wireframe", "success");
+		expect(t.bodyFilter).toContain("grayscale");
+		// Accent dropped → neutral container (no emerald classes).
+		expect(t.container).not.toContain("emerald");
+	});
+
+	it("routes through the accent and skips the filter in repo mode", () => {
+		const t = frameTheme("repo", "success");
+		expect(t.bodyFilter).toBe("");
+		expect(t.container).toContain("emerald");
+	});
+});
diff --git a/src/features/plan-viewer/components/canvas/theme-modes.ts b/src/features/plan-viewer/components/canvas/theme-modes.ts
new file mode 100644
index 000000000..3e8039f13
--- /dev/null
+++ b/src/features/plan-viewer/components/canvas/theme-modes.ts
@@ -0,0 +1,96 @@
+import { cn } from "@/lib/utils";
+import { accentClasses, type PlanAccent } from "../shell/accent";
+
+/**
+ * Per-canvas visual mode, set via `<PlanCanvas theme="...">`.
+ * - `repo` (default): frames use their semantic accent + real color — the
+ *   "polished, repo-themed" look.
+ * - `wireframe`: low-fidelity focus. A `grayscale` filter desaturates the whole
+ *   frame body (even live previews) and chrome falls back to neutral, so the
+ *   reader focuses on layout, not color.
+ */
+export type CanvasTheme = "repo" | "wireframe";
+
+const THEMES = new Set<CanvasTheme>(["repo", "wireframe"]);
+
+/** Resolve a `theme=` prop to a known theme, defaulting to `repo`. */
+export function normalizeTheme(value: string | undefined): CanvasTheme {
+	return value && THEMES.has(value as CanvasTheme)
+		? (value as CanvasTheme)
+		: "repo";
+}
+
+/** Semantic accent for a frame, defaulting to neutral. */
+export function normalizeAccent(value: string | undefined): PlanAccent {
+	const accents: PlanAccent[] = [
+		"neutral",
+		"info",
+		"warning",
+		"danger",
+		"success",
+		"highlight",
+	];
+	return value && accents.includes(value as PlanAccent)
+		? (value as PlanAccent)
+		: "neutral";
+}
+
+export type FrameThemeClasses = {
+	/** Container border + faint fill for the whole frame. */
+	container: string;
+	/** Title-label color. */
+	header: string;
+	/** Small chip (device/kind badge). */
+	badge: string;
+	/** Wrapper applied to the frame BODY — greyscale in wireframe mode. */
+	bodyFilter: string;
+};
+
+/**
+ * Resolve frame classes for a `(theme, accent)` pair. In `wireframe` mode the
+ * accent is ignored (neutral chrome + greyscale body); in `repo` mode it routes
+ * through the shared {@link accentClasses} so frames match the rest of the plan.
+ */
+export function frameTheme(
+	theme: CanvasTheme,
+	accent: PlanAccent,
+): FrameThemeClasses {
+	if (theme === "wireframe") {
+		const neutral = accentClasses("neutral");
+		return {
+			container: neutral.container,
+			header: neutral.header,
+			badge: neutral.badge,
+			bodyFilter: "grayscale",
+		};
+	}
+	const styles = accentClasses(accent);
+	return {
+		container: styles.container,
+		header: styles.header,
+		badge: styles.badge,
+		bodyFilter: "",
+	};
+}
+
+/** Accent border colors at full opacity — for SOLID frame surfaces, where the
+ * fill is opaque `bg-card` (never translucent, so it reads correctly on any
+ * theme incl. dark/Vesper) and the accent lives only in the border. */
+const ACCENT_BORDER: Record<PlanAccent, string> = {
+	neutral: "border-border",
+	info: "border-sky-500/60",
+	warning: "border-amber-500/60",
+	danger: "border-red-500/60",
+	success: "border-emerald-500/60",
+	highlight: "border-violet-500/60",
+};
+
+/**
+ * Classes for an OPAQUE frame surface: a solid `bg-card` fill plus an accent
+ * border (neutral in wireframe mode). Used by frames that own a visible panel
+ * (notes) so they never show the canvas through a translucent fill.
+ */
+export function solidSurface(theme: CanvasTheme, accent: PlanAccent): string {
+	const a = theme === "wireframe" ? "neutral" : accent;
+	return cn("bg-card border", ACCENT_BORDER[a]);
+}
diff --git a/src/features/plan-viewer/mdx/parse.test.ts b/src/features/plan-viewer/mdx/parse.test.ts
index 2cfcd63ab..2817a9c29 100644
--- a/src/features/plan-viewer/mdx/parse.test.ts
+++ b/src/features/plan-viewer/mdx/parse.test.ts
@@ -238,6 +238,43 @@ Second.`;
 		// b3 = Second — the counter is shared across recursion.
 		expect(parsed.blocks.map((b) => b.id)).toEqual(["b0", "b1", "b3"]);
 	});
+
+	it("still parses components when an agent leaks tool-call wrapper tags", () => {
+		// A `Write` call whose closing tags leaked into the saved plan body. The
+		// stray `</content></invoke>` make remark-mdx throw on a closing tag with
+		// no opener; without scrubbing them the WHOLE plan falls back to plain
+		// Markdown and the canvas never renders.
+		const src = [
+			"---",
+			'title: "Leaked"',
+			"status: draft",
+			"---",
+			"",
+			"Intro.",
+			"",
+			'<PlanCanvas theme="repo">',
+			'<CanvasNode id="a" title="A">body</CanvasNode>',
+			"</PlanCanvas>",
+			"",
+			"## Verification",
+			"- Confirm it works.",
+			"</content>",
+			"</invoke>",
+		].join("\n");
+
+		const parsed = parsePlanMdx(src);
+		const canvas = parsed.blocks.find(
+			(b) => b.kind === "component" && b.name === "PlanCanvas",
+		);
+		expect(canvas?.kind).toBe("component");
+		// The stray wrapper tags are gone, not rendered as prose.
+		const prose = parsed.blocks
+			.filter((b) => b.kind === "prose")
+			.map((b) => (b.kind === "prose" ? b.markdown : ""))
+			.join("\n");
+		expect(prose).not.toContain("</invoke>");
+		expect(prose).not.toContain("</content>");
+	});
 });
 
 describe("PlanCanvas structured parsing", () => {
@@ -274,4 +311,101 @@ describe("PlanCanvas structured parsing", () => {
 		expect(first.props.connects).toBe("b");
 		expect(first.childBlocks.some((c) => c.kind === "prose")).toBe(true);
 	});
+
+	it("masks and reattaches a Preview/Wireframe nested inside a CanvasNode", () => {
+		const src = [
+			"---",
+			'title: "T"',
+			"status: draft",
+			'summary: "S"',
+			"---",
+			"",
+			'<PlanCanvas theme="wireframe">',
+			'<CanvasNode id="login" title="Sign in" x="40" y="80">',
+			"<Wireframe>",
+			"section",
+			"  field Email",
+			"  button Continue",
+			"</Wireframe>",
+			"</CanvasNode>",
+			'<CanvasNode id="home" title="Home" x="460" y="80">',
+			"<Preview>",
+			"function App() {",
+			"  return <div onClick={() => {}}>hi</div>",
+			"}",
+			"</Preview>",
+			"</CanvasNode>",
+			"</PlanCanvas>",
+			"",
+		].join("\n");
+
+		const { blocks } = parsePlanMdx(src);
+		const canvas = blocks.find(
+			(b) => b.kind === "component" && b.name === "PlanCanvas",
+		);
+		if (canvas?.kind !== "component") throw new Error("expected component");
+		const nodes = canvas.childBlocks.filter(
+			(b) => b.kind === "component" && b.name === "CanvasNode",
+		);
+		expect(nodes).toHaveLength(2);
+
+		const login = nodes[0];
+		if (login.kind !== "component") throw new Error("expected component");
+		const wireframe = login.childBlocks.find(
+			(c) => c.kind === "component" && c.name === "Wireframe",
+		);
+		if (wireframe?.kind !== "component") throw new Error("expected wireframe");
+		// The raw masker lifted the body verbatim despite the nesting depth.
+		expect(wireframe.rawText).toContain("field Email");
+		expect(wireframe.rawText).toContain("button Continue");
+
+		const home = nodes[1];
+		if (home.kind !== "component") throw new Error("expected component");
+		const preview = home.childBlocks.find(
+			(c) => c.kind === "component" && c.name === "Preview",
+		);
+		if (preview?.kind !== "component") throw new Error("expected preview");
+		// The JS body (which would crash acorn) survived masking intact.
+		expect(preview.rawText).toContain("function App()");
+		expect(preview.rawText).toContain("onClick={() => {}}");
+	});
+
+	it("parses self-closing CanvasFlow and CanvasGroup with their props", () => {
+		const src = [
+			"---",
+			'title: "T"',
+			"status: draft",
+			'summary: "S"',
+			"---",
+			"",
+			'<PlanCanvas theme="wireframe">',
+			'<CanvasGroup id="auth" title="Onboarding" contains="login,home" />',
+			'<CanvasNode id="login" title="Sign in" x="40" y="80" />',
+			'<CanvasNode id="home" title="Home" x="460" y="80" />',
+			'<CanvasFlow from="login" to="home" label="Submit" kind="primary" />',
+			"</PlanCanvas>",
+			"",
+		].join("\n");
+
+		const { blocks } = parsePlanMdx(src);
+		const canvas = blocks.find(
+			(b) => b.kind === "component" && b.name === "PlanCanvas",
+		);
+		if (canvas?.kind !== "component") throw new Error("expected component");
+		const flow = canvas.childBlocks.find(
+			(b) => b.kind === "component" && b.name === "CanvasFlow",
+		);
+		if (flow?.kind !== "component") throw new Error("expected flow");
+		expect(flow.props).toMatchObject({
+			from: "login",
+			to: "home",
+			label: "Submit",
+			kind: "primary",
+		});
+		const group = canvas.childBlocks.find(
+			(b) => b.kind === "component" && b.name === "CanvasGroup",
+		);
+		if (group?.kind !== "component") throw new Error("expected group");
+		expect(group.props.contains).toBe("login,home");
+	});
 });
diff --git a/src/features/plan-viewer/mdx/parse.ts b/src/features/plan-viewer/mdx/parse.ts
index 10ff01cb1..867592ca9 100644
--- a/src/features/plan-viewer/mdx/parse.ts
+++ b/src/features/plan-viewer/mdx/parse.ts
@@ -4,6 +4,7 @@ import { unified } from "unified";
 import { isolateMalformedComponents } from "./isolate";
 import { maskRawComponentBodies } from "./mask-raw";
 import { planChildMode } from "./registry";
+import { stripLeakedToolTags } from "./strip-leaked-tags";
 
 export type PlanBlock =
 	| { kind: "prose"; id: string; markdown: string }
@@ -230,10 +231,17 @@ export function parsePlanMdx(src: string): ParsedPlan {
 	const { yaml, body: rawBody } = splitFrontmatter(src);
 	const frontmatter = parseFrontmatter(yaml);
 
+	// Drop any leaked agent tool-call wrapper tags (e.g. a Write call's trailing
+	// `</content></invoke>`) BEFORE parsing. A single stray closing tag otherwise
+	// throws in remark-mdx and the recovery tiers can't isolate it (not a
+	// capitalised component), dropping the whole plan to plain Markdown. Returns
+	// `null` (→ keep the original body) for the clean common case.
+	const body0 = stripLeakedToolTags(rawBody) ?? rawBody;
+
 	// Lift raw-content component bodies (Preview JS, diffs, generics, …) out of
 	// the source BEFORE MDX parsing — they are not valid MDX and would otherwise
 	// crash the parse. They are reattached verbatim from `stash` during the walk.
-	const { body: maskedBody, stash } = maskRawComponentBodies(rawBody);
+	const { body: maskedBody, stash } = maskRawComponentBodies(body0);
 	const { tree, body } = parseBody(maskedBody);
 
 	// A single counter keeps ids unique and stable in document order, including
diff --git a/src/features/plan-viewer/mdx/registry.tsx b/src/features/plan-viewer/mdx/registry.tsx
index 2ce46551d..b709f9e8b 100644
--- a/src/features/plan-viewer/mdx/registry.tsx
+++ b/src/features/plan-viewer/mdx/registry.tsx
@@ -22,6 +22,12 @@ function CanvasNodeFallback({ children }: { children?: ReactNode }) {
 	return <>{children}</>;
 }
 
+/** CanvasFlow / CanvasGroup are structural-only: they carry no body and are read
+ * from the PlanCanvas's child blocks. Authored standalone they render nothing. */
+function CanvasStructuralFallback() {
+	return null;
+}
+
 /** Sub-components (Option, Before, After, Phase) are consumed by their parent
  * (Decision / BeforeAfter / Timeline). Authored standalone, they just render
  * their body blocks so content is never lost. */
@@ -62,6 +68,8 @@ export const PLAN_COMPONENTS: Record<string, PlanComponentDef> = {
 	Diagram: { render: Diagram, childMode: "raw" },
 	PlanCanvas: { render: PlanCanvas, childMode: "structured" },
 	CanvasNode: { render: CanvasNodeFallback, childMode: "blocks" },
+	CanvasFlow: { render: CanvasStructuralFallback, childMode: "blocks" },
+	CanvasGroup: { render: CanvasStructuralFallback, childMode: "blocks" },
 	Decision: { render: Decision, childMode: "structured" },
 	Option: { render: SubComponentFallback, childMode: "blocks" },
 	BeforeAfter: { render: BeforeAfter, childMode: "structured" },
diff --git a/src/features/plan-viewer/mdx/strip-leaked-tags.test.ts b/src/features/plan-viewer/mdx/strip-leaked-tags.test.ts
new file mode 100644
index 000000000..a3ac99e2a
--- /dev/null
+++ b/src/features/plan-viewer/mdx/strip-leaked-tags.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import { stripLeakedToolTags } from "./strip-leaked-tags";
+
+// Build wrapper tags from parts so this source file never contains a literal
+// leaked tool-call block itself.
+const open = (name: string, attrs = "") => `<${name}${attrs}>`;
+const close = (name: string) => `</${name}>`;
+
+describe("stripLeakedToolTags", () => {
+	it("removes trailing leaked Write-call wrapper tags", () => {
+		const body = [
+			"## Verification",
+			"",
+			"- Do the thing.",
+			close("content"),
+			close("invoke"),
+		].join("\n");
+		expect(stripLeakedToolTags(body)).toBe(
+			["## Verification", "", "- Do the thing."].join("\n"),
+		);
+	});
+
+	it("removes opening wrapper tags with attributes and namespaced variants", () => {
+		const body = [
+			open("function_calls"),
+			open("invoke", ' name="Write"'),
+			open("parameter", ' name="content"'),
+			"# Plan",
+			close("parameter"),
+			close("invoke"),
+			close("function_calls"),
+		].join("\n");
+		expect(stripLeakedToolTags(body)).toBe("# Plan");
+	});
+
+	it("strips namespaced (antml:) wrapper tags", () => {
+		const body = [
+			open("antml:invoke", ' name="x"'),
+			"body",
+			close("antml:invoke"),
+		].join("\n");
+		expect(stripLeakedToolTags(body)).toBe("body");
+	});
+
+	it("returns null for a clean plan (no allocation, byte-identical body kept)", () => {
+		const body = ["# Title", "", "<PlanCanvas>", "</PlanCanvas>"].join("\n");
+		expect(stripLeakedToolTags(body)).toBeNull();
+	});
+
+	it("never touches wrapper markup shown inside a fenced code block", () => {
+		const body = [
+			"Example of a tool call:",
+			"```xml",
+			open("invoke", ' name="Write"'),
+			close("invoke"),
+			"```",
+			"Done.",
+		].join("\n");
+		expect(stripLeakedToolTags(body)).toBeNull();
+	});
+
+	it("leaves inline mentions in prose alone (whole-line only)", () => {
+		const body = `A leaked ${close("invoke")} tag mid-sentence stays.`;
+		expect(stripLeakedToolTags(body)).toBeNull();
+	});
+
+	it("does not match similarly-prefixed tags (word boundary)", () => {
+		const body = [open("contention"), open("parameters"), "x"].join("\n");
+		expect(stripLeakedToolTags(body)).toBeNull();
+	});
+});
diff --git a/src/features/plan-viewer/mdx/strip-leaked-tags.ts b/src/features/plan-viewer/mdx/strip-leaked-tags.ts
new file mode 100644
index 000000000..910a6eb83
--- /dev/null
+++ b/src/features/plan-viewer/mdx/strip-leaked-tags.ts
@@ -0,0 +1,57 @@
+/**
+ * Agent tool-call wrapper tags that occasionally leak into an agent-authored
+ * plan body — e.g. a `Write` call whose closing `</content></invoke>` gets
+ * serialized into the file it was writing. These are never valid plan MDX, and
+ * a single stray closing tag makes remark-mdx throw ("Unexpected closing slash
+ * `/` in tag, expected an open tag first"), which the component-isolation
+ * recovery can't repair (they aren't capitalised component spans) — so the
+ * WHOLE plan silently degrades to plain Markdown and every `<PlanCanvas>` /
+ * `<Decision>` / … renders as prose. Stripping them lets the rest parse.
+ */
+const LEAKED_TAGS = [
+	"function_calls",
+	"invoke",
+	"parameter",
+	"content",
+	// Namespaced harness variants (e.g. `<invoke>`).
+	"antml:[A-Za-z0-9:_-]+",
+];
+
+/** A line that is ENTIRELY a single leaked wrapper tag (open, close, or
+ * self-closing), with optional attributes. Whole-line only, so an inline
+ * mention in prose ("the `</invoke>` tag") or a tag mid-sentence is never
+ * touched. */
+const LEAKED_TAG_LINE = new RegExp(
+	`^\\s*</?(?:${LEAKED_TAGS.join("|")})\\b[^>]*>\\s*$`,
+);
+
+const FENCE = /^\s*(```|~~~)/;
+
+/**
+ * Remove whole-line leaked tool-call wrapper tags from a plan body.
+ *
+ * - Only acts on lines OUTSIDE fenced code blocks — a plan may legitimately
+ *   *show* such markup inside a ``` example fence, and that must stay verbatim.
+ * - Returns `null` when nothing was removed, so callers can keep the original
+ *   (byte-identical) body for the overwhelming common case of a clean plan and
+ *   only pay the cost on an actually-corrupt one.
+ */
+export function stripLeakedToolTags(body: string): string | null {
+	const lines = body.split("\n");
+	const out: string[] = [];
+	let inFence = false;
+	let removed = false;
+	for (const line of lines) {
+		if (FENCE.test(line)) {
+			inFence = !inFence;
+			out.push(line);
+			continue;
+		}
+		if (!inFence && LEAKED_TAG_LINE.test(line)) {
+			removed = true;
+			continue;
+		}
+		out.push(line);
+	}
+	return removed ? out.join("\n") : null;
+}