feat(mcp-server): load .drawio.svg, change summary, XML reference by topic, preview options, truncation message (#982)

* feat(mcp-server): load .drawio.svg (Editable SVG) files with load_diagram

* feat(mcp-server): summarize the user's manual changes per cell in stale rejections and get_diagram

* feat(mcp-server): XML reference for tables, layers and groups via get_drawing_guide topic

* feat(mcp-server): DRAWIO_LANG, DRAWIO_UI and DRAWIO_DARK for the preview page

Three host-config environment variables fix the language, theme and
dark mode of the draw.io editor embedded in the preview page. The new
drawio-themes module holds the theme list and draw.io's locale names
(zh-hant becomes zh-tw); drawioEmbedParams() in http-server.ts builds
the variable tail of the iframe query and getHtmlPage fills the new
{{DRAWIO_PARAMS}} placeholder. Without the variables the page keeps
sending dark=auto as before. Both READMEs document the variables.

* feat(mcp-server): report XML cut off inside a cell and explain drawing in parts

create_new_diagram and add_page now detect bare-cell XML that ends inside an
unfinished mxCell (XML comments stripped first) and return an error with the
last 300 characters of the input, asking the model to resend from that cell or
continue with edit_diagram add operations. isMxCellXmlComplete moves from
lib/utils.ts into packages/mcp-server/src/new-diagram.ts and is re-exported
from lib/utils.ts for the web app. The drawing guide gains a "Large diagrams"
paragraph and the INSTRUCTIONS edit_diagram line mentions drawing in parts.

* fix(mcp-server): review fixes for load .drawio.svg, change summary, XML reference, draw.io embed options, truncation message

* fix(mcp-server): Codex review fixes for .drawio.svg loading, change summary, references, embed options and truncation

- Truncation check: a closing tag such as </mxCell/> that the auto-fix
  repairs is no cut, and input without any cell keeps the validator's
  message
- Guide: a call rejected as cut off drew nothing, so all of its cells are
  sent again; the topic pointer is its own paragraph
- Change summary: decoded labels (no &nbsp; or merged words from <br>),
  a fast path for equal XML, and "the order of the cells changed" as
  the fallback
- DRAWIO_UI in any case, DRAWIO_LANG=zh-Hans maps to draw.io's zh
- load_diagram and export_diagram describe which files load again

packages/mcp-server/src/edit-gate.ts

@@ -142,3 +142,116 @@ export function markPageSeen(
         ? liveXml
         : lastSeenXml
 }
+
+const CELL_TAGS = new Set(["mxCell", "UserObject", "object"])
+
+/** The cells of a page by id: the direct children of its <root>. */
+function pageCells(page: Element): Map<string, Element> {
+    const cells = new Map<string, Element>()
+    for (const el of Array.from(page.querySelector("root")?.children ?? [])) {
+        const id = el.getAttribute("id")
+        if (id && CELL_TAGS.has(el.tagName)) cells.set(id, el)
+    }
+    return cells
+}
+
+/** `id ("label")`: the cell's value without HTML, cut at 30 characters. */
+function describeCell(id: string, cell: Element): string {
+    // getAttributeNode gives the decoded value (linkedom's getAttribute
+    // escapes it again); an HTML label then still holds tags and entities
+    const label = (
+        (cell.getAttributeNode("value") ?? cell.getAttributeNode("label"))
+            ?.value ?? ""
+    )
+        .replace(/<[^>]*>/g, " ")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&amp;/g, "&")
+        .replace(/\s+/g, " ")
+        .trim()
+    if (!label) return id
+    return `${id} ("${label.length > 30 ? `${label.slice(0, 30)}...` : label}")`
+}
+
+/** At most 20 entries, then "and N more". */
+function listCells(cells: string[]): string {
+    const shown = cells.slice(0, 20).join(", ")
+    return cells.length > 20 ? `${shown} and ${cells.length - 20} more` : shown
+}
+
+/**
+ * One paragraph naming what the user changed between the XML the model last
+ * saw and the live store, for stale rejections and get_diagram. Pages are
+ * paired by index (draw.io regenerates diagram ids on re-serialisation) and
+ * cells by id. Returns "" when there is nothing to compare or the two sides
+ * have the same content.
+ */
+export function describeChanges(lastSeenXml: string, liveXml: string): string {
+    if (!lastSeenXml || lastSeenXml === liveXml) return ""
+    const parse = (xml: string) => {
+        const normalized = normalizeToMxfile(xml)
+        return normalized ? parseMxfile(normalized) : null
+    }
+    const before = parse(lastSeenXml)
+    const live = parse(liveXml)
+    if (!before || !live) return ""
+    // Same rule as checkEditGate: a bare <mxGraphModel> carries no page name
+    const includeNames =
+        !isMxGraphModel(liveXml) && !isMxGraphModel(lastSeenXml)
+    if (
+        contentFingerprint(lastSeenXml, includeNames) ===
+        contentFingerprint(liveXml, includeNames)
+    )
+        return ""
+
+    const pagesBefore = Array.from(before.querySelectorAll("diagram"))
+    const pagesLive = Array.from(live.querySelectorAll("diagram"))
+    const pageCount = Math.max(pagesBefore.length, pagesLive.length)
+    const clauses: string[] = []
+    const renames: string[] = []
+    for (let i = 0; i < pageCount; i++) {
+        const pageBefore = pagesBefore[i]
+        const pageLive = pagesLive[i]
+        if (!pageBefore || !pageLive) {
+            clauses.push(`page ${i + 1} ${pageLive ? "added" : "removed"}`)
+            continue
+        }
+        const cellsBefore = pageCells(pageBefore)
+        const cellsLive = pageCells(pageLive)
+        const modified: string[] = []
+        const added: string[] = []
+        const removed: string[] = []
+        for (const [id, cell] of cellsLive) {
+            const old = cellsBefore.get(id)
+            if (!old) added.push(describeCell(id, cell))
+            else if (canonicalizeElement(old) !== canonicalizeElement(cell))
+                modified.push(describeCell(id, cell))
+        }
+        for (const [id, cell] of cellsBefore) {
+            if (!cellsLive.has(id)) removed.push(describeCell(id, cell))
+        }
+        // Name the page only when the document has several
+        const where = pageCount > 1 ? `page ${i + 1} ` : ""
+        if (modified.length)
+            clauses.push(`${where}modified ${listCells(modified)}`)
+        if (added.length) clauses.push(`${where}added ${listCells(added)}`)
+        if (removed.length)
+            clauses.push(`${where}removed ${listCells(removed)}`)
+        if (includeNames) {
+            const name = pageLive.getAttribute("name") ?? ""
+            if (name !== (pageBefore.getAttribute("name") ?? ""))
+                renames.push(`Page ${i + 1} renamed to "${name}".`)
+        }
+    }
+    // The fingerprint also covers the cell order (z-order) and anything in
+    // <root> that is not a cell
+    if (!clauses.length && !renames.length)
+        clauses.push("the order of the cells changed")
+    const intro = "Since you last saw it, the user changed the diagram"
+    const body = clauses.length
+        ? `${intro}: ${clauses.join("; ")}.`
+        : `${intro}.`
+    return [body, ...renames].join(" ")
+}