@yassimba/pi-loom-mermaid 0.4.0 → 0.5.0

package/README.md

@@ -1,28 +1,66 @@
 # pi-loom-mermaid
 
-Draws Mermaid blocks in Pi as Unicode terminal diagrams. Colored borders, hops where edges cross, and fewer stacked rails than Pi's built-in renderer or pi-lovely-mermaid. It also adds a short system prompt so the agent can answer in diagrams when that is clearer than prose.
+Show diagrams directly in Pi, with colored boxes, a clearer layout, and connecting lines that are easier to follow.
 
-Same diagram:
+This extension draws diagrams written in Mermaid, a text format for describing boxes, arrows, and other shapes. It also asks the agent to use diagrams when they explain something more clearly than text.
 
-Pi built-in. One gray box style. Edges share long outer rails.
+## Install
 
-<p align="center">
-  <img src="../../assets/mermaid-pi-builtin.png" alt="Pi built-in Mermaid: gray boxes and stacked outer edges">
-</p>
+Requires Pi and Node.js 22.6 or newer.
+
+1. Install the package:
+
+   ```bash
+   pi install npm:@yassimba/pi-loom-mermaid
+   ```
+
+2. Set `markdown.mermaid` to `"off"` in `~/.pi/agent/settings.json`. Merge this into your existing settings; do not replace the file:
+
+   ```json
+   {
+     "markdown": {
+       "mermaid": "off"
+     }
+   }
+   ```
+
+   This turns off Pi’s own diagram drawing so this extension can draw instead. If you have another Mermaid extension installed, disable it with `pi config`.
+
+3. Run `/reload` in Pi.
+
+## Usage
+
+Ask Pi: “Explain this code with a Mermaid diagram.” Pi draws the diagram in the conversation.
+
+You can also paste the example below. Keep the opening line of three backticks followed by `mermaid`, and the closing line of three backticks.
+
+To show changes, add `:::red` after a box for removed code, `:::orange` for changed code, or `:::green` for added code. These labels give boxes muted colored borders. Text and backgrounds keep your Pi theme’s colors. The `classDef` lines in the example set custom border colors.
+
+If a diagram is too wide, Pi shows its code instead. Widen the terminal or ask Pi to split it into smaller diagrams.
+
+## The same diagram in Pi and GitHub
+
+All three views below use the same Mermaid code.
+
+### Pi built-in
 
-pi-lovely-mermaid. Color, still long parallel paths around the right side.
+Gray boxes. Connecting lines take long paths around the outside.
 
 <p align="center">
-  <img src="../../assets/mermaid-lovely.png" alt="pi-lovely-mermaid: colored borders with long parallel edges">
+  <img src="https://raw.githubusercontent.com/Yassimba/loom/main/assets/mermaid-pi-builtin.png" alt="Pi built-in Mermaid: gray boxes with long connecting lines around the outside">
 </p>
 
-This package. The same colors, plus crossing hops and shorter routes.
+### pi-loom-mermaid
+
+Colored boxes and shorter connecting lines. Small bends mark where lines cross.
 
 <p align="center">
-  <img src="../../assets/mermaid-pi-loom.png" alt="pi-loom-mermaid: colored borders, crossing hops, and shorter routes">
+  <img src="https://raw.githubusercontent.com/Yassimba/loom/main/assets/mermaid-pi-loom.png" alt="pi-loom-mermaid: colored boxes, shorter connecting lines, and bends at crossings">
 </p>
 
-GitHub draws the next blocks with its own Mermaid. Paste the same source into Pi (built-in vs this package) to compare routing and color.
+### GitHub built-in
+
+GitHub draws the code below as a diagram. Copy the code into Pi to compare how it looks.
 
 ```mermaid
 flowchart TD
@@ -59,103 +97,26 @@ flowchart TD
     classDef green stroke:#4f8560
 ```
 
-Stress cases: complex diagrams rendered by both engines.
-
-**State — Pi built-in**
-
-<p align="center">
-  <img src="../../assets/mermaid-state-pi.png" alt="Pi built-in state diagram">
-</p>
-
-**State — pi-loom-mermaid**
-
-<p align="center">
-  <img src="../../assets/mermaid-state-loom.png" alt="pi-loom-mermaid state diagram">
-</p>
-
-**ER — Pi built-in**
-
-<p align="center">
-  <img src="../../assets/mermaid-er-pi.png" alt="Pi built-in ER diagram">
-</p>
-
-**ER — pi-loom-mermaid**
-
-<p align="center">
-  <img src="../../assets/mermaid-er-loom.png" alt="pi-loom-mermaid ER diagram">
-</p>
-
-**Sequence — Pi built-in**
-
-<p align="center">
-  <img src="../../assets/mermaid-sequence-pi.png" alt="Pi built-in sequence diagram">
-</p>
-
-**Sequence — pi-loom-mermaid**
-
-<p align="center">
-  <img src="../../assets/mermaid-sequence-loom.png" alt="pi-loom-mermaid sequence diagram">
-</p>
-
-**Dense class graph — Pi built-in**
+## Update or remove
 
-<p align="center">
-  <img src="../../assets/mermaid-class-pi.png" alt="Pi built-in dense class diagram">
-</p>
-
-**Dense class graph — pi-loom-mermaid**
-
-<p align="center">
-  <img src="../../assets/mermaid-class-loom.png" alt="pi-loom-mermaid dense class diagram">
-</p>
-
-**Dense flowchart — Pi built-in**
-
-<p align="center">
-  <img src="../../assets/mermaid-dense-pi.png" alt="Pi built-in dense flowchart">
-</p>
-
-**Dense flowchart — pi-loom-mermaid**
-
-<p align="center">
-  <img src="../../assets/mermaid-dense-loom.png" alt="pi-loom-mermaid dense flowchart">
-</p>
-
-## Install
-
-From Loom setup, or:
+Update the package, then run `/reload`:
 
 ```bash
-pi install npm:@yassimba/pi-loom-mermaid
+pi update npm:@yassimba/pi-loom-mermaid
 ```
 
-Turn off Pi's built-in Mermaid transformer so this extension gets the original source. In `~/.pi/agent/settings.json`:
+To uninstall:
 
-```json
-{
-  "markdown": {
-    "mermaid": "off"
-  }
-}
+```bash
+pi remove npm:@yassimba/pi-loom-mermaid
 ```
 
-Then run `/reload` in Pi.
-
-## Usage
-
-Mark diff nodes with the built-in `red`, `orange`, and `green` classes:
+Delete the `"mermaid": "off"` setting you added to restore Pi’s own diagram drawing, then run `/reload`.
 
-```mermaid
-flowchart LR
-  A[Removed]:::red --> B[Changed]:::orange --> C[Added]:::green
-```
+## Contributing
 
-Those classes color and dim only the box border. Fill and text stay on Pi's theme. A `classDef` in the diagram overrides a built-in class or adds other colors.
-
-Diagrams wider than the terminal stay as Mermaid source.
+From the [Loom repository](https://github.com/Yassimba/loom) root, run `npm ci`, `npm run check`, and `npm run audit` before opening a pull request.
 
 ## License
 
-[MIT](LICENSE)
-
-pi-loom-mermaid is adapted from pi-lovely-mermaid.
+[MIT](LICENSE). Adapted from pi-lovely-mermaid.

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@yassimba/pi-loom-mermaid",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Loom's advanced Mermaid renderer for Pi, with better routing and color.",
   "license": "MIT",
   "type": "module",
   "engines": {
     "node": ">=22.6"
   },
+  "bin": {
+    "loom-mermaid-render": "./src/cli.ts"
+  },
   "keywords": [
     "pi-package",
     "pi",

package/src/cli.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env -S node --experimental-strip-types
+
+import { transformMermaidForDocument } from "./index.ts";
+
+let markdown = "";
+for await (const chunk of process.stdin) markdown += chunk;
+
+const width = Number.parseInt(process.env.LOOM_MERMAID_WIDTH ?? "100", 10);
+process.stdout.write(transformMermaidForDocument(markdown, Number.isFinite(width) ? width : 100));

package/src/index.ts

@@ -85,6 +85,24 @@ function codeSpan(line: string): string {
   return `${fence}${padding}${content}${padding}${fence}`;
 }
 
+export function transformMermaidForDocument(markdown: string, availableWidth = 100): string {
+  return markdownParser
+    .lexer(markdown)
+    .map((token) => {
+      if (!isMermaid(token)) return token.raw;
+      const art = render(withDiffClasses(token.text).source, { maxWidth: availableWidth });
+      if (!art || art.width > availableWidth) return token.raw;
+      const text = art.plain.join("\n");
+      const longestRun = Math.max(
+        0,
+        ...Array.from(text.matchAll(/`+/g), (match) => match[0].length),
+      );
+      const fence = "`".repeat(Math.max(3, longestRun + 1));
+      return `${fence}\n${text}\n${fence}\n`;
+    })
+    .join("");
+}
+
 export function transformMermaidMarkdown(markdown: string, context: TransformContext): string {
   if (context.messageType === "assistant-thinking") return markdown;
 

package/src/loom-mermaid/diagrams/architecture.ts

@@ -1,12 +1,11 @@
 /**
  * `architecture-beta`: services and junctions inside nested groups.
  *
- * Architecture's cardinal ports choose exact SVG attachment points. The
- * terminal graph router already chooses reachable box sides, so this parser
- * preserves endpoints and arrowheads while leaving port placement to it.
+ * Built-in icons use stable Unicode stand-ins; custom Iconify names remain
+ * visible as text because a terminal cannot draw their SVGs.
  */
 
-import { Graph, MAX_GROUP_DEPTH, MAX_GROUPS } from '../graph.ts'
+import { Graph, MAX_GROUP_DEPTH, MAX_GROUPS, type PortSide } from '../graph.ts'
 import { cleanLabel } from '../labels.ts'
 import { layoutFlowchart, layoutGrouped } from '../graph-render.ts'
 import type { Diagram } from '../registry.ts'
@@ -27,6 +26,14 @@ export const architecture: Diagram = {
 const DECLARATION = /^(group|service)\s+([^\s()[\]:{}]+)\(([^)]*)\)\[([^\]]*)\](?:\s+in\s+([^\s]+))?$/i
 const JUNCTION = /^junction\s+([^\s:{}]+)(?:\s+in\s+([^\s]+))?$/i
 const EDGE = /^([^\s:{}]+)(?:\{group\})?:([TBLR])\s*(<)?--(>)?\s*([TBLR]):([^\s:{}]+)(?:\{group\})?$/i
+const SIDES: Record<string, PortSide> = { T: 'top', B: 'bottom', L: 'left', R: 'right' }
+const ICONS: Record<string, string> = {
+  cloud: '☁',
+  database: '◉',
+  disk: '▰',
+  internet: '◎',
+  server: '▣',
+}
 
 function parseArchitecture(src: string): Graph | null {
   const statements = statementsOf(src)
@@ -43,7 +50,7 @@ function parseArchitecture(src: string): Graph | null {
     const edge = st.match(EDGE)
 
     if (declaration) {
-      const [, kind, id, , rawLabel, parentId] = declaration
+      const [, kind, id, icon, rawLabel, parentId] = declaration
       const parent = parentId === undefined ? null : groupIndex.get(parentId)
       if (parentId !== undefined && parent === undefined) {
         graph.drop(st)
@@ -57,10 +64,10 @@ function parseArchitecture(src: string): Graph | null {
           graph.truncated ??= `subgraph cap (${MAX_GROUPS} groups, depth ${MAX_GROUP_DEPTH}) reached`
         } else {
           groupIndex.set(id, graph.groups.length)
-          graph.groups.push({ id, label: cleanLabel(rawLabel) || id, parent: parent ?? null })
+          graph.groups.push({ id, label: iconLabel(icon, rawLabel || id), parent: parent ?? null })
         }
       } else {
-        addNode(graph, id, cleanLabel(rawLabel) || id, parent ?? null, 'rect')
+        addNode(graph, id, iconLabel(icon, rawLabel || id), parent ?? null, 'rect')
       }
     } else if (junction) {
       const [, id, parentId] = junction
@@ -68,7 +75,7 @@ function parseArchitecture(src: string): Graph | null {
       if (parentId !== undefined && parent === undefined) graph.drop(st)
       else addNode(graph, id, '•', parent ?? null, 'round')
     } else if (edge) {
-      const [, fromId, , leftArrow, rightArrow, , toId] = edge
+      const [, fromId, fromPort, leftArrow, rightArrow, toPort, toId] = edge
       const from = graph.index.get(fromId)
       const to = graph.index.get(toId)
       if (from === undefined || to === undefined) {
@@ -81,6 +88,8 @@ function parseArchitecture(src: string): Graph | null {
           headFrom: leftArrow ? 'arrow' : 'none',
           headTo: rightArrow ? 'arrow' : 'none',
           line: 'solid',
+          fromSide: SIDES[fromPort.toUpperCase()],
+          toSide: SIDES[toPort.toUpperCase()],
         })
       }
     } else if (firstWord(st).toLowerCase() !== 'title') {
@@ -96,6 +105,12 @@ function parseArchitecture(src: string): Graph | null {
   return graph.nodes.length === 0 ? null : graph
 }
 
+function iconLabel(icon: string, rawLabel: string): string {
+  const name = cleanLabel(icon)
+  const mark = ICONS[name.toLowerCase()] ?? `[${name.split(':').at(-1)}]`
+  return `${mark} ${cleanLabel(rawLabel)}`
+}
+
 function addNode(
   graph: Graph,
   id: string,

package/src/loom-mermaid/diagrams/flowchart.ts

@@ -16,7 +16,7 @@ import {
   parseDir,
   type Shape,
 } from '../graph.ts'
-import { asciiLower, cleanLabel, decodeHtmlEntities, isIdChar } from '../labels.ts'
+import { asciiLower, cleanLabel, decodeHtmlEntities, isIdChar, type Limits } from '../labels.ts'
 import { layoutFlowchart, layoutGrouped } from '../graph-render.ts'
 import type { Diagram } from '../registry.ts'
 import {
@@ -35,21 +35,42 @@ import {
 export const flowchart: Diagram = {
   kind: 'flowchart',
   headers: ['graph', 'flowchart'],
-  render(src, limits) {
-    const graph = parseGraph(src)
-    if (graph === null) return null
-    const canvas = graph.groups.length === 0 ? layoutFlowchart(graph, limits) : layoutGrouped(graph, limits)
-    if (canvas === null) return null
-    return { canvas, warnings: graph.warnings, classDefs: graph.classDefs }
-  },
+  render: renderGraph,
+  renderDown: (src, limits) => renderGraph(src, limits, true),
 }
 
-function parseGraph(src: string): Graph | null {
+function renderGraph(src: string, limits: Limits, fallbackDown = false) {
+  const graph = parseGraph(src, fallbackDown)
+  if (graph === null) return null
+  if (fallbackDown && graph.groups.length > 0) {
+    // TD attaches cross-scope edges to frames, losing member anchors and
+    // potentially merging distinct edges. Only retry when none need those anchors.
+    const scopes = [...graph.nodeGroup]
+    const groupNodes = new Set<number>()
+    for (const group of graph.groups) {
+      const node = graph.index.get(group.id)
+      if (node === undefined) continue
+      groupNodes.add(node)
+      scopes[node] = group.parent
+    }
+    if (graph.edges.some((e) => scopes[e.from] !== scopes[e.to] &&
+      (!groupNodes.has(e.from) || !groupNodes.has(e.to)))) return null
+  }
+  const canvas = graph.groups.length === 0 ? layoutFlowchart(graph, limits) : layoutGrouped(graph, limits)
+  if (canvas === null) return null
+  return { canvas, warnings: graph.warnings, classDefs: graph.classDefs }
+}
+
+function parseGraph(src: string, fallbackDown: boolean): Graph | null {
   const statements = statementsOf(src)
   const kind = headerKind(statements)
   if (kind === null || !flowchart.headers.includes(kind)) return null
 
   const graph = new Graph(parseDir(words(statements[0])[1] ?? 'TB'))
+  if (fallbackDown) {
+    if (graph.dir !== 'right') return null
+    graph.dir = 'down'
+  }
   const stack: number[] = []
   /** `class A,B name` assignments, applied after the walk so a statement may
    * precede the nodes it names. Unknown ids are ignored. */
@@ -91,9 +112,12 @@ function parseGraph(src: string): Graph | null {
         if (target) hrefs.push(target)
         continue
       }
+      case 'direction':
+        // Nested directions are not modelled yet; do not reorient an explicit scope.
+        if (fallbackDown && stack.length > 0) return null
+        continue
       case 'style':
       case 'linkstyle':
-      case 'direction':
         continue
       default:
         break

package/src/loom-mermaid/graph-render.ts

@@ -255,6 +255,8 @@ function buildScope(
       headTo: e.headTo,
       headFrom: e.headFrom,
       line: e.line,
+      fromSide: e.fromSide,
+      toSide: e.toSide,
       fromAnchor: anchorOf(f, e.from),
       toAnchor: anchorOf(t, e.to),
     }

package/src/loom-mermaid/graph.ts

@@ -26,6 +26,7 @@ export type Head =
   | 'diamondOpen'
 
 export type LineKind = 'solid' | 'dotted' | 'thick'
+export type PortSide = 'top' | 'bottom' | 'left' | 'right'
 
 type Dir = 'down' | 'up' | 'right' | 'left'
 
@@ -66,6 +67,9 @@ export interface Edge {
   headTo: Head
   headFrom: Head
   line: LineKind
+  /** Exact attachment sides requested by diagrams such as `architecture-beta`. */
+  fromSide?: PortSide
+  toSide?: PortSide
   /**
    * Set on an end that stands for a subgraph frame: the inner node the
    * author actually named, as a box in the frame's sub-canvas coordinates.

package/src/loom-mermaid/index.ts

@@ -20,8 +20,11 @@ export type { MermaidArt, Role, Span } from './types.ts'
  *
  * The diagram is laid out at whatever size it needs; `art.width` reports the
  * columns that turned out to be. Given `maxWidth`, a diagram wider than that
- * is laid out again with progressively tighter label limits and the first
- * fit is returned. Deciding what to do when even the tightest exceeds the
+ * is laid out again with progressively tighter label limits. LR flowcharts
+ * without explicit group directions or cross-scope member edges then retry
+ * top-down before collapsing subgraphs. The first fit is returned; the source
+ * is never rewritten.
+ * Deciding what to do when even the final fallback exceeds the
  * space at hand is the caller's — `sourceBox` is the usual answer:
  *
  * ```ts
@@ -44,18 +47,29 @@ export function render(src: string, options: { maxWidth?: number } = {}): Mermai
   if (src.trim() === '') return null
   const diagram = diagramFor(src)
   if (diagram === null) return null
-  // Too wide for the space given: lay out again with shorter labels and
-  // tighter wrapping, tightest last, and keep the first that fits (else
-  // the tightest, for the caller to judge against `art.width`).
+  // Preserve the requested direction while tightening labels, then try TD
+  // before the existing collapsed fallback. Each attempt parses fresh source.
   let drawn: ReturnType<Diagram['render']> = null
   let art: ReturnType<Canvas['toLines']> = { plain: [], styled: [], width: 0 }
   let collapsed = false
-  for (const limits of LIMITS) {
-    drawn = diagram.render(src, limits)
-    if (drawn === null) return null
-    collapsed = limits.collapse === true
-    art = drawn.canvas.toLines()
-    if (options.maxWidth === undefined || art.width <= options.maxWidth) break
+  fitting: for (const [draw, collapse] of [
+    [diagram.render, false],
+    [diagram.renderDown, false],
+    [diagram.render, true],
+  ] as const) {
+    if (draw === undefined) continue
+    for (const limits of LIMITS) {
+      if ((limits.collapse === true) !== collapse) continue
+      const candidate = draw(src, limits)
+      if (candidate === null) {
+        if (draw === diagram.renderDown) break
+        return null
+      }
+      drawn = candidate
+      collapsed = collapse
+      art = drawn.canvas.toLines()
+      if (options.maxWidth === undefined || art.width <= options.maxWidth) break fitting
+    }
   }
   if (drawn === null) return null
   if (collapsed && /^\s*subgraph\b|^\s*state\s+\S+\s*\{/m.test(src)) {

package/src/loom-mermaid/layout.ts

@@ -11,7 +11,7 @@
  */
 
 import type { Canvas } from './canvas.ts'
-import type { Anchor, Edge, LineKind } from './graph.ts'
+import type { Anchor, Edge, LineKind, PortSide } from './graph.ts'
 import type { Graph } from './graph.ts'
 import { fitLabel, type Limits, wrapLabel } from './labels.ts'
 import { brandesKoepf, type LayeredGraph } from './placement.ts'
@@ -117,7 +117,7 @@ interface Port {
   wanted: number
 }
 
-type Side = 'top' | 'bottom' | 'left' | 'right'
+type Side = PortSide
 
 function framePort(
   sub: Canvas,
@@ -1332,9 +1332,34 @@ function placeTd(
   const boxR = (j: number): number => boxL(j) + sizes.boxW[j] - 1
   const port = (node: number, side: number): number =>
     Math.max(boxL(node) + 1, Math.min(boxR(node) - 1, centers[node] + 2 * side))
+  // An exterior return can clear every intermediate box yet still run
+  // over its wider source. Move a straight, unshared outer chain just
+  // beyond that source so the existing side-port checks can use it. Keep
+  // straight top exits and interior/shared chains in their reserved slots.
+  graph.edges.forEach((e, i) => {
+    const chain = layered.chains[i]
+    if (!isBack(e) || extras[e.from].kind !== 'plain' || chain.length === 0) return
+    const col = centers[chain[0]]
+    const side = Math.sign(col - centers[e.from])
+    if (side === 0 || Math.abs(col - port(e.from, side)) <= 1) return
+    const outer = side < 0 ? 0 : -1
+    if (layered.layers[ranks[e.from]].at(outer) !== e.from) return
+    if (chain.some((v) => centers[v] !== col || layered.shared.has(v) || layered.layers[layerOf[v]].at(outer) !== v)) return
+    const left = centers[e.from] - half(sizes.boxW[e.from])
+    const next = side < 0 ? left - 3 : left + sizes.boxW[e.from] + 2
+    if ((next - col) * side <= 0) return
+    const candidate = [...centers]
+    for (const v of chain) candidate[v] = next
+    const ports = sidePorts(candidate)
+    if (ports.exit[i] !== side) return
+    // Preserve an existing clear target-side entry.
+    const entry = sidePorts(centers).entry[i]
+    if (entry !== 0 && ports.entry[i] !== entry) return
+    centers = candidate
+  })
   // A return entering on the left labels leftward; give the leftmost such
   // label room before the first column.
-  let margin = 0
+  let margin = Math.max(0, -extentsOf(centers)[0])
   graph.edges.forEach((e, i) => {
     const text = edgeText(e)
     if (!isBack(e) || entrySide[i] >= 0 || text === null || chainLabel[i] !== null) return
@@ -1690,7 +1715,9 @@ function placeLr(
     })
   }
   const forward = (e: Edge): boolean => e.from !== e.to && ranks[e.to] > ranks[e.from]
-  let ends = resolve((i) => (forward(graph.edges[i]) ? ['right', 'left'] : null))
+  const requestedSides = (e: Edge): [Side, Side] | null =>
+    e.fromSide !== undefined && e.toSide !== undefined ? [e.fromSide, e.toSide] : null
+  let ends = resolve((i) => requestedSides(graph.edges[i]) ?? (forward(graph.edges[i]) ? ['right', 'left'] : null))
   // A node whose incoming edges all leave their frames at one row off the
   // frame's centre sits that far off its own aligned position, so the
   // edges run straight rather than jog to it (`[*]` after a composite
@@ -1753,6 +1780,8 @@ function placeLr(
   })
   ends = resolve((i) => {
     const e = graph.edges[i]
+    const requested = requestedSides(e)
+    if (requested !== null) return requested
     if (e.from === e.to) return null
     if (ranks[e.to] === ranks[e.from] + 1 || edgeStraight[i]) return ['right', 'left']
     return ranks[e.to] < ranks[e.from] ? ['top', 'top'] : ['bottom', 'bottom']
@@ -1871,14 +1900,40 @@ function placeLr(
     const [from, to] = endsOf(i)
     const through = ends[i].flatMap((p, k) => (p === null ? [] : portAt(p, placed[k === 0 ? edge.from : edge.to]).through))
     const route =
-      to.rank === from.rank + 1
-        ? forwardRouteLr(from, to, edge, bandEnd[from.rank] + 1 + edgeBus[i], max, bundleOf(i) !== undefined)
-        : to.rank > from.rank && edgeStraight[i]
-          ? skipRouteLr(from, to, edge, skipRoute[i], max)
-          : laneRoute(from, to, edge, onTop(i) ? edgeLane[i] : laneBase + edgeLane[i], max, onTop(i), laneEntry(i, from, to))
+      edge.fromSide !== undefined && edge.toSide !== undefined
+        ? portRoute(from, to, edge.fromSide, edge.toSide)
+        : to.rank === from.rank + 1
+          ? forwardRouteLr(from, to, edge, bandEnd[from.rank] + 1 + edgeBus[i], max, bundleOf(i) !== undefined)
+          : to.rank > from.rank && edgeStraight[i]
+            ? skipRouteLr(from, to, edge, skipRoute[i], max)
+            : laneRoute(from, to, edge, onTop(i) ? edgeLane[i] : laneBase + edgeLane[i], max, onTop(i), laneEntry(i, from, to))
     return through.length === 0 ? route : { ...route, through: [...(route.through ?? []), ...through] }
   })
-  return { canvasW, canvasH, routes }
+
+  if (!graph.edges.some((e) => e.fromSide !== undefined)) return { canvasW, canvasH, routes }
+  // Exact side ports may face out of the outermost box. Two cells of margin
+  // keep their first/last segments on-canvas at every nested group level.
+  for (const p of placed) {
+    p.x += 2
+    p.y += 2
+    p.cx += 2
+    p.cy += 2
+  }
+  for (const route of routes) {
+    route.points = route.points.map(([x, y]) => [x + 2, y + 2])
+    route.labels = route.labels.map((label) => ({ ...label, row: label.row + 2, x: label.x + 2 }))
+    if (route.laneLabel !== undefined) {
+      route.laneLabel = {
+        ...route.laneLabel,
+        y: route.laneLabel.y + 2,
+        lo: route.laneLabel.lo + 2,
+        hi: route.laneLabel.hi + 2,
+      }
+    }
+    if (route.through !== undefined)
+      route.through = route.through.map(([x, y, kind]) => [x + 2, y + 2, kind])
+  }
+  return { canvasW: canvasW + 4, canvasH: canvasH + 4, routes }
 }
 
 // -------------------------------------------------------------------- canvas
@@ -2213,6 +2268,50 @@ function chainRoute(
   return { points, labels: chainLabel(edge, headRow, entryX, labelLeft, labelAt, max) }
 }
 
+/** An orthogonal route that leaves and enters the exact requested box sides. */
+function portRoute(from: Placed, to: Placed, fromSide: PortSide, toSide: PortSide): Route {
+  const normal = (side: PortSide): [number, number] =>
+    side === 'left' ? [-1, 0] : side === 'right' ? [1, 0] : side === 'top' ? [0, -1] : [0, 1]
+  const border = (p: Placed, side: PortSide): [number, number] =>
+    side === 'left'
+      ? [p.x, p.cy]
+      : side === 'right'
+        ? [p.x + p.w - 1, p.cy]
+        : side === 'top'
+          ? [p.cx, p.y]
+          : [p.cx, p.y + p.h - 1]
+  const move = ([x, y]: [number, number], [dx, dy]: [number, number]): [number, number] => [x + dx, y + dy]
+
+  const fromNormal = normal(fromSide)
+  const toNormal = normal(toSide)
+  const start = border(from, fromSide)
+  const startOut = move(start, fromNormal)
+  const head = move(border(to, toSide), toNormal)
+  const targetOut = move(head, toNormal)
+  const fromHorizontal = fromNormal[0] !== 0
+  const toHorizontal = toNormal[0] !== 0
+  let middle: [number, number][]
+
+  if (fromHorizontal !== toHorizontal) {
+    middle = [fromHorizontal ? [targetOut[0], startOut[1]] : [startOut[0], targetOut[1]]]
+  } else if (fromHorizontal) {
+    const direction = Math.sign(targetOut[0] - startOut[0])
+    const direct = direction === fromNormal[0] && direction === -toNormal[0]
+    const lane = Math.max(from.y + from.h, to.y + to.h) + 1
+    middle = direct ? [] : [[startOut[0], lane], [targetOut[0], lane]]
+  } else {
+    const direction = Math.sign(targetOut[1] - startOut[1])
+    const direct = direction === fromNormal[1] && direction === -toNormal[1]
+    const lane = Math.max(from.x + from.w, to.x + to.w) + 1
+    middle = direct ? [] : [[lane, startOut[1]], [lane, targetOut[1]]]
+  }
+
+  const points = [start, startOut, ...middle, targetOut, head].filter(
+    ([x, y], i, all) => i === 0 || x !== all[i - 1][0] || y !== all[i - 1][1],
+  ) as [number, number][]
+  return { points, labels: [] }
+}
+
 /**
  * Adjacent ranks, left-to-right: out the right side, jog on the bus
  * column. The verb keeps its usual spot above the line; cardinalities hug

package/src/loom-mermaid/registry.ts

@@ -51,6 +51,8 @@ export interface Diagram {
     warnings: string[]
     classDefs: Record<string, Record<string, string>>
   } | null
+  /** Optional top-down retry; `null` means this source cannot change direction. */
+  renderDown?: Diagram['render']
 }
 
 const DIAGRAMS: Diagram[] = [