feat(diagram-engine): style markers + XML→tree reverse parser

Groundwork for a declarative diagram engine where the model declares nesting and
the engine computes every coordinate, instead of the model emitting raw mxCell XML.

The design keeps the canvas as the SINGLE source of truth: the node tree is never
persisted, it is re-derived from the current canvas XML whenever needed. A user's
manual edits are therefore an input to the next re-layout, not a second copy of
the state that has to be reconciled.

Two behaviours this relies on, both verified against the real embedded editor with
a Playwright mouse drag (reading the editor's own autosave payload):

  1. An AWS group stencil WITHOUT container=1 does not get a dragged shape
     reparented — parent stays "1" and geometry stays absolute. WITH container=1
     it does: parent becomes the frame, geometry becomes parent-relative. So the
     engine must stamp container=1 on every container it emits.
  2. draw.io preserves style keys it does not understand, and resolves a duplicate
     key last-wins. So dai_* markers survive a user edit, and container=1 can be
     appended to a catalog style without first parsing out an existing value —
     which matters because the AWS catalog is inconsistent about it (group_vpc,
     group_region, group_subnet ship without it; group_account ships with it).

markers.ts  — dai_kind / dai_dir / dai_gap / dai_cols / dai_pin, and the container
              token normalisation.
types.ts    — the node tree contract, plus a `foreign` bucket so cells the engine
              does not understand (user annotations, imported shapes) round-trip
              verbatim rather than being destroyed by a re-layout.
parse.ts    — XML → tree. Handles all four icon encodings (resIcon=, bare shape=,
              shape=image data URI, grIcon=), resolves nesting from parent with a
              geometry fallback for frames that lack container=1, recovers layout
              direction from the marker or infers it from child positions, and
              survives cycles, compressed files and multi-page decks.

75 unit tests, including a round-trip against real output from the reference
project's build_vpc.mjs.

One finding worth recording: the reference project's "phantom" node (a wrapper that
participates in layout but emits no cell) makes the round-trip lossy by
construction. In build_vpc.mjs a phantom erased a container's col direction — its
children were reparented onto the grandparent, leaving a 2-D arrangement the parser
can only read as a grid. 26 of the reference project's 31 examples use phantoms, so
our engine needs an invisible-but-real container instead. Tracked separately.

lib/diagram-engine/markers.ts

@@ -0,0 +1,163 @@
+/**
+ * Style markers — how layout structure survives a round-trip through draw.io.
+ *
+ * The layout engine's tree carries information plain draw.io XML does not: which
+ * direction a container stacks its children, the gap between them, and whether the
+ * user has pinned a node's position. We encode that as extra `key=value` tokens in
+ * the cell's style string.
+ *
+ * Two behaviours this relies on, both verified in a real browser (Playwright drag
+ * against the embedded editor, reading the editor's own autosave payload):
+ *
+ *   1. draw.io PRESERVES style keys it does not understand. After a user drags a
+ *      shape and the editor saves, `dai_kind=group;dai_dir=col;dai_gap=22;` came
+ *      back byte-identical.
+ *   2. On a DUPLICATE key, the LAST value wins. A style ending in
+ *      `container=0;pointerEvents=0;container=1;` behaved as a container: a shape
+ *      dragged into it was reparented. So we can append a normalising token without
+ *      first parsing out the old one.
+ *
+ * (2) matters because the AWS catalog is inconsistent: group_region, group_vpc,
+ * group_subnet, group_availability_zone, group_aws_cloud and group_on_premise ship
+ * WITHOUT container=1, while group_account, group_aws_cloud_alt, group_vpc2,
+ * group_security_group and group_corporate_data_center ship WITH it. Appending
+ * unconditionally normalises all of them.
+ */
+
+/** Marker keys. Namespaced with `dai_` so they cannot collide with mxGraph keys. */
+export const MARKER = {
+    /** Node kind, so the parser does not have to re-guess it from the shape. */
+    kind: "dai_kind",
+    /** Child stacking direction of a container: "row" | "col" | "grid". */
+    dir: "dai_dir",
+    /** Gap between children, in px. */
+    gap: "dai_gap",
+    /** Column count, for grid containers. */
+    cols: "dai_cols",
+    /** Set by the user to freeze a node's position across re-layouts. */
+    pin: "dai_pin",
+} as const
+
+export type NodeKind = "group" | "grid" | "icon" | "box" | "title"
+export type Direction = "row" | "col" | "grid"
+
+/**
+ * Tokens that make a shape behave as a container in draw.io: it accepts a shape
+ * dragged into it and reparents that shape (setting `parent` and switching the
+ * child's geometry to parent-relative).
+ *
+ * `pointerEvents=0` keeps clicks falling through to the children — without it the
+ * frame swallows them and the user cannot select what is inside. `collapsible=0`
+ * hides the fold arrow. `recursiveResize=0` stops children from being scaled when
+ * the frame is resized, which would fight the layout engine.
+ */
+const CONTAINER_TOKENS =
+    "container=1;pointerEvents=0;collapsible=0;recursiveResize=0;"
+
+/** Read a marker's raw value out of a style string. Last occurrence wins, as draw.io does. */
+export function readMarker(style: string, key: string): string | null {
+    // Scan all matches and keep the last, mirroring draw.io's duplicate-key resolution.
+    const re = new RegExp(`(?:^|;)${key}=([^;]*)`, "g")
+    let last: string | null = null
+    let m = re.exec(style)
+    while (m !== null) {
+        last = m[1]
+        m = re.exec(style)
+    }
+    return last
+}
+
+export function readKind(style: string): NodeKind | null {
+    const v = readMarker(style, MARKER.kind)
+    if (
+        v === "group" ||
+        v === "grid" ||
+        v === "icon" ||
+        v === "box" ||
+        v === "title"
+    )
+        return v
+    return null
+}
+
+export function readDir(style: string): Direction | null {
+    const v = readMarker(style, MARKER.dir)
+    if (v === "row" || v === "col" || v === "grid") return v
+    return null
+}
+
+/** Read a positive integer marker (gap, cols). Returns null when absent or malformed. */
+export function readIntMarker(style: string, key: string): number | null {
+    const v = readMarker(style, key)
+    if (v === null) return null
+    const n = Number(v)
+    return Number.isFinite(n) && n >= 0 ? Math.round(n) : null
+}
+
+/**
+ * Has the user pinned this node? Any value other than "0"/""/"false" counts as
+ * pinned, so a user typing `dai_pin=1` (or just `dai_pin=yes`) in draw.io's
+ * "Edit Style" dialog gets what they expect.
+ */
+export function isPinned(style: string): boolean {
+    const v = readMarker(style, MARKER.pin)
+    if (v === null) return false
+    const s = v.trim().toLowerCase()
+    return s !== "" && s !== "0" && s !== "false"
+}
+
+/** Append `key=value;`, ensuring the style ends with a separator first. */
+function append(style: string, key: string, value: string | number): string {
+    const base = style.endsWith(";") || style === "" ? style : `${style};`
+    return `${base}${key}=${value};`
+}
+
+/**
+ * Stamp a container's style: make it a real draw.io container and record its
+ * layout parameters.
+ *
+ * Appends rather than rewrites. Duplicate keys are legal and the last one wins, so
+ * a catalog style that already says `container=1` is unharmed, and one that says
+ * nothing (or `container=0`) is corrected.
+ */
+export function stampContainer(
+    style: string,
+    opts: {
+        kind: "group" | "grid"
+        dir: Direction
+        gap: number
+        cols?: number
+    },
+): string {
+    let s = style.endsWith(";") || style === "" ? style : `${style};`
+    s += CONTAINER_TOKENS
+    s = append(s, MARKER.kind, opts.kind)
+    s = append(s, MARKER.dir, opts.dir)
+    s = append(s, MARKER.gap, Math.round(opts.gap))
+    if (opts.kind === "grid" && opts.cols != null)
+        s = append(s, MARKER.cols, Math.max(1, Math.round(opts.cols)))
+    return s
+}
+
+/** Stamp a leaf (icon or box) with its kind, so the parser need not infer it. */
+export function stampLeaf(
+    style: string,
+    kind: "icon" | "box" | "title",
+): string {
+    return append(style, MARKER.kind, kind)
+}
+
+/** Strip every `dai_*` marker — for exporting a clean file, or comparing styles. */
+export function stripMarkers(style: string): string {
+    return style
+        .split(";")
+        .filter((tok) => tok !== "" && !tok.startsWith("dai_"))
+        .join(";")
+        .concat(";")
+        .replace(/^;$/, "")
+}
+
+/** Does this style carry any engine marker? Used to tell engine output from imported files. */
+export function hasMarkers(style: string): boolean {
+    return /(?:^|;)dai_[a-z]+=/.test(style)
+}

lib/diagram-engine/parse.ts

@@ -0,0 +1,538 @@
+/**
+ * XML → tree. The reverse direction, which the reference project (drawio-ai-kit) does
+ * not have — it only goes tree → XML.
+ *
+ * This is what lets the canvas be the single source of truth. The model never holds a
+ * copy of the tree; whenever it wants to restructure a diagram we re-derive the tree
+ * from whatever is on the canvas right now, including everything the user changed by
+ * hand. There is no second copy of the state to drift out of sync.
+ *
+ * Two things make this viable, and both were verified against the real editor:
+ *
+ *   - Engine-emitted containers carry `container=1`, so when a user drags a shape into
+ *     a frame draw.io sets the shape's `parent` to that frame and rewrites its geometry
+ *     to be parent-relative. The `parent` attribute therefore tracks what the user did.
+ *   - draw.io preserves unknown style keys, so the `dai_*` markers written at emit time
+ *     are still there on the way back.
+ *
+ * When a container lacks `container=1` (an imported file, or output from the old
+ * hand-written-XML path) the `parent` attribute and the visual nesting can disagree: a
+ * shape sits inside a frame on screen but its parent is still the root layer. We trust
+ * GEOMETRY over `parent` in exactly that case, and only that case — see resolveNesting.
+ */
+
+import { extractDiagramXML } from "@/lib/utils"
+import {
+    type Direction,
+    hasMarkers,
+    isPinned,
+    readDir,
+    readIntMarker,
+    readKind,
+} from "./markers"
+import type {
+    BoxNode,
+    DiagramNode,
+    DiagramTree,
+    ForeignCell,
+    GridNode,
+    GroupNode,
+    IconNode,
+    LinkSpec,
+    Rect,
+} from "./types"
+
+/** draw.io's own layer/root cells, plus the boundaries layer the engine emits. */
+const LAYER_IDS = new Set(["0", "1", "boundaries"])
+
+/** A flattened cell, before it becomes a node. */
+interface RawCell {
+    id: string
+    parent: string
+    style: string
+    value: string
+    isEdge: boolean
+    source: string | null
+    target: string | null
+    /** Geometry as written: relative to the parent for a nested cell. */
+    geo: Rect | null
+    /** Geometry resolved to page coordinates through the parent chain. */
+    abs: Rect | null
+    /** The cell's serialised XML, kept so unrecognised cells survive verbatim. */
+    xml: string
+}
+
+export interface ParseResult {
+    tree: DiagramTree
+    /** True when no cell carried a `dai_*` marker — an imported or legacy diagram. */
+    needsAdoption: boolean
+    /** Non-fatal problems worth surfacing (cycles broken, cells dropped). */
+    warnings: string[]
+}
+
+/**
+ * Pull the mxGraphModel body of one page out of whatever the caller has: an mxfile
+ * document, a bare mxGraphModel, or the XML embedded in an exported SVG.
+ */
+export function extractPage(xml: string, pageIndex = 0): string | null {
+    let doc = xml.trim()
+    if (doc.startsWith("<svg") || doc.includes("<svg ")) {
+        const inner = extractDiagramXML(doc)
+        if (inner) doc = inner.trim()
+    }
+    const diagrams = [...doc.matchAll(/<diagram\b[^>]*>([\s\S]*?)<\/diagram>/g)]
+    if (diagrams.length > 0) {
+        const body = diagrams[Math.min(pageIndex, diagrams.length - 1)][1]
+        // A compressed page is base64 with no markup — nothing to parse.
+        if (!/<mxCell\b/.test(body)) return null
+        return body
+    }
+    return /<mxCell\b/.test(doc) ? doc : null
+}
+
+/** How many pages the document has. */
+export function countPages(xml: string): number {
+    return [...xml.matchAll(/<diagram\b[^>]*>/g)].length || 1
+}
+
+function attr(tag: string, name: string): string | null {
+    const m = tag.match(new RegExp(`\\b${name}="([^"]*)"`))
+    return m ? m[1] : null
+}
+
+/** Undo the XML entity escaping the builder applies to labels. */
+function unescapeXml(s: string): string {
+    return s
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, "&")
+}
+
+/**
+ * Split the page into cells with a regex rather than a DOM parser.
+ *
+ * The DOM route needs a real parser (browser DOMParser or @xmldom/xmldom) and gives us
+ * nothing extra here: we want each cell's raw XML preserved byte-for-byte so foreign
+ * cells can be re-emitted untouched, and re-serialising a DOM node changes attribute
+ * order and whitespace. The reference project's validator parses the same way.
+ */
+function splitCells(page: string): RawCell[] {
+    const out: RawCell[] = []
+    // Match a full <mxCell …/> or <mxCell …>…</mxCell>.
+    const re = /<mxCell\b[^>]*?(?:\/>|>[\s\S]*?<\/mxCell>)/g
+    for (const m of page.matchAll(re)) {
+        const xml = m[0]
+        const head = xml.slice(0, xml.indexOf(">") + 1)
+        const id = attr(head, "id")
+        if (!id) continue
+        const geoTag = xml.match(/<mxGeometry\b[^>]*?(?:\/>|>)/)?.[0] ?? ""
+        const num = (n: string) => {
+            const v = attr(geoTag, n)
+            return v === null ? null : Number(v)
+        }
+        const x = num("x")
+        const y = num("y")
+        const w = num("width")
+        const h = num("height")
+        out.push({
+            id,
+            parent: attr(head, "parent") ?? "",
+            style: attr(head, "style") ?? "",
+            value: unescapeXml(attr(head, "value") ?? ""),
+            isEdge: attr(head, "edge") === "1",
+            source: attr(head, "source"),
+            target: attr(head, "target"),
+            geo:
+                w !== null && h !== null
+                    ? { x: x ?? 0, y: y ?? 0, w, h }
+                    : null,
+            abs: null,
+            xml,
+        })
+    }
+    return out
+}
+
+/**
+ * Resolve every cell's geometry into page coordinates.
+ *
+ * A nested cell's geometry is relative to its parent, so absolute position is the sum
+ * down the parent chain. The hop limit breaks a cycle in a malformed file instead of
+ * hanging.
+ */
+function resolveAbsolute(cells: RawCell[], warnings: string[]): void {
+    const byId = new Map(cells.map((c) => [c.id, c]))
+    for (const c of cells) {
+        if (!c.geo) continue
+        let x = c.geo.x
+        let y = c.geo.y
+        let p = byId.get(c.parent)
+        let hops = 0
+        while (p && hops < 50) {
+            if (p.geo) {
+                x += p.geo.x
+                y += p.geo.y
+            }
+            p = byId.get(p.parent)
+            hops++
+        }
+        if (hops >= 50)
+            warnings.push(
+                `Parent chain of "${c.id}" exceeded 50 hops — possible cycle; geometry may be wrong.`,
+            )
+        c.abs = { x, y, w: c.geo.w, h: c.geo.h }
+    }
+}
+
+/** Does this style declare a draw.io container? Last duplicate wins, as draw.io does. */
+function declaresContainer(style: string): boolean {
+    const matches = [...style.matchAll(/(?:^|;)container=([^;]*)/g)]
+    if (matches.length === 0) return false
+    return matches[matches.length - 1][1] === "1"
+}
+
+/**
+ * Classify a cell.
+ *
+ * The marker wins when present. Without one we fall back to the shape, which has to
+ * cover four different icon encodings: `resIcon=mxgraph.aws4.<name>` (554 of the 983
+ * AWS icons), a bare `shape=mxgraph.aws4.<name>` (the other 429), `shape=image` with an
+ * embedded data URI (all 626 Azure and 216 GCP icons), and `grIcon=` for group frames.
+ * Keying only on `resIcon=` would misread well over a thousand icons as plain boxes.
+ */
+function classify(
+    c: RawCell,
+    hasChildren: boolean,
+): "group" | "grid" | "icon" | "box" | "title" {
+    const marked = readKind(c.style)
+    if (marked) return marked
+
+    if (/(?:^|;)text;/.test(c.style) || c.id === "__title") return "title"
+    // A group stencil, or anything draw.io treats as a container, or anything that
+    // actually holds children — all are containers regardless of how they were styled.
+    if (/grIcon=/.test(c.style) || declaresContainer(c.style) || hasChildren)
+        return "group"
+    if (
+        /resIcon=/.test(c.style) ||
+        /shape=mxgraph\.[a-z0-9_]+\./.test(c.style) ||
+        /shape=image/.test(c.style)
+    )
+        return "icon"
+    return "box"
+}
+
+/** The catalog name of an icon, when it can be recovered from the style. */
+function iconName(style: string): string | null {
+    return (
+        style.match(/resIcon=mxgraph\.[a-z0-9_]+\.([a-zA-Z0-9_]+)/)?.[1] ??
+        style.match(/shape=mxgraph\.[a-z0-9_]+\.([a-zA-Z0-9_]+)/)?.[1] ??
+        null
+    )
+}
+
+/** The group stencil name of a container, when it has one. */
+function groupName(style: string): string | null {
+    return (
+        style.match(/grIcon=mxgraph\.[a-z0-9_]+\.([a-zA-Z0-9_]+)/)?.[1] ?? null
+    )
+}
+
+function styleValue(style: string, key: string): string | undefined {
+    const all = [...style.matchAll(new RegExp(`(?:^|;)${key}=([^;]*)`, "g"))]
+    return all.length ? all[all.length - 1][1] : undefined
+}
+
+/**
+ * Decide each cell's true parent.
+ *
+ * Normally `parent` is authoritative: with `container=1` in place draw.io maintains it
+ * as the user drags things around. The exception is a container WITHOUT `container=1`
+ * — draw.io will not reparent into it, so a shape the user dropped inside it visually
+ * still claims the root layer as its parent. There, and only there, we believe the
+ * geometry: if a cell sits geometrically inside such a frame and its declared parent is
+ * a layer, we re-home it into the smallest frame that contains it.
+ *
+ * Trusting geometry unconditionally would be wrong the other way round: a legitimately
+ * reparented cell whose geometry got stale for a frame, or a deliberately overlapping
+ * badge, would be silently moved.
+ */
+function resolveNesting(cells: RawCell[]): Map<string, string> {
+    const byId = new Map(cells.map((c) => [c.id, c]))
+    const parentOf = new Map<string, string>()
+
+    const contains = (outer: Rect, inner: Rect) =>
+        inner.x >= outer.x - 2 &&
+        inner.y >= outer.y - 2 &&
+        inner.x + inner.w <= outer.x + outer.w + 2 &&
+        inner.y + inner.h <= outer.y + outer.h + 2
+
+    // Frames that draw.io will NOT reparent into, so their contents may be mis-parented.
+    const looseFrames = cells.filter(
+        (c) =>
+            !c.isEdge &&
+            c.abs !== null &&
+            !declaresContainer(c.style) &&
+            (/grIcon=/.test(c.style) || readKind(c.style) === "group"),
+    )
+
+    for (const c of cells) {
+        let p = c.parent
+        const declaredIsLayer = LAYER_IDS.has(p) || !byId.has(p)
+        if (declaredIsLayer && c.abs && !c.isEdge && looseFrames.length > 0) {
+            let best: RawCell | null = null
+            for (const f of looseFrames) {
+                if (f.id === c.id || !f.abs) continue
+                if (!contains(f.abs, c.abs)) continue
+                // smallest containing frame — the innermost one the user dropped into
+                if (!best?.abs || f.abs.w * f.abs.h < best.abs.w * best.abs.h)
+                    best = f
+            }
+            if (best) p = best.id
+        }
+        parentOf.set(c.id, p)
+    }
+    return parentOf
+}
+
+/**
+ * Recover a container's stacking direction and gap from its children's positions.
+ *
+ * Used only when the style marker is missing. Compares how much the children spread
+ * along each axis: a row varies in x and shares y, a column the reverse. Ties and
+ * genuinely two-dimensional arrangements fall back to a row, which is what an
+ * unlabelled cluster of icons most often is.
+ */
+function inferLayout(children: RawCell[]): { dir: Direction; gap: number } {
+    const boxes = children
+        .map((c) => c.abs)
+        .filter((r): r is Rect => r !== null)
+    if (boxes.length < 2) return { dir: "row", gap: 20 }
+
+    const xs = boxes.map((b) => b.x)
+    const ys = boxes.map((b) => b.y)
+    const spreadX = Math.max(...xs) - Math.min(...xs)
+    const spreadY = Math.max(...ys) - Math.min(...ys)
+
+    // Distinct row/column bands, to notice a real grid.
+    const bands = (vals: number[], tol: number) => {
+        const sorted = [...vals].sort((a, b) => a - b)
+        let n = 1
+        for (let i = 1; i < sorted.length; i++)
+            if (sorted[i] - sorted[i - 1] > tol) n++
+        return n
+    }
+    const rows = bands(ys, 20)
+    const cols = bands(xs, 20)
+    if (rows > 1 && cols > 1) return { dir: "grid", gap: 20 }
+
+    const dir: Direction = spreadX >= spreadY ? "row" : "col"
+
+    // Gap = median edge-to-edge distance between neighbours along the flow axis.
+    const sorted = [...boxes].sort((a, b) =>
+        dir === "row" ? a.x - b.x : a.y - b.y,
+    )
+    const gaps: number[] = []
+    for (let i = 1; i < sorted.length; i++) {
+        const prev = sorted[i - 1]
+        const cur = sorted[i]
+        gaps.push(
+            dir === "row"
+                ? cur.x - (prev.x + prev.w)
+                : cur.y - (prev.y + prev.h),
+        )
+    }
+    gaps.sort((a, b) => a - b)
+    const median = gaps.length ? gaps[Math.floor(gaps.length / 2)] : 20
+    return { dir, gap: Math.max(0, Math.round(median)) }
+}
+
+/** Turn an edge cell into a link spec. */
+function toLink(c: RawCell): LinkSpec | null {
+    if (!c.source || !c.target) return null
+    let label = c.value
+    let step: number | undefined
+    const m = label.match(/^(\d+)\.\s*(.*)$/)
+    if (m) {
+        step = Number(m[1])
+        label = m[2]
+    }
+    return {
+        id: c.id,
+        source: c.source,
+        target: c.target,
+        label: label || undefined,
+        dashed: /(?:^|;)dashed=1/.test(c.style) || undefined,
+        step,
+        style: c.style,
+    }
+}
+
+/**
+ * Re-derive the node tree from a page of canvas XML.
+ *
+ * Cells the classifier cannot place — a shape whose parent is a foreign cell, anything
+ * on the boundaries layer — are returned in `tree.foreign` and re-emitted verbatim, so
+ * a re-layout never deletes a user's annotations.
+ */
+export function parseDiagram(xml: string, pageIndex = 0): ParseResult {
+    const warnings: string[] = []
+    const page = extractPage(xml, pageIndex)
+    if (!page)
+        return {
+            tree: { roots: [], links: [], foreign: [] },
+            needsAdoption: true,
+            warnings: [
+                "No cells found — the page is empty or the .drawio is compressed.",
+            ],
+        }
+
+    const cells = splitCells(page)
+    resolveAbsolute(cells, warnings)
+
+    const marked = cells.some((c) => hasMarkers(c.style))
+    const parentOf = resolveNesting(cells)
+
+    const vertices = cells.filter((c) => !c.isEdge && !LAYER_IDS.has(c.id))
+    const edges = cells.filter((c) => c.isEdge)
+
+    // children, in document order — which is layout order for engine output
+    const childrenOf = new Map<string, RawCell[]>()
+    for (const c of vertices) {
+        const p = parentOf.get(c.id) ?? ""
+        if (!childrenOf.has(p)) childrenOf.set(p, [])
+        childrenOf.get(p)?.push(c)
+    }
+
+    const byId = new Map(cells.map((c) => [c.id, c]))
+    const kindOf = new Map<string, ReturnType<typeof classify>>()
+    for (const c of vertices)
+        kindOf.set(c.id, classify(c, (childrenOf.get(c.id)?.length ?? 0) > 0))
+
+    const foreign: ForeignCell[] = []
+    let title: string | undefined
+
+    const build = (c: RawCell, depth: number): DiagramNode | null => {
+        if (depth > 50) {
+            warnings.push(
+                `Nesting deeper than 50 at "${c.id}" — subtree dropped.`,
+            )
+            return null
+        }
+        const kind = kindOf.get(c.id) ?? "box"
+        const pinned = isPinned(c.style) || undefined
+        const rect = c.abs ?? undefined
+
+        if (kind === "title") {
+            if (title === undefined) title = c.value
+            return null // laid out separately, not part of the flow
+        }
+
+        if (kind === "icon") {
+            const node: IconNode = {
+                kind: "icon",
+                id: c.id,
+                name: iconName(c.style) ?? "",
+                label: c.value,
+                style: c.style,
+                size: c.geo ? Math.round(c.geo.w) : undefined,
+                pinned,
+                rect,
+            }
+            return node
+        }
+
+        if (kind === "box") {
+            const node: BoxNode = {
+                kind: "box",
+                id: c.id,
+                label: c.value,
+                w: c.geo ? Math.round(c.geo.w) : undefined,
+                h: c.geo ? Math.round(c.geo.h) : undefined,
+                fill: styleValue(c.style, "fillColor"),
+                stroke: styleValue(c.style, "strokeColor"),
+                style: c.style,
+                pinned,
+                rect,
+            }
+            return node
+        }
+
+        // container
+        const kids = childrenOf.get(c.id) ?? []
+        const built = kids
+            .map((k) => build(k, depth + 1))
+            .filter((n): n is DiagramNode => n !== null)
+        const markedDir = readDir(c.style)
+        const markedGap = readIntMarker(c.style, "dai_gap")
+        const inferred = markedDir === null ? inferLayout(kids) : null
+        const dir = markedDir ?? inferred?.dir ?? "row"
+        const gap = markedGap ?? inferred?.gap ?? 20
+
+        if (kind === "grid" || dir === "grid") {
+            const cols =
+                readIntMarker(c.style, "dai_cols") ??
+                Math.max(1, Math.round(Math.sqrt(built.length)))
+            const node: GridNode = {
+                kind: "grid",
+                id: c.id,
+                gname: groupName(c.style),
+                label: c.value,
+                cols,
+                gap,
+                children: built,
+                fill: styleValue(c.style, "fillColor"),
+                stroke: styleValue(c.style, "strokeColor"),
+                style: c.style,
+                pinned,
+                rect,
+            }
+            return node
+        }
+
+        const node: GroupNode = {
+            kind: "group",
+            id: c.id,
+            gname: groupName(c.style),
+            label: c.value,
+            dir: dir === "col" ? "col" : "row",
+            gap,
+            children: built,
+            fill: styleValue(c.style, "fillColor"),
+            stroke: styleValue(c.style, "strokeColor"),
+            style: c.style,
+            pinned,
+            rect,
+        }
+        return node
+    }
+
+    // Roots: cells parented to a layer. The boundaries layer holds engine-drawn
+    // cluster frames, which are decoration over the real nesting — keep them verbatim.
+    const roots: DiagramNode[] = []
+    for (const c of vertices) {
+        const p = parentOf.get(c.id) ?? ""
+        if (byId.has(p) && !LAYER_IDS.has(p)) continue // not a root
+        if (p === "boundaries") {
+            foreign.push({ id: c.id, xml: c.xml, parent: p })
+            continue
+        }
+        const n = build(c, 0)
+        if (n) roots.push(n)
+    }
+
+    const links = edges.map(toLink).filter((l): l is LinkSpec => l !== null)
+
+    const pages = countPages(xml)
+    if (pages > 1)
+        warnings.push(
+            `Document has ${pages} pages; parsed page ${pageIndex + 1} only.`,
+        )
+
+    return {
+        tree: { roots, links, title, foreign },
+        needsAdoption: !marked,
+        warnings,
+    }
+}

lib/diagram-engine/types.ts

@@ -0,0 +1,173 @@
+/**
+ * The declarative node tree the layout engine works on.
+ *
+ * The model never writes coordinates. It declares nesting and direction; the engine
+ * computes every x/y/width/height. The tree is not persisted anywhere — it is
+ * re-derived from the canvas XML whenever it is needed (see parse.ts), so the canvas
+ * stays the single source of truth and a user's manual edits are an input, never
+ * something to be reconciled against a second copy of the state.
+ */
+
+import type { Direction } from "./markers"
+
+export type { Direction } from "./markers"
+
+/** A catalog icon: a real stencil, drawn at a fixed glyph size with a label below. */
+export interface IconNode {
+    kind: "icon"
+    id: string
+    /** Catalog name, e.g. "s3" or "azure_virtual_machine". Resolved to a style by the catalog. */
+    name: string
+    label: string
+    /** Glyph size in px. Defaults to the diagram's icon size. */
+    size?: number
+    /** Verbatim style, when recovered from XML. Preferred over re-resolving `name`. */
+    style?: string
+    /** User froze this node's position — the engine must not move it. */
+    pinned?: boolean
+    /** Absolute geometry, when recovered from XML. Only meaningful for a pinned node. */
+    rect?: Rect
+}
+
+/** A plain labelled rectangle, for things the catalog has no icon for. */
+export interface BoxNode {
+    kind: "box"
+    id: string
+    label: string
+    w?: number
+    h?: number
+    fill?: string
+    stroke?: string
+    bold?: boolean
+    style?: string
+    pinned?: boolean
+    rect?: Rect
+}
+
+/** A page title. At most one per diagram; laid out outside the tree flow. */
+export interface TitleNode {
+    kind: "title"
+    id: string
+    label: string
+}
+
+/**
+ * A container that stacks its children in one direction.
+ *
+ * `gname` is the catalog group stencil (group_vpc, group_region, …). When null the
+ * container renders as a plain frame — a labelled rectangle with a border.
+ */
+export interface GroupNode {
+    kind: "group"
+    id: string
+    gname: string | null
+    label: string
+    dir: Extract<Direction, "row" | "col">
+    gap: number
+    children: DiagramNode[]
+    fill?: string
+    stroke?: string
+    style?: string
+    pinned?: boolean
+    rect?: Rect
+}
+
+/** A container that packs its children into a fixed number of columns. */
+export interface GridNode {
+    kind: "grid"
+    id: string
+    gname: string | null
+    label: string
+    cols: number
+    gap: number
+    children: DiagramNode[]
+    fill?: string
+    stroke?: string
+    style?: string
+    pinned?: boolean
+    rect?: Rect
+}
+
+export type ContainerNode = GroupNode | GridNode
+export type LeafNode = IconNode | BoxNode | TitleNode
+export type DiagramNode = ContainerNode | LeafNode
+
+export interface Rect {
+    x: number
+    y: number
+    w: number
+    h: number
+}
+
+/** An arrow. Routing is the engine's business; the model only says what connects to what. */
+export interface LinkSpec {
+    /** Cell id, so an existing edge can be addressed by later operations. */
+    id?: string
+    source: string
+    target: string
+    label?: string
+    /** Dashed line — replication, sync, policy, lineage. */
+    dashed?: boolean
+    /** Step number, rendered as an "N. " prefix on the label. */
+    step?: number
+    /** Verbatim style, when recovered from XML. */
+    style?: string
+}
+
+/** A whole diagram page: the node forest plus its arrows. */
+export interface DiagramTree {
+    /** Top-level nodes, in layout order. */
+    roots: DiagramNode[]
+    links: LinkSpec[]
+    /** Page title, if the diagram has one. */
+    title?: string
+    /**
+     * Cells the parser could not fit into the tree — a user's own annotation boxes, a
+     * legend, shapes from an imported file. Kept verbatim and re-emitted untouched so
+     * a re-layout never destroys work the engine does not understand.
+     */
+    foreign: ForeignCell[]
+}
+
+/** A cell carried through the round-trip without interpretation. */
+export interface ForeignCell {
+    id: string
+    /** The cell's own serialised XML, verbatim. */
+    xml: string
+    /** Parent id at parse time, so it can be re-attached. */
+    parent: string
+}
+
+export function isContainer(n: DiagramNode): n is ContainerNode {
+    return n.kind === "group" || n.kind === "grid"
+}
+
+export function isLeaf(n: DiagramNode): n is LeafNode {
+    return !isContainer(n)
+}
+
+/** Depth-first walk over a node and its descendants. */
+export function* walk(n: DiagramNode): Generator<DiagramNode> {
+    yield n
+    if (isContainer(n)) for (const c of n.children) yield* walk(c)
+}
+
+/** Every node in a tree, in document order. */
+export function* walkTree(t: DiagramTree): Generator<DiagramNode> {
+    for (const r of t.roots) yield* walk(r)
+}
+
+/** Find a node by id, or null. */
+export function findNode(t: DiagramTree, id: string): DiagramNode | null {
+    for (const n of walkTree(t)) if (n.id === id) return n
+    return null
+}
+
+/** The container holding `id`, or null when it is a root or absent. */
+export function findParent(t: DiagramTree, id: string): ContainerNode | null {
+    for (const n of walkTree(t)) {
+        if (!isContainer(n)) continue
+        if (n.children.some((c) => c.id === id)) return n
+    }
+    return null
+}