@diagrammo/dgmo 0.6.1 → 0.6.3

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.1",
+  "version": "0.6.3",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "type": "module",
@@ -26,10 +26,11 @@
     "dist",
     "src",
     "docs",
-    ".claude/skills",
+    ".claude/commands",
     ".github/copilot-instructions.md",
     ".cursorrules",
-    ".windsurfrules"
+    ".windsurfrules",
+    "AGENTS.md"
   ],
   "sideEffects": false,
   "scripts": {
@@ -39,7 +40,9 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "gallery": "pnpm build && node scripts/generate-gallery.mjs",
-    "check:duplication": "jscpd ./src"
+    "check:duplication": "jscpd ./src",
+    "check:deadcode": "knip",
+    "postinstall": "node -e \"console.log('\\n💡 Claude Code user? Run: dgmo --install-claude-skill\\n')\""
   },
   "dependencies": {
     "@dagrejs/dagre": "^2.0.4",
@@ -63,9 +66,9 @@
     "@types/d3-scale": "^4.0.8",
     "@types/d3-selection": "^3.0.11",
     "@types/d3-shape": "^3.1.7",
-    "@types/dagre": "^0.7.54",
     "@types/jsdom": "^28.0.0",
     "jscpd": "^4.0.8",
+    "knip": "^6.0.1",
     "tsup": "^8.5.1",
     "typescript": "^5.7.3",
     "vitest": "^4.0.18"

package/src/c4/layout.ts

@@ -86,7 +86,6 @@ const DESC_LINE_HEIGHT = 16;
 const DESC_CHAR_WIDTH = 6.5;
 const CARD_V_PAD = 14;
 const CARD_H_PAD = 20;
-const TECH_LINE_HEIGHT = 16;
 const META_LINE_HEIGHT = 16;
 const META_CHAR_WIDTH = 6.5;
 const MARGIN = 40;
@@ -109,17 +108,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 +148,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 +215,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 +278,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 +291,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 +310,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;
@@ -415,10 +477,6 @@ export function rollUpContextRelationships(parsed: ParsedC4): ContextRelationshi
   const allRels = collectAllRelationships(parsed.elements, ownerMap);
 
   // Also include orphan relationships
-  for (const rel of parsed.relationships) {
-    // Orphan rels have no source element name — skip them for context roll-up
-  }
-
   // Separate system-level (explicit) from nested (rolled-up)
   const topLevelNames = new Set(parsed.elements.map((e) => e.name));
   const explicitKeys = new Set<string>();

package/src/c4/parser.ts

@@ -3,7 +3,6 @@
 // ============================================================
 
 import type { PaletteColors } from '../palettes';
-import type { DgmoError } from '../diagnostics';
 import { makeDgmoError, formatDgmoError, suggest } from '../diagnostics';
 import type { TagGroup } from '../utils/tag-groups';
 import { matchTagBlockHeading } from '../utils/tag-groups';
@@ -751,21 +750,6 @@ function attachElement(
 // Post-parse validation
 // ============================================================
 
-function collectAllNames(result: ParsedC4): Map<string, number> {
-  const names = new Map<string, number>();
-  function walk(elements: C4Element[]) {
-    for (const el of elements) {
-      names.set(el.name.toLowerCase(), el.lineNumber);
-      walk(el.children);
-      for (const g of el.groups) {
-        walk(g.children);
-      }
-    }
-  }
-  walk(result.elements);
-  return names;
-}
-
 function validateRelationshipTargets(
   result: ParsedC4,
   knownNames: Map<string, number>,

package/src/c4/renderer.ts

@@ -9,8 +9,7 @@ import type { PaletteColors } from '../palettes';
 import { mix } from '../palettes/color-utils';
 import { renderInlineText } from '../utils/inline-markdown';
 import type { ParsedC4 } from './types';
-import type { C4Shape } from './types';
-import type { C4LayoutResult, C4LayoutNode, C4LayoutEdge, C4LayoutBoundary, C4LegendGroup } from './layout';
+import type { C4LayoutResult, C4LayoutEdge, C4LegendGroup } from './layout';
 import { parseC4 } from './parser';
 import { layoutC4Context, layoutC4Containers, layoutC4Components, layoutC4Deployment, collectCardMetadata } from './layout';
 import {
@@ -50,7 +49,6 @@ const CARD_V_PAD = 14;
 const TYPE_LABEL_HEIGHT = 18;
 const DIVIDER_GAP = 6;
 const NAME_HEIGHT = 20;
-const TECH_LINE_HEIGHT = 16;
 const META_FONT_SIZE = 11;
 const META_CHAR_WIDTH = 6.5;
 const META_LINE_HEIGHT = 16;
@@ -257,7 +255,6 @@ export function renderC4Context(
   const scale = Math.min(MAX_SCALE, scaleX, scaleY);
 
   const scaledW = diagramW * scale;
-  const scaledH = diagramH * scale;
   const offsetX = (width - scaledW) / 2;
   const offsetY = titleHeight + DIAGRAM_PADDING;
 
@@ -1300,7 +1297,6 @@ export function renderC4Containers(
   const scale = Math.min(MAX_SCALE, scaleX, scaleY);
 
   const scaledW = diagramW * scale;
-  const scaledH = diagramH * scale;
   const offsetX = (width - scaledW) / 2;
   const offsetY = titleHeight + DIAGRAM_PADDING;
 

package/src/class/layout.ts

@@ -2,7 +2,6 @@ import dagre from '@dagrejs/dagre';
 import type {
   ParsedClassDiagram,
   ClassNode,
-  ClassRelationship,
   RelationshipType,
 } from './types';
 

package/src/class/parser.ts

@@ -383,3 +383,31 @@ export function looksLikeClassDiagram(content: string): boolean {
 
   return false;
 }
+
+// ============================================================
+// Symbol extraction (for completion API)
+// ============================================================
+
+import type { DiagramSymbols } from '../completion';
+
+/**
+ * Extract class names (entities) from class diagram document text.
+ * Used by the dgmo completion API for ghost hints and popup completions.
+ */
+export function extractSymbols(docText: string): DiagramSymbols {
+  const entities: string[] = [];
+  let inMetadata = true;
+  for (const rawLine of docText.split('\n')) {
+    const line = rawLine.trim();
+    if (inMetadata && /^[a-z-]+\s*:/i.test(line)) continue;
+    inMetadata = false;
+    if (line.length === 0 || /^\s/.test(rawLine)) continue;
+    const m = CLASS_DECL_RE.exec(line);
+    if (m && !entities.includes(m[1]!)) entities.push(m[1]!);
+  }
+  return {
+    kind: 'class',
+    entities,
+    keywords: ['extends', 'implements', 'abstract', 'interface', 'enum'],
+  };
+}

package/src/class/renderer.ts

@@ -5,10 +5,11 @@
 import * as d3Selection from 'd3-selection';
 import * as d3Shape from 'd3-shape';
 import { FONT_FAMILY } from '../fonts';
+import { runInExportContainer, extractExportSvg } from '../utils/export-container';
 import type { PaletteColors } from '../palettes';
 import { mix } from '../palettes/color-utils';
 import type { ParsedClassDiagram, ClassModifier, RelationshipType } from './types';
-import type { ClassLayoutResult, ClassLayoutNode, ClassLayoutEdge } from './layout';
+import type { ClassLayoutResult } from './layout';
 import { parseClassDiagram } from './parser';
 import { layoutClassDiagram } from './layout';
 
@@ -99,8 +100,6 @@ function isSourceMarker(type: RelationshipType): boolean {
 // Main renderer
 // ============================================================
 
-type GSelection = d3Selection.Selection<SVGGElement, unknown, null, undefined>;
-
 export function renderClassDiagram(
   container: HTMLDivElement,
   parsed: ParsedClassDiagram,
@@ -125,7 +124,6 @@ export function renderClassDiagram(
   const scale = Math.min(MAX_SCALE, scaleX, scaleY);
 
   const scaledW = diagramW * scale;
-  const scaledH = diagramH * scale;
   const offsetX = (width - scaledW) / 2;
   const offsetY = titleHeight + DIAGRAM_PADDING;
 
@@ -506,16 +504,10 @@ export function renderClassDiagramForExport(
   const layout = layoutClassDiagram(parsed);
   const isDark = theme === 'dark';
 
-  const container = document.createElement('div');
   const exportWidth = layout.width + DIAGRAM_PADDING * 2;
   const exportHeight = layout.height + DIAGRAM_PADDING * 2 + (parsed.title ? 40 : 0);
-  container.style.width = `${exportWidth}px`;
-  container.style.height = `${exportHeight}px`;
-  container.style.position = 'absolute';
-  container.style.left = '-9999px';
-  document.body.appendChild(container);
 
-  try {
+  return runInExportContainer(exportWidth, exportHeight, (container) => {
     renderClassDiagram(
       container,
       parsed,
@@ -525,19 +517,6 @@ export function renderClassDiagramForExport(
       undefined,
       { width: exportWidth, height: exportHeight }
     );
-
-    const svgEl = container.querySelector('svg');
-    if (!svgEl) return '';
-
-    if (theme === 'transparent') {
-      svgEl.style.background = 'none';
-    }
-
-    svgEl.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
-    svgEl.style.fontFamily = FONT_FAMILY;
-
-    return svgEl.outerHTML;
-  } finally {
-    document.body.removeChild(container);
-  }
+    return extractExportSvg(container, theme);
+  });
 }