@zombie-mermaid/svg-renderer 2.2.1

package/src/layout-engine/edge-bundling.ts

@@ -0,0 +1,379 @@
+/**
+ * Edge bundling — merge fan-out / fan-in edge paths into shared trunks.
+ * Split out of layout-engine.ts as a self-contained post-processing pass
+ * over a PositionedGraph's nodes/edges/groups.
+ */
+
+import type {
+  PositionedEdge,
+  PositionedNode,
+  PositionedGroup,
+  Direction,
+  Point,
+} from '@zombie-mermaid/core'
+
+/*
+ * Shrink applied to a node box before testing it against a bundled path, in px.
+ * A trunk that merely grazes a node's border reads as clean, so only a genuine
+ * overlap should disqualify a bundle.
+ */
+const NODE_CLEARANCE = 0.5
+
+/**
+ * True when every segment of `points` stays clear of all `nodes`, ignoring the
+ * ones named in `skipIds` (an edge's own endpoints, which it must touch).
+ *
+ * Bundling replaces a routed path with a trunk plus a straight branch to each
+ * target. That branch is only safe when it spans the gap between two adjacent
+ * layers; a target further away makes it cross every layer in between — and
+ * whatever nodes sit in them. The layout engine already routed those edges
+ * around the obstacles, so a bundle that would collide is rejected and the
+ * original routing kept.
+ *
+ * Paths here are rectilinear, so each segment is tested as a degenerate
+ * rectangle against each node's box.
+ */
+function pathClearOfNodes(
+  points: Point[],
+  nodes: PositionedNode[],
+  skipIds: Set<string>,
+): boolean {
+  for (let i = 0; i < points.length - 1; i++) {
+    const a = points[i]!
+    const b = points[i + 1]!
+    const segMinX = Math.min(a.x, b.x)
+    const segMaxX = Math.max(a.x, b.x)
+    const segMinY = Math.min(a.y, b.y)
+    const segMaxY = Math.max(a.y, b.y)
+
+    for (const node of nodes) {
+      if (skipIds.has(node.id)) continue
+      const minX = node.x + NODE_CLEARANCE
+      const maxX = node.x + node.width - NODE_CLEARANCE
+      const minY = node.y + NODE_CLEARANCE
+      const maxY = node.y + node.height - NODE_CLEARANCE
+      // A node smaller than the clearance on either axis can't block anything.
+      if (minX >= maxX || minY >= maxY) continue
+      if (
+        segMinX < maxX &&
+        segMaxX > minX &&
+        segMinY < maxY &&
+        segMaxY > minY
+      ) {
+        return false
+      }
+    }
+  }
+  return true
+}
+
+/**
+ * Find all groups (outermost first) that geometrically contain the given point.
+ */
+function findGroupsContainingPoint(
+  x: number,
+  y: number,
+  groups: PositionedGroup[],
+): PositionedGroup[] {
+  const result: PositionedGroup[] = []
+  for (const g of groups) {
+    if (x >= g.x && x <= g.x + g.width && y >= g.y && y <= g.y + g.height) {
+      result.push(g)
+      result.push(...findGroupsContainingPoint(x, y, g.children))
+    }
+  }
+  return result
+}
+
+/**
+ * If `junction` falls inside a group that doesn't contain the reference node,
+ * move it just outside the outermost such group boundary.
+ */
+function adjustJunctionForGroups(
+  junctionMain: number, // the junction coordinate along the flow axis (Y for TD, X for LR)
+  refX: number, // reference node center X (for finding its groups)
+  refY: number, // reference node center Y
+  groups: PositionedGroup[],
+  direction: Direction,
+): number {
+  const GAP = 12
+  const isLR = direction === 'LR'
+  const isRL = direction === 'RL'
+  const isBT = direction === 'BT'
+  const isHorizontal = isLR || isRL
+
+  // Groups containing the reference node
+  const refGroupIds = new Set(
+    findGroupsContainingPoint(refX, refY, groups).map((g) => g.id),
+  )
+
+  // Check where the junction point would be along the trunk
+  const probeX = isHorizontal ? junctionMain : refX
+  const probeY = isHorizontal ? refY : junctionMain
+  const junctionGroups = findGroupsContainingPoint(probeX, probeY, groups)
+
+  // Find outermost group containing the junction but NOT the reference node
+  const crossingGroup = junctionGroups.find((g) => !refGroupIds.has(g.id))
+  if (!crossingGroup) return junctionMain
+
+  // Move junction just outside this group
+  if (isLR) return crossingGroup.x - GAP
+  if (isRL) return crossingGroup.x + crossingGroup.width + GAP
+  if (isBT) return crossingGroup.y + crossingGroup.height + GAP
+  return crossingGroup.y - GAP // TD
+}
+
+/**
+ * Bundle fan-out and fan-in edge paths so they share a common trunk segment.
+ *
+ * For fan-out (one source → N targets), all edges exit the source at the same
+ * point, travel along a shared trunk, then branch to their individual targets.
+ * The overlapping trunk segments render as a single visible line.
+ *
+ * Junction points are placed outside subgraph boundaries so branches split
+ * before entering a group, not inside it.
+ *
+ * Constraints: edges in a bundle must share the same style and have no labels.
+ * Self-loops and backward edges (against the graph direction) are excluded.
+ */
+export function bundleEdgePaths(
+  edges: PositionedEdge[],
+  nodes: PositionedNode[],
+  groups: PositionedGroup[],
+  direction: Direction,
+): void {
+  const nodeMap = new Map(nodes.map((n) => [n.id, n]))
+  const processed = new Set<PositionedEdge>()
+
+  const isLR = direction === 'LR'
+  const isRL = direction === 'RL'
+  const isBT = direction === 'BT'
+  const isHorizontal = isLR || isRL
+
+  // --- Fan-out: group edges by shared source ---
+  const fanOutGroups = new Map<string, PositionedEdge[]>()
+  for (const edge of edges) {
+    if (edge.source === edge.target) continue
+    const group = fanOutGroups.get(edge.source) ?? []
+    fanOutGroups.set(edge.source, group)
+    group.push(edge)
+  }
+
+  for (const [sourceId, group] of fanOutGroups) {
+    if (group.length < 2) continue
+
+    const style = group[0]!.style
+    if (group.some((e) => e.label || e.style !== style)) continue
+
+    const source = nodeMap.get(sourceId)
+    if (!source) continue
+
+    // Only bundle edges going in the forward direction. Collects the
+    // resolved target node alongside each edge as it filters, rather than
+    // re-querying nodeMap afterward — the two lookups can't be proven to
+    // agree from a map() over a separately-filtered array.
+    const targets: { edge: PositionedEdge; node: PositionedNode }[] = []
+    for (const e of group) {
+      const t = nodeMap.get(e.target)
+      if (!t) continue
+      const isForward = isLR
+        ? t.x > source.x + source.width
+        : isRL
+          ? t.x + t.width < source.x
+          : isBT
+            ? t.y + t.height < source.y
+            : t.y > source.y + source.height // TD/TB
+      if (isForward) targets.push({ edge: e, node: t })
+    }
+    if (targets.length < 2) continue
+
+    const srcCX = source.x + source.width / 2
+    const srcCY = source.y + source.height / 2
+
+    if (isHorizontal) {
+      const exitX = isLR ? source.x + source.width : source.x
+      const exitY = srcCY
+
+      const nearestX = isLR
+        ? Math.min(...targets.map((t) => t.node.x))
+        : Math.max(...targets.map((t) => t.node.x + t.node.width))
+      let junctionX = exitX + (nearestX - exitX) / 2
+      junctionX = adjustJunctionForGroups(
+        junctionX,
+        srcCX,
+        srcCY,
+        groups,
+        direction,
+      )
+
+      const bundled: { edge: PositionedEdge; points: Point[] }[] = []
+      for (const { edge, node: target } of targets) {
+        const entryX = isLR ? target.x : target.x + target.width
+        const entryY = target.y + target.height / 2
+        const points = [
+          { x: exitX, y: exitY },
+          { x: junctionX, y: exitY },
+          { x: junctionX, y: entryY },
+          { x: entryX, y: entryY },
+        ]
+        if (pathClearOfNodes(points, nodes, new Set([sourceId, target.id]))) {
+          bundled.push({ edge, points })
+        }
+      }
+      // One clear branch is not a bundle — leave the whole group as routed.
+      if (bundled.length < 2) continue
+      for (const { edge, points } of bundled) {
+        edge.points = points
+        processed.add(edge)
+      }
+    } else {
+      const exitX = srcCX
+      const exitY = isBT ? source.y : source.y + source.height
+
+      const nearestY = isBT
+        ? Math.max(...targets.map((t) => t.node.y + t.node.height))
+        : Math.min(...targets.map((t) => t.node.y))
+      let junctionY = exitY + (nearestY - exitY) / 2
+      junctionY = adjustJunctionForGroups(
+        junctionY,
+        srcCX,
+        srcCY,
+        groups,
+        direction,
+      )
+
+      const bundled: { edge: PositionedEdge; points: Point[] }[] = []
+      for (const { edge, node: target } of targets) {
+        const entryX = target.x + target.width / 2
+        const entryY = isBT ? target.y + target.height : target.y
+        const points = [
+          { x: exitX, y: exitY },
+          { x: exitX, y: junctionY },
+          { x: entryX, y: junctionY },
+          { x: entryX, y: entryY },
+        ]
+        if (pathClearOfNodes(points, nodes, new Set([sourceId, target.id]))) {
+          bundled.push({ edge, points })
+        }
+      }
+      // One clear branch is not a bundle — leave the whole group as routed.
+      if (bundled.length < 2) continue
+      for (const { edge, points } of bundled) {
+        edge.points = points
+        processed.add(edge)
+      }
+    }
+  }
+
+  // --- Fan-in: group edges by shared target (skip already-bundled edges) ---
+  const fanInGroups = new Map<string, PositionedEdge[]>()
+  for (const edge of edges) {
+    if (processed.has(edge) || edge.source === edge.target) continue
+    const group = fanInGroups.get(edge.target) ?? []
+    fanInGroups.set(edge.target, group)
+    group.push(edge)
+  }
+
+  for (const [targetId, group] of fanInGroups) {
+    if (group.length < 2) continue
+
+    const style = group[0]!.style
+    if (group.some((e) => e.label || e.style !== style)) continue
+
+    const target = nodeMap.get(targetId)
+    if (!target) continue
+
+    // Collects the resolved source node alongside each edge as it filters,
+    // rather than re-querying nodeMap afterward (see the fan-out loop above
+    // for why: a map() over a separately-filtered array can't be proven to
+    // agree with the filter's own lookup).
+    const sources: { edge: PositionedEdge; node: PositionedNode }[] = []
+    for (const e of group) {
+      const s = nodeMap.get(e.source)
+      if (!s) continue
+      const isForward = isLR
+        ? s.x + s.width < target.x
+        : isRL
+          ? s.x > target.x + target.width
+          : isBT
+            ? s.y > target.y + target.height
+            : s.y + s.height < target.y // TD/TB
+      if (isForward) sources.push({ edge: e, node: s })
+    }
+    if (sources.length < 2) continue
+    const tgtCX = target.x + target.width / 2
+    const tgtCY = target.y + target.height / 2
+
+    if (isHorizontal) {
+      const entryX = isLR ? target.x : target.x + target.width
+      const entryY = tgtCY
+
+      const farthestX = isLR
+        ? Math.max(...sources.map((s) => s.node.x + s.node.width))
+        : Math.min(...sources.map((s) => s.node.x))
+      let junctionX = farthestX + (entryX - farthestX) / 2
+      junctionX = adjustJunctionForGroups(
+        junctionX,
+        tgtCX,
+        tgtCY,
+        groups,
+        direction,
+      )
+
+      const bundled: { edge: PositionedEdge; points: Point[] }[] = []
+      for (const { edge, node: src } of sources) {
+        const exitX = isLR ? src.x + src.width : src.x
+        const exitY = src.y + src.height / 2
+        const points = [
+          { x: exitX, y: exitY },
+          { x: junctionX, y: exitY },
+          { x: junctionX, y: entryY },
+          { x: entryX, y: entryY },
+        ]
+        if (pathClearOfNodes(points, nodes, new Set([src.id, targetId]))) {
+          bundled.push({ edge, points })
+        }
+      }
+      // One clear branch is not a bundle — leave the whole group as routed.
+      if (bundled.length < 2) continue
+      for (const { edge, points } of bundled) {
+        edge.points = points
+      }
+    } else {
+      const entryX = tgtCX
+      const entryY = isBT ? target.y + target.height : target.y
+
+      const farthestY = isBT
+        ? Math.min(...sources.map((s) => s.node.y))
+        : Math.max(...sources.map((s) => s.node.y + s.node.height))
+      let junctionY = farthestY + (entryY - farthestY) / 2
+      junctionY = adjustJunctionForGroups(
+        junctionY,
+        tgtCX,
+        tgtCY,
+        groups,
+        direction,
+      )
+
+      const bundled: { edge: PositionedEdge; points: Point[] }[] = []
+      for (const { edge, node: src } of sources) {
+        const exitX = src.x + src.width / 2
+        const exitY = isBT ? src.y : src.y + src.height
+        const points = [
+          { x: exitX, y: exitY },
+          { x: exitX, y: junctionY },
+          { x: entryX, y: junctionY },
+          { x: entryX, y: entryY },
+        ]
+        if (pathClearOfNodes(points, nodes, new Set([src.id, targetId]))) {
+          bundled.push({ edge, points })
+        }
+      }
+      // One clear branch is not a bundle — leave the whole group as routed.
+      if (bundled.length < 2) continue
+      for (const { edge, points } of bundled) {
+        edge.points = points
+      }
+    }
+  }
+}

package/src/layout-engine/elk-adapter-utils.ts

@@ -0,0 +1,81 @@
+/**
+ * Shared ELK-edge-geometry extraction helpers.
+ *
+ * `from-elk.ts` (flowchart/state), `../class/layout.ts`, and
+ * `../er/layout.ts` each independently walk an ELK edge's
+ * `section.startPoint → bendPoints → endPoint` into a `Point[]`, plus
+ * near-identical edge-label-position math. This module is the single
+ * place that logic lives, so the three call sites can't drift.
+ */
+
+import type { ElkExtendedEdge } from 'elkjs'
+import type { Point } from '@zombie-mermaid/core'
+
+/**
+ * Walk an ELK edge's first routed section into a flat point path:
+ * `startPoint → bendPoints → endPoint`.
+ *
+ * ELK can theoretically produce multiple sections per edge (for edges
+ * split across hierarchy boundaries via ports), but all three call sites
+ * only ever read `sections[0]` — hierarchical decomposition in this
+ * codebase is handled by emitting separate ELK edges (see
+ * `to-elk.ts`/`parseHopEdgeId` in `from-elk.ts`), not multi-section edges.
+ *
+ * `offsetX`/`offsetY` translate the section's coordinates into an
+ * ancestor's coordinate space, for callers walking a nested ELK result
+ * (`from-elk.ts`). Callers with a flat (non-hierarchical) ELK graph
+ * (`class/layout.ts`, `er/layout.ts`) can omit them.
+ *
+ * Returns an empty array if the edge has no routed sections.
+ */
+export function extractEdgePoints(
+  elkEdge: ElkExtendedEdge,
+  offsetX = 0,
+  offsetY = 0,
+): Point[] {
+  const points: Point[] = []
+  if (!elkEdge.sections || elkEdge.sections.length === 0) return points
+
+  const section = elkEdge.sections[0]!
+  points.push({
+    x: section.startPoint.x + offsetX,
+    y: section.startPoint.y + offsetY,
+  })
+  if (section.bendPoints) {
+    for (const bp of section.bendPoints) {
+      points.push({ x: bp.x + offsetX, y: bp.y + offsetY })
+    }
+  }
+  points.push({
+    x: section.endPoint.x + offsetX,
+    y: section.endPoint.y + offsetY,
+  })
+
+  return points
+}
+
+/**
+ * Compute an edge label's center position from ELK's placed label box
+ * (`label.x/y` is the box's top-left corner).
+ *
+ * `offsetX`/`offsetY` translate into an ancestor's coordinate space, same
+ * as `extractEdgePoints`.
+ *
+ * Returns `undefined` if ELK didn't place a label (no label on the edge,
+ * or ELK left `x`/`y` unset).
+ */
+export function extractEdgeLabelPosition(
+  elkEdge: ElkExtendedEdge,
+  offsetX = 0,
+  offsetY = 0,
+): Point | undefined {
+  if (!elkEdge.labels || elkEdge.labels.length === 0) return undefined
+
+  const label = elkEdge.labels[0]!
+  if (label.x == null || label.y == null) return undefined
+
+  return {
+    x: label.x + (label.width ?? 0) / 2 + offsetX,
+    y: label.y + (label.height ?? 0) / 2 + offsetY,
+  }
+}

package/src/layout-engine/elk-graph-builder.ts

@@ -0,0 +1,240 @@
+/**
+ * Shared ELK graph-*construction* helpers.
+ *
+ * The reverse direction (reading geometry back out of an ELK result) lives
+ * in `./elk-adapter-utils.ts`; this module is its input-side counterpart.
+ *
+ * Three renderers build ELK's typed JSON input independently —
+ * `./to-elk.ts` (flowchart + state), `../class/layout.ts`, and
+ * `../er/layout.ts`. They differ in domain model and in which extra
+ * `elk.*` options they set, but the primitives underneath are identical:
+ * one direction mapping, one `elk.padding` string format, one leaf-node
+ * shape, and one measured edge-label box. Those primitives live here so
+ * the three call sites can't drift (issue #616).
+ *
+ * This module deliberately does **not** try to abstract over the three
+ * diagram types' own graph shapes (subgraph nesting, hierarchical ports,
+ * note links) — that would be an engine-neutral intermediate graph, which
+ * is the separately-scoped work in #538.
+ */
+
+import type { ElkExtendedEdge, ElkLabel, ElkNode, LayoutOptions } from 'elkjs'
+import type { Direction } from '@zombie-mermaid/core'
+import { measureMultilineText } from '@zombie-mermaid/core'
+import { FONT_WEIGHTS } from '../styles.ts'
+
+// ============================================================================
+// Direction
+// ============================================================================
+
+/** The four values ELK's `elk.direction` option accepts in this codebase. */
+export type ElkDirection = 'DOWN' | 'UP' | 'LEFT' | 'RIGHT'
+
+/**
+ * The `elk.direction` each diagram type falls back to when its source
+ * carries no `direction` statement.
+ *
+ * These genuinely differ per diagram type, and the difference is
+ * intentional rather than an accident of three separate implementations:
+ *
+ * - **flowchart / state** — `DOWN`. `MermaidGraph.direction` is a required
+ *   field the parser always fills in (defaulting to `TD`), so the fallback
+ *   is only a type-level backstop; the effective default is mermaid's own
+ *   top-down flowchart default.
+ * - **class** — `DOWN`. `ClassDiagram` has no direction concept at all (see
+ *   `ClassRenderOptions` in `packages/core/src/types.ts`: class diagrams
+ *   "have no `direction` or `curve` concept"), so this is the renderer's
+ *   single fixed orientation, matching Mermaid's own TB class rendering —
+ *   which `../class/layout.ts` relies on to put a `note for X` above its
+ *   class.
+ * - **ER** — `RIGHT`. An ER diagram's `direction` is optional
+ *   (`ErDiagram.direction?`), left `undefined` when the source has no
+ *   `direction` statement, and this renderer has always laid those out
+ *   left-to-right. `direction TB`/`LR`/`BT`/`RL` in the source (or
+ *   `RenderOptions.direction`, applied via `withDirectionOverride`) still
+ *   wins over it.
+ *
+ * The *mappings* were never in conflict — both hand-rolled
+ * `directionToElk()` implementations agreed on all five `Direction` values
+ * (`LR`→`RIGHT`, `RL`→`LEFT`, `BT`→`UP`, `TD`/`TB`→`DOWN`). Only the
+ * no-direction fallback differed, which is why it is a parameter here
+ * rather than something to reconcile away.
+ */
+export const ELK_DIRECTION_FALLBACK = {
+  flowchart: 'DOWN',
+  state: 'DOWN',
+  class: 'DOWN',
+  er: 'RIGHT',
+} as const satisfies Record<string, ElkDirection>
+
+/**
+ * Convert a Mermaid `direction` to ELK's `elk.direction` value.
+ *
+ * `fallback` covers the no-`direction`-statement case only — every member
+ * of `Direction` has an explicit mapping. Pass the diagram type's entry
+ * from `ELK_DIRECTION_FALLBACK` rather than a bare string literal, so the
+ * per-type defaults stay documented in one place.
+ */
+export function directionToElk(
+  dir: Direction | undefined,
+  fallback: ElkDirection,
+): ElkDirection {
+  switch (dir) {
+    case 'LR':
+      return 'RIGHT'
+    case 'RL':
+      return 'LEFT'
+    case 'BT':
+      return 'UP'
+    case 'TD':
+    case 'TB':
+      return 'DOWN'
+    default:
+      return fallback
+  }
+}
+
+// ============================================================================
+// Layout options
+// ============================================================================
+
+/** Per-side padding, for the asymmetric case (a subgraph's header gap). */
+export interface ElkPaddingSides {
+  top: number
+  left: number
+  bottom: number
+  right: number
+}
+
+/**
+ * Format ELK's `elk.padding` value. A single number applies to all four
+ * sides; an object sets them individually.
+ */
+export function elkPadding(padding: number | ElkPaddingSides): string {
+  const sides: ElkPaddingSides =
+    typeof padding === 'number'
+      ? { top: padding, left: padding, bottom: padding, right: padding }
+      : padding
+  return `[top=${sides.top},left=${sides.left},bottom=${sides.bottom},right=${sides.right}]`
+}
+
+/**
+ * The `elk.*` options every one of the three graph builders sets, with the
+ * values they all agree on. Callers spread the result and add their own
+ * diagram-specific options on top.
+ */
+export function baseElkLayoutOptions(spec: {
+  direction: ElkDirection
+  nodeSpacing: number
+  layerSpacing: number
+  padding: number | ElkPaddingSides
+}): LayoutOptions {
+  return {
+    'elk.algorithm': 'layered',
+    'elk.direction': spec.direction,
+    'elk.spacing.nodeNode': String(spec.nodeSpacing),
+    'elk.layered.spacing.nodeNodeBetweenLayers': String(spec.layerSpacing),
+    'elk.padding': elkPadding(spec.padding),
+    'elk.edgeRouting': 'ORTHOGONAL',
+  }
+}
+
+// ============================================================================
+// Nodes
+// ============================================================================
+
+/**
+ * Build a leaf ELK node.
+ *
+ * `label` is attached as an ELK label when supplied — the flowchart/state
+ * path does that (ELK reads it for nothing, but `from-elk.ts` reads it
+ * back); class and ER carry labels in their own side tables instead and
+ * omit it. An empty-string label is still a label, so the check is
+ * `undefined`, not truthiness.
+ */
+export function buildElkLeafNode(
+  id: string,
+  size: { width: number; height: number },
+  label?: string,
+): ElkNode {
+  const node: ElkNode = { id, width: size.width, height: size.height }
+  if (label !== undefined) node.labels = [{ text: label }]
+  return node
+}
+
+// ============================================================================
+// Edges
+// ============================================================================
+
+/**
+ * Per-label layout options the flowchart/state path sets on every edge
+ * label. Class and ER instead set `elk.edgeLabels.placement` once on the
+ * root graph, so they pass no per-label options.
+ */
+export const INLINE_CENTERED_EDGE_LABEL: LayoutOptions = {
+  'elk.edgeLabels.inline': 'true',
+  'elk.edgeLabels.placement': 'CENTER',
+}
+
+/**
+ * How a caller wants its edge labels measured and placed. `fontSize` is
+ * the resolved `fontSizes.edgeLabel`; `layoutOptions`, when given, is
+ * attached to the ELK label itself.
+ */
+export interface ElkEdgeLabelStyle {
+  fontSize: number
+  layoutOptions?: LayoutOptions
+}
+
+/**
+ * Measure an edge label and build ELK's label box for it.
+ *
+ * The `+8` / `+6` are the horizontal/vertical breathing room all three
+ * builders have always added around the measured text so ELK reserves a
+ * slightly larger channel than the glyphs strictly need.
+ */
+export function buildElkEdgeLabel(
+  text: string,
+  style: ElkEdgeLabelStyle,
+): ElkLabel {
+  const metrics = measureMultilineText(
+    text,
+    style.fontSize,
+    FONT_WEIGHTS.edgeLabel,
+  )
+  const label: ElkLabel = {
+    text,
+    width: metrics.width + 8,
+    height: metrics.height + 6,
+  }
+  // Copied, not aliased: every label previously got its own fresh options
+  // literal, and ELK receives this graph by reference (see
+  // `elkLayoutSync`'s `saveDispatch`) rather than through a structured
+  // clone — so a shared object would be shared into ELK's own hands too.
+  if (style.layoutOptions) label.layoutOptions = { ...style.layoutOptions }
+  return label
+}
+
+/**
+ * Build a single-source/single-target ELK edge, with a measured label when
+ * `label` is non-empty. An absent or empty label leaves `labels` off the
+ * edge entirely (rather than setting it to an empty array or `undefined`),
+ * matching what all three builders did by hand.
+ */
+export function buildElkEdge(spec: {
+  id: string
+  source: string
+  target: string
+  label?: string
+  labelStyle: ElkEdgeLabelStyle
+}): ElkExtendedEdge {
+  const edge: ElkExtendedEdge = {
+    id: spec.id,
+    sources: [spec.source],
+    targets: [spec.target],
+  }
+  if (spec.label) {
+    edge.labels = [buildElkEdgeLabel(spec.label, spec.labelStyle)]
+  }
+  return edge
+}