@yassimba/pi-loom-mermaid 0.2.0

package/src/loom-mermaid/paint.ts

@@ -0,0 +1,325 @@
+/**
+ * Painting a `Layout` onto a `Canvas`: boxes, frames, routes, labels. The
+ * only module that both knows the layout geometry and draws glyphs.
+ */
+
+import {
+  Canvas,
+  CONT,
+  D,
+  drawText,
+  drawTextOverEdges,
+  L,
+  R,
+  STY_DOT,
+  STY_SOLID,
+  STY_THICK,
+  U,
+} from './canvas.ts'
+import type { Edge, Graph, Head, Shape } from './graph.ts'
+import { fitLabel } from './labels.ts'
+import {
+  edgeText,
+  half,
+  type LaneLabel,
+  type Layout,
+  type NodeExtra,
+  PAD,
+  type Placed,
+  type Route,
+  sat,
+} from './layout.ts'
+import { measured, stringWidth } from './width.ts'
+
+/**
+ * Paint a layout onto a fresh canvas: boxes (plain, class compartments or
+ * subgraph frames), then every route, then the labels across them.
+ */
+export function paint(graph: Graph, extras: NodeExtra[], lay: Layout): Canvas {
+  const { placed, routes } = lay
+  const canvas = new Canvas(lay.w, lay.h)
+  for (let idx = 0; idx < graph.nodes.length; idx++) {
+    const extra = extras[idx]
+    canvas.curTag = graph.nodes[idx].classes?.join(' ')
+    canvas.curHref = graph.nodes[idx].href
+    // `BT` mirrors the finished canvas; multi-row content draws upside down so
+    // the flip restores reading order (flipHorizontal's text runs, vertically).
+    const mirrored = graph.dir === 'up'
+    if (extra.kind === 'frame')
+      drawFrame(canvas, placed[idx], graph.nodes[idx].label, extra.sub, mirrored)
+    else if (extra.kind === 'compartments')
+      drawClassBox(canvas, placed[idx], extra.sections, mirrored)
+    else drawBox(canvas, placed[idx], lay.labels[idx], graph.nodes[idx].shape, mirrored)
+  }
+  canvas.curTag = undefined
+  canvas.curHref = undefined
+
+  graph.edges.forEach((edge, i) => {
+    canvas.curStyle =
+      edge.line === 'dotted' ? STY_DOT : edge.line === 'thick' ? STY_THICK : STY_SOLID
+    const route = routes[i]
+    if (route.points.length === 0) drawSelfLoop(canvas, placed[edge.from], edge)
+    else drawRoute(canvas, edge, route)
+    for (const { text, row, x } of route.labels) placeLabel(canvas, text, row, x)
+  })
+  flushLabels(canvas)
+  placeLaneLabels(canvas, routes.flatMap((r) => (r?.laneLabel === undefined ? [] : [r.laneLabel])))
+
+  canvas.finalizeMask()
+  return canvas
+}
+
+/** Apply the direction flip a finished canvas needs for `BT` / `RL`. */
+export function orient(canvas: Canvas, graph: Graph): Canvas {
+  if (graph.dir === 'up') canvas.flipVertical()
+  else if (graph.dir === 'left') canvas.flipHorizontal()
+  return canvas
+}
+
+
+export function drawBox(
+  canvas: Canvas,
+  p: Placed,
+  lines: string[],
+  shape: Shape,
+  mirrored = false,
+): void {
+  const { x, y, w, h } = p
+  const right = x + w - 1
+  const bottom = y + h - 1
+
+  // A diamond is a double-line box — the terminal's nod to `A{...}`.
+  const [tl, tr, bl, br] =
+    shape === 'diamond'
+      ? ['╔', '╗', '╚', '╝']
+      : shape === 'round'
+        ? ['╭', '╮', '╰', '╯']
+        : ['┌', '┐', '└', '┘']
+  canvas.set(x, y, tl, 'border')
+  canvas.set(right, y, tr, 'border')
+  canvas.set(x, bottom, bl, 'border')
+  canvas.set(right, bottom, br, 'border')
+
+  if (shape === 'diamond') {
+    // Double lines have no direction bits; edges tee into them through the
+    // mixed junctions (`╤` `╧` `╟` `╢`) that `finalizeMask` resolves.
+    for (let cx = x + 1; cx < right; cx++) {
+      canvas.set(cx, y, '═', 'border')
+      canvas.set(cx, bottom, '═', 'border')
+    }
+    for (let cy = y + 1; cy < bottom; cy++) {
+      canvas.set(x, cy, '║', 'border')
+      canvas.set(right, cy, '║', 'border')
+    }
+  } else {
+    // The perimeter is drawn as bits so edges can tee into it, but it is the
+    // box outline, so it claims `border` rather than `edge`.
+    for (let cx = x + 1; cx < right; cx++) {
+      canvas.addBits(cx, y, L | R, 'border')
+      canvas.addBits(cx, bottom, L | R, 'border')
+    }
+    for (let cy = y + 1; cy < bottom; cy++) {
+      canvas.addBits(x, cy, U | D, 'border')
+      canvas.addBits(right, cy, U | D, 'border')
+    }
+  }
+
+  for (let cy = y; cy <= bottom; cy++) {
+    for (let cx = x; cx <= right; cx++) {
+      const i = canvas.idx(cx, cy)
+      canvas.occupied[i] = 1
+      if (canvas.curTag !== undefined) canvas.tag[i] = canvas.curTag
+      if (canvas.curHref !== undefined) canvas.href[i] = canvas.curHref
+    }
+  }
+
+  const inner = Math.max(1, sat(w, 2 * PAD + 2))
+  const ordered = mirrored ? [...lines].reverse() : lines
+  ordered.forEach((line, li) => {
+    const text = fitLabel(line, inner)
+    const textX = x + 1 + PAD + half(sat(inner, stringWidth(text)))
+    drawText(canvas, text, textX, y + 1 + li, 'text')
+  })
+}
+
+/** A class or ER box: sections separated by horizontal rules, title centred. */
+function drawClassBox(canvas: Canvas, p: Placed, sections: string[][], mirrored = false): void {
+  drawBox(canvas, p, [], 'rect')
+  const inner = Math.max(1, sat(p.w, 2 * PAD + 2))
+  const rows: ({ sep: true } | { sep?: undefined; text: string; center: boolean })[] = []
+  sections.forEach((section, si) => {
+    if (section.length === 0) return
+    if (rows.length > 0) rows.push({ sep: true })
+    for (const line of section) rows.push({ text: fitLabel(line, inner), center: si === 0 })
+  })
+  if (mirrored) rows.reverse()
+  rows.forEach((r, ri) => {
+    const row = p.y + 1 + ri
+    if (r.sep) {
+      canvas.set(p.x, row, '├', 'border')
+      for (let x = p.x + 1; x < p.x + p.w - 1; x++) canvas.set(x, row, '─', 'border')
+      canvas.set(p.x + p.w - 1, row, '┤', 'border')
+    } else {
+      const tx = r.center ? p.x + 1 + PAD + half(sat(inner, stringWidth(r.text))) : p.x + 1 + PAD
+      drawTextOverEdges(canvas, r.text, tx, row, 'text')
+    }
+  })
+}
+
+/** A subgraph frame: a titled box with a finished sub-canvas centred inside. */
+function drawFrame(canvas: Canvas, p: Placed, title: string, sub: Canvas, mirrored = false): void {
+  drawBox(canvas, p, [], 'rect')
+  // An unlabelled frame (a state `--` region) keeps its border unbroken.
+  if (title !== '') {
+    const t = fitLabel(title, sat(p.w, 4))
+    // Mirrored: the bottom border becomes the top after the flip.
+    drawTextOverEdges(canvas, ` ${t} `, p.x + 1, mirrored ? p.y + p.h - 1 : p.y, 'text')
+  }
+  canvas.blit(sub, p.x + 1 + half(p.w - 2 - sub.w), p.y + 1 + half(p.h - 2 - sub.h))
+}
+
+// ------------------------------------------------------------------- routing
+
+function headGlyph(head: Head, arrow: string): string {
+  switch (head) {
+    case 'circle':
+      return 'o'
+    case 'cross':
+      return '×'
+    case 'diamondFill':
+      return '◆'
+    case 'diamondOpen':
+      return '◇'
+    case 'triangle':
+      return { '▼': '▽', '▲': '△', '◄': '◁', '▶': '▷' }[arrow] ?? arrow
+    default:
+      return arrow
+  }
+}
+
+/** Direction bit from one cell toward the next (they share a row or column). */
+const toward = ([x0, y0]: [number, number], [x1, y1]: [number, number]): number =>
+  x1 > x0 ? R : x1 < x0 ? L : y1 > y0 ? D : U
+
+const ARROW: Record<number, string> = { [D]: '▼', [U]: '▲', [R]: '▶', [L]: '◄' }
+
+/**
+ * Paint a route: junction bits where it leaves the source border, a
+ * segment per pair of corners, then the tail and head glyphs facing the
+ * way the line leaves and arrives. A head of `none` just meets the box.
+ */
+function drawRoute(canvas: Canvas, edge: Edge, route: Route): void {
+  const { points } = route
+  const [sx, sy] = points[0]
+  const [hx, hy] = points[points.length - 1]
+  const leave = toward(points[0], points[1])
+  const arrive = toward(points[points.length - 2], points[points.length - 1])
+  canvas.junction(sx, sy, leave)
+  for (let k = 0; k + 1 < points.length; k++) {
+    const [x0, y0] = points[k]
+    const [x1, y1] = points[k + 1]
+    if (x0 === x1) canvas.segV(x0, y0, y1)
+    else canvas.segH(y0, x0, x1)
+  }
+  if (edge.headTo === 'none') canvas.addBits(hx, hy, toward(points[points.length - 1], points[points.length - 2]))
+  else canvas.set(hx, hy, headGlyph(edge.headTo, ARROW[arrive]), 'edge')
+  if (edge.headFrom !== 'none') {
+    canvas.set(sx, sy, headGlyph(edge.headFrom, ARROW[toward(points[1], points[0])]), 'edge')
+  }
+}
+
+/** A self-edge: a stub loop hanging below the box. */
+function drawSelfLoop(canvas: Canvas, p: Placed, edge: Edge): void {
+  const bottom = p.y + p.h - 1
+  const exitX = p.cx + 1
+  const retX = p.x + p.w - 2
+  if (retX <= exitX || bottom + 2 >= canvas.h) return
+
+  const [v, h, bl, br] =
+    edge.line === 'dotted'
+      ? ['╎', '╌', '╰', '╯']
+      : edge.line === 'thick'
+        ? ['┃', '━', '┗', '┛']
+        : ['│', '─', '╰', '╯']
+
+  canvas.junction(exitX, bottom, D)
+  canvas.set(exitX, bottom + 1, v, 'edge')
+  canvas.set(exitX, bottom + 2, bl, 'edge')
+  for (let x = exitX + 1; x < retX; x++) canvas.set(x, bottom + 2, h, 'edge')
+  canvas.set(retX, bottom + 2, br, 'edge')
+  canvas.set(retX, bottom + 1, headGlyph(edge.headTo, '▲'), 'edge')
+}
+
+/**
+ * Write each lane label onto its own row, centred on the run but slid to
+ * the nearest stretch free of crossing verticals, arrowheads and earlier
+ * labels — clearing a crossing line under a label would sever it.
+ */
+function placeLaneLabels(canvas: Canvas, labels: LaneLabel[]): void {
+  for (const { text, y, lo, hi } of labels) {
+    const tw = stringWidth(text)
+    const lastStart = hi - 1 - tw
+    if (lastStart < lo + 1 || y >= canvas.h) continue
+    const clear = (start: number): boolean => {
+      for (let x = start; x < start + tw; x++) {
+        const i = canvas.idx(x, y)
+        if (canvas.occupied[i] === 1) return false
+        if ((canvas.mask[i] & (U | D)) !== 0) return false
+        if (canvas.ch[i] !== ' ') return false
+      }
+      return true
+    }
+    const mid = Math.min(Math.max(half(lo + hi) - half(tw), lo + 1), lastStart)
+    let at = mid
+    for (let d = 0; ; d++) {
+      const left = mid - d
+      const right = mid + d
+      if (left < lo + 1 && right > lastStart) break
+      if (left >= lo + 1 && clear(left)) {
+        at = left
+        break
+      }
+      if (right <= lastStart && clear(right)) {
+        at = right
+        break
+      }
+    }
+    drawTextOverEdges(canvas, text, at, y, 'edgeLabel')
+  }
+}
+
+/**
+ * Edge labels queued while routing and written once every route has
+ * landed (`flushLabels`), so a label knows what it sits on: it interrupts
+ * a line the way a lane label interrupts its lane (the text sits across the
+ * line, which stays readable either side — a cardinality on its own bus
+ * row, a label across a return climbing past it) and stops short of a box
+ * or other text.
+ */
+/** Queue a label to be written after every line, so it interrupts them. */
+function placeLabel(canvas: Canvas, label: string, row: number, x: number): void {
+  canvas.labels.push({ label, row, x })
+}
+
+function flushLabels(canvas: Canvas): void {
+  for (const { label, row, x } of canvas.labels.splice(0)) writeLabel(canvas, label, row, x)
+}
+
+function writeLabel(canvas: Canvas, label: string, row: number, startX: number): void {
+  if (row >= canvas.h) return
+  let x = startX
+  for (const [c, cw] of measured(label)) {
+    if (cw === 0) continue
+    if (x + cw > canvas.w) break
+    let blocked = false
+    for (let k = 0; k < cw; k++) {
+      const i = canvas.idx(x + k, row)
+      if (canvas.ch[i] !== ' ' || canvas.occupied[i]) blocked = true
+    }
+    if (blocked) break
+    for (let k = 0; k < cw; k++) canvas.mask[canvas.idx(x + k, row)] = 0
+    canvas.set(x, row, c, 'edgeLabel')
+    for (let k = 1; k < cw; k++) canvas.set(x + k, row, CONT, 'edgeLabel')
+    x += cw
+  }
+}

package/src/loom-mermaid/placement.ts

@@ -0,0 +1,255 @@
+/**
+ * Cross-axis coordinate assignment for a layered graph — Brandes and Köpf,
+ * "Fast and Simple Horizontal Coordinate Assignment" (2002).
+ *
+ * Every node is aligned with a median neighbour where that crosses no
+ * long-edge chain (a type-1 conflict), aligned nodes form blocks that get
+ * one coordinate, and blocks are compacted as tightly as the ordering and
+ * the separations allow. Of the four runs (top/bottom × left/right) the one
+ * with the straightest segments is kept.
+ *
+ * Input and output are in the layered graph of `orderRanks`: ids are real
+ * nodes and virtual chain nodes alike, `size[v]` is each one's cross-axis
+ * extent, and a virtual node is any id at or past `realCount`. The returned
+ * centres are non-negative integers that keep `sep(left, right)` cells
+ * between each pair of neighbours. `offset(v)` moves a node off its aligned
+ * coordinate afterwards — a chain that should line up with a port beside
+ * its endpoint's centre rather than the centre itself.
+ */
+
+export interface LayeredGraph {
+  layers: number[][]
+  up: number[][]
+  down: number[][]
+}
+
+export function brandesKoepf(
+  g: LayeredGraph,
+  size: number[],
+  sep: (left: number, right: number) => number,
+  realCount: number,
+  offset: (v: number) => number = () => 0,
+): number[] {
+  const n = g.up.length
+  const layerOf = new Array<number>(n).fill(0)
+  const pos = new Array<number>(n).fill(0)
+  g.layers.forEach((row, r) => {
+    row.forEach((v, i) => {
+      layerOf[v] = r
+      pos[v] = i
+    })
+  })
+  const conflicts = markConflicts(g, pos, realCount)
+
+  const runs: number[][] = []
+  const roots: number[][] = []
+  for (const fromBottom of [false, true]) {
+    for (const fromRight of [false, true]) {
+      const layers = fromBottom ? [...g.layers].reverse() : g.layers
+      const view: LayeredGraph = {
+        layers: fromRight ? layers.map((row) => [...row].reverse()) : layers,
+        up: fromBottom ? g.down : g.up,
+        down: fromBottom ? g.up : g.down,
+      }
+      const vpos = new Array<number>(n).fill(0)
+      for (const row of view.layers) row.forEach((v, i) => (vpos[v] = i))
+      // Mirrored runs see the pair the other way round.
+      const gap = fromRight ? (l: number, r: number) => sep(r, l) : sep
+      const alignment = alignVertically(view, vpos, conflicts)
+      const x = compact(view, vpos, size, gap, alignment)
+      runs.push(fromRight ? x.map((c) => -c) : x)
+      roots.push(alignment.root)
+    }
+  }
+  const chosen = straightest(runs, g, size, realCount)
+  const centers = runs[chosen].map((c, v) => c + offset(v))
+  const root = roots[chosen]
+
+  // Rounding, offsets and the class shifts of the compaction can shave a
+  // cell off a separation; sweeping each layer left to right restores it,
+  // moving a whole aligned block so the run's straight segments stay
+  // straight, until every layer holds. Then pin the origin at 0.
+  const members = new Map<number, number[]>()
+  for (let v = 0; v < n; v++) {
+    const list = members.get(root[v])
+    if (list) list.push(v)
+    else members.set(root[v], [v])
+  }
+  for (let pass = 0; pass < n; pass++) {
+    let moved = false
+    for (const row of g.layers) {
+      for (let i = 1; i < row.length; i++) {
+        const [u, w] = [row[i - 1], row[i]]
+        const gap = size[u] / 2 + sep(u, w) + size[w] / 2
+        const deficit = centers[u] + gap - centers[w]
+        if (deficit <= 0) continue
+        for (const m of members.get(root[w]) ?? [w]) centers[m] += deficit
+        moved = true
+      }
+    }
+    if (!moved) break
+  }
+  let min = Number.POSITIVE_INFINITY
+  for (const row of g.layers) for (const v of row) min = Math.min(min, centers[v] - size[v] / 2)
+  if (!Number.isFinite(min)) min = 0
+  return centers.map((c) => Math.max(0, Math.round(c - min)))
+}
+
+/**
+ * Type-1 conflicts: a segment between a real node and anything crossing an
+ * inner segment (virtual to virtual). Inner segments win alignment so long
+ * edges stay straight; the crossing segment is barred from aligning.
+ */
+function markConflicts(g: LayeredGraph, pos: number[], realCount: number): Set<number> {
+  const n = g.up.length
+  const conflicts = new Set<number>()
+  const isVirtual = (v: number): boolean => v >= realCount
+  const innerUpper = (v: number): number | null => {
+    if (!isVirtual(v)) return null
+    const u = g.up[v].find(isVirtual)
+    return u === undefined ? null : u
+  }
+  for (let i = 1; i < g.layers.length; i++) {
+    const row = g.layers[i]
+    const upper = g.layers[i - 1]
+    let k0 = 0
+    let l = 0
+    for (let l1 = 0; l1 < row.length; l1++) {
+      const v = row[l1]
+      const inner = innerUpper(v)
+      if (l1 !== row.length - 1 && inner === null) continue
+      const k1 = inner === null ? upper.length - 1 : pos[inner]
+      for (; l <= l1; l++) {
+        const w = row[l]
+        for (const u of g.up[w]) {
+          if ((pos[u] < k0 || pos[u] > k1) && !(isVirtual(u) && isVirtual(w))) {
+            conflicts.add(u * n + w)
+          }
+        }
+      }
+      k0 = k1
+    }
+  }
+  return conflicts
+}
+
+interface Alignment {
+  root: number[]
+  align: number[]
+}
+
+/** Align each node with a median upper neighbour, left to right, no crossings. */
+function alignVertically(g: LayeredGraph, pos: number[], conflicts: Set<number>): Alignment {
+  const n = g.up.length
+  const root = Array.from({ length: n }, (_, v) => v)
+  const align = [...root]
+  for (let i = 1; i < g.layers.length; i++) {
+    let r = -1
+    for (const v of g.layers[i]) {
+      const ups = [...g.up[v]].sort((a, b) => pos[a] - pos[b])
+      const d = ups.length
+      if (d === 0) continue
+      const medians = d % 2 === 1 ? [ups[(d - 1) / 2]] : [ups[d / 2 - 1], ups[d / 2]]
+      for (const u of medians) {
+        if (align[v] !== v) break
+        if (conflicts.has(u * n + v) || r >= pos[u]) continue
+        align[u] = v
+        root[v] = root[u]
+        align[v] = root[v]
+        r = pos[u]
+      }
+    }
+  }
+  return { root, align }
+}
+
+/** Place blocks as far left as the ordering allows; returns centre per node. */
+function compact(
+  g: LayeredGraph,
+  pos: number[],
+  size: number[],
+  sep: (left: number, right: number) => number,
+  { root, align }: Alignment,
+): number[] {
+  const n = g.up.length
+  const pred = new Array<number>(n).fill(-1)
+  for (const row of g.layers) for (let i = 1; i < row.length; i++) pred[row[i]] = row[i - 1]
+  const sink = Array.from({ length: n }, (_, v) => v)
+  const shift = new Array<number>(n).fill(Number.POSITIVE_INFINITY)
+  const x = new Array<number>(n).fill(Number.NaN)
+  const delta = (u: number, w: number): number => size[u] / 2 + sep(u, w) + size[w] / 2
+
+  const placeBlock = (v: number): void => {
+    if (!Number.isNaN(x[v])) return
+    x[v] = 0
+    let w = v
+    do {
+      if (pos[w] > 0) {
+        const p = pred[w]
+        const u = root[p]
+        placeBlock(u)
+        if (sink[v] === v) sink[v] = sink[u]
+        if (sink[v] !== sink[u]) {
+          shift[sink[u]] = Math.min(shift[sink[u]], x[v] - x[u] - delta(p, w))
+        } else {
+          x[v] = Math.max(x[v], x[u] + delta(p, w))
+        }
+      }
+      w = align[w]
+    } while (w !== v)
+  }
+  for (let v = 0; v < n; v++) if (root[v] === v) placeBlock(v)
+
+  const out = new Array<number>(n)
+  for (let v = 0; v < n; v++) {
+    out[v] = x[root[v]]
+    const s = shift[sink[root[v]]]
+    if (Number.isFinite(s)) out[v] += s
+  }
+  return out
+}
+
+/**
+ * The run whose segments bend least (weighted sum of cross-axis offsets)
+ * among those no wider than the narrowest run plus a fifth. Brandes–Köpf
+ * balance the four by averaging medians, which splits the difference
+ * wherever the runs disagree and leaves a chain kinked by a cell or two;
+ * on a cell grid one consistent run reads better. On a large graph a
+ * straighter run can be much wider, and width is what a terminal lacks.
+ */
+function straightest(
+  runs: number[][],
+  g: LayeredGraph,
+  size: number[],
+  realCount: number,
+): number {
+  // A kinked chain segment costs most (a bus track in every band it jogs
+  // through), a kinked edge between boxes next; the jog where a long edge
+  // leaves or reaches its box is the natural place for it to step aside.
+  const weight = (v: number, w: number): number => {
+    const virtual = Number(v >= realCount) + Number(w >= realCount)
+    return virtual === 2 ? 8 : virtual === 1 ? 1 : 4
+  }
+  const scored = runs.map((x, index) => {
+    let bends = 0
+    for (let v = 0; v < g.down.length; v++) {
+      for (const w of g.down[v]) bends += weight(v, w) * Math.abs(x[v] - x[w])
+    }
+    let lo = Number.POSITIVE_INFINITY
+    let hi = Number.NEGATIVE_INFINITY
+    x.forEach((c, v) => {
+      lo = Math.min(lo, c - size[v] / 2)
+      hi = Math.max(hi, c + size[v] / 2)
+    })
+    return { index, bends, width: hi - lo }
+  })
+  const narrowest = Math.min(...scored.map((s) => s.width))
+  let best = scored[0]
+  for (const s of scored) {
+    if (s.width > narrowest * 1.2) continue
+    if (best.width > narrowest * 1.2 || s.bends < best.bends || (s.bends === best.bends && s.width < best.width)) {
+      best = s
+    }
+  }
+  return best.index
+}

package/src/loom-mermaid/registry.ts

@@ -0,0 +1,88 @@
+/**
+ * The diagram registry: one entry per supported diagram type.
+ *
+ * `diagramKind` and `render` both resolve through this table, so the header
+ * test each parser gates on and the one `diagramKind` reports are the same
+ * function by construction. Adding a diagram type is one module in
+ * `diagrams/` plus one entry here.
+ */
+
+import type { Canvas } from './canvas.ts'
+import { classDiagram } from './diagrams/class.ts'
+import { er } from './diagrams/er.ts'
+import { flowchart } from './diagrams/flowchart.ts'
+import { gitgraph } from './diagrams/gitgraph.ts'
+import { mindmap } from './diagrams/mindmap.ts'
+import { pie } from './diagrams/pie.ts'
+import { sequence } from './diagrams/sequence.ts'
+import { state } from './diagrams/state.ts'
+import { timeline } from './diagrams/timeline.ts'
+import { type Limits, stripControls } from './labels.ts'
+import { headerKind, statementsOf } from './statements.ts'
+
+/** A diagram type this renderer draws. */
+export type DiagramKind =
+  | 'flowchart'
+  | 'state'
+  | 'class'
+  | 'er'
+  | 'sequence'
+  | 'pie'
+  | 'mindmap'
+  | 'timeline'
+  | 'gitgraph'
+
+export interface Diagram {
+  kind: DiagramKind
+  /**
+   * Header keywords declaring this diagram type, lowercased. Matched exactly:
+   * upstream's prefix tests accept junk like `stateDiagramFoo` that mermaid
+   * proper rejects at the grammar stage.
+   */
+  headers: string[]
+  /** Parse and lay out within `limits`; `null` means nothing was drawn. */
+  render(
+    src: string,
+    limits: Limits,
+  ): {
+    canvas: Canvas
+    warnings: string[]
+    classDefs: Record<string, Record<string, string>>
+  } | null
+}
+
+const DIAGRAMS: Diagram[] = [
+  flowchart,
+  state,
+  classDiagram,
+  er,
+  sequence,
+  pie,
+  mindmap,
+  timeline,
+  gitgraph,
+]
+
+/** The registry entry `src`'s header declares, or `null`. */
+export function diagramFor(src: string): Diagram | null {
+  const header = headerKind(statementsOf(src))
+  if (header === null) return null
+  return DIAGRAMS.find((d) => d.headers.includes(header)) ?? null
+}
+
+/**
+ * The kind of diagram `src` declares, or `null` if its header names no type
+ * this renderer draws.
+ *
+ * Reads the header only — it says nothing about whether the body parses. Pair
+ * it with `render` to tell a source this renderer will never draw from one that
+ * is merely malformed:
+ *
+ * ```ts
+ * render(src) === null && diagramKind(src) !== null   // syntax error
+ * ```
+ */
+export function diagramKind(src: string): DiagramKind | null {
+  // The same strip `render` applies, so the two entry points agree on any src.
+  return diagramFor(stripControls(src))?.kind ?? null
+}