@jarenjs/mermaid 0.34.0

package/src/parser/sequence.js

@@ -0,0 +1,156 @@
+//@ts-check
+/**
+ * @file Sequence grammar → sequence AST. Flowchart and sequence are
+ * the two fully-modeled diagram types; this is the second.
+ *
+ * Line-oriented, with a block stack for loop/alt/opt/par/critical/break.
+ * Explicitly declared participants keep their declaration order; a
+ * message to an undeclared actor is legal (the layout pass creates the
+ * lifeline), so the AST records only what the source states — faithful
+ * and geometry-free. Module-const regexes only.
+ */
+
+import {
+  seqParticipant, seqMessage, seqNote, seqActivation, seqBlock, sequenceAst,
+} from '../ast.js';
+import { fail } from '../errors.js';
+import { firstToken } from '../utils.js';
+
+/** A message: `A->>+B: text`. */
+const RE_MSG = /^([^-<>:]+?)\s*((?:-{1,2})(?:>>|>|x|\)))\s*([+-]?)\s*([^:]+?)\s*:\s*(.*)$/;
+/** `participant A as Alice` / `actor A`. */
+const RE_PARTICIPANT = /^(participant|actor)\s+(.+)$/;
+/** `note left of A: t` / `note right of A: t` / `note over A,B: t`. */
+const RE_NOTE = /^[Nn]ote\s+(left of|right of|over)\s+([^:]+):\s*(.*)$/;
+
+/** Block openers whose first word starts a frame. */
+const OPEN_BLOCKS = new Set(['loop', 'opt', 'alt', 'par', 'critical', 'break', 'rect']);
+
+/**
+ * @param {string[]} lines body lines (config stripped)
+ * @param {number} lineOffset absolute line number of `lines[0]`
+ * @returns {object}
+ */
+export function parseSequence(lines, lineOffset) {
+  const participants = [];
+  const seen = new Set();
+  const rootStatements = [];
+  let current = rootStatements;
+  /** @type {{ block: any, parent: any[], skip: boolean }[]} */
+  const stack = [];
+  let autonumber = false;
+
+  const declare = (id, label, kind) => {
+    if (seen.has(id)) return;
+    seen.add(id);
+    participants.push(seqParticipant(id, label ?? id, kind));
+  };
+
+  for (let li = 0; li < lines.length; li++) {
+    const line = lines[li].trim();
+    if (line === '') continue;
+    const lineNo = lineOffset + li + 1;
+    const firstWord = firstToken(line);
+
+    if (line === 'autonumber') { autonumber = true; continue; }
+
+    if (firstWord === 'participant' || firstWord === 'actor') {
+      const m = RE_PARTICIPANT.exec(line);
+      if (m !== null) {
+        const { id, label } = splitAlias(m[2].trim());
+        declare(id, label, /** @type {any} */ (m[1]));
+      }
+      continue;
+    }
+
+    if (firstWord === 'activate' || firstWord === 'deactivate') {
+      const actor = line.slice(firstWord.length).trim();
+      current.push(seqActivation(/** @type {any} */ (firstWord), actor));
+      continue;
+    }
+
+    if (/^[Nn]ote\s/.test(line)) {
+      const m = RE_NOTE.exec(line);
+      if (m !== null) {
+        const actors = m[2].split(',').map((s) => s.trim()).filter(Boolean);
+        current.push(seqNote(/** @type {any} */ (m[1]), actors, m[3].trim()));
+      }
+      continue;
+    }
+
+    // Block control.
+    if (OPEN_BLOCKS.has(firstWord)) {
+      const label = line.slice(firstWord.length).trim();
+      if (firstWord === 'rect') {
+        // Background rectangle: parse-accept, statements flow to parent.
+        stack.push({ block: null, parent: current, skip: true });
+        continue;
+      }
+      const block = seqBlock(/** @type {any} */ (firstWord), [{ label, statements: [] }]);
+      current.push(block);
+      stack.push({ block, parent: current, skip: false });
+      current = block.branches[0].statements;
+      continue;
+    }
+    if (firstWord === 'else' || firstWord === 'and' || firstWord === 'option') {
+      const top = stack[stack.length - 1];
+      if (top === undefined || top.block === null) {
+        fail(`'${firstWord}' outside a block`, lineNo);
+      }
+      const branch = { label: line.slice(firstWord.length).trim(), statements: [] };
+      top.block.branches.push(branch);
+      current = branch.statements;
+      continue;
+    }
+    if (line === 'end') {
+      const entry = stack.pop();
+      if (entry === undefined) fail("unexpected 'end'", lineNo);
+      current = entry.parent;
+      continue;
+    }
+
+    // A message.
+    const mm = RE_MSG.exec(line);
+    if (mm !== null) {
+      const from = mm[1].trim();
+      const arrow = mm[2];
+      const activation = mm[3] === '+' ? 'activate' : mm[3] === '-' ? 'deactivate' : null;
+      const to = mm[4].trim();
+      const text = mm[5];
+      declare(from, from, 'participant');
+      declare(to, to, 'participant');
+      const { line: lineStyle, head } = classifyArrow(arrow);
+      current.push(seqMessage(from, to, text, lineStyle, head, /** @type {any} */ (activation)));
+      continue;
+    }
+
+    // Unknown directive — lenient parse-accept (title:, links, etc.).
+  }
+
+  return sequenceAst(participants, rootStatements, autonumber);
+}
+
+/**
+ * Classify a sequence arrow token into line style + head.
+ * @param {string} arrow
+ * @returns {{ line: 'solid'|'dotted', head: 'arrow'|'open'|'cross'|'point' }}
+ */
+function classifyArrow(arrow) {
+  const line = arrow.startsWith('--') ? 'dotted' : 'solid';
+  const head = arrow.endsWith('>>') ? 'arrow'
+    : arrow.endsWith('x') ? 'cross'
+      : arrow.endsWith(')') ? 'point'
+        : 'open';
+  return { line, head };
+}
+
+/**
+ * `A as Alice` → { id, label }; `A` → { id, label: id }.
+ * @param {string} text
+ * @returns {{ id: string, label: string }}
+ */
+function splitAlias(text) {
+  const idx = text.indexOf(' as ');
+  if (idx === -1) return { id: text.trim(), label: text.trim() };
+  return { id: text.slice(0, idx).trim(), label: text.slice(idx + 4).trim() };
+}

package/src/parser/state.js

@@ -0,0 +1,137 @@
+//@ts-check
+/**
+ * @file State-diagram grammar (`stateDiagram-v2`) → state AST. Models
+ * the finite state machine faithfully: states, transitions
+ * (`A --> B : label`), the `[*]` start/end pseudo-states, `state "x" as
+ * s` descriptions and `s : desc` labels. This is the AST the flagship
+ * `state ⇄ workflow` JSLT projection consumes.
+ *
+ * A transition carries its verbatim `label` — what renderers draw and
+ * `toMermaid` prints — plus the label's UML reading, parsed into
+ * `event [guard] / effect` parts (each null when absent). A label that
+ * fits no UML pattern reads whole as the event, so plain labels keep
+ * their historical meaning byte for byte.
+ *
+ * Composite states (`state Foo { … }`) are flattened one level: the
+ * inner transitions are captured with their parent recorded, keeping the
+ * AST geometry-free.
+ */
+
+/** `A --> B` / `A --> B : label`. */
+const RE_TRANSITION = /^(\S+)\s*-->\s*(\S+)(?:\s*:\s*(.*))?$/;
+
+/**
+ * Read a transition label's UML parts: `event [guard] / effect`, every
+ * part optional. The first `[` opens the guard (nesting counted), and
+ * the effect starts at the first `/` after the guard (or the first `/`
+ * at all when there is none). Anything that breaks the pattern — an
+ * unmatched `[`, or text between `]` and `/` — reads whole as the
+ * event, which is exactly the historical meaning of a plain label.
+ * @param {string|null} label
+ * @returns {{ event: string|null, guard: string|null, effect: string|null }}
+ */
+function parseTransitionLabel(label) {
+  const part = (s) => {
+    const t = s.trim();
+    return t === '' ? null : t;
+  };
+  if (label === null) return { event: null, guard: null, effect: null };
+  const open = label.indexOf('[');
+  if (open === -1) {
+    const slash = label.indexOf('/');
+    if (slash === -1) return { event: part(label), guard: null, effect: null };
+    return { event: part(label.slice(0, slash)), guard: null, effect: part(label.slice(slash + 1)) };
+  }
+  let depth = 0;
+  let close = -1;
+  for (let i = open; i < label.length; i++) {
+    if (label[i] === '[') depth++;
+    else if (label[i] === ']') {
+      depth--;
+      if (depth === 0) { close = i; break; }
+    }
+  }
+  if (close === -1) return { event: part(label), guard: null, effect: null };
+  const after = label.slice(close + 1);
+  const slash = after.indexOf('/');
+  const between = slash === -1 ? after : after.slice(0, slash);
+  if (between.trim() !== '') return { event: part(label), guard: null, effect: null };
+  return {
+    event: part(label.slice(0, open)),
+    guard: part(label.slice(open + 1, close)),
+    effect: slash === -1 ? null : part(after.slice(slash + 1)),
+  };
+}
+/** `state "long description" as id`. */
+const RE_STATE_AS = /^state\s+"([^"]*)"\s+as\s+(\S+)\s*$/;
+/** `id : description`. */
+const RE_STATE_DESC = /^(\S+)\s*:\s*(.*)$/;
+
+/**
+ * @param {string[]} lines
+ * @returns {object}
+ */
+export function parseState(lines) {
+  /** @type {Map<string, { id: string, label: string }>} */
+  const stateMap = new Map();
+  const order = [];
+  const transitions = [];
+  /** @type {string[]} */
+  const parentStack = [];
+
+  const ensure = (id, label) => {
+    if (id === '[*]') return;
+    let st = stateMap.get(id);
+    if (st === undefined) {
+      st = { id, label: label ?? id };
+      stateMap.set(id, st);
+      order.push(id);
+    }
+    else if (label != null) {
+      st.label = label;
+    }
+  };
+
+  for (let li = 0; li < lines.length; li++) {
+    let line = lines[li].trim();
+    if (line === '' || line.startsWith('%%')) continue;
+    if (line === 'end' || line === '}') { parentStack.pop(); continue; }
+
+    // Composite state opener: `state Foo {`
+    if (line.startsWith('state ') && line.endsWith('{')) {
+      const inner = line.slice('state '.length, -1).trim();
+      const id = inner.split(/\s+/)[0];
+      ensure(id, id);
+      parentStack.push(id);
+      continue;
+    }
+
+    const sa = RE_STATE_AS.exec(line);
+    if (sa !== null) { ensure(sa[2], sa[1]); continue; }
+
+    const tr = RE_TRANSITION.exec(line);
+    if (tr !== null) {
+      if (tr[1] !== '[*]') ensure(tr[1], null);
+      if (tr[2] !== '[*]') ensure(tr[2], null);
+      const label = tr[3] ? tr[3].trim() : null;
+      const parts = parseTransitionLabel(label === '' ? null : label);
+      transitions.push({
+        from: tr[1],
+        to: tr[2],
+        label: label === '' ? null : label,
+        event: parts.event,
+        guard: parts.guard,
+        effect: parts.effect,
+        parent: parentStack.length ? parentStack[parentStack.length - 1] : null,
+      });
+      continue;
+    }
+
+    if (line.startsWith('state ')) { ensure(line.slice('state '.length).trim(), null); continue; }
+
+    const sd = RE_STATE_DESC.exec(line);
+    if (sd !== null && sd[1] !== '[*]') { ensure(sd[1], sd[2].trim()); continue; }
+  }
+
+  return { states: order.map((id) => stateMap.get(id)), transitions };
+}

package/src/plugin.js

@@ -0,0 +1,76 @@
+//@ts-check
+/**
+ * @file The Markdown plugin — the md→mermaid dependency arrow.
+ * `mermaidPlugin()` returns a **plain, self-frozen object**
+ * shaped exactly like `@jarenjs/md`'s `MdPlugin` typedef, but it does
+ * **not** import `definePlugin` from `@jarenjs/md` — so there is no
+ * import cycle. `@jarenjs/md` re-exports this and adds `@jarenjs/mermaid`
+ * to its dependencies; consumers who never use it tree-shake it away
+ * (`sideEffects:false`).
+ *
+ * `render` is pure, synchronous and error-safe: a `mermaid`
+ * fence becomes inline SVG with no injected instance and no `innerHTML`,
+ * so a Markdown document renders to a full SVG string through SSR with
+ * no browser — a capability the old injection wrapper lacked.
+ *
+ * `hydrate` exists only when a consumer asks for `interactive: true`. The
+ * render is complete without it: hydration adds pan/zoom/touch to an already
+ * finished SVG, so server output is byte-identical either way and a page that
+ * does not opt in never loads the module.
+ */
+
+import { diagramToVnode } from './render/index.js';
+import { toMermaid } from './to-mermaid.js';
+import { hashContent } from './utils.js';
+
+/**
+ * @param {{ theme?: any, [k: string]: any }} [options]
+ * @returns {Readonly<{ name: string, fences: string[], node: string, render: (node: any, h: any, ctx: any) => any }>}
+ */
+export function mermaidPlugin(options = {}) {
+  return Object.freeze({
+    name: 'mermaid',
+    fences: Object.freeze(['mermaid', 'mmd']),
+    node: 'mermaid',
+    /**
+     * @param {{ value: string, meta?: any }} node
+     */
+    render: (node) => {
+      const hash = hashContent(node.value);
+      const svg = diagramToVnode(node.value, options);
+      const props = { class: 'md-mermaid mermaid-block', key: hash };
+      // The hydrate marker is what the md component looks for; emitting it
+      // only when interactive keeps non-interactive output unchanged.
+      if (options.interactive === true) {
+        props['data-md-hydrate'] = 'mermaid';
+        props['data-md-hash'] = hash;
+      }
+      return ['div', props, svg];
+    },
+    ...(options.interactive === true
+      ? {
+        /**
+         * @param {any} el the rendered block element
+         */
+        hydrate: async (el) => {
+          const { attachInteractiveDiagram } = await import('./interactive.js');
+          attachInteractiveDiagram(el);
+        },
+      }
+      : {}),
+  });
+}
+
+/**
+ * Refresh a `mermaid` fence node's source after a JSLT transform so the
+ * generic Markdown fence printer re-emits the new diagram. Because
+ * there is no per-plugin `toMarkdown` hook, this is the primitive that
+ * makes a transformed diagram round-trip through `toMarkdown`.
+ *
+ * @param {{ value: string, [k: string]: any }} node the fence node (mutated copy is caller's job)
+ * @param {import('./ast.js').DiagramDocument} newDoc the transformed document
+ * @returns {{ type: string, value: string, meta: any }} a fresh fence node
+ */
+export function refreshMermaidFence(node, newDoc) {
+  return { type: 'mermaid', value: toMermaid(newDoc), meta: node.meta ?? null };
+}

package/src/render/error.js

@@ -0,0 +1,55 @@
+//@ts-check
+/**
+ * @file The error vnode. The render path never
+ * throws: a parse/layout failure becomes a clear error box — message +
+ * offending line — mirroring Mermaid's own error box, keyed so the
+ * patcher swaps it cleanly.
+ *
+ * It themes like every other diagram (DESIGN.md §7): concrete colors ride
+ * as presentation attributes so `toSvgString()` stays standalone-valid,
+ * and the root carries the inline `--mm-*` stamp plus a class per shape,
+ * so a host theme re-colors the error box along with the diagrams it
+ * replaces. The font is pinned to monospace because the box quotes source.
+ */
+
+import { rect, svgRoot, textAt } from '@jarenjs/view/helpers';
+import { hashContent } from '../utils.js';
+import { createTheme } from '../theme.js';
+
+/**
+ * @param {string} message
+ * @param {number} [line]
+ * @param {string} [sourceLine] the offending source line, if known
+ * @param {ReturnType<typeof createTheme>} [theme] the resolved theme; the
+ *   default keeps the vnode renderable on its own (a parse failure has no
+ *   document to read a theme from)
+ * @returns {any} an SVG error vnode
+ */
+export function errorVnode(message, line = 0, sourceLine = '', theme = createTheme('default')) {
+  const width = 520;
+  const height = sourceLine ? 96 : 72;
+  const key = 'mmerr-' + hashContent(message + ':' + line);
+  const lineLabel = line > 0 ? `Line ${line}: ` : '';
+  const t = theme.tokens;
+  return svgRoot('mermaid mm-error', width, height, theme, [
+    rect(1, 1, width - 2, height - 2, {
+      rx: 6, class: 'mm-error-box', fill: t.errFill, stroke: t.errStroke, 'stroke-width': 1.5,
+    }),
+    textAt(14, 26, 'Mermaid parse error', 14, {
+      class: 'mm-error-title', 'font-weight': 'bold', fill: t.errTitle,
+    }),
+    textAt(14, 48, lineLabel + message, 12, { class: 'mm-error-msg', fill: t.errText }),
+    ...(sourceLine
+      ? [textAt(14, 72, truncate(sourceLine, 72), 12, {
+        class: 'mm-error-source', fill: t.errSource, style: { 'white-space': 'pre' },
+      })]
+      : []),
+  ], key, { fontFamily: 'monospace' });
+}
+
+/**
+ * @param {string} s @param {number} max @returns {string}
+ */
+function truncate(s, max) {
+  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}

package/src/render/flowchart.js

@@ -0,0 +1,249 @@
+//@ts-check
+/**
+ * @file Flowchart renderer: `PositionedDiagram` → pure-vnode SVG. One
+ * specialized closure over the scene graph; arrowheads are inline
+ * polygons (no `<marker>` id collisions across diagrams on one page),
+ * every shape carries a `mm-*` class for CSS re-theming and concrete
+ * theme colors for standalone SSR.
+ */
+
+import {
+  svgRoot, group, rect, path, circle, polygon, textAt, textLines, num,
+} from '@jarenjs/view/helpers';
+
+import { shapeAttributes, shapeStyle, textColor } from '../styles.js';
+
+/**
+ * @param {any} scene PositionedDiagram (flowchart or state, via its adapter)
+ * @param {{ tokens: Record<string,string>, cssVars: Record<string,string> }} theme
+ * @param {string} hash content hash for the root key
+ * @param {string} [rootClass] root `class` — the state renderer adds `mm-state`
+ * @returns {any}
+ */
+export function renderFlowchart(scene, theme, hash, rootClass = 'mermaid mm-svg') {
+  const t = theme.tokens;
+  const children = [];
+
+  // Subgraph frames first (behind nodes).
+  for (const sg of scene.subgraphs) {
+    if (sg.w === 0) continue;
+    children.push(group({ class: 'mm-cluster', key: 'sg-' + sg.id }, [
+      rect(sg.x, sg.y, sg.w, sg.h, {
+        rx: 6, class: 'mm-cluster-rect',
+        fill: t.clusterFill, stroke: t.clusterStroke, 'stroke-width': 1,
+      }),
+      sg.label
+        ? textAt(sg.x + sg.w / 2, sg.y + 15, sg.label, scene.fontSize, {
+          'text-anchor': 'middle', class: 'mm-cluster-label', fill: t.nodeText,
+        })
+        : null,
+    ]));
+  }
+
+  // Edges (behind nodes so the node fill covers endpoints).
+  for (let i = 0; i < scene.edges.length; i++) {
+    const e = scene.edges[i];
+    if (e.points.length < 2) continue;
+    children.push(renderEdge(e, t, scene.fontSize, i));
+  }
+
+  // Nodes.
+  for (const node of scene.nodes) {
+    children.push(renderNode(node, t, scene.fontSize));
+  }
+
+  return svgRoot(rootClass, scene.width, scene.height, theme, children,
+    'mmfc-' + hash, { fit: false });
+}
+
+/**
+ * @param {any} node @param {Record<string,string>} t @param {number} fontSize
+ * @returns {any}
+ */
+function renderNode(node, t, fontSize) {
+  const shapeEl = shapeVnode(node, t);
+  const cx = node.x + node.w / 2;
+  const cy = node.y + node.h / 2;
+  const color = textColor(node.styles, t);
+  const label = textLines(cx, cy, node.label.split('\n'), fontSize,
+    color === null
+      ? { class: 'mm-label', fill: t.nodeText }
+      : { class: 'mm-label', fill: color, style: `fill:${color}` });
+  // `data-id` is the stable identity an editor's event delegation and
+  // hit-testing key on (MERMAID-FORMAT §7): the AST node id, verbatim.
+  return group({ class: 'mm-node', key: 'n-' + node.id, 'data-id': node.id }, [shapeEl, label]);
+}
+
+/**
+ * @param {any} node @param {Record<string,string>} t
+ * @returns {any}
+ */
+function shapeVnode(node, t) {
+  const { x, y, w, h } = node;
+  const fill = t.nodeFill;
+  const stroke = t.nodeStroke;
+  // Author styles (classDef / class / style) win over the theme defaults;
+  // spreading them last is what makes `class X note` repaint the box.
+  // Presentation attributes carry the theme (so standalone SSR looks right
+  // with no stylesheet); the author's own styles go inline, which is what
+  // outranks the stylesheet's `.mm-node-shape` rule.
+  const authored = shapeStyle(node.styles, t);
+  const common = {
+    class: 'mm-node-shape', fill, stroke, 'stroke-width': 1,
+    ...shapeAttributes(node.styles, t),
+    ...(authored === null ? {} : { style: authored }),
+  };
+  switch (node.shape) {
+    case 'round':
+      return rect(x, y, w, h, { rx: 8, ...common });
+    case 'stadium':
+      return rect(x, y, w, h, { rx: h / 2, ...common });
+    case 'subroutine':
+      return group({}, [
+        rect(x, y, w, h, common),
+        path(`M${x + 6},${y} L${x + 6},${y + h} M${x + w - 6},${y} L${x + w - 6},${y + h}`, { fill: 'none', stroke, 'stroke-width': 1 }),
+      ]);
+    case 'cylinder': {
+      const ry = Math.min(8, h / 6);
+      const d = `M${x},${y + ry} C${x},${y - ry / 2} ${x + w},${y - ry / 2} ${x + w},${y + ry}`
+        + ` L${x + w},${y + h - ry} C${x + w},${y + h + ry / 2} ${x},${y + h + ry / 2} ${x},${y + h - ry} Z`;
+      return path(d, common);
+    }
+    case 'circle':
+      return circle(x + w / 2, y + h / 2, Math.min(w, h) / 2, common);
+    case 'statedot':
+      // the state diagram's start marker: a small filled dot (the state
+      // layout is the only producer; flowchart source cannot spell it)
+      return circle(x + w / 2, y + h / 2, Math.min(w, h) / 2,
+        { ...common, fill: stroke });
+    case 'doublecircle': {
+      const r = Math.min(w, h) / 2;
+      return group({}, [
+        circle(x + w / 2, y + h / 2, r, common),
+        circle(x + w / 2, y + h / 2, r - 4, { ...common, fill: 'none' }),
+      ]);
+    }
+    case 'diamond':
+      return polygon([
+        { x: x + w / 2, y }, { x: x + w, y: y + h / 2 },
+        { x: x + w / 2, y: y + h }, { x, y: y + h / 2 },
+      ], common);
+    case 'hexagon': {
+      const o = Math.min(14, w / 4);
+      return polygon([
+        { x: x + o, y }, { x: x + w - o, y }, { x: x + w, y: y + h / 2 },
+        { x: x + w - o, y: y + h }, { x: x + o, y: y + h }, { x, y: y + h / 2 },
+      ], common);
+    }
+    case 'parallelogram': {
+      const o = Math.min(16, w / 4);
+      return polygon([
+        { x: x + o, y }, { x: x + w, y }, { x: x + w - o, y: y + h }, { x, y: y + h },
+      ], common);
+    }
+    case 'parallelogram_alt': {
+      const o = Math.min(16, w / 4);
+      return polygon([
+        { x, y }, { x: x + w - o, y }, { x: x + w, y: y + h }, { x: x + o, y: y + h },
+      ], common);
+    }
+    case 'trapezoid': {
+      const o = Math.min(16, w / 4);
+      return polygon([
+        { x: x + o, y }, { x: x + w - o, y }, { x: x + w, y: y + h }, { x, y: y + h },
+      ], common);
+    }
+    case 'trapezoid_alt': {
+      const o = Math.min(16, w / 4);
+      return polygon([
+        { x, y }, { x: x + w, y }, { x: x + w - o, y: y + h }, { x: x + o, y: y + h },
+      ], common);
+    }
+    case 'asymmetric':
+      return polygon([
+        { x, y }, { x: x + w - 8, y }, { x: x + w, y: y + h / 2 }, { x: x + w - 8, y: y + h }, { x, y: y + h },
+      ], common);
+    default:
+      return rect(x, y, w, h, common);
+  }
+}
+
+/**
+ * @param {any} e @param {Record<string,string>} t @param {number} fontSize @param {number} i
+ * @returns {any}
+ */
+function renderEdge(e, t, fontSize, i) {
+  const p1 = e.points[0];
+  const p2 = e.points[e.points.length - 1];
+  const stroke = t.lineColor;
+  const strokeWidth = e.stroke === 'thick' ? 3 : 1.5;
+  const dash = e.stroke === 'dotted' ? '3 3' : null;
+  const lineProps = {
+    class: 'mm-edge-line', fill: 'none', stroke, 'stroke-width': strokeWidth,
+  };
+  if (dash) lineProps['stroke-dasharray'] = dash;
+
+  const parts = [path(`M${num(p1.x)},${num(p1.y)} L${num(p2.x)},${num(p2.y)}`, lineProps)];
+
+  if (e.head !== 'none') parts.push(marker(p2, p1, e.head, stroke));
+  if (e.tail !== 'none') parts.push(marker(p1, p2, e.tail, stroke));
+
+  if (e.label != null && e.labelPos) {
+    // The layout measured the label and resolved its position; re-estimating
+    // the width here is what let a long label overflow its own background.
+    const lw = e.labelW ?? (e.label.length * fontSize * 0.55 + 8);
+    const lh = e.labelH ?? fontSize * 1.4;
+    parts.push(rect(e.labelPos.x - lw / 2, e.labelPos.y - lh / 2, lw, lh, {
+      class: 'mm-edge-label-bg', fill: t.edgeLabelBg, stroke: 'none',
+    }));
+    parts.push(textAt(e.labelPos.x, e.labelPos.y, e.label, fontSize, {
+      'text-anchor': 'middle', 'dominant-baseline': 'central',
+      class: 'mm-edge-label', fill: t.edgeLabelText,
+    }));
+  }
+
+  // Edge identity for editors: endpoints plus `data-edge`, the edge's
+  // AST position — which is also its docPath tail (MERMAID-FORMAT §7).
+  return group({
+    class: 'mm-edge', key: 'e-' + i,
+    'data-edge': i, 'data-from': e.from, 'data-to': e.to,
+  }, parts);
+}
+
+/**
+ * An endpoint marker (arrow/circle/cross) at `tip`, oriented away from
+ * `from`.
+ * @param {{x:number,y:number}} tip
+ * @param {{x:number,y:number}} from
+ * @param {string} kind
+ * @param {string} color
+ * @returns {any}
+ */
+function marker(tip, from, kind, color) {
+  const dx = tip.x - from.x;
+  const dy = tip.y - from.y;
+  const len = Math.hypot(dx, dy) || 1;
+  const ux = dx / len;
+  const uy = dy / len;
+  if (kind === 'circle') {
+    return circle(tip.x - ux * 4, tip.y - uy * 4, 4, { fill: color, stroke: color });
+  }
+  if (kind === 'cross') {
+    const s = 5;
+    const px = -uy, py = ux;
+    return path(
+      `M${num(tip.x - ux * 8 + px * s)},${num(tip.y - uy * 8 + py * s)} L${num(tip.x - px * s)},${num(tip.y - py * s)}`
+      + ` M${num(tip.x - ux * 8 - px * s)},${num(tip.y - uy * 8 - py * s)} L${num(tip.x + px * s)},${num(tip.y + py * s)}`,
+      { stroke: color, 'stroke-width': 1.5, fill: 'none' });
+  }
+  // arrow (default)
+  const size = 9;
+  const px = -uy, py = ux;
+  const baseX = tip.x - ux * size;
+  const baseY = tip.y - uy * size;
+  return polygon([
+    { x: tip.x, y: tip.y },
+    { x: baseX + px * (size / 2.4), y: baseY + py * (size / 2.4) },
+    { x: baseX - px * (size / 2.4), y: baseY - py * (size / 2.4) },
+  ], { class: 'mm-arrowhead', fill: color, stroke: color });
+}