Add critical edge geometry requirements to documentation and code comments

alderg · alderg · commit fe8e05951047 · 2026-03-11T10:07:46.000+01:00
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -85,6 +85,13 @@ Opens the draw.io editor with a Mermaid.js diagram definition.
 
 ## Edge Routing Best Practices
 
+**CRITICAL: Every edge `mxCell` must contain a `<mxGeometry relative="1" as="geometry" />` child element**, even when there are no waypoints. Self-closing edge cells (e.g. `<mxCell ... edge="1" ... />`) are invalid and will not render correctly. Always use the expanded form:
+```xml
+<mxCell id="e1" edge="1" parent="1" source="a" target="b" style="...">
+  <mxGeometry relative="1" as="geometry" />
+</mxCell>
+```
+
 draw.io does **not** have built-in collision detection for edges. You must plan layout and routing carefully:
 
 - Use `edgeStyle=orthogonalEdgeStyle` for right-angle connectors (most common)
diff --git a/mcp-app-server/src/shared.js b/mcp-app-server/src/shared.js
@@ -324,6 +324,7 @@ export function createServer(html, serverOptions = {})
       description:
         "Creates and displays an interactive draw.io diagram. Pass draw.io XML (mxGraphModel format) to render it inline. " +
         "IMPORTANT: The XML must be well-formed. Do NOT use double hyphens (--) inside XML comments, as this is invalid XML and will break the parser. Use single hyphens or rephrase instead (e.g. <!-- Order 1 to OrderItem --> not <!-- Order 1 --- OrderItem -->). " +
+        "EDGE GEOMETRY: Every edge mxCell MUST contain a <mxGeometry relative=\"1\" as=\"geometry\" /> child element, even when there are no waypoints. Self-closing edge cells (<mxCell ... edge=\"1\" ... />) are invalid and will not render correctly. " +
         "EDGE ROUTING: Use edgeStyle=orthogonalEdgeStyle for right-angle connectors. " +
         "Space nodes at least 60px apart to avoid overlapping edges. " +
         "Use exitX/exitY/entryX/entryY (0-1) to control which side of a node an edge connects to, spreading connections across different sides. " +
diff --git a/mcp-tool-server/src/index.js b/mcp-tool-server/src/index.js
@@ -109,6 +109,7 @@ const tools =
       "Use this to view, edit, or create diagrams in draw.io format. " +
       "The XML should be valid draw.io/mxGraph XML format. " +
       "IMPORTANT: Do NOT use double hyphens (--) inside XML comments, as this is invalid XML and will break the parser. Use single hyphens or rephrase instead. " +
+      "EDGE GEOMETRY: Every edge mxCell MUST contain a <mxGeometry relative=\"1\" as=\"geometry\" /> child element, even when there are no waypoints. Self-closing edge cells (<mxCell ... edge=\"1\" ... />) are invalid and will not render correctly. " +
       "EDGE ROUTING: Use edgeStyle=orthogonalEdgeStyle for right-angle connectors. " +
       "Space nodes at least 60px apart to avoid overlapping edges. " +
       "Use exitX/exitY/entryX/entryY (0-1) to control which side of a node an edge connects to, spreading connections across different sides. " +
diff --git a/project-instructions/claude-project-instructions.txt b/project-instructions/claude-project-instructions.txt
@@ -105,6 +105,13 @@ print(f"""<!DOCTYPE html>
 
 ## Edge Routing (XML)
 
+**CRITICAL: Every edge `mxCell` must contain a `<mxGeometry relative="1" as="geometry" />` child element**, even when there are no waypoints. Self-closing edge cells (e.g. `<mxCell ... edge="1" ... />`) are invalid and will not render correctly. Always use the expanded form:
+```xml
+<mxCell id="e1" edge="1" parent="1" source="a" target="b" style="...">
+  <mxGeometry relative="1" as="geometry" />
+</mxCell>
+```
+
 draw.io does **not** have built-in collision detection for edges. Plan layout carefully:
 
 - Use `edgeStyle=orthogonalEdgeStyle` for right-angle connectors
diff --git a/skill-cli/SKILL.md b/skill-cli/SKILL.md
@@ -157,6 +157,13 @@ Every diagram must have this structure:
 
 ## Edge routing
 
+**CRITICAL: Every edge `mxCell` must contain a `<mxGeometry relative="1" as="geometry" />` child element**, even when there are no waypoints. Self-closing edge cells (e.g. `<mxCell ... edge="1" ... />`) are invalid and will not render correctly. Always use the expanded form:
+```xml
+<mxCell id="e1" edge="1" parent="1" source="a" target="b" style="...">
+  <mxGeometry relative="1" as="geometry" />
+</mxCell>
+```
+
 draw.io does **not** have built-in collision detection for edges. Plan layout and routing carefully:
 
 - Use `edgeStyle=orthogonalEdgeStyle` for right-angle connectors (most common)
