@diagrammo/dgmo 0.6.0 → 0.6.2

package/docs/ai-integration.md

@@ -1,14 +1,16 @@
 # DGMO AI Integration Guide
 
-Use AI coding tools to generate `.dgmo` diagrams. This guide covers Claude Code, Copilot, Cursor, and other AI tools.
+Use AI coding tools to generate `.dgmo` diagrams. This guide covers Claude Code, Copilot, Cursor, Windsurf, and any tool with an MCP client.
 
-## MCP Server
+---
 
-`@diagrammo/dgmo-mcp` provides an MCP server that exposes DGMO rendering, sharing, and documentation tools. Works with Claude Desktop, Claude Code, and any MCP-compatible client.
+## MCP Server (recommended for Claude)
 
-5 tools: `render_diagram`, `share_diagram`, `open_in_app`, `list_chart_types`, `get_language_reference`.
+`@diagrammo/dgmo-mcp` provides an MCP server that gives Claude the ability to render, share, and look up DGMO diagrams directly — no file management needed.
 
-Setup (Claude Code — add to `.claude/settings.local.json`):
+**5 tools:** `render_diagram`, `share_diagram`, `open_in_app`, `list_chart_types`, `get_language_reference`
+
+Add to `~/.claude/settings.json` (global) or `.claude/settings.local.json` (project):
 
 ```json
 {
@@ -23,60 +25,46 @@ Setup (Claude Code — add to `.claude/settings.local.json`):
 
 See `dgmo-mcp/README.md` for full configuration options.
 
-## Claude Code — Skills
-
-Copy the `.claude/skills/dgmo-*` directories from this repo into your project's `.claude/skills/` directory. This gives you four slash commands:
+---
 
-| Command | What it does |
-|---------|-------------|
-| `/dgmo-generate <description>` | Picks the best diagram type automatically |
-| `/dgmo-sequence <flow>` | Generates a sequence diagram |
-| `/dgmo-flowchart <process>` | Generates a flowchart |
-| `/dgmo-chart <data description>` | Generates a data chart |
+## Claude Code — Skill (slash command)
 
-### Setup
+Installs a `/dgmo` slash command that gives Claude full dgmo context — all chart types, CLI flags, workflow, and tips.
 
 ```bash
-# Copy skills into your project
-cp -r node_modules/@diagrammo/dgmo/.claude/skills/dgmo-* .claude/skills/
-
-# Or if dgmo is installed globally
-cp -r $(npm root -g)/@diagrammo/dgmo/.claude/skills/dgmo-* .claude/skills/
+dgmo --install-claude-skill
 ```
 
-### Usage examples
+This copies a skill file into `~/.claude/commands/`, making `/dgmo` available in every Claude Code session.
 
-```
-/dgmo-generate an ER diagram for a blog with users, posts, and comments
-/dgmo-sequence the OAuth2 authorization code flow
-/dgmo-flowchart CI/CD pipeline with build, test, and deploy stages
-/dgmo-chart quarterly revenue: Q1 100, Q2 120, Q3 110, Q4 130
-```
+---
 
 ## Claude Code — CLAUDE.md snippet
 
-Add this to your project's `CLAUDE.md` to teach Claude about DGMO without installing skills:
+To teach Claude about DGMO in a specific project without the global skill, add this to your `CLAUDE.md`:
 
 ```markdown
 ## DGMO Diagrams
 
-When the user asks for a diagram, generate a `.dgmo` file. DGMO is a text-based diagram language.
+When the user asks for a diagram, generate a `.dgmo` file.
 
 Quick reference:
-- Sequence: `A -> B: message` or `A -message-> B`
+- Sequence: `A -message-> B` or `A <-response- B`
 - Flowchart: `(Start) -> [Process] -> <Decision?> -yes-> (End)`
 - Bar chart: `chart: bar` then `Label: value` lines
 - ER diagram: `chart: er` then table definitions and `table1 1--* table2` relationships
 - Org chart: `chart: org` then indented hierarchy
 
-Full reference: see `node_modules/@diagrammo/dgmo/docs/language-reference.md`
+Full reference: `node_modules/@diagrammo/dgmo/docs/language-reference.md`
 
-Render with: `dgmo file.dgmo -o output.svg` or `dgmo file.dgmo -o url` for shareable link.
+Render with: `dgmo file.dgmo` (PNG) or `dgmo file.dgmo -o url` (shareable link).
 ```
 
+---
+
 ## Other AI Tools — Prompt Files
 
-DGMO ships prompt files for popular AI coding tools. These are included in the npm package:
+DGMO ships context files for popular AI coding tools, included in the npm package and auto-loaded when present in a project root.
 
 | File | Tool | How it works |
 |------|------|-------------|
@@ -84,42 +72,37 @@ DGMO ships prompt files for popular AI coding tools. These are included in the n
 | `.cursorrules` | Cursor | Auto-loaded when present in project root |
 | `.windsurfrules` | Windsurf | Auto-loaded when present in project root |
 
-### Setup
-
 Copy the relevant file into your project root:
 
 ```bash
-# From node_modules
+# From node_modules (if installed as a dependency)
 cp node_modules/@diagrammo/dgmo/.cursorrules .
 cp node_modules/@diagrammo/dgmo/.windsurfrules .
 mkdir -p .github && cp node_modules/@diagrammo/dgmo/.github/copilot-instructions.md .github/
 
-# Or from global install
+# From global npm install
 cp $(npm root -g)/@diagrammo/dgmo/.cursorrules .
 ```
 
-Each file contains a condensed DGMO syntax reference with examples for the most common diagram types, all 29 chart types listed, rendering commands, and common mistakes to avoid.
+Each file contains a condensed DGMO syntax reference with examples, all chart types listed, rendering commands, and common mistakes to avoid.
 
-## Rendering
+---
 
-If the `dgmo` CLI is installed, diagrams can be rendered:
+## Rendering commands
 
 ```bash
-# Install
-npm install -g @diagrammo/dgmo   # or: brew install diagrammo/dgmo/dgmo
-
-# Render
 dgmo diagram.dgmo                # PNG output
 dgmo diagram.dgmo -o output.svg  # SVG output
-dgmo diagram.dgmo -o url         # Shareable URL
-
-# AI-friendly JSON output
-dgmo diagram.dgmo -o output.svg --json
-dgmo --chart-types --json         # List all chart types
+dgmo diagram.dgmo -o url         # Shareable diagrammo.app URL
+dgmo diagram.dgmo -o url --copy  # URL copied to clipboard
+dgmo --chart-types               # List all supported chart types
+dgmo --chart-types --json        # Machine-readable chart type list
 ```
 
+---
+
 ## Supported chart types
 
 Run `dgmo --chart-types` for the full list, or see `docs/language-reference.md`.
 
-32 types: bar, line, area, pie, doughnut, radar, polar-area, bar-stacked, scatter, sankey, chord, function, heatmap, funnel, slope, wordcloud, arc, timeline, venn, quadrant, sequence, flowchart, state, class, er, org, kanban, c4, initiative-status, sitemap, infra.
+29 types: bar, line, area, multi-line, pie, doughnut, radar, polar-area, bar-stacked, scatter, sankey, chord, function, heatmap, funnel, slope, wordcloud, arc, timeline, venn, quadrant, sequence, flowchart, class, er, org, kanban, c4, initiative-status, infra.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "type": "module",
@@ -26,7 +26,7 @@
     "dist",
     "src",
     "docs",
-    ".claude/skills",
+    ".claude/commands",
     ".github/copilot-instructions.md",
     ".cursorrules",
     ".windsurfrules"
@@ -39,7 +39,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "gallery": "pnpm build && node scripts/generate-gallery.mjs",
-    "check:duplication": "jscpd ./src"
+    "check:duplication": "jscpd ./src",
+    "postinstall": "node -e \"console.log('\\n💡 Claude Code user? Run: dgmo --install-claude-skill\\n')\""
   },
   "dependencies": {
     "@dagrejs/dagre": "^2.0.4",

package/src/c4/layout.ts

@@ -109,17 +109,31 @@ const LEGEND_CAPSULE_PAD = 4;
 // Post-Layout Crossing Reduction
 // ============================================================
 
+interface NodeGeometry {
+  y: number;
+  width: number;
+  height: number;
+}
+
+// Large penalty per edge-node collision — dominates the distance term so the
+// sifter strongly prefers orderings where edges don't pass through other nodes.
+const EDGE_NODE_COLLISION_WEIGHT = 5000;
+
 /**
  * Compute penalty for an edge ordering. Uses degree-weighted edge distance:
  * long edges to high-degree nodes are penalized more than to low-degree nodes.
  * This places shared/important nodes closer to their neighbors, reducing
  * visual edge congestion.
  *
+ * When nodeGeometry is provided, also adds a heavy penalty for each case where
+ * a straight-line edge bounding box overlaps another node — driving the sifter
+ * to prefer orderings that avoid edge-node collisions.
  */
 function computeEdgePenalty(
   edgeList: { source: string; target: string }[],
   nodePositions: Map<string, number>,
-  degrees: Map<string, number>
+  degrees: Map<string, number>,
+  nodeGeometry?: Map<string, NodeGeometry>
 ): number {
   let penalty = 0;
 
@@ -135,6 +149,48 @@ function computeEdgePenalty(
     penalty += dist * weight;
   }
 
+  // Edge-node collision penalty: for each edge A→B, check if any other node C
+  // has its bounding box inside the straight-line bounding box of the edge.
+  // Uses x from nodePositions (updated per permutation) and y/size from nodeGeometry.
+  if (nodeGeometry) {
+    for (const edge of edgeList) {
+      const geomA = nodeGeometry.get(edge.source);
+      const geomB = nodeGeometry.get(edge.target);
+      if (!geomA || !geomB) continue;
+
+      const ax = nodePositions.get(edge.source) ?? 0;
+      const bx = nodePositions.get(edge.target) ?? 0;
+      const ay = geomA.y;
+      const by = geomB.y;
+
+      // Skip edges within the same rank — they have no vertical span to check
+      if (ay === by) continue;
+
+      const edgeMinX = Math.min(ax, bx);
+      const edgeMaxX = Math.max(ax, bx);
+      const edgeMinY = Math.min(ay, by);
+      const edgeMaxY = Math.max(ay, by);
+
+      for (const [name, geomC] of nodeGeometry) {
+        if (name === edge.source || name === edge.target) continue;
+        const cx = nodePositions.get(name) ?? 0;
+        const cy = geomC.y;
+        const hw = geomC.width / 2;
+        const hh = geomC.height / 2;
+
+        // AABB overlap: node C's box intersects the edge's straight-line bounding box
+        if (
+          cx + hw > edgeMinX &&
+          cx - hw < edgeMaxX &&
+          cy + hh > edgeMinY &&
+          cy - hh < edgeMaxY
+        ) {
+          penalty += EDGE_NODE_COLLISION_WEIGHT;
+        }
+      }
+    }
+  }
+
   return penalty;
 }
 
@@ -160,6 +216,13 @@ function reduceCrossings(
     degrees.set(edge.target, (degrees.get(edge.target) ?? 0) + 1);
   }
 
+  // Build geometry map for edge-node collision scoring
+  const nodeGeometry = new Map<string, NodeGeometry>();
+  for (const name of g.nodes()) {
+    const pos = g.node(name);
+    if (pos) nodeGeometry.set(name, { y: pos.y, width: pos.width, height: pos.height });
+  }
+
   // Group nodes by rank
   const rankMap = new Map<number, string[]>();
   for (const name of g.nodes()) {
@@ -216,7 +279,7 @@ function reduceCrossings(
       }
 
       // Current penalty
-      const currentPenalty = computeEdgePenalty(edgeList, basePositions, degrees);
+      const currentPenalty = computeEdgePenalty(edgeList, basePositions, degrees, nodeGeometry);
 
       // Try permutations (feasible for partition sizes ≤ 8)
       let bestPerm = [...partition];
@@ -229,7 +292,7 @@ function reduceCrossings(
           for (let i = 0; i < perm.length; i++) {
             testPositions.set(perm[i]!, xSlots[i]!);
           }
-          const penalty = computeEdgePenalty(edgeList, testPositions, degrees);
+          const penalty = computeEdgePenalty(edgeList, testPositions, degrees, nodeGeometry);
           if (penalty < bestPenalty) {
             bestPenalty = penalty;
             bestPerm = [...perm];
@@ -248,14 +311,14 @@ function reduceCrossings(
             for (let k = 0; k < workingOrder.length; k++) {
               testPositions.set(workingOrder[k]!, xSlots[k]!);
             }
-            const before = computeEdgePenalty(edgeList, testPositions, degrees);
+            const before = computeEdgePenalty(edgeList, testPositions, degrees, nodeGeometry);
 
             [workingOrder[i], workingOrder[i + 1]] = [workingOrder[i + 1]!, workingOrder[i]!];
             const testPositions2 = new Map(basePositions);
             for (let k = 0; k < workingOrder.length; k++) {
               testPositions2.set(workingOrder[k]!, xSlots[k]!);
             }
-            const after = computeEdgePenalty(edgeList, testPositions2, degrees);
+            const after = computeEdgePenalty(edgeList, testPositions2, degrees, nodeGeometry);
 
             if (after < before) {
               improved = true;
@@ -603,19 +666,12 @@ export function computeC4NodeDimensions(
 // Legend Helpers
 // ============================================================
 
-function computeLegendGroups(
-  tagGroups: OrgTagGroup[],
-  usedValuesByGroup?: Map<string, Set<string>>
-): C4LegendGroup[] {
+function computeLegendGroups(tagGroups: OrgTagGroup[]): C4LegendGroup[] {
   const result: C4LegendGroup[] = [];
 
   for (const group of tagGroups) {
     const entries: C4LegendEntry[] = [];
     for (const entry of group.entries) {
-      if (usedValuesByGroup) {
-        const used = usedValuesByGroup.get(group.name.toLowerCase());
-        if (!used?.has(entry.value.toLowerCase())) continue;
-      }
       entries.push({ value: entry.value, color: entry.color });
     }
     if (entries.length === 0) continue;
@@ -813,20 +869,9 @@ export function layoutC4Context(
   let totalWidth = nodes.length > 0 ? maxX - minX + MARGIN * 2 : 0;
   let totalHeight = nodes.length > 0 ? maxY - minY + MARGIN * 2 : 0;
 
-  // Legend
-  const usedValuesByGroup = new Map<string, Set<string>>();
-  for (const el of contextElements) {
-    for (const group of parsed.tagGroups) {
-      const key = group.name.toLowerCase();
-      const val = el.metadata[key];
-      if (val) {
-        if (!usedValuesByGroup.has(key)) usedValuesByGroup.set(key, new Set());
-        usedValuesByGroup.get(key)!.add(val.toLowerCase());
-      }
-    }
-  }
-
-  const legendGroups = computeLegendGroups(parsed.tagGroups, usedValuesByGroup);
+  // Legend: show all defined tag groups and entries so users see the full
+  // tag vocabulary regardless of which elements are visible at this view level.
+  const legendGroups = computeLegendGroups(parsed.tagGroups);
 
   // Position legend below diagram
   if (legendGroups.length > 0) {
@@ -1236,20 +1281,7 @@ export function layoutC4Containers(
   let totalWidth = maxX - minX + MARGIN * 2;
   let totalHeight = maxY - minY + MARGIN * 2;
 
-  // Legend
-  const usedValuesByGroup = new Map<string, Set<string>>();
-  for (const el of [...containers, ...externals]) {
-    for (const group of parsed.tagGroups) {
-      const key = group.name.toLowerCase();
-      const val = el.metadata[key];
-      if (val) {
-        if (!usedValuesByGroup.has(key)) usedValuesByGroup.set(key, new Set());
-        usedValuesByGroup.get(key)!.add(val.toLowerCase());
-      }
-    }
-  }
-
-  const legendGroups = computeLegendGroups(parsed.tagGroups, usedValuesByGroup);
+  const legendGroups = computeLegendGroups(parsed.tagGroups);
 
   // Position legend below diagram
   if (legendGroups.length > 0) {
@@ -1722,24 +1754,8 @@ export function layoutC4Components(
   let totalWidth = maxX - minX + MARGIN * 2;
   let totalHeight = maxY - minY + MARGIN * 2;
 
-  // Legend
-  const usedValuesByGroup = new Map<string, Set<string>>();
-  for (const el of [...components, ...externals]) {
-    for (const group of parsed.tagGroups) {
-      const key = group.name.toLowerCase();
-      // Check element + ancestors for inherited values
-      let val = el.metadata[key];
-      if (!val && components.includes(el)) {
-        val = targetContainer.metadata[key] ?? system.metadata[key];
-      }
-      if (val) {
-        if (!usedValuesByGroup.has(key)) usedValuesByGroup.set(key, new Set());
-        usedValuesByGroup.get(key)!.add(val.toLowerCase());
-      }
-    }
-  }
 
-  const legendGroups = computeLegendGroups(parsed.tagGroups, usedValuesByGroup);
+  const legendGroups = computeLegendGroups(parsed.tagGroups);
 
   // Position legend below diagram
   if (legendGroups.length > 0) {
@@ -2104,20 +2120,7 @@ export function layoutC4Deployment(
   let totalWidth = maxX - minX + MARGIN * 2;
   let totalHeight = maxY - minY + MARGIN * 2;
 
-  // Legend
-  const usedValuesByGroup = new Map<string, Set<string>>();
-  for (const r of refEntries) {
-    for (const group of parsed.tagGroups) {
-      const key = group.name.toLowerCase();
-      const val = r.element.metadata[key];
-      if (val) {
-        if (!usedValuesByGroup.has(key)) usedValuesByGroup.set(key, new Set());
-        usedValuesByGroup.get(key)!.add(val.toLowerCase());
-      }
-    }
-  }
-
-  const legendGroups = computeLegendGroups(parsed.tagGroups, usedValuesByGroup);
+  const legendGroups = computeLegendGroups(parsed.tagGroups);
 
   if (legendGroups.length > 0) {
     const legendY = totalHeight + MARGIN;