@yassimba/pi-loom-mermaid 0.2.0

package/src/loom-mermaid/labels.ts

@@ -0,0 +1,353 @@
+import { measured, stringWidth } from './width.ts'
+
+/** How much text a diagram shows before wrapping or truncating. */
+export interface Limits {
+  /** Node labels wrap to at most this many display columns per line ... */
+  wrap: number
+  /** ... and at most this many lines; overflow is truncated with an ellipsis. */
+  lines: number
+  /** Edge labels are truncated to this many columns. */
+  label: number
+}
+
+/** The default limits, and the tighter ones `render` falls back through
+ * when a diagram is wider than the space it was given. */
+export const LIMITS: Limits[] = [
+  { wrap: 24, lines: 4, label: 28 },
+  { wrap: 16, lines: 3, label: 16 },
+  { wrap: 12, lines: 2, label: 10 },
+]
+export const DEFAULT_LIMITS: Limits = LIMITS[0]
+
+/**
+ * Identifier-boundary characters preferred as break points when a single word
+ * is too wide to fit, so it is not sliced mid-segment.
+ *
+ * Mirrors `TOKEN_BREAK_CHARS` in grok-build's
+ * `third_party/mermaid-to-svg/src/text_wrap.rs`; the two renderers are
+ * deliberately independent, so keep these in sync.
+ */
+const LABEL_BREAK_CHARS = ['_', '-', '.', '/']
+
+/**
+ * ASCII-only case folding, matching Rust's `to_ascii_lowercase`.
+ *
+ * `String.prototype.toLowerCase` can change a string's length (`İ` becomes two
+ * code points), which would desync the byte offsets some parsers slice with.
+ */
+export const asciiLower = (s: string): string => s.replace(/[A-Z]/g, (c) => c.toLowerCase())
+export const asciiUpper = (s: string): string => s.replace(/[a-z]/g, (c) => c.toUpperCase())
+
+/**
+ * C0 and C1 controls, less the `\t\n\r` the parsers and `srcLines` read.
+ *
+ * They measure one column and paint none, so a box sized around one is drawn a
+ * column short of its own border; NUL also collides with the `CONT` sentinel
+ * and is dropped after layout has already paid for its cell; ESC would inject
+ * ANSI into the caller's scrollback. `decodeEntityBody` refuses to decode an
+ * entity into one — this closes the same hole for literals.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the point is to match them
+const CONTROLS = /[\0-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g
+
+/** Applied by every public entry point that takes untrusted source. */
+export const stripControls = (src: string): string => src.replace(CONTROLS, '')
+
+/**
+ * Split source into lines the way Rust's `str::lines()` does: on `\n`, with a
+ * trailing `\r` stripped, and *without* a final empty line when the input ends
+ * in a newline. `String.split` yields that extra element, which would show up
+ * as a spurious blank row inside a source box.
+ */
+export function srcLines(src: string): string[] {
+  const out = src.split('\n').map((l) => (l.endsWith('\r') ? l.slice(0, -1) : l))
+  if (out.length > 0 && out[out.length - 1] === '') out.pop()
+  return out
+}
+
+const ALNUM = /[\p{Alphabetic}\p{N}]/u
+
+/** Matches Rust's `char::is_alphanumeric`. */
+const isAlphanumeric = (c: string): boolean => ALNUM.test(c)
+
+/** Characters allowed in a bare node/state/class identifier. */
+export const isIdChar = (c: string): boolean => isAlphanumeric(c) || c === '_'
+
+const ENTITY_LOOKAHEAD = 10
+
+const NAMED_ENTITIES: Record<string, string> = {
+  lt: '<',
+  gt: '>',
+  amp: '&',
+  quot: '"',
+  apos: "'",
+}
+
+function decodeEntityBody(body: string): string | null {
+  const named = NAMED_ENTITIES[body]
+  if (named !== undefined) return named
+  if (!body.startsWith('#')) return null
+  const num = body.slice(1)
+  const hex = /^[xX]/.test(num)
+  const digits = hex ? num.slice(1) : num
+  if (!(hex ? /^[0-9a-fA-F]+$/ : /^[0-9]+$/).test(digits)) return null
+  const code = Number.parseInt(digits, hex ? 16 : 10)
+  // Surrogates and out-of-range values are not characters at all.
+  if (code > 0x10ffff || (code >= 0xd800 && code <= 0xdfff)) return null
+  // Reject control chars: NUL collides with the CONT sentinel and ESC would
+  // inject ANSI into scrollback.
+  if (code < 0x20 || (code >= 0x7f && code <= 0x9f)) return null
+  return String.fromCodePoint(code)
+}
+
+/**
+ * Decode HTML entities in label text. Called once per label: via `cleanLabel`
+ * for bracketed labels, or explicitly at each direct-push sink.
+ */
+export function decodeHtmlEntities(s: string): string {
+  if (!s.includes('&')) return s
+  const chars = [...s]
+  let out = ''
+  let i = 0
+  while (i < chars.length) {
+    if (chars[i] !== '&') {
+      out += chars[i]
+      i++
+      continue
+    }
+    // Scan a bounded window including the terminating `;`, so a stray `&` or an
+    // over-long run stays literal.
+    const hi = Math.min(i + 1 + ENTITY_LOOKAHEAD, chars.length)
+    let semi = -1
+    for (let j = i + 1; j < hi; j++) {
+      if (chars[j] === ';') {
+        semi = j
+        break
+      }
+    }
+    const decoded = semi === -1 ? null : decodeEntityBody(chars.slice(i + 1, semi).join(''))
+    if (decoded === null) {
+      out += '&'
+      i++
+    } else {
+      // Resume past the `;`. The single pass never re-scans emitted text, so
+      // `&amp;lt;` decodes to the literal `&lt;` rather than to `<`.
+      out += decoded
+      i = semi + 1
+    }
+  }
+  return out
+}
+
+/** Strip markdown emphasis from a `` `backtick` `` label string. */
+function stripMarkdown(s: string): string {
+  const noCode = [...s].filter((c) => c !== '`').join('')
+  const noStrong = noCode.replaceAll('**', '').replaceAll('__', '')
+  const chars = [...noStrong]
+  let out = ''
+  for (let i = 0; i < chars.length; i++) {
+    const c = chars[i]
+    // Keep `*`/`_` only when they sit inside a word, so snake_case survives.
+    const inWord =
+      i > 0 &&
+      isAlphanumeric(chars[i - 1]) &&
+      chars[i + 1] !== undefined &&
+      isAlphanumeric(chars[i + 1])
+    if ((c === '*' || c === '_') && !inWord) continue
+    out += c
+  }
+  return out.trim()
+}
+
+/**
+ * Inline formatting tags that carry no meaning in a terminal. Anything else
+ * that looks like a tag — `Vec<String>`, `<id>` — is left alone.
+ */
+const HTML_FORMAT_TAGS = new Set([
+  'b',
+  'strong',
+  'i',
+  'em',
+  'u',
+  's',
+  'strike',
+  'del',
+  'ins',
+  'mark',
+  'small',
+  'big',
+  'sub',
+  'sup',
+  'code',
+  'kbd',
+  'samp',
+  'var',
+  'tt',
+  'span',
+  'font',
+  'q',
+  'abbr',
+  'cite',
+  'pre',
+])
+
+/** Read a tag starting at `start`, returning its name and the index after `>`. */
+function htmlTagAt(chars: string[], start: number): { name: string; end: number } | null {
+  let i = start + 1
+  if (chars[i] === '/') i++
+  const nameStart = i
+  while (i < chars.length && /^[0-9A-Za-z]$/.test(chars[i])) i++
+  if (i === nameStart) return null
+  const name = chars.slice(nameStart, i).join('')
+  while (i < chars.length && chars[i] !== '>') {
+    if (chars[i] === '<') return null
+    i++
+  }
+  return chars[i] === '>' ? { name, end: i + 1 } : null
+}
+
+function stripHtmlTags(s: string): string {
+  const chars = [...s]
+  let out = ''
+  let i = 0
+  while (i < chars.length) {
+    if (chars[i] === '<') {
+      const tag = htmlTagAt(chars, i)
+      if (tag) {
+        const lower = tag.name.toLowerCase()
+        if (lower === 'br') {
+          out += ' '
+          i = tag.end
+          continue
+        }
+        if (HTML_FORMAT_TAGS.has(lower)) {
+          i = tag.end
+          continue
+        }
+      }
+    }
+    out += chars[i]
+    i++
+  }
+  return out
+}
+
+/** Strip one matching pair of wrapping delimiters, if present. */
+function unwrap(s: string, open: string, close: string): string | null {
+  return s.length >= open.length + close.length && s.startsWith(open) && s.endsWith(close)
+    ? s.slice(open.length, s.length - close.length)
+    : null
+}
+
+/**
+ * Normalise raw label text: strip markup, unquote, and decode entities.
+ *
+ * Decoding happens after tag-stripping so `<b>` is removed as markup while
+ * `&lt;b&gt;` survives as the literal text `<b>`.
+ */
+export function cleanLabel(raw: string): string {
+  const trimmed = stripHtmlTags(raw.trim()).trim()
+  const unquoted = (unwrap(trimmed, '"', '"') ?? unwrap(trimmed, "'", "'") ?? trimmed).trim()
+  const md = unwrap(unquoted, '`', '`')
+  return decodeHtmlEntities(md === null ? unquoted : stripMarkdown(md.trim()))
+}
+
+/** Mermaid writes generics as `List~T~`; show them as `List<T>`. */
+export function displayGenerics(s: string): string {
+  let out = ''
+  let open = false
+  for (const c of s) {
+    if (c === '~') {
+      out += open ? '>' : '<'
+      open = !open
+    } else {
+      out += c
+    }
+  }
+  return out
+}
+
+/** Index of the last identifier-boundary character, or -1. */
+function lastBreak(s: string): number {
+  let best = -1
+  for (const c of LABEL_BREAK_CHARS) best = Math.max(best, s.lastIndexOf(c))
+  return best
+}
+
+/**
+ * Wrap a label to `width` columns over at most `maxLines` lines, truncating the
+ * last line with an ellipsis if it overflows.
+ *
+ * A word too wide to fit is broken after the last identifier boundary
+ * (`_-./`) that fits, falling back to a per-character break when it has none.
+ */
+export function wrapLabel(label: string, width: number, maxLines: number): string[] {
+  width = Math.max(1, width)
+  const lines: string[] = []
+  let cur = ''
+  let curW = 0
+
+  for (const word of label.split(/\s+/).filter((w) => w !== '')) {
+    const ww = stringWidth(word)
+    if (ww > width) {
+      if (cur !== '') {
+        lines.push(cur)
+        cur = ''
+      }
+      let chunk = ''
+      let chunkW = 0
+      for (const [ch, cw] of measured(word)) {
+        if (chunkW + cw > width && chunk !== '') {
+          const p = lastBreak(chunk)
+          const carry = p === -1 ? '' : chunk.slice(p + 1)
+          lines.push(p === -1 ? chunk : chunk.slice(0, p + 1))
+          chunk = carry
+          chunkW = stringWidth(carry)
+        }
+        chunk += ch
+        chunkW += cw
+      }
+      cur = chunk
+      curW = chunkW
+    } else if (cur === '') {
+      cur = word
+      curW = ww
+    } else if (curW + 1 + ww <= width) {
+      cur += ` ${word}`
+      curW += 1 + ww
+    } else {
+      lines.push(cur)
+      cur = word
+      curW = ww
+    }
+  }
+  if (cur !== '') lines.push(cur)
+  if (lines.length === 0) lines.push('')
+
+  if (lines.length > maxLines) {
+    lines.length = maxLines
+    const target = Math.max(1, width - 1)
+    let s = ''
+    let sw = 0
+    for (const [ch, cw] of measured(lines[lines.length - 1])) {
+      if (sw + cw > target) break
+      s += ch
+      sw += cw
+    }
+    lines[lines.length - 1] = `${s}…`
+  }
+  return lines
+}
+
+/** Truncate to `inner` columns, leaving room for the ellipsis. */
+export function fitLabel(label: string, inner: number): string {
+  if (stringWidth(label) <= inner) return label
+  let out = ''
+  let used = 0
+  for (const [c, cw] of measured(label)) {
+    if (used + cw + 1 > inner) break
+    out += c
+    used += cw
+  }
+  return `${out}…`
+}

package/src/loom-mermaid/layout-seq.ts

@@ -0,0 +1,234 @@
+/**
+ * Sequence diagram layout.
+ *
+ * Participants get one column each, with lifelines running the full height and
+ * a box repeated at top and bottom. Column gaps are solved from the widest
+ * thing that has to fit between any two columns — a message label, a note, a
+ * self-message stub — then items stack down the canvas in source order.
+ */
+
+import { Canvas, D, drawTextOverEdges, L, R, U } from './canvas.ts'
+import type { NoteAnchor, SeqItem, Sequence } from './diagrams/sequence.ts'
+import { fitLabel, type Limits } from './labels.ts'
+import type { CanvasResult } from './graph-render.ts'
+import { half, MAX_CANVAS_CELLS, PAD, type Placed, sat } from './layout.ts'
+import { drawBox } from './paint.ts'
+import { stringWidth } from './width.ts'
+
+/** Minimum columns between adjacent lifelines. */
+const SEQ_GAP = 5
+
+/** Where a note box sits, given the lifeline positions. */
+function noteGeometry(xs: number[], anchor: NoteAnchor, textW: number): { x: number; w: number } {
+  if (anchor.kind === 'over') {
+    const center = half(xs[anchor.from] + xs[anchor.to])
+    const w = Math.max(xs[anchor.to] - xs[anchor.from] + 5, textW + 2 * PAD + 2)
+    return { x: sat(center, half(w)), w }
+  }
+  const w = textW + 2 * PAD + 2
+  if (anchor.kind === 'left') return { x: sat(xs[anchor.at], 2 + w - 1), w }
+  return { x: xs[anchor.at] + 2, w }
+}
+
+const itemTextW = (text: string | null): number => (text === null ? 0 : stringWidth(text))
+
+export function layoutSequence(seq: Sequence, limits: Limits): CanvasResult {
+  const n = seq.labels.length
+  const labels = seq.labels.map((l) => fitLabel(l, limits.wrap))
+  const boxW = labels.map((l) => Math.max(1, stringWidth(l)) + 2 * PAD + 2)
+  const boxH = 3
+
+  const gaps = Array.from({ length: sat(n, 1) }, (_, i) =>
+    Math.max(SEQ_GAP, Math.ceil(boxW[i] / 2) + Math.ceil(boxW[i + 1] / 2) + 1),
+  )
+
+  // Each requirement is "columns l..r together need at least `need` cells".
+  const reqs: [number, number, number][] = []
+  for (const item of seq.items) {
+    if (item.kind === 'message') {
+      const tw = itemTextW(item.text)
+      if (item.from !== item.to) {
+        reqs.push([Math.min(item.from, item.to), Math.max(item.from, item.to), Math.max(tw + 2, 4)])
+      } else if (item.from + 1 < n) {
+        reqs.push([item.from, item.from + 1, 5 + tw + 2])
+      }
+    } else if (item.kind === 'note') {
+      const tw = stringWidth(item.text)
+      const a = item.anchor
+      if (a.kind === 'over' && a.from < a.to) {
+        reqs.push([a.from, a.to, sat(tw, 1)])
+      } else if (a.kind === 'over') {
+        const need = Math.ceil((tw + 4) / 2) + 2
+        if (a.from > 0) reqs.push([a.from - 1, a.from, need])
+        if (a.from + 1 < n) reqs.push([a.from, a.from + 1, need])
+      } else if (a.kind === 'left' && a.at > 0) {
+        reqs.push([a.at - 1, a.at, tw + 7])
+      } else if (a.kind === 'right' && a.at + 1 < n) {
+        reqs.push([a.at, a.at + 1, tw + 7])
+      }
+    }
+  }
+  // Narrowest spans first, so a wide requirement absorbs what they already gave.
+  reqs.sort((a, b) => a[1] - a[0] - (b[1] - b[0]))
+  for (const [l, r, need] of reqs) {
+    let cur = 0
+    for (let i = l; i < r; i++) cur += gaps[i]
+    if (cur < need) gaps[r - 1] += need - cur
+  }
+
+  const xs = new Array<number>(n)
+  xs[0] = half(boxW[0])
+  for (let i = 1; i < n; i++) xs[i] = xs[i - 1] + gaps[i - 1]
+
+  // A note left of the first participant has no gap to grow; shift the whole
+  // diagram right instead so the note box lands beside the lifeline, not on it.
+  let leftPad = 0
+  for (const item of seq.items) {
+    if (item.kind === 'note' && item.anchor.kind === 'left' && item.anchor.at === 0) {
+      const w = stringWidth(item.text) + 2 * PAD + 2
+      leftPad = Math.max(leftPad, sat(w + 1, xs[0]))
+    }
+  }
+  if (leftPad > 0) for (let i = 0; i < n; i++) xs[i] += leftPad
+
+  let canvasW = xs[n - 1] + Math.ceil(boxW[n - 1] / 2) + 1
+  for (const item of seq.items) {
+    if (item.kind === 'message' && item.from === item.to) {
+      canvasW = Math.max(canvasW, xs[item.from] + 5 + itemTextW(item.text) + 1)
+    } else if (item.kind === 'note') {
+      const g = noteGeometry(xs, item.anchor, stringWidth(item.text))
+      canvasW = Math.max(canvasW, g.x + g.w + 1)
+    } else if (item.kind === 'divider') {
+      canvasW = Math.max(canvasW, stringWidth(item.text) + 4)
+    }
+  }
+
+  const rows: number[] = []
+  let y = boxH + 1
+  for (const item of seq.items) {
+    rows.push(y)
+    y += rowHeight(item)
+  }
+  const bottomTop = y
+  const canvasH = bottomTop + boxH
+
+  if (canvasW * canvasH > MAX_CANVAS_CELLS) return null
+
+  const canvas = new Canvas(canvasW, canvasH)
+
+  for (let i = 0; i < n; i++) {
+    for (const by of [0, bottomTop]) {
+      drawBox(canvas, box(sat(xs[i], half(boxW[i])), by, boxW[i], boxH), [labels[i]], 'rect')
+    }
+  }
+  seq.items.forEach((item, k) => {
+    if (item.kind !== 'note') return
+    const g = noteGeometry(xs, item.anchor, stringWidth(item.text))
+    drawBox(canvas, box(g.x, rows[k], g.w, 3), [item.text], 'rect')
+  })
+
+  for (const x of xs) {
+    canvas.junction(x, boxH - 1, D)
+    canvas.segV(x, boxH, bottomTop - 1)
+    canvas.junction(x, bottomTop, U)
+  }
+
+  seq.items.forEach((item, k) => {
+    const r = rows[k]
+    if (item.kind === 'message') drawMessage(canvas, item, xs, r)
+    else if (item.kind === 'divider') drawDivider(canvas, item.text, r, canvasW)
+  })
+
+  // Activations turn the lifeline into a double line from the activating
+  // message's arrow row to the deactivating one's (to the bottom while still
+  // open) — two rails, echoing mermaid's slim activation rectangle. Setting
+  // the glyph directly leaves the mask bits for `finalizeMask`, whose
+  // double-tee pass resolves message junctions on the run (║ → ╟ ╢ ╫).
+  const startRow = (k: number): number => {
+    const item = seq.items[k]
+    const labeled = item.kind === 'message' && item.from !== item.to && item.text !== null
+    return rows[k] + (labeled ? 1 : 0)
+  }
+  const endRow = (k: number): number => {
+    const item = seq.items[k]
+    // A self-message stub returns two rows below where it left.
+    return item.kind === 'message' && item.from === item.to ? rows[k] + 2 : startRow(k)
+  }
+  for (const a of seq.activations) {
+    const y1 = a.to === null ? bottomTop - 1 : endRow(a.to)
+    for (let y = startRow(a.from); y <= y1; y++) {
+      const i = canvas.idx(xs[a.at], y)
+      if (canvas.mask[i] !== 0) canvas.ch[i] = '║'
+    }
+  }
+
+  canvas.finalizeMask()
+  return canvas
+}
+
+function rowHeight(item: SeqItem): number {
+  if (item.kind === 'note') return 4
+  if (item.kind === 'divider') return 2
+  if (item.from === item.to) return 4
+  return item.text !== null ? 3 : 2
+}
+
+/** Geometry for a box drawn by position and size; ranks are irrelevant here. */
+const box = (x: number, y: number, w: number, h: number): Placed => ({
+  x,
+  y,
+  w,
+  h,
+  cx: x + half(w),
+  cy: y + 1,
+  rank: 0,
+})
+
+function drawMessage(
+  canvas: Canvas,
+  item: Extract<SeqItem, { kind: 'message' }>,
+  xs: number[],
+  r: number,
+): void {
+  const lineCh = item.dashed ? '╌' : '─'
+
+  if (item.from === item.to) {
+    // A stub that leaves the lifeline and returns two rows down.
+    const x = xs[item.from]
+    canvas.junction(x, r, R)
+    canvas.set(x + 1, r, lineCh, 'edge')
+    canvas.set(x + 2, r, lineCh, 'edge')
+    canvas.set(x + 3, r, '╮', 'edge')
+    canvas.set(x + 3, r + 1, '│', 'edge')
+    canvas.set(x + 1, r + 2, item.head === 'cross' ? '×' : '◄', 'edge')
+    canvas.set(x + 2, r + 2, lineCh, 'edge')
+    canvas.set(x + 3, r + 2, '╯', 'edge')
+    if (item.text !== null) drawTextOverEdges(canvas, item.text, x + 5, r + 1, 'text')
+    return
+  }
+
+  const x0 = xs[item.from]
+  const x1 = xs[item.to]
+  const rightward = x1 > x0
+  // A labelled message writes its text on `r` and draws the arrow below it.
+  const arrowRow = item.text !== null ? r + 1 : r
+  const lo = Math.min(x0, x1)
+  const hi = Math.max(x0, x1)
+
+  canvas.junction(x0, arrowRow, rightward ? R : L)
+  for (let x = lo + 1; x < hi; x++) canvas.set(x, arrowRow, lineCh, 'edge')
+  const headCh = item.head === 'cross' ? '×' : rightward ? '▶' : '◄'
+  canvas.set(rightward ? x1 - 1 : x1 + 1, arrowRow, headCh, 'edge')
+
+  if (item.text !== null) {
+    const span = hi - lo - 1
+    const t = fitLabel(item.text, Math.max(1, span))
+    drawTextOverEdges(canvas, t, lo + 1 + half(sat(span, stringWidth(t))), r, 'text')
+  }
+}
+
+/** A full-width rule labelling a `loop` / `alt` / `opt` block boundary. */
+function drawDivider(canvas: Canvas, text: string, r: number, canvasW: number): void {
+  for (let x = 0; x < canvasW; x++) canvas.set(x, r, '─', 'edge')
+  drawTextOverEdges(canvas, ` ${fitLabel(text, sat(canvasW, 4))} `, 2, r, 'edgeLabel')
+}