@yassimba/pi-loom-mermaid 0.3.0 → 0.4.1

package/package.json

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

package/src/index.ts

@@ -110,6 +110,6 @@ 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: 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).`,
+    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/diagrams/architecture.ts

@@ -0,0 +1,131 @@
+/**
+ * `architecture-beta`: services and junctions inside nested groups.
+ *
+ * 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, type PortSide } 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
+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)
+  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, icon, 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: iconLabel(icon, rawLabel || id), parent: parent ?? null })
+        }
+      } else {
+        addNode(graph, id, iconLabel(icon, 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, fromPort, leftArrow, rightArrow, toPort, 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',
+          fromSide: SIDES[fromPort.toUpperCase()],
+          toSide: SIDES[toPort.toUpperCase()],
+        })
+      }
+    } 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 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,
+  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

@@ -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

@@ -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

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,
@@ -1690,7 +1690,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 +1755,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 +1875,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 +2243,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

@@ -8,6 +8,7 @@
  */
 
 import type { Canvas } from './canvas.ts'
+import { architecture } from './diagrams/architecture.ts'
 import { classDiagram } from './diagrams/class.ts'
 import { er } from './diagrams/er.ts'
 import { flowchart } from './diagrams/flowchart.ts'
@@ -22,6 +23,7 @@ import { headerKind, statementsOf } from './statements.ts'
 
 /** A diagram type this renderer draws. */
 export type DiagramKind =
+  | 'architecture'
   | 'flowchart'
   | 'state'
   | 'class'
@@ -52,6 +54,7 @@ export interface Diagram {
 }
 
 const DIAGRAMS: Diagram[] = [
+  architecture,
   flowchart,
   state,
   classDiagram,