feat(layout): nested-JSON architecture diagram layout engine (auto-routing) + MCP tool

mcp-local/sandbox_tools.py

@@ -369,18 +369,36 @@ def _fp(c: dict) -> str:
                             cmd_png = ["pdftoppm", "-png", "-scale-to", "1280", str(pdf_path), str(png_outdir / "page")]
                             subprocess.run(cmd_png, capture_output=True, text=True, stdin=subprocess.DEVNULL)
 
+                            # pdftoppm zero-pads the page number to the width of
+                            # the largest page index, so a 1-9 page export is
+                            # "page-1.png" (no padding), 10-99 is "page-01.png",
+                            # etc. Try every plausible width instead of assuming
+                            # one — the old code only tried 6/2/3 and silently
+                            # produced an empty preview list for <10-page decks.
                             filtered_previews = []
+                            missing = []
                             for idx_p, slug in enumerate(pptx_slugs):
-                                src_png = png_outdir / f"page-{idx_p + 1:06d}.png"
-                                if not src_png.exists():
-                                    src_png = png_outdir / f"page-{idx_p + 1:02d}.png"
-                                if not src_png.exists():
-                                    src_png = png_outdir / f"page-{idx_p + 1:03d}.png"
-                                if src_png.exists():
+                                n_p = idx_p + 1
+                                src_png = None
+                                for width in (1, 2, 3, 4, 6):
+                                    cand = png_outdir / f"page-{n_p:0{width}d}.png"
+                                    if cand.exists():
+                                        src_png = cand
+                                        break
+                                if src_png:
                                     dst = preview_dir / f"{slug}.png"
                                     shutil.copy2(src_png, dst)
                                     filtered_previews.append(str(dst))
+                                else:
+                                    missing.append(slug)
                             result["preview_files"] = filtered_previews
+                            if missing:
+                                # Surface the silent gap instead of returning [].
+                                produced = sorted(p.name for p in png_outdir.glob("*.png"))
+                                result["preview_error"] = (
+                                    f"No PNG matched slugs {missing}; "
+                                    f"pdftoppm produced {produced}"
+                                )
                     except Exception as e:
                         result["preview_error"] = str(e)
 

mcp-local/server.py

@@ -92,6 +92,7 @@
 mcp.tool()(tools.read_guides)
 mcp.tool()(tools.code_to_slide)
 mcp.tool()(tools.grid)
+mcp.tool()(tools.arch_diagram)
 mcp.tool()(tools.pptx_to_json)
 
 # Sandbox tools (shared)

mcp-local/server_acp.py

@@ -52,6 +52,7 @@
 mcp.tool()(tools.read_guides)
 mcp.tool()(tools.code_to_slide)
 mcp.tool()(tools.grid)
+mcp.tool()(tools.arch_diagram)
 mcp.tool()(tools.pptx_to_json)
 
 # Sandbox tools (shared)

mcp-local/server_with_instruction.py

@@ -40,6 +40,7 @@
 mcp.tool()(tools.read_guides)
 mcp.tool()(tools.code_to_slide)
 mcp.tool()(tools.grid)
+mcp.tool()(tools.arch_diagram)
 mcp.tool()(tools.pptx_to_json)
 
 # Sandbox tools (shared)

mcp-local/tools.py

@@ -322,6 +322,61 @@ def grid(purpose: str, spec: str) -> dict[str, Any]:
     return compute_grid(grid_spec)
 
 
+def arch_diagram(
+    spec: str,
+    x: int = 100, y: int = 180, width: int = 1720, height: int = 800,
+    theme: str = "dark",
+) -> dict[str, Any]:
+    """Auto-layout an architecture/flow diagram from a logical-structure JSON.
+
+    Turns a nested structure of groups, icons and connections into fully-placed
+    slide elements with auto-routed orthogonal arrows. You describe *what
+    connects to what*; the engine computes coordinates, clusters related icons,
+    picks arrow ports/bends, and minimizes crossings and icon pierces. Prefer
+    this over hand-placing coordinates for any diagram with more than a few
+    connections.
+
+    Read the guide `arch-layout-engine` (via read_guides) for the JSON schema
+    and the techniques that reach 0 crossings (connect to a GROUP not every
+    icon; `fan: "merge"` bundles; perpendicular branch wrappers).
+
+    Args:
+        spec: JSON string. Top-level keys: `direction` ("horizontal"/"vertical"),
+            `iconSize`, `children` (nested nodes/groups), `connections`
+            (`{from, to, label?, fan?}`). A `targetArea` object inside the JSON
+            overrides x/y/width/height.
+        x: Target area X offset in px.
+        y: Target area Y offset in px.
+        width: Target area width in px (engine scales the diagram to fit).
+        height: Target area height in px.
+        theme: "dark" or "light" — affects box-node text colors.
+
+    Returns:
+        Dict with:
+          - `elements`: sdpm element array — drop into a slide, or write to a
+            file and reference with `{"type": "include", "src": "..."}`.
+          - `bbox`: final bounding box after scale-to-fit.
+          - `warnings`: human-readable facts about layout defects (facts, not
+            prescriptions) — may be absent when clean.
+          - `metrics`: objective QA numbers. `crossings` / `pierces` /
+            `group_pierces` are 0 for a clean diagram; `overflow` > 0 means the
+            layout spills off the target box; `score` is the internal judge's
+            lexicographic tuple (lower is better). Inspect these and iterate on
+            STRUCTURE (not coordinates) when defects remain.
+    """
+    import json
+    from sdpm.layout.render import render_architecture
+
+    try:
+        tree = json.loads(spec)
+    except (json.JSONDecodeError, TypeError) as e:
+        return {"error": f"Invalid diagram spec JSON: {e}"}
+    return render_architecture(
+        tree, x=x, y=y, width=width, height=height, theme=theme,
+        include_metrics=True,
+    )
+
+
 def pptx_to_json(pptx_path: str) -> dict[str, Any]:
     """Convert an existing PPTX file to JSON representation.
 

mcp-server/server.py

@@ -943,6 +943,57 @@ def grid(spec: str, purpose: str = "") -> str:
     return json.dumps(result, ensure_ascii=False, indent=2)
 
 
+@mcp.tool()
+def arch_diagram(
+    spec: str,
+    x: int = 100, y: int = 180, width: int = 1720, height: int = 800,
+    theme: str = "dark",
+) -> str:
+    """Auto-layout an architecture/flow diagram from a logical-structure JSON.
+
+    Turns a nested structure of groups, icons and connections into fully-placed
+    slide elements with auto-routed orthogonal arrows. You describe *what
+    connects to what*; the engine computes coordinates, clusters related icons,
+    picks arrow ports/bends, and minimizes crossings and icon pierces. Prefer
+    this over hand-placing coordinates for any diagram with more than a few
+    connections.
+
+    Read the guide `arch-layout-engine` (via read_guides) for the JSON schema
+    and the techniques that reach 0 crossings (connect to a GROUP not every
+    icon; `fan: "merge"` bundles; perpendicular branch wrappers).
+
+    Args:
+        spec: JSON string. Top-level keys: `direction` ("horizontal"/"vertical"),
+            `iconSize`, `children` (nested nodes/groups), `connections`
+            (`{from, to, label?, fan?}`). A `targetArea` object inside the JSON
+            overrides x/y/width/height.
+        x: Target area X offset in px.
+        y: Target area Y offset in px.
+        width: Target area width in px (engine scales the diagram to fit).
+        height: Target area height in px.
+        theme: "dark" or "light" — affects box-node text colors.
+
+    Returns:
+        JSON with `elements` (sdpm element array), `bbox` (final bounding box),
+        optional `warnings` (facts about layout defects), and `metrics`
+        (objective QA numbers: `crossings`/`pierces`/`group_pierces` are 0 for a
+        clean diagram; `overflow` > 0 means the layout spills off the box;
+        `score` is the judge's lexicographic tuple, lower is better). Inspect
+        these and iterate on STRUCTURE (not coordinates) when defects remain.
+    """
+    from sdpm.layout.render import render_architecture
+
+    try:
+        tree = json.loads(spec)
+    except (json.JSONDecodeError, TypeError) as e:
+        return json.dumps({"error": f"Invalid diagram spec JSON: {e}"})
+    result = render_architecture(
+        tree, x=x, y=y, width=width, height=height, theme=theme,
+        include_metrics=True,
+    )
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
 # --- Style Execution (Code Interpreter) ---
 
 

skill/references/guides/arch-elements.md

@@ -6,6 +6,13 @@ Common components for architecture diagrams (borders, groups, arrows, scale, col
 
 Shared components and rules used across architecture diagram patterns (simple / complex).
 
+> **Building a diagram from connections (what-links-to-what)?** Prefer the
+> nested-JSON layout engine — it auto-places icons and auto-routes orthogonal
+> arrows, minimizing crossings/pierces. See
+> [arch-layout-engine.md](arch-layout-engine.md). This file (arch-elements.md)
+> covers the shared vocabulary — group colors/types, boundary & logo, box
+> nodes, manual arrow geometry — used by both the engine and hand-placement.
+
 ---
 
 ## Core Principles
@@ -289,7 +296,7 @@ Minimal (label only):
 
 ### Rendering
 
-The layout engine expands box nodes into existing element types (colors switch with `--theme`):
+The layout engine expands box nodes into existing element types (colors switch with the `theme` arg / `--theme` flag):
 
 - `rounded_rectangle`: semi-transparent background (opacity 0.18) + border + shadow "sm" + corner radius (0.07)
 - `textbox`: sublabel (muted) → label (bold) → description (muted), with autofit