@diagrammo/dgmo 0.33.0 → 0.35.0

package/docs/ai-integration.md

@@ -4,44 +4,56 @@ Use AI coding tools to generate `.dgmo` diagrams. This guide covers Claude Code,
 
 ---
 
-## MCP Server (recommended for Claude)
+## One-step setup (recommended)
 
-`@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.
+Install the `dgmo` CLI, then run one command:
 
-**5 tools:** `render_diagram`, `share_diagram`, `open_in_app`, `list_chart_types`, `get_language_reference`
+```bash
+brew install diagrammo/dgmo/dgmo   # or: npm install -g @diagrammo/dgmo
+dgmo install                       # auto-detects every AI assistant you have
+```
 
-Add to `~/.claude/settings.json` (global) or `.claude/settings.local.json` (project):
+`dgmo install` with **no target** scans for Claude Code, Codex, Claude Desktop, Cursor, Windsurf, and Copilot, then configures each one non-interactively — no prompts, no second package to install. The only binary you ever need is `dgmo`; it provides the MCP server through its own `dgmo mcp` subcommand.
 
-```json
-{
-  "mcpServers": {
-    "dgmo": {
-      "command": "npx",
-      "args": ["-y", "@diagrammo/dgmo-mcp"]
-    }
-  }
-}
+Target a single assistant, or pick a scope, when you want to:
+
+```bash
+dgmo install claude-code              # just one surface
+dgmo install codex --scope project    # write config into the current repo
+dgmo install --dry-run                # preview every change, write nothing
 ```
 
-See `dgmo-mcp/README.md` for full configuration options.
+For Claude Code this copies the `/dgmo` skill into `~/.claude/commands/` (full dgmo context — all chart types, CLI flags, workflow, and tips) and adds the MCP server to `~/.claude/settings.json`. Restart the assistant afterward.
+
+**Keeping it current:**
+- **Homebrew** bundles the MCP server, so `brew upgrade dgmo` upgrades the CLI *and* the server together. Re-run `dgmo install` afterward only to refresh the **skill files** (those are copies in your home dir).
+- **npm global**: a plain `dgmo` upgrade doesn't touch the server or skill copies — re-run `dgmo install`, which overwrites the skills and upgrades the server to the latest.
+- Either way, `DGMO_MCP_LATEST=1` in the environment makes `dgmo mcp` always fetch the newest server at launch (network round-trip on start), so it's never stale.
 
 ---
 
-## Claude Code — Skill (slash command)
+## Manual MCP configuration
 
-Installs a `/dgmo` slash command that gives Claude full dgmo context — all chart types, CLI flags, workflow, and tips.
+`dgmo install` is the easy path. To wire the MCP server by hand, point any MCP client at the `dgmo` binary's `mcp` subcommand:
 
-```bash
-dgmo --install-claude-skill
+```json
+{
+  "mcpServers": {
+    "dgmo": {
+      "command": "dgmo",
+      "args": ["mcp"]
+    }
+  }
+}
 ```
 
-This copies a skill file into `~/.claude/commands/`, making `/dgmo` available in every Claude Code session.
+**5 tools:** `render_diagram`, `share_diagram`, `open_in_app`, `list_chart_types`, `get_language_reference`. `dgmo mcp` execs the installed server, or fetches it on demand via `npx` if it isn't installed yet — so no separate `dgmo-mcp` step is required. (If you'd rather not install the CLI at all, `{ "command": "npx", "args": ["-y", "@diagrammo/dgmo-mcp"] }` still works.) See `dgmo-mcp/README.md` for full options.
 
 ---
 
 ## Claude Code — CLAUDE.md snippet
 
-To teach Claude about DGMO in a specific project without the global skill, paste the generated core below into your `CLAUDE.md`. It is the same single-sourced anti-patterns + 45-type index that every DGMO AI surface carries (see "How the AI core is generated"). Render with `dgmo file.dgmo` (PNG) or `dgmo file.dgmo -o url` (shareable link); full per-type syntax lives in `node_modules/@diagrammo/dgmo/docs/language-reference.md`.
+To teach Claude about DGMO in a specific project without the global skill, paste the generated core below into your `CLAUDE.md`. It is the same single-sourced anti-patterns + 45-type index that every DGMO AI surface carries (see "How the AI core is generated"). Render with `dgmo file.dgmo` (PNG) or `dgmo share file.dgmo` (shareable link); full per-type syntax lives in `node_modules/@diagrammo/dgmo/docs/language-reference.md`.
 
 <!-- GENERATED by dgmo/scripts/gen-ai-core.mjs from docs/language-reference.md — DO NOT EDIT between the DGMO-AI-CORE markers; run `node scripts/gen-ai-core.mjs` (or sync-language-ref.sh) to regenerate. -->
 <!-- DGMO-AI-CORE:START -->
@@ -477,7 +489,15 @@ DGMO ships context files for popular AI coding tools, included in the npm packag
 | `.cursorrules` | Cursor | Auto-loaded when present in project root |
 | `.windsurfrules` | Windsurf | Auto-loaded when present in project root (byte-identical to `.cursorrules`) |
 
-Copy the relevant file into your project root:
+The easiest way to set these up is `dgmo install` — it does the right thing per tool:
+
+```bash
+dgmo install cursor      # wires MCP (~/.cursor/mcp.json) + drops .cursorrules
+dgmo install windsurf    # wires MCP (~/.codeium/windsurf/mcp_config.json) + .windsurfrules
+dgmo install copilot     # writes ./.github/copilot-instructions.md (Copilot has no MCP)
+```
+
+Cursor and Windsurf speak MCP, so `dgmo install` gives them the full render/share tools (pointed at `dgmo mcp`), plus the inline rules file. Copilot is guidance-only. `dgmo install` with no target also writes Copilot's file automatically when the current repo has a `.github` directory. To set the context files up by hand instead:
 
 ```bash
 # From node_modules (if installed as a dependency)
@@ -510,14 +530,14 @@ Regeneration runs inside `sync-language-ref.sh`; a Vitest gate parses every emit
 ```bash
 dgmo diagram.dgmo                # PNG output
 dgmo diagram.dgmo -o output.svg  # SVG output
-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
+dgmo share diagram.dgmo          # Shareable diagrammo.app URL (copied to clipboard)
+dgmo share diagram.dgmo --no-copy  # Print URL without touching the clipboard
+dgmo types                       # List all supported chart types
+dgmo types --json                # Machine-readable chart type list
 ```
 
 ---
 
 ## Supported chart types
 
-Run `dgmo --chart-types` for the full, authoritative list, call the MCP `list_chart_types` tool, or see the 45-type index in `docs/language-reference.md` (§0 AI Core). The list is intentionally not duplicated here — it drifts every time a chart type is added.
+Run `dgmo types` for the full, authoritative list, call the MCP `list_chart_types` tool, or see the 45-type index in `docs/language-reference.md` (§0 AI Core). The list is intentionally not duplicated here — it drifts every time a chart type is added.

package/docs/language-reference.md

@@ -3188,7 +3188,7 @@ Markers in cells are always **rendered in canonical alphabet order** (`R A C I`,
 <!-- TYPE:map -->
 
 <!-- TIPS start -->
-**Styling tips:** the zero-config map already looks good — name places and stop. When POIs fall into categories, tag them so each category gets its own color; keep place labels to the place name; leave region colorize and coastlines on unless the user asks to hide them. **For flights and airport routes, use IATA codes, not city names** — `LHR ~> JFK`, `LHR ~> DXB`, `LHR ~> SIN`, `LHR ~> HND` — the bundled airport set (large international hubs + all US commercial airports) resolves them to the right coordinates and labels them with the code. **For cities, use the exact canonical name**: "New York City" (NOT "New York"), "Washington, D.C.", etc. — a name the gazetteer doesn't have **silently drops that point** and the map just reframes around the rest, so it looks fine but is wrong. When unsure of the exact token, look it up: `dgmo map search "<place>"` (or the `lookup_map_location` MCP tool) returns the city name or airport code to paste; fall back to coordinates (`poi Name as 40.71,-74.0`) for anything not found. **For routes/flows from a hub** (an airport's daily flights, a distribution center's shipments), write ONE edge per line and repeat the origin — never indented edges (those error). Use **arcs** (`~>`) for flights and long-haul links so the spokes separate; the connector label carries the relationship (`~daily~>`, `~2x daily~>`). Endpoints auto-create POIs, so don't add separate `poi` lines for places already in an edge. Reach for a `route` block only when the trip is an **ordered voyage** that continues stop→stop (a cruise itinerary), not a set of independent routes from one origin.
+**Styling tips:** the zero-config map already looks good — name places and stop. When POIs fall into categories, tag them so each category gets its own color; keep place labels to the place name; leave region colorize and coastlines on unless the user asks to hide them. **For flights and airport routes, use IATA codes, not city names** — `LHR ~> JFK`, `LHR ~> DXB`, `LHR ~> SIN`, `LHR ~> HND` — the bundled airport set (large international hubs + all US commercial airports) resolves them to the right coordinates and labels them with the code. **For cities, use the exact canonical name**: "New York City" (NOT "New York"), "Washington, D.C.", etc. — a name the gazetteer doesn't have **silently drops that point** and the map just reframes around the rest, so it looks fine but is wrong. When unsure of the exact token, look it up: `dgmo map-search "<place>"` (or the `lookup_map_location` MCP tool) returns the city name or airport code to paste; fall back to coordinates (`poi Name as 40.71,-74.0`) for anything not found. **For routes/flows from a hub** (an airport's daily flights, a distribution center's shipments), write ONE edge per line and repeat the origin — never indented edges (those error). Use **arcs** (`~>`) for flights and long-haul links so the spokes separate; the connector label carries the relationship (`~daily~>`, `~2x daily~>`). Endpoints auto-create POIs, so don't add separate `poi` lines for places already in an edge. Reach for a `route` block only when the trip is an **ordered voyage** that continues stop→stop (a cruise itinerary), not a set of independent routes from one origin.
 <!-- TIPS end -->
 
 Geographic concept maps: highlight/shade political subdivisions, drop points of interest (POIs), and connect them with routes or edges. For "share a concept" business maps, not cartography. Renders at a fixed, auto-fit position — no pan/zoom. Basemap and viewport are **inferred from the content you reference** — most maps need no directives. v1 boundaries: world countries + US states.
@@ -3332,7 +3332,7 @@ cove -> hav l: March    # the LINE turns green
   - The redundant `Georgia US-GA` still works but isn't needed (a mismatched code like `Georgia US-CA` is rejected). A bare ambiguous `Georgia` follows the inferred US-scope signal and warns with both fixes named.
 - **IATA airport codes** resolve to airport coordinates — `poi JFK`, `route JFK -> LAX` — with no new syntax (large international hubs + all US scheduled-commercial airports). Case-insensitive (`jfk`/`JFK`). Airports are the **lowest-precedence** identifier: a token that is both a city and a code resolves to the **city** (`Ufa` → the city, not UFA airport), with a hint naming the airport. Resolution is by **code only** (never by airport name); the POI label is the typed code. An unknown three-letter code errors with an `as <CODE>` coordinates hint.
 - **A city name must match the gazetteer's canonical form** — `New York City`, not `New York`; `Washington, D.C.`, not `Washington`. An unrecognized name is dropped (with a did-you-mean note) and the map reframes around the places that *did* resolve, so the result can look complete but be missing a point. Use the exact name or coordinates.
-- **Discover the exact token** with the lookup surface rather than guessing — `dgmo map search "<place>"` (CLI; `--json` for machine output) or the `lookup_map_location` MCP tool. It substring-searches cities **and** the bundled airports and returns the precise token to paste (e.g. `york` → `New York City`; `heathrow` → `LHR`). There is intentionally **no exhaustive printed list** — the gazetteer holds thousands of cities plus ~1,500 airports; search is the interface.
+- **Discover the exact token** with the lookup surface rather than guessing — `dgmo map-search "<place>"` (CLI; `--json` for machine output) or the `lookup_map_location` MCP tool. It substring-searches cities **and** the bundled airports and returns the precise token to paste (e.g. `york` → `New York City`; `heathrow` → `LHR`). There is intentionally **no exhaustive printed list** — the gazetteer holds thousands of cities plus ~1,500 airports; search is the interface.
 - Positional coordinates are the escape hatch for anything missing/ambiguous (including forcing an airport over a colliding city: `poi 54.56 55.87 as UFA`).
 
 ### Directives & reserved keys

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "repository": {
@@ -134,13 +134,13 @@
     "check:deadcode": "knip",
     "check:spelling": "cspell \"src/**/*.ts\" \"tests/**/*.ts\"",
     "check:all": "pnpm check:deadcode && pnpm check:spelling && pnpm check:duplication && pnpm check:circular && pnpm check:deps && pnpm check:security && pnpm build && bash scripts/check-api.sh check && pnpm check:publish && pnpm check:types",
-    "check:circular": "madge --circular --extensions ts src/ --json | node -e \"const c=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); const n=c.length; if(n>6){console.error('New circular deps found ('+n+' > 6 known type-only/dynamic cycles)');process.exit(1)}else if(n>0){console.log(n+' known type-only/dynamic cycles (safe)')}else{console.log('No circular dependencies')}\"",
+    "check:circular": "madge --circular --extensions ts src/ --json | node -e \"const c=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); const n=c.length; if(n>7){console.error('New circular deps found ('+n+' > 7 known type-only/dynamic cycles)');process.exit(1)}else if(n>0){console.log(n+' known type-only/dynamic cycles (safe)')}else{console.log('No circular dependencies')}\"",
     "check:deps": "depcheck --ignores='@diagrammo/dgmo,@codemirror/language,@lezer/*,husky,lint-staged,tsup,axe-core,type-coverage'",
     "check:security": "pnpm audit --prod",
     "check:publish": "publint",
     "check:size": "pnpm build && du -sh dist/ && echo '---' && ls -lh dist/*.js dist/*.cjs",
     "check:types": "attw --pack . --ignore-rules no-resolution false-export-default",
-    "postinstall": "node -e \"console.log('\\n💡 Claude Code user? Run: dgmo --install-claude-skill\\n')\"",
+    "postinstall": "node -e \"console.log('\\n💡 Claude Code user? Run: dgmo install claude-code\\n')\"",
     "prepare": "husky"
   },
   "dependencies": {

package/src/advanced.ts

@@ -797,15 +797,3 @@ export { themes, type Theme } from './themes';
 
 // Public-API alias for parseDgmo (also exported from the public root as `validate`)
 export { parseDgmo as validate } from './dgmo-router';
-
-// `dgmo migrate` — programmatic access to the 0.18.0 legacy `|` → §1.4
-// migration. Consumed by `@diagrammo/dgmo-mcp`'s `migrate_diagram` tool
-// and by external authoring tools that want to offer in-place migration.
-export {
-  migrateContent,
-  formatLineDiff,
-  isLegacyMetadataLine,
-  findUnsafePipePositions,
-  transformLine,
-} from './migrate';
-export type { ContentMigration, TransformResult } from './migrate';

package/src/boxes-and-lines/label-placement.ts

@@ -0,0 +1,339 @@
+// ============================================================
+// Boxes and Lines Diagram — Edge label placement
+// ============================================================
+//
+// Makes edge/arrow labels legible regardless of length or layout via a priority
+// ladder (each step only fires when the previous can't make the label legible):
+//
+//   1. WRAP   — cap label width and wrap onto up to MAX_LABEL_LINES lines.
+//   2. MOVE   — if the wrapped box still overlaps a node box, slide it to a clear
+//               spot near its own line (along the polyline, then a small
+//               perpendicular offset), staying proximal. No leader line.
+//   3. RELAYOUT (last resort, owned by layout.ts) — re-run the search reserving
+//               dagre label space so a gap opens; this module only reports which
+//               labels stayed unresolved so the caller can decide to escalate.
+//
+// Placement runs in layout (not the renderer) so it sees node/group boxes and so
+// the relayout decision can re-invoke the search. The renderer is a pure consumer
+// of the labelX/labelY/labelWidth/labelHeight/labelLines fields written here.
+
+import type { BLLayoutResult } from './layout';
+import {
+  measureText,
+  wrapTextToWidth,
+  truncateText,
+} from '../utils/text-measure';
+
+// Keep in sync with EDGE_LABEL_FONT_SIZE in renderer.ts (ScaleContext is identity
+// there, so layout-space px == screen px for the unscaled diagram coords).
+export const EDGE_LABEL_FONT_SIZE = 11;
+
+const LABEL_MAX_WIDTH = 160; // ≈ DESC_NODE_WIDTH + slack; flat (not canvas-relative)
+const MAX_LABEL_LINES = 3;
+const LABEL_LINE_HEIGHT = 1.3;
+const H_PAD = 6; // horizontal halo padding (each side)
+const V_PAD = 3; // vertical halo padding (each side)
+const BOX_CLEAR_PAD = 4; // min clearance kept between a label box and a node box
+const PERP_STEP = 8; // perpendicular offset increment (px)
+const PERP_MAX = 40; // max perpendicular offset before giving up
+const SLIDE_SAMPLES = 9; // arc-length samples per side when sliding along the edge
+
+type Pt = { readonly x: number; readonly y: number };
+
+interface Rect {
+  readonly minX: number;
+  readonly minY: number;
+  readonly maxX: number;
+  readonly maxY: number;
+}
+
+export interface MeasuredLabel {
+  readonly lines: readonly string[];
+  /** Halo box width, including 2·H_PAD. */
+  readonly width: number;
+  /** Halo box height, including 2·V_PAD. */
+  readonly height: number;
+}
+
+/**
+ * Wrap + measure an edge label into a bounded multi-line box. Long unbreakable
+ * tokens are hard-broken at the char boundary; overflow past MAX_LABEL_LINES is
+ * ellipsized so the box is bounded in both axes.
+ */
+export function measureEdgeLabel(
+  label: string,
+  fontSize: number = EDGE_LABEL_FONT_SIZE,
+  maxWidth: number = LABEL_MAX_WIDTH
+): MeasuredLabel {
+  let lines = wrapTextToWidth(label, fontSize, maxWidth, { hardBreak: true });
+  if (lines.length > MAX_LABEL_LINES) {
+    const kept = lines.slice(0, MAX_LABEL_LINES - 1);
+    const rest = lines.slice(MAX_LABEL_LINES - 1).join(' ');
+    kept.push(truncateText(rest, fontSize, maxWidth));
+    lines = kept;
+  }
+  let textW = 0;
+  for (const ln of lines) {
+    const w = measureText(ln, fontSize);
+    if (w > textW) textW = w;
+  }
+  return {
+    lines,
+    width: textW + 2 * H_PAD,
+    height: lines.length * fontSize * LABEL_LINE_HEIGHT + 2 * V_PAD,
+  };
+}
+
+/** Point at the half-way arc length along an edge polyline — the geometric
+ *  centre of the connector, so a label seeds in the gap BETWEEN the two nodes
+ *  rather than drifting under the target. Degenerate point lists fall back. */
+export function edgePolylineMidpoint(points: ReadonlyArray<Pt>): Pt {
+  return pointAtArcFraction(points, 0.5).p;
+}
+
+/** Position + unit normal at arc-length fraction t∈[0,1] of a polyline. The
+ *  normal is perpendicular to the local segment (for proximal perp offsets). */
+function pointAtArcFraction(
+  points: ReadonlyArray<Pt>,
+  t: number
+): { p: Pt; nx: number; ny: number } {
+  if (points.length === 0) return { p: { x: 0, y: 0 }, nx: 0, ny: 1 };
+  if (points.length === 1)
+    return { p: { x: points[0]!.x, y: points[0]!.y }, nx: 0, ny: 1 };
+  const segLen: number[] = [];
+  let total = 0;
+  for (let k = 1; k < points.length; k++) {
+    const len = Math.hypot(
+      points[k]!.x - points[k - 1]!.x,
+      points[k]!.y - points[k - 1]!.y
+    );
+    segLen.push(len);
+    total += len;
+  }
+  let want = total * Math.max(0, Math.min(1, t));
+  for (let k = 1; k < points.length; k++) {
+    const len = segLen[k - 1]!;
+    if (want <= len || k === points.length - 1) {
+      const f = len === 0 ? 0 : Math.min(1, want / len);
+      const ax = points[k - 1]!.x;
+      const ay = points[k - 1]!.y;
+      const bx = points[k]!.x;
+      const by = points[k]!.y;
+      const dx = bx - ax;
+      const dy = by - ay;
+      const dlen = Math.hypot(dx, dy) || 1;
+      // Unit normal = perpendicular to the local tangent.
+      return {
+        p: { x: ax + dx * f, y: ay + dy * f },
+        nx: -dy / dlen,
+        ny: dx / dlen,
+      };
+    }
+    want -= len;
+  }
+  const last = points[points.length - 1]!;
+  return { p: { x: last.x, y: last.y }, nx: 0, ny: 1 };
+}
+
+function rectFromCenter(cx: number, cy: number, w: number, h: number): Rect {
+  return {
+    minX: cx - w / 2,
+    minY: cy - h / 2,
+    maxX: cx + w / 2,
+    maxY: cy + h / 2,
+  };
+}
+
+/** Does a label box centred at (cx,cy) overlap any obstacle (within pad)? */
+function overlapsAny(
+  cx: number,
+  cy: number,
+  w: number,
+  h: number,
+  obstacles: readonly Rect[],
+  pad: number
+): boolean {
+  const minX = cx - w / 2 - pad;
+  const minY = cy - h / 2 - pad;
+  const maxX = cx + w / 2 + pad;
+  const maxY = cy + h / 2 + pad;
+  for (const o of obstacles) {
+    if (minX < o.maxX && maxX > o.minX && minY < o.maxY && maxY > o.minY)
+      return true;
+  }
+  return false;
+}
+
+/** Arc-length fractions sampled centre-outward (keeps the label proximal to the
+ *  true midpoint), clamped away from the endpoints. */
+function slideFractions(): number[] {
+  const out = [0.5];
+  for (let k = 1; k <= SLIDE_SAMPLES; k++) {
+    const off = k * 0.08;
+    if (0.5 - off >= 0.12) out.push(0.5 - off);
+    if (0.5 + off <= 0.88) out.push(0.5 + off);
+  }
+  return out;
+}
+
+/** Find the nearest clear centre for a label box of (w,h) along/near `points`.
+ *  Pass 1 slides along the line; pass 2 offsets perpendicular. null = no clear
+ *  spot found within the proximity budget. */
+function findClearPosition(
+  w: number,
+  h: number,
+  points: ReadonlyArray<Pt>,
+  obstacles: readonly Rect[]
+): Pt | null {
+  const ts = slideFractions();
+  for (const t of ts) {
+    const { p } = pointAtArcFraction(points, t);
+    if (!overlapsAny(p.x, p.y, w, h, obstacles, BOX_CLEAR_PAD)) return p;
+  }
+  for (let mag = PERP_STEP; mag <= PERP_MAX; mag += PERP_STEP) {
+    for (const t of ts) {
+      const { p, nx, ny } = pointAtArcFraction(points, t);
+      for (const sign of [-1, 1]) {
+        const x = p.x + nx * mag * sign;
+        const y = p.y + ny * mag * sign;
+        if (!overlapsAny(x, y, w, h, obstacles, BOX_CLEAR_PAD)) return { x, y };
+      }
+    }
+  }
+  return null;
+}
+
+interface LabelBox {
+  edgeIdx: number;
+  cx: number;
+  cy: number;
+  w: number;
+  h: number;
+  lines: readonly string[];
+  resolved: boolean;
+}
+
+/** Separate overlapping label boxes vertically (variable sizes), mirroring the
+ *  old renderer pass. Runs after node-collision resolution; the caller re-checks
+ *  node overlap afterwards. */
+function resolveLabelOverlaps(boxes: LabelBox[]): void {
+  const MAX_PASSES = 8;
+  const PAD = 4;
+  for (let pass = 0; pass < MAX_PASSES; pass++) {
+    let moved = false;
+    for (let i = 0; i < boxes.length; i++) {
+      for (let j = i + 1; j < boxes.length; j++) {
+        const a = boxes[i]!;
+        const b = boxes[j]!;
+        const dx = Math.abs(a.cx - b.cx);
+        const dy = Math.abs(a.cy - b.cy);
+        const overlapX = (a.w + b.w) / 2 + PAD - dx;
+        const overlapY = (a.h + b.h) / 2 + PAD - dy;
+        if (overlapX > 0 && overlapY > 0) {
+          const shift = overlapY / 2 + 1;
+          if (a.cy < b.cy) {
+            a.cy -= shift;
+            b.cy += shift;
+          } else {
+            a.cy += shift;
+            b.cy -= shift;
+          }
+          moved = true;
+        }
+      }
+    }
+    if (!moved) break;
+  }
+}
+
+export interface PlaceEdgeLabelsResult {
+  readonly layout: BLLayoutResult;
+  /** Edge indices whose label still overlaps a node box (escalate to relayout). */
+  readonly unresolved: number[];
+}
+
+/**
+ * Wrap, then collision-resolve every edge label against node boxes (steps 1–2),
+ * writing labelX/labelY/labelWidth/labelHeight/labelLines onto each edge. Returns
+ * the edge indices that could not be cleared so the caller can trigger a
+ * last-resort relayout.
+ */
+export function placeEdgeLabels(
+  layout: BLLayoutResult,
+  opts?: { fontSize?: number; maxWidth?: number }
+): PlaceEdgeLabelsResult {
+  const fontSize = opts?.fontSize ?? EDGE_LABEL_FONT_SIZE;
+  const maxWidth = opts?.maxWidth ?? LABEL_MAX_WIDTH;
+
+  // Obstacles = real node boxes + collapsed groups (drawn as boxes). Expanded
+  // groups are containers — their interior is valid label space, so they are NOT
+  // obstacles.
+  const obstacles: Rect[] = [];
+  for (const n of layout.nodes)
+    obstacles.push(rectFromCenter(n.x, n.y, n.width, n.height));
+  for (const g of layout.groups)
+    if (g.collapsed)
+      obstacles.push(rectFromCenter(g.x, g.y, g.width, g.height));
+
+  const boxes: LabelBox[] = [];
+  layout.edges.forEach((e, idx) => {
+    if (!e.label || e.points.length < 2) return;
+    const m = measureEdgeLabel(e.label, fontSize, maxWidth);
+    const mid = edgePolylineMidpoint(e.points);
+    let cy = mid.y;
+    // Fold in the parallel-edge fan offset so each line's label clears its line.
+    if (e.parallelCount > 1 && e.yOffset !== 0)
+      cy += (e.yOffset < 0 ? -1 : 1) * (m.height / 2);
+    boxes.push({
+      edgeIdx: idx,
+      cx: mid.x,
+      cy,
+      w: m.width,
+      h: m.height,
+      lines: m.lines,
+      resolved: true,
+    });
+  });
+
+  // Step 2: reposition any box that overlaps a node.
+  for (const box of boxes) {
+    if (!overlapsAny(box.cx, box.cy, box.w, box.h, obstacles, BOX_CLEAR_PAD))
+      continue;
+    const e = layout.edges[box.edgeIdx]!;
+    const clear = findClearPosition(box.w, box.h, e.points, obstacles);
+    if (clear) {
+      box.cx = clear.x;
+      box.cy = clear.y;
+    } else {
+      box.resolved = false;
+    }
+  }
+
+  // Separate stacked labels, then re-check node overlap (a vertical nudge can
+  // push a label back onto a box — that becomes an unresolved escalation).
+  resolveLabelOverlaps(boxes);
+  for (const box of boxes) {
+    if (overlapsAny(box.cx, box.cy, box.w, box.h, obstacles, BOX_CLEAR_PAD))
+      box.resolved = false;
+  }
+
+  const boxByIdx = new Map<number, LabelBox>();
+  for (const b of boxes) boxByIdx.set(b.edgeIdx, b);
+  const edges = layout.edges.map((e, idx) => {
+    const b = boxByIdx.get(idx);
+    if (!b) return e;
+    return {
+      ...e,
+      labelX: b.cx,
+      labelY: b.cy,
+      labelWidth: b.w,
+      labelHeight: b.h,
+      labelLines: b.lines,
+    };
+  });
+
+  return {
+    layout: { ...layout, edges },
+    unresolved: boxes.filter((b) => !b.resolved).map((b) => b.edgeIdx),
+  };
+}

package/src/boxes-and-lines/layout-search.ts

@@ -23,6 +23,7 @@ import {
 } from './layout';
 import { layeredCandidates } from './layout-layered';
 import { groupedTierCandidates } from './layout-grouped';
+import { measureEdgeLabel, EDGE_LABEL_FONT_SIZE } from './label-placement';
 
 type Pt = { x: number; y: number };
 
@@ -917,9 +918,14 @@ export async function layoutBoxesAndLinesSearch(
      *  indicator. Omit it (CLI/export) and the search runs straight through with
      *  no added latency. */
     onProgress?: (done: number, total: number, phase: string) => void;
+    /** Last-resort label legibility: reserve dagre label space for every labeled
+     *  edge so the layout opens a gap wide enough for the (wrapped) label. Only
+     *  set by layout.ts when steps 1–2 left a label overlapping a node box. */
+    reserveEdgeLabels?: boolean;
   }
 ): Promise<BLLayoutResult> {
   const hideDescriptions = opts?.hideDescriptions ?? false;
+  const reserveEdgeLabels = opts?.reserveEdgeLabels ?? false;
   const onProgress = opts?.onProgress;
   // Yield to a macrotask (lets the browser repaint between heavy placements);
   // no-op when there's no progress observer so non-interactive callers pay
@@ -1323,8 +1329,16 @@ export async function layoutBoxesAndLinesSearch(
     for (const e of ord(parsed.edges)) {
       const s = srcRep(e.source);
       const t = tgtRep(e.target);
-      if (s !== t && g.hasNode(s) && g.hasNode(t))
-        g.setEdge(s, t, {}, edgeKey(e));
+      if (s !== t && g.hasNode(s) && g.hasNode(t)) {
+        // Last-resort label legibility: reserve a virtual label node on the edge
+        // so dagre widens the rank gap to fit the (wrapped) label.
+        let edgeLabel: object = {};
+        if (reserveEdgeLabels && e.label) {
+          const m = measureEdgeLabel(e.label, EDGE_LABEL_FONT_SIZE);
+          edgeLabel = { width: m.width, height: m.height, labelpos: 'c' };
+        }
+        g.setEdge(s, t, edgeLabel, edgeKey(e));
+      }
     }
     dagre.layout(g);
 

package/src/boxes-and-lines/layout.ts

@@ -9,6 +9,7 @@
 
 import type { ParsedBoxesAndLines, BLNode, BLGroup } from './types';
 import { measureText, wrapTextToWidth } from '../utils/text-measure';
+import { placeEdgeLabels } from './label-placement';
 import {
   resolveNotes,
   buildPlacedNotes,
@@ -58,8 +59,14 @@ export interface BLLayoutEdge {
   readonly bidirectional: boolean;
   readonly lineNumber: number;
   readonly points: ReadonlyArray<{ readonly x: number; readonly y: number }>;
+  /** Centre of the label box (set by label-placement). */
   readonly labelX?: number;
   readonly labelY?: number;
+  /** Wrapped label box dimensions + lines (set by label-placement; the renderer
+   *  draws the halo + tspans straight from these). */
+  readonly labelWidth?: number;
+  readonly labelHeight?: number;
+  readonly labelLines?: readonly string[];
   readonly yOffset: number;
   readonly parallelCount: number;
   readonly metadata: Readonly<Record<string, string>>;
@@ -205,7 +212,7 @@ export async function layoutBoxesAndLines(
   }
 ): Promise<BLLayoutResult> {
   const { layoutBoxesAndLinesSearch } = await import('./layout-search');
-  const searched = await layoutBoxesAndLinesSearch(parsed, collapseInfo, {
+  const searchOpts = {
     ...(layoutOptions?.hideDescriptions !== undefined && {
       hideDescriptions: layoutOptions.hideDescriptions,
     }),
@@ -215,14 +222,31 @@ export async function layoutBoxesAndLines(
     ...(layoutOptions?.onProgress !== undefined && {
       onProgress: layoutOptions.onProgress,
     }),
-  });
-  // Engine-agnostic post-processing: fan parallel edges, then float notes
-  // (and shift the canvas to fit them).
-  return attachNotes(
-    applyParallelEdgeOffsets(searched),
+  };
+  const searched = await layoutBoxesAndLinesSearch(
     parsed,
-    layoutOptions?.collapsedNotes
+    collapseInfo,
+    searchOpts
   );
+
+  // Edge-label legibility (priority ladder): wrap + reposition labels on the
+  // chosen layout. If any label still can't clear a node box, escalate ONCE to a
+  // label-aware relayout that reserves dagre label space so a gap opens — and
+  // keep it only if it actually resolves more labels.
+  let placed = placeEdgeLabels(applyParallelEdgeOffsets(searched));
+  if (placed.unresolved.length > 0) {
+    const relaid = await layoutBoxesAndLinesSearch(parsed, collapseInfo, {
+      ...searchOpts,
+      reserveEdgeLabels: true,
+    });
+    const relaidPlaced = placeEdgeLabels(applyParallelEdgeOffsets(relaid));
+    if (relaidPlaced.unresolved.length < placed.unresolved.length)
+      placed = relaidPlaced;
+  }
+
+  // Engine-agnostic post-processing: float notes (and shift the canvas to fit
+  // them) on the label-placed layout.
+  return attachNotes(placed.layout, parsed, layoutOptions?.collapsedNotes);
 }
 
 /**
@@ -312,6 +336,7 @@ function attachNotes(
         points: e.points.map((pt) => ({ x: pt.x + shiftX, y: pt.y + shiftY })),
         ...(e.labelX !== undefined && { labelX: e.labelX + shiftX }),
         ...(e.labelY !== undefined && { labelY: e.labelY + shiftY }),
+        // labelWidth/labelHeight/labelLines are shift-invariant — carried via spread.
       }))
     : layout.edges;
   const finalGroups = shifted