zombie-mermaid 2.2.1 → 2.2.2

package/{src/ascii → packages/ascii-renderer/src}/er-diagram.ts

@@ -9,13 +9,13 @@
 // Relationship lines use Manhattan routing between entity boxes.
 // ============================================================================
 
-import { parseErDiagram } from '../er/parser.ts'
+import { parseErDiagram } from '@zombie-mermaid/mermaid-parser'
 import type {
   ErDiagram,
   ErEntity,
   ErAttribute,
   Cardinality,
-} from '../er/types.ts'
+} from '@zombie-mermaid/mermaid-parser'
 import type {
   AsciiConfig,
   CharRole,

package/packages/ascii-renderer/src/flowchart.ts

@@ -0,0 +1,94 @@
+// ============================================================================
+// ASCII renderer — Flowchart / state diagram
+//
+// Renders flowcharts (graph TD / flowchart LR) and state diagrams
+// (stateDiagram-v2) to ASCII/Unicode box-drawing art via the shared
+// grid-based layout + A* pathfinding pipeline (converter -> grid -> draw).
+//
+// Extracted from the inline sequence that used to live directly in
+// `renderMermaidASCII`'s switch/fallback (src/ascii/index.ts) so flowchart
+// can be registered in `asciiRegistry` (src/ascii/registry.ts) alongside
+// every other diagram type — see
+// docs/decisions/diagram-type-registry-partial.md and issue #745. A pure,
+// behavior-preserving extraction: same functions, same call order, same
+// arguments.
+// ============================================================================
+
+import { parseMermaid } from '../../../src/parser.ts'
+import { withDirectionOverride } from '@zombie-mermaid/core'
+import type { Direction } from '@zombie-mermaid/core'
+import { convertToAsciiGraph } from './converter.ts'
+import { createMapping } from './grid.ts'
+import { drawGraph } from './draw.ts'
+import {
+  canvasToString,
+  flipCanvasVertically,
+  flipRoleCanvasVertically,
+} from './canvas.ts'
+import { buildNodeLinkCanvas, flipLinkCanvasVertically } from './hyperlinks.ts'
+import type { AsciiConfig, AsciiTheme, ColorMode } from './types.ts'
+
+/**
+ * Flowchart-only ASCII extras: `direction` (override the parsed top-level
+ * direction, same semantics as `RenderOptions.direction` for SVG — see
+ * issue #276) and `hyperlinks` (OSC 8 terminal links). No other registered
+ * ASCII type reads `direction`; `hyperlinks` is shared with `class` (see
+ * `AsciiRenderExtras` in ./registry.ts).
+ */
+export interface FlowchartAsciiExtras {
+  direction?: Direction
+  hyperlinks?: boolean
+}
+
+/**
+ * Render a flowchart or state diagram to ASCII/Unicode text art.
+ *
+ * Matches every other diagram type's ASCII entry-point shape
+ * (`text, config, colorMode, theme, extras`) so it can slot into
+ * `asciiRegistry` — see ./registry.ts.
+ */
+export function renderFlowchartAscii(
+  text: string,
+  config: AsciiConfig,
+  colorMode: ColorMode,
+  theme: AsciiTheme,
+  extras: FlowchartAsciiExtras = {},
+): string {
+  // `extras.direction` replaces the parsed top-level direction before
+  // layout; see packages/core/src/direction-override.ts.
+  const parsed = withDirectionOverride(parseMermaid(text), extras.direction)
+
+  // Normalize direction for grid layout.
+  // BT is laid out as TD then flipped vertically after drawing.
+  // RL is treated as LR (full RL support not yet implemented).
+  if (parsed.direction === 'LR' || parsed.direction === 'RL') {
+    config.graphDirection = 'LR'
+  } else {
+    config.graphDirection = 'TD'
+  }
+
+  const graph = convertToAsciiGraph(parsed, config)
+  createMapping(graph)
+  drawGraph(graph)
+
+  // Opt-in OSC 8 hyperlinks: mark each `click`-linked node's label cells
+  // now, from the drawn node positions, before any flip below moves them.
+  const linkCanvas = extras.hyperlinks
+    ? buildNodeLinkCanvas(graph, parsed.interactions)
+    : undefined
+
+  // BT: flip the finished canvas vertically so the flow runs bottom→top.
+  // The grid layout ran as TD; flipping + character remapping produces BT.
+  if (parsed.direction === 'BT') {
+    flipCanvasVertically(graph.canvas)
+    flipRoleCanvasVertically(graph.roleCanvas)
+    if (linkCanvas) flipLinkCanvasVertically(linkCanvas)
+  }
+
+  return canvasToString(graph.canvas, {
+    roleCanvas: graph.roleCanvas,
+    colorMode,
+    theme,
+    linkCanvas,
+  })
+}

package/{src/ascii → packages/ascii-renderer/src}/grid.ts

@@ -40,6 +40,8 @@ import {
 } from './edge-cell-styles.ts'
 import { drawBox } from './draw.ts'
 import { getShapeDimensions } from './shapes/index.ts'
+import { splitLines } from './multiline-utils.ts'
+import { displayWidth } from './display-width.ts'
 
 // `requireGridCoord` is defined in types.ts (a pure predicate over
 // AsciiNode with no grid-state dependency) and re-exported here so the two
@@ -469,6 +471,27 @@ function calculateSubgraphBoundingBox(
   sg.minY = minY - subgraphPadding - subgraphLabelSpace
   sg.maxX = maxX + subgraphPadding
   sg.maxY = maxY + subgraphPadding
+
+  // Widen the box, if necessary, so the subgraph's own cluster label fits
+  // without truncation. `drawSubgraphLabel` (draw-subgraphs.ts) writes the
+  // label into the interior columns `1..width-1` (width = maxX - minX), so
+  // the box needs `width >= labelWidth + 1` to avoid clipping the label
+  // against its own right border. Widening symmetrically (splitting any
+  // extra columns across both sides) keeps the child nodes visually
+  // centered inside the enlarged box rather than skewing it to one side.
+  const labelWidth = Math.max(
+    0,
+    ...splitLines(sg.name).map((line) => displayWidth(line)),
+  )
+  const currentWidth = sg.maxX - sg.minX
+  const requiredWidth = labelWidth + 1
+  if (requiredWidth > currentWidth) {
+    const extra = requiredWidth - currentWidth
+    const extraLeft = Math.floor(extra / 2)
+    const extraRight = extra - extraLeft
+    sg.minX -= extraLeft
+    sg.maxX += extraRight
+  }
 }
 
 /** Ensure non-overlapping root subgraphs have minimum spacing. */

package/{src/ascii → packages/ascii-renderer/src}/index.ts

@@ -16,22 +16,10 @@
 //   const ascii = renderMermaidASCII('graph LR\n  A --> B')
 // ============================================================================
 
-import { parseMermaid } from '../parser.ts'
-import { withDirectionOverride, detectDiagramType } from '@zombie-mermaid/core'
+import { detectDiagramType } from '@zombie-mermaid/core'
 import type { Direction, DiagramType } from '@zombie-mermaid/core'
-import { convertToAsciiGraph } from './converter.ts'
-import { createMapping } from './grid.ts'
-import { drawGraph } from './draw.ts'
-import {
-  canvasToString,
-  flipCanvasVertically,
-  flipRoleCanvasVertically,
-} from './canvas.ts'
-import { renderSequenceAscii } from './sequence.ts'
-import { renderClassAscii } from './class-diagram.ts'
 import { asciiRegistry } from './registry.ts'
 import { addCoordsOverlay } from './coords.ts'
-import { buildNodeLinkCanvas, flipLinkCanvasVertically } from './hyperlinks.ts'
 import {
   detectColorMode,
   DEFAULT_ASCII_THEME,
@@ -142,7 +130,7 @@ export function renderMermaidASCII(
     paddingX: options.paddingX ?? DEFAULT_PADDING_X,
     paddingY: options.paddingY ?? DEFAULT_PADDING_Y,
     boxBorderPadding: options.boxBorderPadding ?? DEFAULT_BOX_BORDER_PADDING,
-    graphDirection: 'TD', // default, overridden for flowcharts below
+    graphDirection: 'TD', // default; renderFlowchartAscii overrides this for flowcharts/state diagrams
   }
 
   // Resolve color mode ('auto' or unset → detect environment, otherwise use specified mode)
@@ -156,76 +144,17 @@ export function renderMermaidASCII(
 
   const diagramType: DiagramType = detectDiagramType(text)
 
-  let result: string
-
-  // Registry lookup first (see src/ascii/registry.ts — issue #533):
-  // 'xychart' and 'er' are registered there and dispatch to the exact same
-  // renderer calls their switch cases below used to make. Anything not
-  // registered (currently 'sequence', 'class', 'flowchart') falls through
-  // to the switch, unchanged.
-  const registered = asciiRegistry[diagramType]
-
-  if (registered) {
-    result = registered(text, config, colorMode, theme, {})
-    return options.showCoords ? addCoordsOverlay(result) : result
-  }
-
-  switch (diagramType) {
-    case 'sequence':
-      result = renderSequenceAscii(text, config, colorMode, theme)
-      break
-
-    case 'class':
-      result = renderClassAscii(text, config, colorMode, theme, {
-        hyperlinks: options.hyperlinks ?? false,
-      })
-      break
-
-    case 'flowchart':
-    default: {
-      // Flowchart + state diagram pipeline (original). `options.direction`
-      // replaces the parsed top-level direction before layout; see
-      // packages/core/src/direction-override.ts.
-      const parsed = withDirectionOverride(
-        parseMermaid(text),
-        options.direction,
-      )
-
-      // Normalize direction for grid layout.
-      // BT is laid out as TD then flipped vertically after drawing.
-      // RL is treated as LR (full RL support not yet implemented).
-      if (parsed.direction === 'LR' || parsed.direction === 'RL') {
-        config.graphDirection = 'LR'
-      } else {
-        config.graphDirection = 'TD'
-      }
-
-      const graph = convertToAsciiGraph(parsed, config)
-      createMapping(graph)
-      drawGraph(graph)
-
-      // Opt-in OSC 8 hyperlinks: mark each `click`-linked node's label cells
-      // now, from the drawn node positions, before any flip below moves them.
-      const linkCanvas = options.hyperlinks
-        ? buildNodeLinkCanvas(graph, parsed.interactions)
-        : undefined
-
-      // BT: flip the finished canvas vertically so the flow runs bottom→top.
-      // The grid layout ran as TD; flipping + character remapping produces BT.
-      if (parsed.direction === 'BT') {
-        flipCanvasVertically(graph.canvas)
-        flipRoleCanvasVertically(graph.roleCanvas)
-        if (linkCanvas) flipLinkCanvasVertically(linkCanvas)
-      }
-
-      result = canvasToString(graph.canvas, {
-        roleCanvas: graph.roleCanvas,
-        colorMode,
-        theme,
-        linkCanvas,
-      })
-    }
-  }
+  // Registry dispatch (see src/ascii/registry.ts — issue #533 / #745):
+  // every diagram type, including 'flowchart', is registered there and
+  // dispatches to the exact same renderer calls each type's original
+  // switch case (or, for 'flowchart', inline sequence) used to make.
+  // `extras` carries every ASCII-only per-type option: `hyperlinks` (read
+  // by 'class' and 'flowchart') and `direction` (read by 'flowchart'
+  // only); both are ignored by every other registered type.
+  const result = asciiRegistry[diagramType](text, config, colorMode, theme, {
+    hyperlinks: options.hyperlinks ?? false,
+    direction: options.direction,
+  })
 
   return options.showCoords ? addCoordsOverlay(result) : result
 }

package/{src/ascii → packages/ascii-renderer/src}/registry.ts

@@ -25,27 +25,31 @@
 // no longer names anything under `src/ascii/`. Both directions are now
 // one-way, and the set of registered types stays a single decision per
 // renderer rather than a `switch` re-listed at each front door — the point of
-// #533. Adding a type to one renderer's table without the other is now
-// expressible, which matches reality: 'sequence'/'class'/'flowchart' are
-// unregistered on both sides today only because neither renderer's signature
-// has been adapted yet, not because the two must move in lockstep.
+// #533. Adding a type to one renderer's table without the other is
+// expressible in principle, though in practice 'xychart'/'er'/'sequence'/
+// 'class'/'flowchart' now move together on both sides.
 // ============================================================================
 
-import type { DiagramType } from '@zombie-mermaid/core'
+import type { DiagramType, Direction } from '@zombie-mermaid/core'
 import type { AsciiConfig, AsciiTheme, ColorMode } from './types.ts'
 import { renderXYChartAscii } from './xychart.ts'
 import { renderErAscii } from './er-diagram.ts'
+import { renderSequenceAscii } from './sequence.ts'
+import { renderClassAscii } from './class-diagram.ts'
+import { renderFlowchartAscii } from './flowchart.ts'
 
 /**
- * Small, closed set of ASCII-only extras not every type needs — today only
- * `class` reads `hyperlinks` (see `ClassAsciiOptions` in
- * src/ascii/class-diagram.ts), and `class` is not registered here yet. Kept
+ * Small, closed set of ASCII-only extras not every type needs — `class`
+ * reads `hyperlinks` (see `ClassAsciiOptions` in
+ * src/ascii/class-diagram.ts), `flowchart` reads both `direction` and
+ * `hyperlinks` (see `FlowchartAsciiExtras` in src/ascii/flowchart.ts). Kept
  * as its own type rather than reusing `AsciiRenderOptions` from
  * src/ascii/index.ts so this module stays a leaf of the ASCII tree: index.ts
  * imports it, never the other way round.
  */
 export interface AsciiRenderExtras {
   hyperlinks?: boolean
+  direction?: Direction
 }
 
 /**
@@ -65,13 +69,20 @@ export type AsciiRenderer = (
 ) => string
 
 /**
- * Types `renderMermaidASCII` dispatches through the registry. Anything
- * absent (currently 'sequence', 'class', 'flowchart') falls through to that
- * function's own switch, unchanged.
+ * Every diagram type `renderMermaidASCII` supports, dispatched through this
+ * table — see that function in src/ascii/index.ts, which has no fallback
+ * switch left now that 'flowchart' (the last holdout — see
+ * docs/decisions/diagram-type-registry-partial.md) is registered here too.
  */
-export const asciiRegistry: Partial<Record<DiagramType, AsciiRenderer>> = {
+export const asciiRegistry: Record<DiagramType, AsciiRenderer> = {
   xychart: (text, config, colorMode, theme) =>
     renderXYChartAscii(text, config, colorMode, theme),
   er: (text, config, colorMode, theme) =>
     renderErAscii(text, config, colorMode, theme),
+  sequence: (text, config, colorMode, theme) =>
+    renderSequenceAscii(text, config, colorMode, theme),
+  class: (text, config, colorMode, theme, extras) =>
+    renderClassAscii(text, config, colorMode, theme, extras),
+  flowchart: (text, config, colorMode, theme, extras) =>
+    renderFlowchartAscii(text, config, colorMode, theme, extras),
 }

package/{src/ascii → packages/ascii-renderer/src}/sequence.ts

@@ -9,8 +9,8 @@
 // Instead: actors → columns, messages → rows, all positioned linearly.
 // ============================================================================
 
-import { parseSequenceDiagram } from '../sequence/parser.ts'
-import type { Block } from '../sequence/types.ts'
+import { parseSequenceDiagram } from '@zombie-mermaid/mermaid-parser'
+import type { Block } from '@zombie-mermaid/mermaid-parser'
 import type { AsciiConfig, CharRole, AsciiTheme, ColorMode } from './types.ts'
 import {
   mkCanvas,
@@ -28,7 +28,7 @@ import {
   toDisplayCells,
   WIDE_CHAR_PLACEHOLDER,
 } from './display-width.ts'
-import type { Message } from '../sequence/types.ts'
+import type { Message } from '@zombie-mermaid/mermaid-parser'
 import { DEFAULT_PADDING_X, DEFAULT_PADDING_Y, paddingOffset } from './types.ts'
 
 // Width of a self-message's loop glyphs (├──┐ / ◀──┘), excluding the label.
@@ -256,6 +256,37 @@ export function renderSequenceAscii(
     }
   }
 
+  // Width (including border + padding, matching the box drawn in the
+  // vertical-layout pass below) of a note anchored to an actor. Computed up
+  // front, before lifeline x-positions are finalized, so `left`/`right`
+  // notes can participate in gap sizing the same way message labels already
+  // do (issue #953 case C) instead of only being checked against a layout
+  // that's already fixed.
+  function noteBoxWidth(note: (typeof diagram.notes)[number]): number {
+    const nLines = splitLines(note.text)
+    return Math.max(...nLines.map((l) => displayWidth(l))) + 2 + 2 * boxPad
+  }
+
+  // Per-actor widest 'left'/'right' note anchored to it. A `left` note on
+  // actor i draws into the gap to its left (between actor i-1 and i, or —
+  // for the leftmost actor — the canvas's own left margin); a `right` note
+  // draws into the gap to its right (between actor i and i+1). Both need to
+  // be reserved as part of layout, not clamped after the fact (issue #953
+  // cases A-C: notes previously only ever collided with whatever gap
+  // message-label sizing happened to leave).
+  const leftNoteWidth: number[] = new Array(diagram.actors.length).fill(0)
+  const rightNoteWidth: number[] = new Array(diagram.actors.length).fill(0)
+  for (const note of diagram.notes) {
+    if (note.position !== 'left' && note.position !== 'right') continue
+    const aIdx = actorIdx.get(note.actorIds[0]!) ?? 0
+    const w = noteBoxWidth(note)
+    if (note.position === 'left') {
+      leftNoteWidth[aIdx] = Math.max(leftNoteWidth[aIdx]!, w)
+    } else {
+      rightNoteWidth[aIdx] = Math.max(rightNoteWidth[aIdx]!, w)
+    }
+  }
+
   // Compute lifeline x-positions (greedy left-to-right).
   // See paddingOffset's doc comment (types.ts) for why this is an offset
   // from the paddingX default rather than the raw config value.
@@ -269,8 +300,19 @@ export function renderSequenceAscii(
   // adjacent participants in different groups (or one grouped, one not)
   // need room for the wall(s) between their boxes, plus a blank column on
   // each side of every wall. Same-group neighbours have no wall between.
+  //
+  // A `left` note on the leftmost actor has no left neighbour to reserve a
+  // gap against — it draws into the canvas's own left margin instead, so
+  // that margin (the initial lifeline position itself) must be at least
+  // wide enough for it: `nx = llX[0] - nWidth - 1 >= 0` (see the note-x
+  // calculation below) requires `llX[0] >= nWidth + 1` (issue #953 case A —
+  // previously `nx` was clamped to 0 instead, forcing the note onto the
+  // lifeline it's supposed to sit beside).
   const llX: number[] = [
-    halfBox[0]! + (boxSpanOf[0] === -1 ? 0 : BRACKET_GAP + 1),
+    Math.max(
+      halfBox[0]! + (boxSpanOf[0] === -1 ? 0 : BRACKET_GAP + 1),
+      leftNoteWidth[0]! + 1,
+    ),
   ]
   for (let i = 1; i < diagram.actors.length; i++) {
     const prevSpan = boxSpanOf[i - 1]!
@@ -282,9 +324,16 @@ export function renderSequenceAscii(
     // The base constraint already leaves two blank columns between boxes;
     // each wall needs one column of its own plus one more blank beside it.
     const wallExtra = walls === 0 ? 0 : walls * (BRACKET_GAP + 1) - 1
+    // A `right` note on actor i-1, or a `left` note on actor i, draws into
+    // this gap — reserve room for whichever is wider (issue #953 cases B/C)
+    // so a wide note doesn't overflow into the neighbouring lifeline. The
+    // `+2` mirrors adjMaxWidth's own margin below and matches the 1-column
+    // clearance the note-x calculation already leaves on the lifeline side.
+    const noteGapNeed = Math.max(rightNoteWidth[i - 1]!, leftNoteWidth[i]!) + 2
     const gap = Math.max(
       halfBox[i - 1]! + halfBox[i]! + 2 + wallExtra,
       adjMaxWidth[i - 1]! + 2,
+      noteGapNeed,
       minLifelineGap,
     )
     llX[i] = llX[i - 1]! + gap
@@ -435,8 +484,7 @@ export function renderSequenceAscii(
     if (note.afterIndex !== -1) continue
     curY += rowGap // gap before note
     const nLines = splitLines(note.text)
-    const nWidth =
-      Math.max(...nLines.map((l) => displayWidth(l))) + 2 + 2 * boxPad
+    const nWidth = noteBoxWidth(note)
     const nHeight = nLines.length + 2
 
     const aIdx = actorIdx.get(note.actorIds[0]!) ?? 0
@@ -533,8 +581,7 @@ export function renderSequenceAscii(
         curY += rowGap
         const note = diagram.notes[n]!
         const nLines = splitLines(note.text)
-        const nWidth =
-          Math.max(...nLines.map((l) => displayWidth(l))) + 2 + 2 * boxPad
+        const nWidth = noteBoxWidth(note)
         const nHeight = nLines.length + 2
 
         // Determine x position based on note.position

package/{src/ascii → packages/ascii-renderer/src}/xychart.ts

@@ -11,8 +11,12 @@
 // Multi-series support: each series gets a distinct color from a palette.
 // ============================================================================
 
-import { parseXYChart } from '../xychart/parser.ts'
-import type { XYChart } from '../xychart/types.ts'
+import {
+  parseXYChart,
+  getSeriesColor,
+  CHART_ACCENT_FALLBACK,
+} from '@zombie-mermaid/mermaid-parser'
+import type { XYChart } from '@zombie-mermaid/mermaid-parser'
 import type {
   AsciiConfig,
   AsciiTheme,
@@ -23,7 +27,6 @@ import type {
 } from './types.ts'
 import { colorizeText } from './ansi.ts'
 import { mkCanvas, mkRoleCanvas, write } from './canvas.ts'
-import { getSeriesColor, CHART_ACCENT_FALLBACK } from '../xychart/colors.ts'
 import { splitStatements } from '@zombie-mermaid/core'
 
 // ============================================================================

package/packages/core/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Craft Docs
+Copyright (c) 2026 Dustin Fadler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/packages/core/src/click-directive.ts

@@ -0,0 +1,106 @@
+import type { NodeInteraction } from './types.ts'
+
+// ============================================================================
+// Shared `click` directive parsing and href sanitization.
+//
+// Every diagram type that recognizes Mermaid's `click` statement (flowchart/
+// state via src/parser.ts, class diagrams via
+// packages/mermaid-parser/src/class/parser.ts) shares this exact grammar
+// and the same href-safety rules — pulled out here so
+// neither copy can drift from the other. See
+// docs/decisions/no-script-interactivity.md for the tier model this
+// implements: an `href` becomes a real `<a>` link (tier 2), a tooltip
+// becomes a `<title>` (tier 1), and a `call`/`callback` binding is recorded
+// as data but never executed (tier 3 stays unimplemented, permanently).
+// ============================================================================
+
+/**
+ * Parse a `click <id> ...` statement and record the resulting
+ * {@link NodeInteraction} in `interactions`, keyed by whatever id scheme the
+ * caller's diagram type uses (flowchart/state node id, class diagram class
+ * id, ...).
+ *
+ * Supported forms:
+ *   click id "url" ["tooltip"] [_blank|_self|_parent|_top]
+ *   click id href "url" ["tooltip"] [_blank|_self|_parent|_top]
+ *   click id call fn() ["tooltip"]
+ *   click id callback fn() ["tooltip"]
+ *
+ * A line that doesn't match `click <id> ...` at all is a no-op — callers are
+ * expected to have already gated on a leading `click` keyword before calling
+ * this (see the `/^click\s+/i` checks at each call site) purely so this
+ * function's own regex can stay anchored to the id capture.
+ */
+export function applyClickStatement(
+  line: string,
+  interactions: Map<string, NodeInteraction>,
+): void {
+  const match = line.match(/^click\s+([\w\p{L}-]+)\s+(.*)$/iu)
+  if (!match) return
+
+  const nodeId = match[1]!
+  let rest = match[2]!.trim()
+
+  const interaction: NodeInteraction = { ...interactions.get(nodeId) }
+
+  // `call fn()` / `callback fn()` — a script binding.
+  const callMatch = rest.match(/^(?:call|callback)\s+(.+?)\s*$/i)
+  if (callMatch) {
+    // A trailing quoted tooltip may follow the callback expression.
+    const withTooltip = callMatch[1]!.match(/^(.*?\))\s+"([^"]*)"\s*$/)
+    if (withTooltip) {
+      interaction.callback = withTooltip[1]!.trim()
+      interaction.tooltip = withTooltip[2]
+    } else {
+      interaction.callback = callMatch[1]!.trim()
+    }
+    interactions.set(nodeId, interaction)
+    return
+  }
+
+  // Optional explicit `href` keyword.
+  rest = rest.replace(/^href\s+/i, '')
+
+  // Remaining tokens: "url" ["tooltip"] [_target]
+  const quoted = [...rest.matchAll(/"([^"]*)"/g)].map((m) => m[1]!)
+  if (quoted.length > 0) interaction.href = quoted[0]
+  if (quoted.length > 1) interaction.tooltip = quoted[1]
+
+  const targetMatch = rest.match(/(_blank|_self|_parent|_top)\s*$/i)
+  if (targetMatch) interaction.target = targetMatch[1]!.toLowerCase()
+
+  if (interaction.href !== undefined || interaction.tooltip !== undefined) {
+    interactions.set(nodeId, interaction)
+  }
+}
+
+/**
+ * Accept only link schemes that cannot execute script.
+ *
+ * A `click` target comes from diagram text, which may be untrusted. An
+ * `href` of `javascript:...` (or a `data:` URL containing markup) would turn
+ * a rendered diagram into an XSS vector for any page that inlines the SVG, so
+ * anything but http/https/mailto and same-document or relative references is
+ * dropped rather than emitted.
+ *
+ * C0 controls are rejected outright, before any other check. The URL parser
+ * strips tab and newline from *anywhere* in a URL, so `java\tscript:` reaches
+ * a browser as `javascript:` — while the scheme match below sees `java\t…`,
+ * finds no scheme, and waves it through as a relative reference. Splitting a
+ * blocked scheme with a control character is the whole bypass; there is no
+ * legitimate URL with a raw control in it, so the entire range goes.
+ */
+export function safeHref(href: string | undefined): string | undefined {
+  if (!href) return undefined
+
+  if (/[\x00-\x1F\x7F]/.test(href)) return undefined
+
+  const trimmed = href.trim()
+  // Relative, absolute-path, and fragment references carry no scheme.
+  if (/^[./#?]/.test(trimmed)) return trimmed
+
+  const scheme = trimmed.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/)?.[1]
+  if (scheme === undefined) return trimmed
+
+  return /^(https?|mailto)$/i.test(scheme) ? trimmed : undefined
+}