feat: uploaded the first version of excali-draw

app.py

@@ -0,0 +1,218 @@
+"""
+Gradio front-end for the Excalidraw-DSL pipeline (the HF Space).
+
+Flow per request:
+  prompt --> Modal GPU endpoint --> DSL string
+         --> strip code fences  --> validate_dsl (one retry if invalid)
+         --> Converter           --> Excalidraw scene JSON
+         --> rendered live in an embedded (read-only) Excalidraw canvas
+         --> downloadable .excalidraw file
+
+The GPU work (generation) is remote on Modal; everything here is free CPU work. The validator
+and converter are the SAME modules used in training/eval — imported, not reimplemented.
+
+Files this Space needs (upload alongside this one):
+  app.py  requirements.txt  packages.txt
+  convert_dsl_to_excalidraw.py  validate_dsl.py  dsl_schema.json
+
+Space env vars (Settings -> Variables and secrets):
+  MODEL_ENDPOINT        the deployed Modal URL (…-model-generate.modal.run)   [required]
+  MODEL_ENDPOINT_KEY    Modal-Key   — only if you enabled proxy auth          [optional]
+  MODEL_ENDPOINT_SECRET Modal-Secret— only if you enabled proxy auth          [optional]
+"""
+
+import html
+import json
+import os
+import re
+import sys
+import tempfile
+import pathlib
+
+import requests
+import gradio as gr
+
+# Import the canonical validator + converter. They sit next to this file on the Space; one dir
+# up in the local repo. Add both so it works in either layout.
+ROOT = pathlib.Path(__file__).resolve().parent
+for p in (ROOT, ROOT.parent):
+    if str(p) not in sys.path:
+        sys.path.insert(0, str(p))
+
+from validate_dsl import load_schema, validate_dsl_text  # noqa: E402
+from convert_dsl_to_excalidraw import Converter  # noqa: E402
+
+SCHEMA = load_schema()
+ENDPOINT = os.environ.get("MODEL_ENDPOINT", "").strip()
+ENDPOINT_KEY = os.environ.get("MODEL_ENDPOINT_KEY", "").strip()
+ENDPOINT_SECRET = os.environ.get("MODEL_ENDPOINT_SECRET", "").strip()
+
+EXCALIDRAW_VERSION = "0.17.6"  # UMD build pinned for the embedded read-only canvas
+
+
+# --------------------------------------------------------------------------- model call
+def call_model(prompt: str, temperature: float = 0.0) -> str:
+    if not ENDPOINT:
+        raise RuntimeError(
+            "MODEL_ENDPOINT is not set. Deploy serve/modal_infer.py and put its URL in the "
+            "Space's environment variables."
+        )
+    headers = {"content-type": "application/json"}
+    if ENDPOINT_KEY and ENDPOINT_SECRET:  # only when proxy auth is enabled
+        headers["Modal-Key"] = ENDPOINT_KEY
+        headers["Modal-Secret"] = ENDPOINT_SECRET
+    r = requests.post(
+        ENDPOINT,
+        headers=headers,
+        json={"prompt": prompt, "temperature": temperature},
+        timeout=180,  # generous: covers a cold start of the scaled-to-zero container
+    )
+    r.raise_for_status()
+    body = r.json()
+    if "error" in body:
+        raise RuntimeError(f"model endpoint error: {body['error']}")
+    return body["dsl"]
+
+
+# --------------------------------------------------------------------------- DSL cleanup
+_FENCE = re.compile(r"^\s*```(?:json)?\s*|\s*```\s*$", re.IGNORECASE)
+
+
+def strip_fences(text: str) -> str:
+    """Models occasionally wrap output in ```json fences despite the system prompt."""
+    text = _FENCE.sub("", text.strip())
+    # Keep only the outermost JSON object if there is trailing prose.
+    start, end = text.find("{"), text.rfind("}")
+    if start != -1 and end != -1 and end > start:
+        text = text[start:end + 1]
+    return text.strip()
+
+
+def get_valid_dsl(prompt: str):
+    """Returns (dsl_obj, dsl_text, status_md). Retries once with sampling if the first
+    (greedy) attempt fails validation."""
+    attempts = [("greedy", 0.0), ("retry (sampled)", 0.4)]
+    last_err = ""
+    for label, temp in attempts:
+        raw = call_model(prompt, temperature=temp)
+        text = strip_fences(raw)
+        res = validate_dsl_text(text, SCHEMA)
+        if res.ok:
+            warn = (f" · {len(res.warnings)} warning(s)" if res.warnings else "")
+            return json.loads(text), text, f"✅ valid DSL ({label}){warn}"
+        last_err = ", ".join(c for c, _ in res.errors) or "unparseable"
+    # Both attempts failed — surface the raw text so the user can see what happened.
+    return None, text, f"❌ DSL failed validation: {last_err}"
+
+
+# --------------------------------------------------------------------------- render
+def render_scene_html(scene: dict) -> str:
+    """An <iframe> hosting a read-only Excalidraw canvas initialised with `scene`."""
+    scene_json = json.dumps(scene)
+    doc = f"""<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8"/>
+<style>html,body,#root{{margin:0;padding:0;height:100%;width:100%}}</style>
+<script>window.EXCALIDRAW_ASSET_PATH="https://unpkg.com/@excalidraw/excalidraw@{EXCALIDRAW_VERSION}/dist/";</script>
+<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
+<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+<script crossorigin src="https://unpkg.com/@excalidraw/excalidraw@{EXCALIDRAW_VERSION}/dist/excalidraw.production.min.js"></script>
+</head>
+<body>
+<div id="root"></div>
+<script>
+  const scene = {scene_json};
+  const App = () => React.createElement(ExcalidrawLib.Excalidraw, {{
+    initialData: {{
+      elements: scene.elements || [],
+      appState: Object.assign({{}}, scene.appState, {{viewModeEnabled: true}}),
+      files: scene.files || {{}},
+      scrollToContent: true,
+    }},
+    viewModeEnabled: true,
+    UIOptions: {{canvasActions: {{export: false, saveToActiveFile: false}}}},
+  }});
+  ReactDOM.createRoot(document.getElementById("root")).render(React.createElement(App));
+</script>
+</body>
+</html>"""
+    srcdoc = html.escape(doc, quote=True)
+    return (
+        f'<iframe title="excalidraw preview" '
+        f'style="width:100%;height:600px;border:1px solid #ddd;border-radius:8px" '
+        f'srcdoc="{srcdoc}"></iframe>'
+    )
+
+
+def write_excalidraw_file(scene: dict) -> str:
+    tmp = tempfile.NamedTemporaryFile(
+        mode="w", suffix=".excalidraw", delete=False, encoding="utf-8"
+    )
+    json.dump(scene, tmp, ensure_ascii=False, indent=2)
+    tmp.close()
+    return tmp.name
+
+
+# --------------------------------------------------------------------------- main handler
+EMPTY_PREVIEW = '<div style="height:600px;display:flex;align-items:center;justify-content:center;color:#999;border:1px dashed #ccc;border-radius:8px">Your diagram preview will appear here</div>'
+
+
+def generate(prompt: str):
+    prompt = (prompt or "").strip()
+    if not prompt:
+        return EMPTY_PREVIEW, "", None, "Enter a prompt to start."
+    try:
+        obj, dsl_text, status = get_valid_dsl(prompt)
+    except Exception as e:  # noqa: BLE001 — show the user what broke
+        return EMPTY_PREVIEW, "", None, f"❌ {type(e).__name__}: {e}"
+
+    if obj is None:
+        return EMPTY_PREVIEW, dsl_text, None, status
+
+    try:
+        scene = Converter(obj).build()
+    except Exception as e:  # noqa: BLE001
+        return EMPTY_PREVIEW, dsl_text, None, f"{status}, but converter failed: {e}"
+
+    html_preview = render_scene_html(scene)
+    file_path = write_excalidraw_file(scene)
+    return html_preview, dsl_text, file_path, f"{status} · {len(scene.get('elements', []))} elements"
+
+
+# --------------------------------------------------------------------------- UI
+EXAMPLES = [
+    "Left-to-right architecture for a food delivery app: customer app, API gateway, order service, payment service, Redis cache, Postgres, delivery worker.",
+    "Flowchart for a user login flow with validation and a retry on failure.",
+    "ER diagram for a blog: users, posts, comments, tags.",
+    "Sequence diagram for a checkout: client, API, payment gateway, database.",
+    "Data pipeline: ingest events from Kafka, transform in Spark, load into a warehouse, dashboard on top.",
+]
+
+with gr.Blocks(title="Excalidraw DSL Generator") as demo:
+    gr.Markdown(
+        "# 🖍️ Excalidraw Diagram Generator\n"
+        "Describe a diagram → fine-tuned model emits compact DSL → deterministic converter "
+        "produces a real `.excalidraw` file. Preview is live and editable after download."
+    )
+    with gr.Row():
+        with gr.Column(scale=2):
+            prompt = gr.Textbox(
+                label="Describe your diagram",
+                placeholder="e.g. architecture for a URL shortener with cache and worker",
+                lines=3,
+            )
+            go = gr.Button("Generate", variant="primary")
+            status = gr.Markdown("")
+            gr.Examples(examples=EXAMPLES, inputs=prompt)
+        with gr.Column(scale=3):
+            preview = gr.HTML(EMPTY_PREVIEW)
+            download = gr.DownloadButton("⬇️ Download .excalidraw", interactive=True)
+            with gr.Accordion("Generated DSL (JSON)", open=False):
+                dsl_view = gr.Code(language="json", label="DSL")
+
+    go.click(generate, inputs=prompt, outputs=[preview, dsl_view, download, status])
+    prompt.submit(generate, inputs=prompt, outputs=[preview, dsl_view, download, status])
+
+if __name__ == "__main__":
+    demo.launch()

convert_dsl_to_excalidraw.py

@@ -0,0 +1,679 @@
+#!/usr/bin/env python3
+"""
+convert_dsl_to_excalidraw.py
+
+Deterministic converter: Diagram DSL (see dsl.schema.json / DSL_SPEC.md)  ->  .excalidraw JSON.
+
+Design:
+  - Graph family (system_architecture, flowchart, data_pipeline, er_diagram) is laid out by
+    Graphviz `dot` (called as a subprocess with -Tjson). Only dependency: the `dot` binary.
+  - sequence_diagram, timeline, mind_map, mobile_wireframe use hand-rolled layouts.
+  - A shared emit layer builds valid Excalidraw elements (shapes, bound text, bound arrows),
+    handles z-ordering, and self-validates the output (no dangling refs, overlap warnings).
+
+The DSL carries ONLY semantic decisions. Everything geometric/stylistic is computed here.
+
+Usage:
+    python3 convert_dsl_to_excalidraw.py input.dsl.json -o output.excalidraw
+    cat input.dsl.json | python3 convert_dsl_to_excalidraw.py - > output.excalidraw
+"""
+
+import argparse
+import hashlib
+import json
+import math
+import subprocess
+import sys
+
+# --------------------------------------------------------------------------------------
+# Constants
+# --------------------------------------------------------------------------------------
+
+FONT = 20
+TITLE_FONT = 28
+FONT_FAMILY = 1            # 1 = Excalidraw hand-drawn (Virgil)
+LINE_HEIGHT = 1.25
+CHAR_W = 0.60             # avg glyph width as a fraction of font size (approx for Virgil)
+PAD_X = 22
+PAD_Y = 16
+NODE_MIN_W = 120
+NODE_MAX_W = 320
+NODE_MIN_H = 56
+INK = "#1e1e1e"
+TRANSPARENT = "transparent"
+WHITE = "#ffffff"
+
+# role -> (shape, fill, stroke, rounded, dashed)
+# shape in {"rectangle","ellipse","diamond"}.  Mirrors the table in DSL_SPEC.md.
+ROLE_STYLE = {
+    "actor":       ("ellipse",   "#e9ecef", "#343a40", False, False),
+    "client":      ("rectangle", "#a5d8ff", "#1971c2", False, False),
+    "service":     ("rectangle", "#b2f2bb", "#2f9e44", True,  False),
+    "gateway":     ("diamond",   "#d0bfff", "#7048e8", False, False),
+    "database":    ("rectangle", "#a5d8ff", "#1971c2", False, False),
+    "cache":       ("rectangle", "#ffd8a8", "#e8590c", True,  False),
+    "queue":       ("rectangle", "#ffec99", "#f08c00", False, False),
+    "worker":      ("rectangle", "#b2f2bb", "#2f9e44", True,  False),
+    "storage":     ("rectangle", "#e9ecef", "#495057", False, False),
+    "external":    ("rectangle", "#f1f3f5", "#868e96", False, True),
+    "monitoring":  ("rectangle", "#ffec99", "#f08c00", False, False),
+    "auth":        ("rectangle", "#d0bfff", "#7048e8", False, False),
+    "start":       ("ellipse",   "#b2f2bb", "#2f9e44", False, False),
+    "end":         ("ellipse",   "#ffec99", "#e8590c", False, False),
+    "process":     ("rectangle", "#a5d8ff", "#1971c2", True,  False),
+    "decision":    ("diamond",   "#ffec99", "#f08c00", False, False),
+    "io":          ("rectangle", "#e9ecef", "#495057", False, False),
+    "source":      ("rectangle", "#b2f2bb", "#2f9e44", True,  False),
+    "transform":   ("rectangle", "#a5d8ff", "#1971c2", True,  False),
+    "sink":        ("rectangle", "#d0bfff", "#7048e8", True,  False),
+    "entity":      ("rectangle", WHITE,     "#1e1e1e", False, False),
+    "participant": ("rectangle", "#a5d8ff", "#1971c2", False, False),
+    "milestone":   ("ellipse",   "#a5d8ff", "#1971c2", False, False),
+    "root":        ("rectangle", "#d0bfff", "#7048e8", True,  False),
+    "branch":      ("rectangle", "#a5d8ff", "#1971c2", True,  False),
+    "leaf":        ("rectangle", "#b2f2bb", "#2f9e44", True,  False),
+    "screen":      ("rectangle", TRANSPARENT, "#343a40", True, False),
+    "ui_element":  ("rectangle", "#e9ecef", "#495057", False, False),
+    "component":   ("rectangle", "#e9ecef", "#495057", True,  False),
+    "generic":     ("rectangle", "#e9ecef", "#495057", False, False),
+}
+
+COLOR_OVERRIDE = {
+    "red":    ("#ffc9c9", "#e03131"),
+    "orange": ("#ffd8a8", "#e8590c"),
+    "yellow": ("#ffec99", "#f08c00"),
+    "green":  ("#b2f2bb", "#2f9e44"),
+    "blue":   ("#a5d8ff", "#1971c2"),
+    "violet": ("#d0bfff", "#7048e8"),
+    "gray":   ("#e9ecef", "#495057"),
+    "black":  ("#e9ecef", "#1e1e1e"),
+}
+
+STROKE_STYLE = {"solid": "solid", "dashed": "dashed", "dotted": "dotted"}
+
+DEFAULT_DIRECTION = {
+    "system_architecture": "LR",
+    "flowchart": "TB",
+    "data_pipeline": "LR",
+    "er_diagram": "LR",
+    "sequence_diagram": "LR",
+    "timeline": "LR",
+    "mind_map": "radial",
+    "mobile_wireframe": "TB",
+}
+
+GRAPH_FAMILY = {"system_architecture", "flowchart", "data_pipeline", "er_diagram"}
+
+# --------------------------------------------------------------------------------------
+# Text measurement / sizing
+# --------------------------------------------------------------------------------------
+
+def text_dims(text, font=FONT):
+    lines = str(text).split("\n")
+    w = max((len(l) for l in lines), default=1) * font * CHAR_W
+    h = len(lines) * font * LINE_HEIGHT
+    return max(w, font * CHAR_W), max(h, font * LINE_HEIGHT)
+
+
+def node_size(label):
+    tw, th = text_dims(label, FONT)
+    w = min(max(tw + 2 * PAD_X, NODE_MIN_W), NODE_MAX_W)
+    h = max(th + 2 * PAD_Y, NODE_MIN_H)
+    return w, h
+
+
+# --------------------------------------------------------------------------------------
+# Converter
+# --------------------------------------------------------------------------------------
+
+class Converter:
+    def __init__(self, dsl, seed=None):
+        self.dsl = dsl
+        self.diagram = dsl["diagram"]
+        self.title = dsl["title"]
+        self.direction = dsl.get("direction") or DEFAULT_DIRECTION[self.diagram]
+        self.nodes = dsl.get("nodes", [])
+        self.edges = dsl.get("edges", [])
+        self.groups = dsl.get("groups", [])
+        self.node_by_id = {n["id"]: n for n in self.nodes}
+
+        if seed is None:
+            h = hashlib.md5((self.diagram + "|" + self.title).encode()).hexdigest()
+            seed = int(h[:8], 16)
+        self._seed = seed
+        self._rng_state = seed & 0x7FFFFFFF
+
+        self.elements = []        # accumulates element dicts (with temporary "_z")
+        self.box_elem = {}        # node_id -> shape element dict (to append boundElements)
+        self.boxes = {}           # node_id -> (x, y, w, h)
+        self._idc = 0
+
+    # ---- deterministic helpers -------------------------------------------------------
+
+    def _rand(self):
+        # simple LCG so output is reproducible without Date.now()/random module state
+        self._rng_state = (self._rng_state * 1103515245 + 12345) & 0x7FFFFFFF
+        return self._rng_state
+
+    def _new_id(self, prefix):
+        self._idc += 1
+        return f"{prefix}_{self._idc}"
+
+    def _base(self, typ, x, y, w, h, z):
+        return {
+            "id": None, "type": typ,
+            "x": round(x, 2), "y": round(y, 2),
+            "width": round(w, 2), "height": round(h, 2),
+            "angle": 0,
+            "strokeColor": INK, "backgroundColor": TRANSPARENT,
+            "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid",
+            "roughness": 1, "opacity": 100,
+            "groupIds": [], "frameId": None, "roundness": None,
+            "seed": self._rand(), "version": 1, "versionNonce": self._rand(),
+            "isDeleted": False, "boundElements": [], "updated": 1,
+            "link": None, "locked": False,
+            "_z": z,
+        }
+
+    def _add(self, el):
+        self.elements.append(el)
+        return el
+
+    # ---- element builders ------------------------------------------------------------
+
+    def add_box(self, node_id, x, y, w, h, role, color_override=None, z=2):
+        shape, fill, stroke, rounded, dashed = ROLE_STYLE.get(role, ROLE_STYLE["generic"])
+        if color_override and color_override in COLOR_OVERRIDE:
+            fill, stroke = COLOR_OVERRIDE[color_override]
+        el = self._base(shape, x, y, w, h, z)
+        el["id"] = self._new_id("sh")
+        el["backgroundColor"] = fill
+        el["strokeColor"] = stroke
+        if rounded and shape == "rectangle":
+            el["roundness"] = {"type": 3}
+        if dashed:
+            el["strokeStyle"] = "dashed"
+        self._add(el)
+        if node_id is not None:
+            self.box_elem[node_id] = el
+            self.boxes[node_id] = (x, y, w, h)
+        return el
+
+    def add_label(self, container_el, text, align="center", valign="middle",
+                  font=FONT, color=INK, z=3, cx=None, cy=None):
+        tw, th = text_dims(text, font)
+        bx, by = container_el["x"], container_el["y"]
+        bw, bh = container_el["width"], container_el["height"]
+        if cx is None:
+            if align == "left":
+                tx = bx + PAD_X
+            else:
+                tx = bx + (bw - tw) / 2
+        else:
+            tx = cx - tw / 2
+        if cy is None:
+            if valign == "top":
+                ty = by + PAD_Y
+            else:
+                ty = by + (bh - th) / 2
+        else:
+            ty = cy - th / 2
+        el = self._base("text", tx, ty, tw, th, z)
+        el["id"] = self._new_id("tx")
+        el["strokeColor"] = color
+        el.update({
+            "fontSize": font, "fontFamily": FONT_FAMILY,
+            "text": str(text), "originalText": str(text),
+            "textAlign": align, "verticalAlign": valign,
+            "containerId": container_el["id"], "lineHeight": LINE_HEIGHT,
+            "autoResize": True,
+        })
+        container_el["boundElements"].append({"type": "text", "id": el["id"]})
+        self._add(el)
+        return el
+
+    def add_free_text(self, text, cx, top, font=FONT, color=INK, z=4):
+        tw, th = text_dims(text, font)
+        el = self._base("text", cx - tw / 2, top, tw, th, z)
+        el["id"] = self._new_id("tx")
+        el["strokeColor"] = color
+        el.update({
+            "fontSize": font, "fontFamily": FONT_FAMILY,
+            "text": str(text), "originalText": str(text),
+            "textAlign": "center", "verticalAlign": "top",
+            "containerId": None, "lineHeight": LINE_HEIGHT, "autoResize": True,
+        })
+        self._add(el)
+        return el
+
+    def _linear(self, typ, pts, style="solid", arrowhead=True,
+                stroke=INK, src_id=None, dst_id=None, z=1):
+        x0, y0 = pts[0]
+        rel = [[round(px - x0, 2), round(py - y0, 2)] for px, py in pts]
+        xs = [p[0] for p in rel]
+        ys = [p[1] for p in rel]
+        el = self._base(typ, x0, y0, max(xs) - min(xs), max(ys) - min(ys), z)
+        el["id"] = self._new_id("ln" if typ == "line" else "ar")
+        el["strokeColor"] = stroke
+        el["strokeStyle"] = STROKE_STYLE.get(style, "solid")
+        el["roundness"] = {"type": 2}
+        el["points"] = rel
+        el["lastCommittedPoint"] = None
+        el["startArrowhead"] = None
+        el["endArrowhead"] = "arrow" if (arrowhead and typ == "arrow") else None
+        el["startBinding"] = None
+        el["endBinding"] = None
+        if src_id is not None and src_id in self.box_elem:
+            el["startBinding"] = {"elementId": self.box_elem[src_id]["id"], "focus": 0, "gap": 4}
+            self.box_elem[src_id]["boundElements"].append({"type": "arrow", "id": el["id"]})
+        if dst_id is not None and dst_id in self.box_elem:
+            el["endBinding"] = {"elementId": self.box_elem[dst_id]["id"], "focus": 0, "gap": 4}
+            self.box_elem[dst_id]["boundElements"].append({"type": "arrow", "id": el["id"]})
+        self._add(el)
+        return el
+
+    def add_arrow(self, pts, label=None, style="solid", src_id=None, dst_id=None,
+                  arrowhead=True, stroke=INK):
+        el = self._linear("arrow", pts, style, arrowhead, stroke, src_id, dst_id)
+        if label:
+            mid = pts[len(pts) // 2]
+            self.add_label(el, label, cx=mid[0], cy=mid[1], font=16)
+        return el
+
+    def add_line(self, pts, style="solid", stroke=INK):
+        return self._linear("line", pts, style, arrowhead=False, stroke=stroke)
+
+    def add_frame(self, x, y, w, h, label=None, stroke="#868e96"):
+        el = self._base("rectangle", x, y, w, h, z=0)
+        el["id"] = self._new_id("fr")
+        el["strokeColor"] = stroke
+        el["strokeStyle"] = "dashed"
+        el["roundness"] = {"type": 3}
+        self._add(el)
+        if label:
+            self.add_free_text(label, x + 70, y + 8, font=16, color=stroke, z=1)
+        return el
+
+    # ---- geometry --------------------------------------------------------------------
+
+    @staticmethod
+    def _clip(box, toward):
+        """Point on box border in the direction of `toward` (center of another box)."""
+        x, y, w, h = box
+        cx, cy = x + w / 2, y + h / 2
+        dx, dy = toward[0] - cx, toward[1] - cy
+        if dx == 0 and dy == 0:
+            return (cx, cy)
+        hw, hh = w / 2, h / 2
+        scale = 1.0 / max(abs(dx) / hw if hw else 1e9, abs(dy) / hh if hh else 1e9)
+        return (cx + dx * scale, cy + dy * scale)
+
+    def _center(self, node_id):
+        x, y, w, h = self.boxes[node_id]
+        return (x + w / 2, y + h / 2)
+
+    # ----------------------------------------------------------------------------------
+    # Graphviz-backed layout (graph family)
+    # ----------------------------------------------------------------------------------
+
+    def build_graph_family(self):
+        OFFX, OFFY = 80, 120
+        rankdir = self.direction if self.direction in ("LR", "RL", "TB", "BT") else "TB"
+
+        # precompute node render sizes
+        sizes = {}
+        labels = {}
+        for n in self.nodes:
+            if self.diagram == "er_diagram":
+                label = self._er_label(n)
+            else:
+                label = n["label"]
+            labels[n["id"]] = label
+            sizes[n["id"]] = node_size(label) if self.diagram != "er_diagram" \
+                else self._er_size(label)
+
+        # build dot source
+        src = ["digraph G {",
+               f'  graph [rankdir={rankdir}, nodesep=0.5, ranksep=0.9, splines=true];',
+               '  node [shape=box, fixedsize=true];']
+        group_members = {g["id"]: [] for g in self.groups}
+        for n in self.nodes:
+            if n.get("group") in group_members:
+                group_members[n["group"]].append(n["id"])
+        grouped = set()
+        for g in self.groups:
+            members = group_members.get(g["id"], [])
+            if not members:
+                continue
+            src.append(f'  subgraph cluster_{g["id"]} {{')
+            src.append(f'    label="{self._esc(g["label"])}"; style=dashed; color="#868e96";')
+            for nid in members:
+                w, h = sizes[nid]
+                src.append(f'    "{nid}" [width={w/72:.3f}, height={h/72:.3f}, label=""];')
+                grouped.add(nid)
+            src.append("  }")
+        for n in self.nodes:
+            if n["id"] in grouped:
+                continue
+            w, h = sizes[n["id"]]
+            src.append(f'  "{n["id"]}" [width={w/72:.3f}, height={h/72:.3f}, label=""];')
+        for e in self.edges:
+            src.append(f'  "{e["from"]}" -> "{e["to"]}";')
+        src.append("}")
+        dot_src = "\n".join(src)
+
+        data = self._run_dot(dot_src)
+        bb = [float(v) for v in data["bb"].split(",")]
+        H = bb[3]
+
+        def flip(x, y):
+            return (x + OFFX, (H - y) + OFFY)
+
+        # nodes + clusters
+        gvid_name = {}
+        for o in data.get("objects", []):
+            name = o.get("name", "")
+            gvid_name[o.get("_gvid")] = name
+            if name.startswith("cluster_") and "bb" in o:
+                x0, y0, x1, y1 = [float(v) for v in o["bb"].split(",")]
+                fx0, fy1 = flip(x0, y0)
+                fx1, fy0 = flip(x1, y1)
+                glabel = o.get("label") or ""
+                self.add_frame(min(fx0, fx1), min(fy0, fy1),
+                               abs(fx1 - fx0), abs(fy1 - fy0), label=glabel)
+            elif name in self.node_by_id and "pos" in o:
+                px, py = [float(v) for v in o["pos"].split(",")]
+                cx, cy = flip(px, py)
+                w, h = sizes[name]
+                node = self.node_by_id[name]
+                box = self.add_box(name, cx - w / 2, cy - h / 2, w, h,
+                                   node["role"], node.get("color"))
+                if self.diagram == "er_diagram":
+                    self.add_label(box, labels[name], align="left", valign="top")
+                else:
+                    self.add_label(box, labels[name])
+
+        # edges (match output edges back to DSL edges for label/style)
+        pending = {}
+        for e in self.edges:
+            pending.setdefault((e["from"], e["to"]), []).append(e)
+        for oe in data.get("edges", []):
+            frm = gvid_name.get(oe.get("tail"))
+            to = gvid_name.get(oe.get("head"))
+            attrs = {}
+            q = pending.get((frm, to))
+            if q:
+                attrs = q.pop(0)
+            pts = self._spline(oe.get("pos", ""), flip)
+            if len(pts) < 2:
+                pts = [self._center(frm), self._center(to)]
+            label = attrs.get("label")
+            if self.diagram == "er_diagram" and attrs.get("meta", {}).get("cardinality"):
+                label = attrs["meta"]["cardinality"] + (f"  {label}" if label else "")
+            self.add_arrow(pts, label=label, style=attrs.get("style", "solid"),
+                           src_id=frm, dst_id=to)
+
+    @staticmethod
+    def _spline(pos, flip):
+        start = end = None
+        mids = []
+        for tok in pos.split():
+            if tok.startswith("e,"):
+                x, y = tok[2:].split(",")
+                end = flip(float(x), float(y))
+            elif tok.startswith("s,"):
+                x, y = tok[2:].split(",")
+                start = flip(float(x), float(y))
+            elif "," in tok:
+                x, y = tok.split(",")
+                mids.append(flip(float(x), float(y)))
+        poly = []
+        if start:
+            poly.append(start)
+        poly.extend(mids)
+        if end:
+            poly.append(end)
+        return poly
+
+    def _er_label(self, node):
+        lines = [node["label"]]
+        for f in node.get("meta", {}).get("fields", []):
+            key = f.get("key", "none")
+            tag = {"pk": "🔑 ", "fk": "↗ "}.get(key, "")
+            t = f.get("type", "")
+            lines.append(f"{tag}{f['name']}" + (f": {t}" if t else ""))
+        return "\n".join(lines)
+
+    @staticmethod
+    def _er_size(label):
+        tw, th = text_dims(label, FONT)
+        return min(max(tw + 2 * PAD_X, 160), 360), th + 2 * PAD_Y
+
+    @staticmethod
+    def _esc(s):
+        return str(s).replace("\\", "\\\\").replace('"', '\\"')
+
+    @staticmethod
+    def _run_dot(src):
+        try:
+            p = subprocess.run(["dot", "-Tjson"], input=src.encode(),
+                               capture_output=True, timeout=30)
+        except FileNotFoundError:
+            raise SystemExit("ERROR: graphviz `dot` not found. Install graphviz.")
+        if p.returncode != 0:
+            raise SystemExit("ERROR: dot failed:\n" + p.stderr.decode())
+        return json.loads(p.stdout.decode())
+
+    # ----------------------------------------------------------------------------------
+    # Hand-rolled layouts
+    # ----------------------------------------------------------------------------------
+
+    def build_sequence(self):
+        MX, TOP = 100, 100
+        gap = max((node_size(n["label"])[0] for n in self.nodes), default=160) + 80
+        part_x = {}
+        box_h = 50
+        for i, n in enumerate(self.nodes):
+            w, _ = node_size(n["label"])
+            cx = MX + i * gap
+            part_x[n["id"]] = cx
+            box = self.add_box(n["id"], cx - w / 2, TOP, w, box_h, n["role"], n.get("color"))
+            self.add_label(box, n["label"])
+        n_msgs = max(len(self.edges), 1)
+        life_bottom = TOP + box_h + 60 + n_msgs * 55 + 40
+        for nid, cx in part_x.items():
+            self.add_line([(cx, TOP + box_h), (cx, life_bottom)], style="dashed", stroke="#adb5bd")
+        y = TOP + box_h + 60
+        for e in self.edges:
+            x1, x2 = part_x[e["from"]], part_x[e["to"]]
+            kind = e.get("meta", {}).get("kind", "sync")
+            style = "dashed" if kind in ("async", "return") else "solid"
+            self.add_arrow([(x1, y), (x2, y)], label=e.get("label"), style=style)
+            y += 55
+
+    def build_timeline(self):
+        nodes = sorted(self.nodes, key=lambda n: str(n.get("meta", {}).get("date", "")))
+        MX, AXIS = 120, 320
+        gap = max((node_size(n["label"])[0] for n in nodes), default=160) + 60
+        xs = [MX + i * gap for i in range(len(nodes))]
+        if xs:
+            self.add_arrow([(MX - 40, AXIS), (xs[-1] + 60, AXIS)], stroke="#495057")
+        for i, n in enumerate(nodes):
+            cx = xs[i]
+            marker = self.add_box(n["id"], cx - 9, AXIS - 9, 18, 18, "milestone", n.get("color"))
+            above = (i % 2 == 0)
+            w, h = node_size(n["label"])
+            by = AXIS - 70 - h if above else AXIS + 70
+            box = self.add_box(None, cx - w / 2, by, w, h, "generic", n.get("color"))
+            self.add_label(box, n["label"])
+            date = n.get("meta", {}).get("date", "")
+            if date:
+                self.add_free_text(str(date), cx, AXIS + (-95 if not above else 75), font=14,
+                                   color="#868e96")
+            connector_y = (by + h, AXIS) if above else (by, AXIS)
+            self.add_line([(cx, connector_y[0]), (cx, connector_y[1])], stroke="#adb5bd")
+
+    def build_mind_map(self):
+        roots = [n for n in self.nodes if n["role"] == "root"] or self.nodes[:1]
+        root = roots[0]
+        adj = {n["id"]: [] for n in self.nodes}
+        for e in self.edges:
+            adj[e["from"]].append(e["to"])
+            adj[e["to"]].append(e["from"])
+        CX, CY = 700, 450
+        placed = {root["id"]: (CX, CY)}
+        order = [(root["id"], 0.0, 2 * math.pi, 0)]
+        visited = {root["id"]}
+        edges_to_draw = []
+        while order:
+            nid, a0, a1, depth = order.pop(0)
+            children = [c for c in adj[nid] if c not in visited]
+            if not children:
+                continue
+            span = (a1 - a0) / len(children)
+            r = (depth + 1) * 230
+            for i, c in enumerate(children):
+                visited.add(c)
+                ang = a0 + span * (i + 0.5)
+                cx, cy = CX + r * math.cos(ang), CY + r * math.sin(ang)
+                placed[c] = (cx, cy)
+                edges_to_draw.append((nid, c))
+                order.append((c, a0 + span * i, a0 + span * (i + 1), depth + 1))
+        for n in self.nodes:
+            cx, cy = placed.get(n["id"], (CX, CY))
+            w, h = node_size(n["label"])
+            role = "root" if n["id"] == root["id"] else n["role"]
+            box = self.add_box(n["id"], cx - w / 2, cy - h / 2, w, h, role, n.get("color"))
+            self.add_label(box, n["label"])
+        for frm, to in edges_to_draw:
+            p1 = self._clip(self.boxes[frm], self._center(to))
+            p2 = self._clip(self.boxes[to], self._center(frm))
+            self.add_arrow([p1, p2], arrowhead=False, src_id=frm, dst_id=to, stroke="#868e96")
+
+    def build_wireframe(self):
+        screens = self.groups or [{"id": "__all__", "label": self.dsl.get("title", "Screen")}]
+        members = {g["id"]: [] for g in screens}
+        for n in self.nodes:
+            g = n.get("group", "__all__")
+            members.setdefault(g, []).append(n)
+        FW, FH, MX, TOP, GAP = 300, 600, 100, 120, 60
+        kind_h = {"header": 56, "nav": 48, "tab": 44, "footer": 56, "button": 50,
+                  "input": 50, "text": 40, "image": 140, "list": 200, "card": 120}
+        for si, sc in enumerate(screens):
+            fx = MX + si * (FW + GAP)
+            self.add_frame(fx, TOP, FW, FH, label=sc["label"], stroke="#343a40")
+            y = TOP + 20
+            for n in members.get(sc["id"], []):
+                kind = n.get("meta", {}).get("kind", "text")
+                h = kind_h.get(kind, 50)
+                box = self.add_box(n["id"], fx + 16, y, FW - 32, h, "ui_element", n.get("color"))
+                self.add_label(box, n["label"])
+                y += h + 14
+
+    # ----------------------------------------------------------------------------------
+    # Finalize
+    # ----------------------------------------------------------------------------------
+
+    def _content_bbox(self):
+        xs0, ys0, xs1, ys1 = [], [], [], []
+        for el in self.elements:
+            xs0.append(el["x"]); ys0.append(el["y"])
+            xs1.append(el["x"] + el["width"]); ys1.append(el["y"] + el["height"])
+        if not xs0:
+            return (0, 0, 200, 200)
+        return (min(xs0), min(ys0), max(xs1), max(ys1))
+
+    def build(self):
+        if self.diagram in GRAPH_FAMILY:
+            self.build_graph_family()
+        elif self.diagram == "sequence_diagram":
+            self.build_sequence()
+        elif self.diagram == "timeline":
+            self.build_timeline()
+        elif self.diagram == "mind_map":
+            self.build_mind_map()
+        elif self.diagram == "mobile_wireframe":
+            self.build_wireframe()
+        else:
+            raise SystemExit(f"Unsupported diagram type: {self.diagram}")
+
+        x0, y0, x1, _ = self._content_bbox()
+        self.add_free_text(self.title, (x0 + x1) / 2, y0 - 60, font=TITLE_FONT)
+
+        self._assign_z_and_index()
+        self._self_validate()
+        return {
+            "type": "excalidraw",
+            "version": 2,
+            "source": "convert_dsl_to_excalidraw.py",
+            "elements": [self._strip(e) for e in self.elements],
+            "appState": {"viewBackgroundColor": WHITE, "gridSize": None},
+            "files": {},
+        }
+
+    def _assign_z_and_index(self):
+        # stable sort by z layer, then assign fractional index in that order
+        order = sorted(range(len(self.elements)), key=lambda i: (self.elements[i]["_z"], i))
+        self.elements = [self.elements[i] for i in order]
+        for i, el in enumerate(self.elements):
+            el["index"] = f"a{i:07d}"
+
+    @staticmethod
+    def _strip(el):
+        el = dict(el)
+        el.pop("_z", None)
+        return el
+
+    def _self_validate(self):
+        ids = {el["id"] for el in self.elements}
+        warns = []
+        for el in self.elements:
+            for be in el.get("boundElements", []):
+                if be["id"] not in ids:
+                    warns.append(f"dangling boundElement {be['id']} on {el['id']}")
+            if el.get("containerId") and el["containerId"] not in ids:
+                warns.append(f"dangling containerId {el['containerId']} on {el['id']}")
+            for b in ("startBinding", "endBinding"):
+                if el.get(b) and el[b]["elementId"] not in ids:
+                    warns.append(f"dangling {b} on {el['id']}")
+        # overlap warning between node boxes
+        items = list(self.boxes.items())
+        for i in range(len(items)):
+            for j in range(i + 1, len(items)):
+                a, b = items[i][1], items[j][1]
+                ox = max(0, min(a[0] + a[2], b[0] + b[2]) - max(a[0], b[0]))
+                oy = max(0, min(a[1] + a[3], b[1] + b[3]) - max(a[1], b[1]))
+                if ox > 5 and oy > 5:
+                    warns.append(f"overlap: {items[i][0]} & {items[j][0]}")
+        if warns:
+            sys.stderr.write("[self-validate] " + str(len(warns)) + " warning(s):\n")
+            for w in warns[:20]:
+                sys.stderr.write("  - " + w + "\n")
+
+
+# --------------------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------------------
+
+def main():
+    ap = argparse.ArgumentParser(description="Convert Diagram DSL JSON to .excalidraw")
+    ap.add_argument("input", help="DSL json file, or '-' for stdin")
+    ap.add_argument("-o", "--output", help="output .excalidraw (default: stdout)")
+    ap.add_argument("--seed", type=int, default=None, help="override deterministic seed")
+    args = ap.parse_args()
+
+    raw = sys.stdin.read() if args.input == "-" else open(args.input, encoding="utf-8").read()
+    dsl = json.loads(raw)
+
+    out = Converter(dsl, seed=args.seed).build()
+    text = json.dumps(out, indent=2, ensure_ascii=False)
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(text)
+        sys.stderr.write(f"wrote {args.output} ({len(out['elements'])} elements)\n")
+    else:
+        sys.stdout.write(text)
+
+
+if __name__ == "__main__":
+    main()

dsl_schema.json

@@ -0,0 +1,269 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://excali-ft/dsl.schema.json",
+  "title": "Excalidraw Diagram DSL",
+  "description": "Compact, semantic-only description of a diagram. Carries planning decisions (what exists, what connects, what type). All geometry, sizing, IDs, colors, and Excalidraw format fields are computed deterministically by the converter and MUST NOT appear here.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["diagram", "title", "nodes"],
+  "properties": {
+    "diagram": {
+      "description": "Selects the converter strategy and default layout.",
+      "type": "string",
+      "enum": [
+        "system_architecture",
+        "flowchart",
+        "er_diagram",
+        "sequence_diagram",
+        "data_pipeline",
+        "timeline",
+        "mind_map",
+        "mobile_wireframe"
+      ]
+    },
+    "title": {
+      "description": "Human-readable diagram title, rendered as a heading text element.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80
+    },
+    "direction": {
+      "description": "Primary flow/layout direction. Optional; the converter applies a per-diagram default when omitted (e.g. TB for flowchart, LR for architecture, radial for mind_map).",
+      "type": "string",
+      "enum": ["LR", "RL", "TB", "BT", "radial"]
+    },
+    "nodes": {
+      "description": "The boxes/entities/participants/milestones. Internal `id`s are reference handles only and are never rendered.",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 40,
+      "items": { "$ref": "#/$defs/node" }
+    },
+    "edges": {
+      "description": "Connections between nodes. For sequence_diagram, array order is message order. May be empty (e.g. some timelines/mind maps without explicit links).",
+      "type": "array",
+      "maxItems": 80,
+      "items": { "$ref": "#/$defs/edge" },
+      "default": []
+    },
+    "groups": {
+      "description": "Optional clusters/swimlanes/screens. A node joins a group via node.group = group.id.",
+      "type": "array",
+      "maxItems": 12,
+      "items": { "$ref": "#/$defs/group" },
+      "default": []
+    },
+    "meta": {
+      "description": "Diagram-level escape hatch for type-specific knobs. Keep empty unless a type below defines a key.",
+      "type": "object",
+      "additionalProperties": true,
+      "default": {}
+    }
+  },
+
+  "$defs": {
+    "id": {
+      "description": "Stable snake_case identifier, unique within its collection. Reference handle only — not rendered.",
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "minLength": 1,
+      "maxLength": 40
+    },
+    "label": {
+      "description": "Visible text. Non-empty, single line preferred.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 60
+    },
+    "role": {
+      "description": "Semantic kind of the node. The converter maps role -> {shape, fill color, stroke color}. The model never picks shapes or colors directly.",
+      "type": "string",
+      "enum": [
+        "actor",
+        "client",
+        "service",
+        "gateway",
+        "database",
+        "cache",
+        "queue",
+        "worker",
+        "storage",
+        "external",
+        "monitoring",
+        "auth",
+        "start",
+        "end",
+        "process",
+        "decision",
+        "io",
+        "source",
+        "transform",
+        "sink",
+        "entity",
+        "participant",
+        "milestone",
+        "root",
+        "branch",
+        "leaf",
+        "screen",
+        "ui_element",
+        "component",
+        "generic"
+      ]
+    },
+    "node": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "label", "role"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "label": { "$ref": "#/$defs/label" },
+        "role": { "$ref": "#/$defs/role" },
+        "group": {
+          "description": "Optional group membership; must equal some groups[].id.",
+          "$ref": "#/$defs/id"
+        },
+        "color": {
+          "description": "OPTIONAL explicit override only when a human would intentionally choose a color (e.g. emphasis). Otherwise omit and let the converter derive color from role.",
+          "type": "string",
+          "enum": ["red", "orange", "yellow", "green", "blue", "violet", "gray", "black"]
+        },
+        "meta": {
+          "description": "Type-specific node data. See per-diagram rules in DSL_SPEC.md. Examples: er_diagram fields, timeline date, wireframe ui kind.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "fields": {
+              "description": "er_diagram only: entity columns.",
+              "type": "array",
+              "maxItems": 20,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["name"],
+                "properties": {
+                  "name": { "type": "string", "minLength": 1, "maxLength": 40 },
+                  "type": { "type": "string", "maxLength": 30 },
+                  "key": { "type": "string", "enum": ["pk", "fk", "none"], "default": "none" }
+                }
+              }
+            },
+            "date": {
+              "description": "timeline only: ISO-ish date or short label used for ordering and display.",
+              "type": "string",
+              "maxLength": 30
+            },
+            "kind": {
+              "description": "mobile_wireframe only: the UI element kind.",
+              "type": "string",
+              "enum": ["header", "nav", "text", "input", "button", "list", "image", "card", "tab", "footer"]
+            }
+          }
+        }
+      }
+    },
+    "edge": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["from", "to"],
+      "properties": {
+        "from": {
+          "description": "Source node id. Must reference an existing node.",
+          "$ref": "#/$defs/id"
+        },
+        "to": {
+          "description": "Target node id. Must reference an existing node.",
+          "$ref": "#/$defs/id"
+        },
+        "label": {
+          "description": "Optional edge label. For flowchart decision branches use 'yes'/'no'.",
+          "type": "string",
+          "maxLength": 40
+        },
+        "style": {
+          "description": "Line style. Default solid.",
+          "type": "string",
+          "enum": ["solid", "dashed", "dotted"],
+          "default": "solid"
+        },
+        "meta": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "cardinality": {
+              "description": "er_diagram only: relationship cardinality.",
+              "type": "string",
+              "enum": ["1:1", "1:N", "N:1", "N:M"]
+            },
+            "kind": {
+              "description": "sequence_diagram only: message kind.",
+              "type": "string",
+              "enum": ["sync", "async", "return"],
+              "default": "sync"
+            }
+          }
+        }
+      }
+    },
+    "group": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "label"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "label": { "$ref": "#/$defs/label" }
+      }
+    }
+  },
+
+  "allOf": [
+    {
+      "description": "ER diagrams: relationships should carry cardinality.",
+      "if": { "properties": { "diagram": { "const": "er_diagram" } } },
+      "then": {
+        "properties": {
+          "edges": {
+            "items": {
+              "properties": {
+                "meta": { "required": ["cardinality"] }
+              },
+              "required": ["meta"]
+            }
+          }
+        }
+      }
+    },
+    {
+      "description": "Timelines: every milestone node should carry a date.",
+      "if": { "properties": { "diagram": { "const": "timeline" } } },
+      "then": {
+        "properties": {
+          "nodes": {
+            "items": {
+              "properties": {
+                "meta": { "required": ["date"] }
+              },
+              "required": ["meta"]
+            }
+          }
+        }
+      }
+    },
+    {
+      "description": "Mobile wireframes: every node needs a UI kind.",
+      "if": { "properties": { "diagram": { "const": "mobile_wireframe" } } },
+      "then": {
+        "properties": {
+          "nodes": {
+            "items": {
+              "properties": {
+                "meta": { "required": ["kind"] }
+              },
+              "required": ["meta"]
+            }
+          }
+        }
+      }
+    }
+  ]
+}

packages.txt

@@ -0,0 +1 @@
+graphviz

requirements.txt

@@ -0,0 +1,2 @@
+gradio>=4.44,<6
+requests>=2.31

validate_dsl.py

@@ -0,0 +1,757 @@
+#!/usr/bin/env python3
+"""
+validate_dsl.py
+
+The Phase 2 accept/reject gate for Diagram DSL.
+
+Two layers, both enforced here (zero pip dependencies — pure stdlib):
+
+  1. STRUCTURAL  — a small JSON-Schema validator that reads `dsl_schema.json` and checks
+     types, enums, required keys, additionalProperties, lengths, patterns, and the
+     diagram-specific allOf/if-then conditionals. The schema file stays the single source
+     of truth; this validator just interprets it.
+
+  2. SEMANTIC    — the rules JSON Schema cannot express (DSL_SPEC.md section 2): unique ids,
+     edge endpoints resolve, no isolated nodes, flowchart-has-one-start, pipeline-is-acyclic,
+     mind_map-is-a-tree, etc. These are the rules that actually keep the dataset clean.
+
+A DSL is ACCEPTED iff it produces zero errors. Warnings never reject — they flag rows worth
+a human glance (e.g. very dense graphs, heavy color overrides).
+
+Usage:
+    # validate a single DSL file (or '-' for stdin)
+    python3 validate_dsl.py diagram.dsl.json
+    cat diagram.dsl.json | python3 validate_dsl.py -
+
+    # validate every assistant DSL in a training file (the dataset gate)
+    python3 validate_dsl.py --jsonl train.jsonl
+    python3 validate_dsl.py --jsonl train.jsonl --max-show 20 --warnings
+
+Exit code is 0 when everything passed, 1 otherwise — usable in CI / generation loops.
+
+As a library:
+    from validate_dsl import validate_dsl, validate_dsl_text, Result
+    res = validate_dsl(dsl_dict)
+    if res.ok: ...
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+
+SCHEMA_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "dsl_schema.json")
+
+# Diagram types whose every node must touch at least one edge (DSL_SPEC U7).
+CONNECTED_TYPES = {"system_architecture", "flowchart", "data_pipeline", "mind_map"}
+
+
+# --------------------------------------------------------------------------------------
+# Result accumulator
+# --------------------------------------------------------------------------------------
+
+class Result:
+    """Collects validation findings. `ok` is True iff there are no errors."""
+
+    def __init__(self):
+        self.errors = []    # list of (code, message)
+        self.warnings = []  # list of (code, message)
+
+    def error(self, code, message):
+        self.errors.append((code, message))
+
+    def warn(self, code, message):
+        self.warnings.append((code, message))
+
+    @property
+    def ok(self):
+        return not self.errors
+
+    def extend(self, other):
+        self.errors.extend(other.errors)
+        self.warnings.extend(other.warnings)
+
+    def __str__(self):
+        lines = []
+        for code, msg in self.errors:
+            lines.append(f"  ERROR [{code}] {msg}")
+        for code, msg in self.warnings:
+            lines.append(f"  WARN  [{code}] {msg}")
+        if not lines:
+            lines.append("  OK")
+        return "\n".join(lines)
+
+
+# --------------------------------------------------------------------------------------
+# Layer 1: structural validation (a minimal JSON-Schema interpreter for our schema)
+# --------------------------------------------------------------------------------------
+
+_JSON_TYPES = {
+    "object": dict,
+    "array": list,
+    "string": str,
+    "number": (int, float),
+    "integer": int,
+    "boolean": bool,
+    "null": type(None),
+}
+
+
+def _type_matches(value, type_name):
+    # bool is a subclass of int in Python; keep number/integer from swallowing booleans.
+    if type_name in ("number", "integer") and isinstance(value, bool):
+        return False
+    if type_name == "boolean":
+        return isinstance(value, bool)
+    return isinstance(value, _JSON_TYPES[type_name])
+
+
+class SchemaValidator:
+    """Interprets the subset of JSON Schema 2020-12 that dsl_schema.json actually uses:
+    $ref/$defs, type, enum, const, required, properties, additionalProperties, items,
+    minItems/maxItems, minLength/maxLength, pattern, allOf, and if/then/else."""
+
+    def __init__(self, schema):
+        self.root = schema
+
+    def validate(self, instance):
+        errors = []
+        self._check(instance, self.root, "$", errors)
+        return errors
+
+    # -- internals --------------------------------------------------------------------
+
+    def _resolve(self, schema):
+        # Follow a $ref chain ("#/$defs/node"). Sibling keywords in this schema are only
+        # `description` (non-validating), so replacing the node with its target is safe.
+        seen = 0
+        while isinstance(schema, dict) and "$ref" in schema:
+            ref = schema["$ref"]
+            parts = [p for p in ref.lstrip("#/").split("/") if p]
+            target = self.root
+            for p in parts:
+                target = target[p]
+            schema = target
+            seen += 1
+            if seen > 50:
+                break
+        return schema
+
+    def _matches(self, instance, schema):
+        """True iff `instance` validates against `schema` (used for if/then)."""
+        tmp = []
+        self._check(instance, schema, "$", tmp)
+        return not tmp
+
+    def _check(self, instance, schema, path, errors):
+        schema = self._resolve(schema)
+        if not isinstance(schema, dict):
+            return
+
+        # allOf
+        for sub in schema.get("allOf", []):
+            self._check(instance, sub, path, errors)
+
+        # if / then / else
+        if "if" in schema:
+            if self._matches(instance, schema["if"]):
+                if "then" in schema:
+                    self._check(instance, schema["then"], path, errors)
+            elif "else" in schema:
+                self._check(instance, schema["else"], path, errors)
+
+        # type
+        if "type" in schema:
+            t = schema["type"]
+            types = t if isinstance(t, list) else [t]
+            if not any(_type_matches(instance, tn) for tn in types):
+                errors.append(("schema", f"{path}: expected type {t}, got {_pytype(instance)}"))
+                return  # deeper keyword checks would just produce noise
+
+        # enum / const
+        if "enum" in schema and instance not in schema["enum"]:
+            errors.append(("schema", f"{path}: {instance!r} is not one of {schema['enum']}"))
+        if "const" in schema and instance != schema["const"]:
+            errors.append(("schema", f"{path}: expected const {schema['const']!r}"))
+
+        if isinstance(instance, str):
+            self._check_string(instance, schema, path, errors)
+        elif isinstance(instance, list):
+            self._check_array(instance, schema, path, errors)
+        elif isinstance(instance, dict):
+            self._check_object(instance, schema, path, errors)
+
+    def _check_string(self, instance, schema, path, errors):
+        if "minLength" in schema and len(instance) < schema["minLength"]:
+            errors.append(("schema", f"{path}: shorter than minLength {schema['minLength']}"))
+        if "maxLength" in schema and len(instance) > schema["maxLength"]:
+            errors.append(("schema", f"{path}: longer than maxLength {schema['maxLength']}"))
+        if "pattern" in schema and not re.search(schema["pattern"], instance):
+            errors.append(("schema", f"{path}: {instance!r} does not match pattern {schema['pattern']}"))
+
+    def _check_array(self, instance, schema, path, errors):
+        if "minItems" in schema and len(instance) < schema["minItems"]:
+            errors.append(("schema", f"{path}: fewer than minItems {schema['minItems']}"))
+        if "maxItems" in schema and len(instance) > schema["maxItems"]:
+            errors.append(("schema", f"{path}: more than maxItems {schema['maxItems']}"))
+        items = schema.get("items")
+        if items is not None:
+            for i, el in enumerate(instance):
+                self._check(el, items, f"{path}[{i}]", errors)
+
+    def _check_object(self, instance, schema, path, errors):
+        props = schema.get("properties", {})
+        for req in schema.get("required", []):
+            if req not in instance:
+                errors.append(("schema", f"{path}: missing required property '{req}'"))
+        additional = schema.get("additionalProperties", True)
+        for key, val in instance.items():
+            if key in props:
+                self._check(val, props[key], f"{path}.{key}", errors)
+            elif additional is False:
+                errors.append(("schema", f"{path}: unexpected property '{key}' (additionalProperties=false)"))
+            elif isinstance(additional, dict):
+                self._check(val, additional, f"{path}.{key}", errors)
+
+
+def _pytype(v):
+    if isinstance(v, bool):
+        return "boolean"
+    if isinstance(v, dict):
+        return "object"
+    if isinstance(v, list):
+        return "array"
+    if isinstance(v, str):
+        return "string"
+    if isinstance(v, (int, float)):
+        return "number"
+    if v is None:
+        return "null"
+    return type(v).__name__
+
+
+# --------------------------------------------------------------------------------------
+# Layer 2: semantic validation (DSL_SPEC.md section 2)
+# --------------------------------------------------------------------------------------
+
+def _semantic(dsl, res):
+    diagram = dsl["diagram"]
+    nodes = dsl["nodes"]
+    edges = dsl.get("edges", []) or []
+    groups = dsl.get("groups", []) or []
+
+    node_ids = [n["id"] for n in nodes]
+    id_set = set(node_ids)
+    by_id = {n["id"]: n for n in nodes}
+    group_ids = [g["id"] for g in groups]
+
+    _universal(dsl, diagram, nodes, edges, groups, node_ids, id_set, group_ids, res)
+
+    # Edges that actually resolve — later graph checks must not crash on dangling refs.
+    valid_edges = [e for e in edges if e["from"] in id_set and e["to"] in id_set]
+
+    dispatch = {
+        "flowchart": _flowchart,
+        "data_pipeline": _data_pipeline,
+        "sequence_diagram": _sequence,
+        "er_diagram": _er,
+        "mind_map": _mind_map,
+        "timeline": _timeline,
+        "mobile_wireframe": _wireframe,
+    }
+    fn = dispatch.get(diagram)
+    if fn:
+        fn(nodes, valid_edges, edges, by_id, id_set, groups, res)
+
+    _size_guards(nodes, edges, res)
+
+
+def _roles(nodes, role):
+    return [n for n in nodes if n.get("role") == role]
+
+
+def _universal(dsl, diagram, nodes, edges, groups, node_ids, id_set, group_ids, res):
+    # U1 — unique node ids
+    for dup in _dups(node_ids):
+        res.error("U1", f"duplicate node id '{dup}'")
+    # U2 — unique group ids
+    for dup in _dups(group_ids):
+        res.error("U2", f"duplicate group id '{dup}'")
+    group_set = set(group_ids)
+
+    # U3 — edge endpoints resolve
+    for i, e in enumerate(edges):
+        if e["from"] not in id_set:
+            res.error("U3", f"edges[{i}].from '{e['from']}' is not a node id")
+        if e["to"] not in id_set:
+            res.error("U3", f"edges[{i}].to '{e['to']}' is not a node id")
+
+    # U4 — group membership resolves
+    for n in nodes:
+        g = n.get("group")
+        if g is not None and g not in group_set:
+            res.error("U4", f"node '{n['id']}' references unknown group '{g}'")
+
+    # U5 — no self loops
+    for i, e in enumerate(edges):
+        if e["from"] == e["to"]:
+            res.error("U5", f"edges[{i}] is a self-loop on '{e['from']}'")
+
+    # U6 — no duplicate edges (sequence_diagram may legitimately repeat a pair)
+    if diagram != "sequence_diagram":
+        seen = set()
+        for i, e in enumerate(edges):
+            key = (e["from"], e["to"], e.get("label", ""))
+            if key in seen:
+                res.error("U6", f"edges[{i}] duplicates edge {e['from']}->{e['to']} (label {e.get('label','')!r})")
+            seen.add(key)
+
+    # U7 — no isolated nodes for connected types
+    if diagram in CONNECTED_TYPES:
+        touched = set()
+        for e in edges:
+            touched.add(e["from"])
+            touched.add(e["to"])
+        for n in nodes:
+            if n["id"] not in touched:
+                res.error("U7", f"node '{n['id']}' is isolated (no edge) in a connected diagram")
+
+    # U8 — color override sanity (warn only)
+    overrides = sum(1 for n in nodes if n.get("color"))
+    if nodes and overrides / len(nodes) > 0.30:
+        res.warn("U8", f"{overrides}/{len(nodes)} nodes override color (>30%) — styling should come from role")
+
+    # U9 — label hygiene
+    _label_hygiene("title", dsl.get("title", ""), res)
+    for n in nodes:
+        _label_hygiene(f"node '{n['id']}' label", n.get("label", ""), res)
+    for g in groups:
+        _label_hygiene(f"group '{g['id']}' label", g.get("label", ""), res)
+    for i, e in enumerate(edges):
+        if "label" in e:
+            _label_hygiene(f"edges[{i}] label", e["label"], res)
+
+
+def _label_hygiene(where, text, res):
+    if "\n" in text or "\r" in text:
+        res.error("U9", f"{where} contains a newline (converter handles wrapping)")
+    elif text != text.strip():
+        res.warn("U9", f"{where} has leading/trailing whitespace")
+
+
+def _flowchart(nodes, edges, raw_edges, by_id, id_set, groups, res):
+    starts = _roles(nodes, "start")
+    # F1 — exactly one start
+    if len(starts) != 1:
+        res.error("F1", f"flowchart needs exactly one 'start' node, found {len(starts)}")
+    # F2 — at least one end
+    if not _roles(nodes, "end"):
+        res.error("F2", "flowchart needs at least one 'end' node")
+
+    out = _out_adj(edges)
+    # F3 — decision branches labeled, >= 2 outgoing
+    for n in nodes:
+        if n.get("role") == "decision":
+            outs = [e for e in edges if e["from"] == n["id"]]
+            if len(outs) < 2:
+                res.error("F3", f"decision node '{n['id']}' has {len(outs)} outgoing edges (need >= 2)")
+            for e in outs:
+                if not e.get("label", "").strip():
+                    res.error("F3", f"decision node '{n['id']}' has an unlabeled branch to '{e['to']}'")
+
+    # F4 — reachability from the (first) start
+    if starts:
+        reachable = _bfs(starts[0]["id"], out)
+        for n in nodes:
+            if n["id"] not in reachable:
+                res.error("F4", f"node '{n['id']}' is not reachable from start '{starts[0]['id']}'")
+
+
+def _data_pipeline(nodes, edges, raw_edges, by_id, id_set, groups, res):
+    out = _out_adj(edges)
+    indeg = _indegree(nodes, edges)
+    outdeg = _outdegree(nodes, edges)
+
+    # P1 — acyclic
+    cycle = _find_cycle(nodes, out)
+    if cycle:
+        res.error("P1", f"data_pipeline must be acyclic; cycle through {' -> '.join(cycle)}")
+
+    # P2 — has >=1 source and >=1 sink (by role)
+    sources = _roles(nodes, "source")
+    sinks = _roles(nodes, "sink")
+    if not sources:
+        res.error("P2", "data_pipeline needs at least one 'source' node")
+    if not sinks:
+        res.error("P2", "data_pipeline needs at least one 'sink' node")
+
+    # P3 — sources have no incoming, sinks have no outgoing
+    for n in sources:
+        if indeg.get(n["id"], 0) > 0:
+            res.error("P3", f"source '{n['id']}' has incoming edges")
+    for n in sinks:
+        if outdeg.get(n["id"], 0) > 0:
+            res.error("P3", f"sink '{n['id']}' has outgoing edges")
+
+
+def _sequence(nodes, edges, raw_edges, by_id, id_set, groups, res):
+    # S1 — all nodes are participants (or actors)
+    for n in nodes:
+        if n.get("role") not in ("participant", "actor"):
+            res.error("S1", f"sequence_diagram node '{n['id']}' has role '{n.get('role')}' (expected participant/actor)")
+
+    # S4 — return messages should point back toward an earlier sender (warn only).
+    prior_pairs = set()
+    for i, e in enumerate(raw_edges):
+        kind = (e.get("meta") or {}).get("kind")
+        if kind == "return":
+            if (e["to"], e["from"]) not in prior_pairs:
+                res.warn("S4", f"edges[{i}] is a 'return' to '{e['to']}' with no preceding message from it")
+        prior_pairs.add((e["from"], e["to"]))
+
+
+def _er(nodes, edges, raw_edges, by_id, id_set, groups, res):
+    # E1 — nodes are entities
+    for n in nodes:
+        if n.get("role") != "entity":
+            res.error("E1", f"er_diagram node '{n['id']}' has role '{n.get('role')}' (expected entity)")
+    # E2 — each entity declares >=1 field; at most one pk
+    for n in nodes:
+        fields = (n.get("meta") or {}).get("fields")
+        if not fields:
+            res.error("E2", f"entity '{n['id']}' declares no fields")
+            continue
+        pks = [f for f in fields if f.get("key") == "pk"]
+        if len(pks) > 1:
+            res.error("E2", f"entity '{n['id']}' has {len(pks)} primary keys (max 1)")
+    # E3 — relationships carry cardinality (also schema-enforced; restated)
+    for i, e in enumerate(raw_edges):
+        if not (e.get("meta") or {}).get("cardinality"):
+            res.error("E3", f"edges[{i}] ({e['from']}->{e['to']}) is missing meta.cardinality")
+
+
+def _mind_map(nodes, edges, raw_edges, by_id, id_set, groups, res):
+    roots = _roles(nodes, "root")
+    # M1 — exactly one root
+    if len(roots) != 1:
+        res.error("M1", f"mind_map needs exactly one 'root' node, found {len(roots)}")
+
+    n = len(nodes)
+    # M2 — tree shape: undirected connected & acyclic, every non-root has one parent.
+    if len(edges) != n - 1:
+        res.error("M2", f"mind_map is not a tree: {n} nodes need exactly {n-1} edges, found {len(edges)}")
+    undirected = _undirected_adj(edges)
+    if roots:
+        seen = _bfs(roots[0]["id"], undirected)
+        if len(seen) != n:
+            res.error("M2", f"mind_map is not connected: {len(seen)}/{n} nodes reachable from root (undirected)")
+        # directed parent check: root in-degree 0, others exactly 1
+        indeg = _indegree(nodes, edges)
+        for nd in nodes:
+            d = indeg.get(nd["id"], 0)
+            if nd["id"] == roots[0]["id"]:
+                if d != 0:
+                    res.error("M2", f"root '{nd['id']}' has {d} incoming edges (expected 0)")
+            elif d != 1:
+                res.error("M2", f"node '{nd['id']}' has {d} parents (expected exactly 1)")
+
+        # M3 — root reaches all (directed)
+        out = _out_adj(edges)
+        reach = _bfs(roots[0]["id"], out)
+        for nd in nodes:
+            if nd["id"] not in reach:
+                res.error("M3", f"node '{nd['id']}' is not reachable from root (directed)")
+
+
+def _timeline(nodes, edges, raw_edges, by_id, id_set, groups, res):
+    # T1 — every node has meta.date (schema-enforced; restated). T2 — sortable.
+    for n in nodes:
+        date = (n.get("meta") or {}).get("date")
+        if not date:
+            res.error("T1", f"timeline node '{n['id']}' is missing meta.date")
+        elif _date_sort_key(date) is None:
+            res.warn("T2", f"timeline node '{n['id']}' date {date!r} is not obviously sortable")
+
+
+def _wireframe(nodes, edges, raw_edges, by_id, id_set, groups, res):
+    # W1 — every node has meta.kind (schema-enforced; restated)
+    for n in nodes:
+        if not (n.get("meta") or {}).get("kind"):
+            res.error("W1", f"wireframe node '{n['id']}' is missing meta.kind")
+    # W2 — every node belongs to a screen group
+    if not groups:
+        res.error("W2", "mobile_wireframe has no groups (screens)")
+    for n in nodes:
+        if not n.get("group"):
+            res.error("W2", f"wireframe node '{n['id']}' is not assigned to a screen group")
+
+
+def _size_guards(nodes, edges, res):
+    # G1 / G3 — schema already bounds counts; these are quality warnings.
+    if len(nodes) > 25:
+        res.warn("G1", f"{len(nodes)} nodes — layout quality tends to degrade past ~25")
+    if nodes and len(edges) > len(nodes) * 3:
+        res.warn("G3", f"{len(edges)} edges for {len(nodes)} nodes (>3x) — likely too dense")
+
+
+# --------------------------------------------------------------------------------------
+# Graph helpers
+# --------------------------------------------------------------------------------------
+
+def _dups(seq):
+    seen, dups = set(), []
+    for x in seq:
+        if x in seen and x not in dups:
+            dups.append(x)
+        seen.add(x)
+    return dups
+
+
+def _out_adj(edges):
+    adj = {}
+    for e in edges:
+        adj.setdefault(e["from"], []).append(e["to"])
+    return adj
+
+
+def _undirected_adj(edges):
+    adj = {}
+    for e in edges:
+        adj.setdefault(e["from"], []).append(e["to"])
+        adj.setdefault(e["to"], []).append(e["from"])
+    return adj
+
+
+def _indegree(nodes, edges):
+    deg = {n["id"]: 0 for n in nodes}
+    for e in edges:
+        deg[e["to"]] = deg.get(e["to"], 0) + 1
+    return deg
+
+
+def _outdegree(nodes, edges):
+    deg = {n["id"]: 0 for n in nodes}
+    for e in edges:
+        deg[e["from"]] = deg.get(e["from"], 0) + 1
+    return deg
+
+
+def _bfs(start, adj):
+    seen, stack = set(), [start]
+    while stack:
+        cur = stack.pop()
+        if cur in seen:
+            continue
+        seen.add(cur)
+        for nxt in adj.get(cur, []):
+            if nxt not in seen:
+                stack.append(nxt)
+    return seen
+
+
+def _find_cycle(nodes, adj):
+    """Return a node sequence describing a directed cycle, or None. DFS with colors."""
+    WHITE, GRAY, BLACK = 0, 1, 2
+    color = {n["id"]: WHITE for n in nodes}
+    parent = {}
+
+    def visit(u):
+        color[u] = GRAY
+        for v in adj.get(u, []):
+            if v not in color:           # endpoint outside node set; skip defensively
+                continue
+            if color[v] == WHITE:
+                parent[v] = u
+                r = visit(v)
+                if r:
+                    return r
+            elif color[v] == GRAY:       # back edge u->v closes a cycle
+                path = [u]               # walk parents from u up to the ancestor v
+                x = u
+                while x != v and x in parent:
+                    x = parent[x]
+                    path.append(x)
+                path.reverse()           # now v ... u
+                return path + [v]         # close the loop: v ... u -> v
+        color[u] = BLACK
+        return None
+
+    sys.setrecursionlimit(10000)
+    for n in nodes:
+        if color[n["id"]] == WHITE:
+            r = visit(n["id"])
+            if r:
+                return r
+    return None
+
+
+_DATE_RE = re.compile(r"^\d{4}(-\d{2}(-\d{2})?)?$")
+
+
+def _date_sort_key(date):
+    """Return a sortable key for common date forms, or None if not obviously sortable.
+    Accepts ISO-ish (YYYY, YYYY-MM, YYYY-MM-DD) and 'Q<n> YYYY' style labels."""
+    date = date.strip()
+    if _DATE_RE.match(date):
+        return date
+    m = re.match(r"^Q([1-4])\s+(\d{4})$", date)
+    if m:
+        return f"{m.group(2)}-Q{m.group(1)}"
+    return None
+
+
+# --------------------------------------------------------------------------------------
+# Public API
+# --------------------------------------------------------------------------------------
+
+_SCHEMA_CACHE = None
+
+
+def load_schema(path=SCHEMA_FILE):
+    global _SCHEMA_CACHE
+    if _SCHEMA_CACHE is None:
+        with open(path, "r", encoding="utf-8") as f:
+            _SCHEMA_CACHE = json.load(f)
+    return _SCHEMA_CACHE
+
+
+def validate_dsl(dsl, schema=None):
+    """Validate a parsed DSL object. Returns a Result (res.ok == accepted)."""
+    res = Result()
+    schema = schema if schema is not None else load_schema()
+
+    # Layer 1 — structural. If it fails, semantic checks would just crash on the same
+    # malformed data, so we stop here and report the structural errors.
+    structural_errors = SchemaValidator(schema).validate(dsl)
+    if structural_errors:
+        for code, msg in structural_errors:
+            res.error(code, msg)
+        return res
+
+    # Layer 2 — semantic.
+    _semantic(dsl, res)
+    return res
+
+
+def validate_dsl_text(text, schema=None):
+    """Validate DSL given as a JSON string (e.g. a model's assistant output)."""
+    res = Result()
+    try:
+        dsl = json.loads(text)
+    except json.JSONDecodeError as e:
+        res.error("json", f"not valid JSON: {e}")
+        return res
+    if not isinstance(dsl, dict):
+        res.error("json", f"top-level DSL must be an object, got {_pytype(dsl)}")
+        return res
+    return validate_dsl(dsl, schema)
+
+
+def _assistant_content(row):
+    """Pull the assistant DSL string out of a chat-format training row."""
+    msgs = row.get("messages")
+    if not isinstance(msgs, list):
+        return None
+    for m in reversed(msgs):
+        if isinstance(m, dict) and m.get("role") == "assistant":
+            return m.get("content")
+    return None
+
+
+# --------------------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------------------
+
+def _read(path):
+    if path == "-":
+        return sys.stdin.read()
+    with open(path, "r", encoding="utf-8") as f:
+        return f.read()
+
+
+def _run_single(path, show_warnings):
+    res = validate_dsl_text(_read(path))
+    status = "PASS" if res.ok else "FAIL"
+    print(f"{status}: {path}")
+    for code, msg in res.errors:
+        print(f"  ERROR [{code}] {msg}")
+    if show_warnings:
+        for code, msg in res.warnings:
+            print(f"  WARN  [{code}] {msg}")
+    return 0 if res.ok else 1
+
+
+def _run_jsonl(path, show_warnings, max_show):
+    text = _read(path)
+    total = passed = failed = warned = 0
+    shown = 0
+    error_codes = {}
+    for lineno, line in enumerate(text.splitlines(), 1):
+        line = line.strip()
+        if not line:
+            continue
+        total += 1
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError as e:
+            failed += 1
+            error_codes["json"] = error_codes.get("json", 0) + 1
+            if shown < max_show:
+                print(f"FAIL line {lineno}: row is not valid JSON: {e}")
+                shown += 1
+            continue
+
+        content = _assistant_content(row) if isinstance(row, dict) else None
+        # Accept either a chat row or a bare DSL object on the line.
+        res = validate_dsl_text(content) if content is not None else validate_dsl(row) \
+            if isinstance(row, dict) else Result()
+        if content is None and not isinstance(row, dict):
+            res = Result()
+            res.error("json", "line is neither a chat row nor a DSL object")
+
+        if res.warnings:
+            warned += 1
+        for code, _ in res.errors:
+            error_codes[code] = error_codes.get(code, 0) + 1
+
+        if res.ok:
+            passed += 1
+            if show_warnings and res.warnings and shown < max_show:
+                print(f"WARN line {lineno}:")
+                for code, msg in res.warnings:
+                    print(f"  WARN  [{code}] {msg}")
+                shown += 1
+        else:
+            failed += 1
+            if shown < max_show:
+                print(f"FAIL line {lineno}:")
+                for code, msg in res.errors:
+                    print(f"  ERROR [{code}] {msg}")
+                shown += 1
+
+    print("-" * 60)
+    print(f"total={total}  passed={passed}  failed={failed}  with_warnings={warned}")
+    if error_codes:
+        breakdown = "  ".join(f"{c}={n}" for c, n in sorted(error_codes.items(), key=lambda x: -x[1]))
+        print(f"error breakdown: {breakdown}")
+    return 0 if failed == 0 else 1
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="Validate Diagram DSL (structural + semantic gate).")
+    ap.add_argument("input", help="DSL JSON file, JSONL dataset, or '-' for stdin")
+    ap.add_argument("--jsonl", action="store_true",
+                    help="treat input as a JSONL dataset; validate each row's assistant DSL")
+    ap.add_argument("--warnings", action="store_true", help="also show warnings")
+    ap.add_argument("--max-show", type=int, default=20,
+                    help="max failing/warning rows to print in --jsonl mode (default 20)")
+    args = ap.parse_args(argv)
+
+    if args.jsonl:
+        return _run_jsonl(args.input, args.warnings, args.max_show)
+    return _run_single(args.input, args.warnings)
+
+
+if __name__ == "__main__":
+    sys.exit(main())