@yassimba/pi-loom-mermaid 0.2.0 → 0.4.0

package/README.md

@@ -1,14 +1,135 @@
-# Colored Mermaid diagrams for Pi
+# pi-loom-mermaid
 
-Render Mermaid blocks as Unicode terminal diagrams with per-node colors.
+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.
+
+Same diagram:
+
+Pi built-in. One gray box style. Edges share long outer rails.
+
+<p align="center">
+  <img src="../../assets/mermaid-pi-builtin.png" alt="Pi built-in Mermaid: gray boxes and stacked outer edges">
+</p>
+
+pi-lovely-mermaid. Color, still long parallel paths around the right side.
+
+<p align="center">
+  <img src="../../assets/mermaid-lovely.png" alt="pi-lovely-mermaid: colored borders with long parallel edges">
+</p>
+
+This package. The same colors, plus crossing hops and shorter routes.
+
+<p align="center">
+  <img src="../../assets/mermaid-pi-loom.png" alt="pi-loom-mermaid: colored borders, crossing hops, and shorter routes">
+</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.
+
+```mermaid
+flowchart TD
+    CLI["turbine CLI<br/>shell.main"]:::orange
+    LSP["Editor<br/>turbine-lsp"]:::orange
+    HTTP["HTTP client"]:::red
+
+    CLI --> SELECT["Select ProjectLayout"]:::orange
+    LSP --> WORKSPACE["Discover Projects<br/>EditorWorkspace.open"]:::orange
+
+    SELECT --> RUNTIME["ProjectRuntime.create"]:::orange
+    WORKSPACE --> RUNTIME
+
+    ENTRY["Installed turbine.extension<br/>entry points"]:::red --> EXT["Discover, order, and admit<br/>Extensions"]:::orange
+    RUNTIME --> EXT
+    EXT --> CATALOG["ExtensionCatalog"]:::green
+    CATALOG --> FORMATS["InstalledFormats"]:::green
+    CATALOG --> LINT["CachedProjectLint"]:::green
+
+    RUNTIME --> SNAPSHOT["ProjectSnapshotCache"]:::green
+    RUNTIME --> RUN["CheckRun"]:::green
+    RUNTIME --> HISTORY["RunHistoryReader"]:::green
+
+    SNAPSHOT --> COMMANDS["CLI commands"]:::orange
+    SNAPSHOT --> SESSION["EditorSession"]:::orange
+    SNAPSHOT --> API["Management API"]:::orange
+
+    CLI --> COMMANDS
+    LSP --> SESSION
+    HTTP --> API
+
+    classDef red stroke:#9f5555
+    classDef orange stroke:#9a7438
+    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**
+
+<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:
+
 ```bash
 pi install npm:@yassimba/pi-loom-mermaid
 ```
 
-Disable Pi's built-in Mermaid transformer in `~/.pi/agent/settings.json` so this extension receives the original Mermaid source:
+Turn off Pi's built-in Mermaid transformer so this extension gets the original source. In `~/.pi/agent/settings.json`:
 
 ```json
 {
@@ -18,11 +139,23 @@ Disable Pi's built-in Mermaid transformer in `~/.pi/agent/settings.json` so this
 }
 ```
 
-Run `/reload`, then mark diff nodes with the built-in `red`, `orange`, and `green` classes:
+Then run `/reload` in Pi.
+
+## Usage
+
+Mark diff nodes with the built-in `red`, `orange`, and `green` classes:
 
 ```mermaid
 flowchart LR
   A[Removed]:::red --> B[Changed]:::orange --> C[Added]:::green
 ```
 
-The built-in classes dim and color only the box border; backgrounds and text keep Pi's normal theme. Standard Mermaid `classDef` declarations can override these defaults or add other colors. Diagrams wider than the terminal remain Mermaid source blocks.
+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.
+
+## License
+
+[MIT](LICENSE)
+
+pi-loom-mermaid is adapted from pi-lovely-mermaid.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yassimba/pi-loom-mermaid",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Loom's advanced Mermaid renderer for Pi, with better routing and color.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Marked, type Token } from "@earendil-works/pi-tui";
-import { render, toAnsi } from "./loom-mermaid/index.ts";
+import { diagramKind, render, toAnsi } from "./loom-mermaid/index.ts";
+import { isClosedFence, streamingPrefixes } from "./streaming.ts";
 
 const markdownParser = new Marked();
 const diffClasses = {
@@ -12,7 +13,7 @@ const diffClasses = {
 type TransformContext = {
   messageType: "user" | "assistant" | "assistant-thinking";
   availableWidth: number;
-  /** The message is still arriving; an unclosed fence shows as source until it closes. */
+  /** Draw completed statements while the message is still arriving. */
   isStreaming?: boolean;
 };
 
@@ -22,11 +23,11 @@ type TransformContext = {
  * laid out again for each token after it. Layout is deterministic, so the
  * first render is the only one needed.
  */
-const rendered = new Map<string, string>();
+const rendered = new Map<string, string | null>();
 const CACHE_SIZE = 64;
 
 function renderBlock(text: string, availableWidth: number): string | null {
-  const key = `${availableWidth}\0${text}`;
+  const key = `${availableWidth}\0${text.trimEnd()}`;
   const hit = rendered.get(key);
   if (hit !== undefined) {
     rendered.delete(key);
@@ -35,16 +36,15 @@ function renderBlock(text: string, availableWidth: number): string | null {
   }
   const styledSource = withDiffClasses(text);
   const art = render(styledSource.source, { maxWidth: availableWidth });
-  if (!art || art.width > availableWidth) return null;
-  const out = `${dimDefaultBorders(toAnsi(art), styledSource.dimSgr).map(codeSpan).join("  \n")}\n`;
+  const out =
+    !art || art.width > availableWidth
+      ? null
+      : `${dimDefaultBorders(toAnsi(art), styledSource.dimSgr).map(codeSpan).join("  \n")}\n`;
   rendered.set(key, out);
   if (rendered.size > CACHE_SIZE) rendered.delete(rendered.keys().next().value as string);
   return out;
 }
 
-/** A fenced block whose closing fence has arrived. */
-const isClosed = (token: { raw: string }): boolean => /\n\s*(`{3,}|~{3,})\s*$/.test(token.raw);
-
 function isMermaid(token: Token): token is Token & { type: "code"; text: string; lang?: string } {
   return (
     token.type === "code" && token.lang?.trim().split(/\s+/, 1)[0]?.toLowerCase() === "mermaid"
@@ -92,7 +92,16 @@ export function transformMermaidMarkdown(markdown: string, context: TransformCon
     .lexer(markdown)
     .map((token) => {
       if (!isMermaid(token)) return token.raw;
-      if (context.isStreaming === true && !isClosed(token)) return token.raw;
+      if (context.isStreaming === true && !isClosedFence(token.raw)) {
+        if (diagramKind(token.text) === null) return token.raw;
+        // Marked removes the last newline from unclosed code tokens.
+        const source = token.text + (token.raw.endsWith("\n") ? "\n" : "");
+        for (const prefix of streamingPrefixes(source)) {
+          const out = renderBlock(prefix, context.availableWidth);
+          if (out !== null) return out;
+        }
+        return "_Drawing Mermaid…_\n";
+      }
       return renderBlock(token.text, context.availableWidth) ?? token.raw;
     })
     .join("");
@@ -100,4 +109,7 @@ export function transformMermaidMarkdown(markdown: string, context: TransformCon
 
 export default function piLovelyMermaid(pi: ExtensionAPI): void {
   pi.registerMarkdownTransformer(transformMermaidMarkdown);
+  pi.on("before_agent_start", (event) => ({
+    systemPrompt: `${event.systemPrompt}\n\nUse fenced \`mermaid\` blocks; they render automatically in the user’s session. Use Mermaid proactively to explain relationships, flows, and changes. Choose by subject: architecture for deployed services, flowchart for dependencies/decisions, sequence for interactions, state for lifecycles, ER/class for models, mindmap for hierarchies, timeline/git graph for history, pie for proportions. Use complementary diagrams when explaining multiple aspects. Keep diagram labels short. Mark changes (like diff but also other changes) with: :::red removed, :::green added, :::orange changed. In general prefer colored outlines to logically group things (if there are no changes involved).`,
+  }));
 }

package/src/loom-mermaid/ansi.ts

@@ -25,7 +25,7 @@ const rgb = (hex: string, sgr: 38 | 48): string =>
 /**
  * The truecolor SGR a class style gives a span of the given role, or
  * undefined when the style says nothing about it (fall back to the theme).
- * `stroke` colors borders, `color` text; `fill` backs every painted cell,
+ * `stroke` colors borders, `color` text; `fill` backs interior cells only,
  * with a black/white foreground picked for contrast when none was declared.
  * A style that colors nothing for this role keeps `fallback` (the theme's
  * SGR), so a bold-only class bolds the themed look instead of replacing it.
@@ -33,9 +33,11 @@ const rgb = (hex: string, sgr: 38 | 48): string =>
 export function classSgr(st: ClassStyle, role: Role, fallback?: string): string | undefined {
   const p: string[] = []
   const fg = role === 'border' ? (st.stroke ?? st.color) : role === 'edge' ? undefined : st.color
-  const backed = fg ?? (st.fill === undefined ? undefined : contrastOn(st.fill))
+  // Terminal backgrounds cover whole cells, including the outside half of an outline glyph.
+  const fill = role === 'border' ? undefined : st.fill
+  const backed = fg ?? (fill === undefined ? undefined : contrastOn(fill))
   if (backed !== undefined) p.push(rgb(backed, 38))
-  if (st.fill !== undefined) p.push(rgb(st.fill, 48))
+  if (fill !== undefined) p.push(rgb(fill, 48))
   if (p.length === 0 && fallback !== undefined) p.push(fallback)
   if (st.bold === true) p.unshift('1')
   return p.length > 0 ? p.join(';') : undefined

package/src/loom-mermaid/canvas.ts

@@ -120,7 +120,9 @@ export class Canvas {
         this.href[di] = sub.href[si]
         this.style[di] = sub.style[si]
         this.pass[di] = sub.pass[si]
-        this.occupied[di] = 1
+        // Blank padding inside the frame stays free: a cross-frame route
+        // may run a stub through it to the inner node it joins.
+        this.occupied[di] = sub.occupied[si] || sub.ch[si] !== ' ' ? 1 : 0
       }
     }
   }
@@ -129,6 +131,12 @@ export class Canvas {
   junction(x: number, y: number, bits: number): void {
     if (x >= this.w || y >= this.h) return
     const i = this.idx(x, y)
+    // A plain border glyph stamped from a sub-canvas goes back to bits so
+    // the tee resolves with the rest.
+    if (this.ch[i] === '│' || this.ch[i] === '─') {
+      this.mask[i] |= this.ch[i] === '│' ? U | D : L | R
+      this.ch[i] = ' '
+    }
     this.mask[i] |= bits
     this.pass[i] |= JOINED
     if (this.role[i] !== 'border') this.role[i] = 'edge'

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

@@ -0,0 +1,116 @@
+/**
+ * `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.
+ */
+
+import { Graph, MAX_GROUP_DEPTH, MAX_GROUPS } from '../graph.ts'
+import { cleanLabel } from '../labels.ts'
+import { layoutFlowchart, layoutGrouped } from '../graph-render.ts'
+import type { Diagram } from '../registry.ts'
+import { firstWord, headerKind, statementsOf } from '../statements.ts'
+
+export const architecture: Diagram = {
+  kind: 'architecture',
+  headers: ['architecture-beta'],
+  render(src, limits) {
+    const graph = parseArchitecture(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: {} }
+  },
+}
+
+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
+
+function parseArchitecture(src: string): Graph | null {
+  const statements = statementsOf(src)
+  if (headerKind(statements) !== 'architecture-beta') return null
+
+  // Architecture has no global direction. LR gives grouped boundary edges the
+  // existing router's more precise inner-node anchors.
+  const graph = new Graph('right')
+  const groupIndex = new Map<string, number>()
+
+  for (const st of statements.slice(1)) {
+    const declaration = st.match(DECLARATION)
+    const junction = st.match(JUNCTION)
+    const edge = st.match(EDGE)
+
+    if (declaration) {
+      const [, kind, id, , rawLabel, parentId] = declaration
+      const parent = parentId === undefined ? null : groupIndex.get(parentId)
+      if (parentId !== undefined && parent === undefined) {
+        graph.drop(st)
+      } else if (kind.toLowerCase() === 'group') {
+        if (groupIndex.has(id)) {
+          graph.drop(st)
+        } else if (
+          graph.groups.length >= MAX_GROUPS ||
+          groupDepth(graph, parent ?? null) >= MAX_GROUP_DEPTH
+        ) {
+          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 })
+        }
+      } else {
+        addNode(graph, id, cleanLabel(rawLabel) || id, parent ?? null, 'rect')
+      }
+    } else if (junction) {
+      const [, id, parentId] = junction
+      const parent = parentId === undefined ? null : groupIndex.get(parentId)
+      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 from = graph.index.get(fromId)
+      const to = graph.index.get(toId)
+      if (from === undefined || to === undefined) {
+        graph.drop(st)
+      } else {
+        graph.pushEdge({
+          from,
+          to,
+          label: null,
+          headFrom: leftArrow ? 'arrow' : 'none',
+          headTo: rightArrow ? 'arrow' : 'none',
+          line: 'solid',
+        })
+      }
+    } else if (firstWord(st).toLowerCase() !== 'title') {
+      graph.drop(st)
+    }
+
+    if (graph.truncated !== null) {
+      graph.warnings.push(`diagram truncated: ${graph.truncated}`)
+      break
+    }
+  }
+
+  return graph.nodes.length === 0 ? null : graph
+}
+
+function addNode(
+  graph: Graph,
+  id: string,
+  label: string,
+  group: number | null,
+  shape: 'rect' | 'round',
+): void {
+  const previous = graph.curGroup
+  graph.curGroup = group
+  graph.nodeIndex(id, label, shape)
+  graph.curGroup = previous
+}
+
+function groupDepth(graph: Graph, parent: number | null): number {
+  let depth = 0
+  for (let at = parent; at !== null; at = graph.groups[at].parent) depth++
+  return depth
+}

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

@@ -5,11 +5,11 @@
  */
 
 import { Canvas } from './canvas.ts'
-import type { Edge, Node } from './graph.ts'
+import type { Anchor, Edge, Node } from './graph.ts'
 import { Graph } from './graph.ts'
 import type { Limits } from './labels.ts'
 import { layout, type NodeExtra } from './layout.ts'
-import { orient, paint } from './paint.ts'
+import { frameOrigin, orient, paint } from './paint.ts'
 
 /** A laid-out canvas, or `null` when the diagram is empty or over the cell cap. */
 export type CanvasResult = Canvas | null
@@ -33,6 +33,66 @@ export function layoutClass(graph: Graph, limits: Limits): CanvasResult {
 
 // -------------------------------------------------------------------- groups
 
+/**
+ * The overview of a grouped diagram: every top-level subgraph becomes one
+ * node labelled with its title and member count in parentheses, edges between two
+ * subgraphs (or a subgraph and a loose node) merge into one, and edges
+ * inside a subgraph disappear. Multilevel drawing's coarsest level
+ * (Walshaw), used when the full diagram is too wide for the space.
+ */
+function collapseGroups(graph: Graph): Graph {
+  const out = new Graph(graph.dir)
+  out.classDefs = graph.classDefs
+  const topOf = (g: number | null): number | null => {
+    let cur = g
+    while (cur !== null && graph.groups[cur].parent !== null) cur = graph.groups[cur].parent
+    return cur
+  }
+  const groupNode = new Map<number, number>()
+  const members = new Map<number, number>()
+  graph.nodeGroup.forEach((g) => {
+    const t = topOf(g)
+    if (t !== null) members.set(t, (members.get(t) ?? 0) + 1)
+  })
+  const nodeAt = new Map<number, number>()
+  graph.nodes.forEach((node, v) => {
+    const t = topOf(graph.nodeGroup[v])
+    if (t === null) {
+      if (graph.groups.some((g) => graph.index.get(g.id) === v)) return
+      nodeAt.set(v, out.nodes.length)
+      out.nodes.push(node)
+      out.nodeGroup.push(null)
+      return
+    }
+    let gn = groupNode.get(t)
+    if (gn === undefined) {
+      gn = out.nodes.length
+      const count = members.get(t) ?? 0
+      out.nodes.push({ label: `${graph.groups[t].label || graph.groups[t].id} (${count})`, shape: 'rect' })
+      out.nodeGroup.push(null)
+      groupNode.set(t, gn)
+    }
+    nodeAt.set(v, gn)
+  })
+  // A node whose id names a subgraph stands for it.
+  graph.groups.forEach((g, gi) => {
+    const v = graph.index.get(g.id)
+    const t = topOf(gi)
+    if (v !== undefined && t !== null && groupNode.has(t)) nodeAt.set(v, groupNode.get(t) as number)
+  })
+  const seen = new Set<string>()
+  for (const e of graph.edges) {
+    const a = nodeAt.get(e.from)
+    const b = nodeAt.get(e.to)
+    if (a === undefined || b === undefined || a === b) continue
+    const key = `${a}>${b}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.edges.push({ ...e, from: a, to: b, label: null, cardFrom: undefined, cardTo: undefined })
+  }
+  return out
+}
+
 /** An endpoint inside a scope: a plain node or a (proxied) subgraph. */
 interface ScopeItem {
   group: boolean
@@ -47,6 +107,7 @@ interface ScopeItem {
  * one crossing a subgraph boundary attaches to the frame instead of the node.
  */
 export function layoutGrouped(graph: Graph, limits: Limits): CanvasResult {
+  if (limits.collapse) return layoutFlowchart(collapseGroups(graph), limits)
   // A node whose id matches a subgraph id stands in for that subgraph.
   const proxy = new Map<number, number>()
   graph.groups.forEach((g, gi) => {
@@ -115,8 +176,14 @@ export function layoutGrouped(graph: Graph, limits: Limits): CanvasResult {
     if (g.parent === null) visit(gi)
   })
 
-  const canvas = buildScope(graph, null, scopeEdges, directNodes, keep, limits)
-  return canvas && orient(canvas, graph)
+  const scope = buildScope(graph, null, scopeEdges, directNodes, keep, limits)
+  return scope && orient(scope.canvas, graph)
+}
+
+/** A laid-out scope: its canvas and where every node inside it (at any depth) landed. */
+interface Scope {
+  canvas: Canvas
+  anchors: Map<number, Anchor>
 }
 
 function buildScope(
@@ -126,19 +193,33 @@ function buildScope(
   directNodes: Map<number | null, number[]>,
   keep: boolean[],
   limits: Limits,
-): CanvasResult {
+): Scope | null {
   const items: ScopeItem[] = (directNodes.get(scope) ?? []).map((i) => ({ group: false, i }))
   const childGroups = graph.groups
     .map((_, gi) => gi)
     .filter((gi) => graph.groups[gi].parent === scope && keep[gi])
   items.push(...childGroups.map((i) => ({ group: true, i })))
+  // In declaration order, a frame standing where its first member was
+  // named: ranking breaks cycles from the first item, the author's entry.
+  const firstIn = (gi: number): number => {
+    let first = graph.nodes.length
+    graph.nodeGroup.forEach((g, ni) => {
+      for (let at: number | null = g; at !== null; at = graph.groups[at].parent) {
+        if (at === gi) first = Math.min(first, ni)
+      }
+    })
+    return first
+  }
+  const order = (item: ScopeItem): number => (item.group ? firstIn(item.i) : item.i)
+  items.sort((a, b) => order(a) - order(b))
 
-  if (items.length === 0) return new Canvas(1, 1)
+  if (items.length === 0) return { canvas: new Canvas(1, 1), anchors: new Map() }
 
   const nodeAt = new Map<number, number>()
   const groupAt = new Map<number, number>()
   const nodes: Node[] = []
   const extras: NodeExtra[] = []
+  const subScopes = new Map<number, Scope>()
   for (const item of items) {
     ;(item.group ? groupAt : nodeAt).set(item.i, nodes.length)
     if (!item.group) {
@@ -152,11 +233,15 @@ function buildScope(
     } else {
       const sub = buildScope(graph, item.i, scopeEdges, directNodes, keep, limits)
       if (sub === null) return null
+      subScopes.set(nodes.length, sub)
       nodes.push({ label: graph.groups[item.i].label, shape: 'rect' })
-      extras.push({ kind: 'frame', sub })
+      extras.push({ kind: 'frame', sub: sub.canvas })
     }
   }
 
+  // An end standing for a frame remembers the inner node it really joins.
+  const anchorOf = (item: ScopeItem, node: number): Anchor | undefined =>
+    item.group ? subScopes.get(groupAt.get(item.i) as number)?.anchors.get(node) : undefined
   const edges: Edge[] = []
   for (const [f, t, ei] of scopeEdges.get(scope) ?? []) {
     const fi = (f.group ? groupAt : nodeAt).get(f.i)
@@ -170,11 +255,21 @@ function buildScope(
       headTo: e.headTo,
       headFrom: e.headFrom,
       line: e.line,
+      fromAnchor: anchorOf(f, e.from),
+      toAnchor: anchorOf(t, e.to),
     }
-    // Edges from (or to) different nodes inside one frame collapse onto
-    // the frame and become indistinguishable; draw them once.
+    // Repeats of one inner-node pair ride the same cells; draw them once.
+    // Top-down layout still ports at the frame (ponytail: anchors are wired
+    // into placeLr only), so there every pair of frames is one edge.
+    const ported = graph.dir === 'right' || graph.dir === 'left'
     const twin = (a: Edge, b: Edge): boolean =>
-      a.from === b.from && a.to === b.to && a.label === b.label && a.headTo === b.headTo && a.headFrom === b.headFrom && a.line === b.line
+      a.from === b.from &&
+      a.to === b.to &&
+      (!ported || (a.fromAnchor?.node === b.fromAnchor?.node && a.toAnchor?.node === b.toAnchor?.node)) &&
+      a.label === b.label &&
+      a.headTo === b.headTo &&
+      a.headFrom === b.headFrom &&
+      a.line === b.line
     if ((f.group || t.group) && edges.some((x) => twin(x, collapsed))) continue
     edges.push(collapsed)
   }
@@ -183,7 +278,23 @@ function buildScope(
   const synth = new Graph(graph.dir)
   synth.nodes = nodes
   synth.edges = edges
-  return layoutCanvas(synth, extras, limits)
+  const lay = layout(synth, extras, limits)
+  if (lay === null) return null
+  const canvas = paint(synth, extras, lay)
+
+  const anchors = new Map<number, Anchor>()
+  for (const item of items) {
+    const li = (item.group ? groupAt : nodeAt).get(item.i) as number
+    const p = lay.placed[li]
+    if (!item.group) {
+      anchors.set(item.i, { node: item.i, x: p.x, y: p.y, w: p.w, h: p.h })
+      continue
+    }
+    const sub = subScopes.get(li) as Scope
+    const [ox, oy] = frameOrigin(p, sub.canvas)
+    for (const a of sub.anchors.values()) anchors.set(a.node, { ...a, x: a.x + ox, y: a.y + oy })
+  }
+  return { canvas, anchors }
 }
 
 /** Lay out and paint one scope. */

package/src/loom-mermaid/graph.ts

@@ -66,6 +66,22 @@ export interface Edge {
   headTo: Head
   headFrom: Head
   line: LineKind
+  /**
+   * 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.
+   * Layout ports the edge at that node instead of the frame's centre.
+   */
+  fromAnchor?: Anchor
+  toAnchor?: Anchor
+}
+
+/** An inner node's box inside a frame's sub-canvas. */
+export interface Anchor {
+  node: number
+  x: number
+  y: number
+  w: number
+  h: number
 }
 
 export interface Group {

package/src/loom-mermaid/index.ts

@@ -14,9 +14,9 @@ export type { MermaidArt, Role, Span } from './types.ts'
 /**
  * Render a Mermaid source block as Unicode box-drawing art.
  *
- * Supported: `graph`/`flowchart` (including `subgraph`), `stateDiagram`,
- * `classDiagram`, `erDiagram`, `sequenceDiagram`, `pie`, `mindmap`,
- * `timeline` and `gitGraph`.
+ * Supported: `architecture-beta`, `graph`/`flowchart` (including `subgraph`),
+ * `stateDiagram`, `classDiagram`, `erDiagram`, `sequenceDiagram`, `pie`,
+ * `mindmap`, `timeline` and `gitGraph`.
  *
  * 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
@@ -49,13 +49,18 @@ export function render(src: string, options: { maxWidth?: number } = {}): Mermai
   // the tightest, for the caller to judge against `art.width`).
   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
   }
   if (drawn === null) return null
+  if (collapsed && /^\s*subgraph\b|^\s*state\s+\S+\s*\{/m.test(src)) {
+    drawn.warnings.push('too wide for the space: subgraphs drawn collapsed, one box each')
+  }
 
   // A frontmatter `title:` is centred above the art, in the `title` role.
   const title = frontmatterTitle(src)