@zombie-mermaid/svg-renderer 3.2.0 → 4.1.0

package/src/layout-engine/to-elk.ts

@@ -17,6 +17,8 @@ import type { FontSizes } from '../styles.ts'
 import { FONT_WEIGHTS, NODE_PADDING } from '../styles.ts'
 import { measureMultilineText } from '@zombie-mermaid/core'
 import { DEFAULTS } from './constants.ts'
+import { findBackEdgeIndexes } from './back-edges.ts'
+import type { LayoutHints } from './layout-hints.ts'
 import {
   ELK_DIRECTION_FALLBACK,
   INLINE_CENTERED_EDGE_LABEL,
@@ -29,6 +31,112 @@ import {
   type ElkPaddingSides,
 } from './elk-graph-builder.ts'
 
+/**
+ * ELK layer constraint for a top-level `[*]` marker: the start marker is
+ * pinned to the first layer so a back-edge can't drag it into the middle
+ * (#1240). The end marker is deliberately left unconstrained: it settles in
+ * the layer right after the state(s) that transition into it, instead of a
+ * layer of its own after every other node (`LAST_SEPARATE`), which drew
+ * `Closed --> [*]` as a long line down the page edge when `Closed` is near
+ * the top. Keyed by node shape.
+ */
+const STATE_MARKER_LAYER_CONSTRAINT: Partial<Record<string, string>> = {
+  'state-start': 'FIRST',
+}
+
+/**
+ * Root-graph ELK options applied to state diagrams only (flowcharts keep
+ * their tuned defaults).
+ *
+ * Flowcharts deliberately do not get `MODEL_ORDER` cycle breaking (#1307).
+ * They already break cycles the way mermaid.js does, by reversing the
+ * depth-first back edges before ELK runs (`edgesReversedForLayout`), so ELK
+ * has no cycle left to break; adding `MODEL_ORDER` on top only moved nodes
+ * away from mermaid.js. Measured against mermaid 11.17.2 (relative placement
+ * of every node pair, `scripts/layout-oracle.ts` style): applied to every
+ * flowchart it changed 5 of the 26 gallery samples and 49 of 104 doc/test
+ * flowcharts, closer for 0 and 2, further for 4 and 41; applied only to
+ * graphs with a subgraph direction override (the one case where the
+ * pre-reversal is skipped) it changed 1 and 7, closer for 0 and 2, further
+ * for 1 and 5.
+ *
+ * - `cycleBreaking: MODEL_ORDER` reverses the edge that points *against*
+ *   declaration order instead of whichever edge ELK's greedy heuristic picks.
+ *   The greedy default reversed the main chain of `[*] --> Idle`,
+ *   `Idle --> Active`, `Active --> Idle`, drawing it bottom-to-top with the
+ *   start marker beside a state.
+ * - `postCompaction: NONE`: LEFT_RIGHT_CONSTRAINT_LOCKING compaction slides
+ *   nodes sideways after edges are routed, which leaves state edges ending
+ *   in a horizontal run along the target's top border (arrowhead sideways).
+ */
+const STATE_LAYOUT_OPTIONS: LayoutOptions = {
+  'elk.layered.cycleBreaking.strategy': 'MODEL_ORDER',
+  'elk.layered.compaction.postCompaction.strategy': 'NONE',
+}
+
+/**
+ * Whether `graph` is a `stateDiagram` (it has `[*]` markers, the only thing
+ * that distinguishes a state graph from a flowchart here). Composite states
+ * are included: their compound nodes are placed among their siblings at
+ * first-mention position (see `firstMentionRank`), so `MODEL_ORDER` reads
+ * them in source order instead of after every leaf (#1287).
+ */
+export function isStateGraph(graph: MermaidGraph): boolean {
+  for (const node of graph.nodes.values()) {
+    if (node.shape === 'state-start' || node.shape === 'state-end') return true
+  }
+  return false
+}
+
+/**
+ * Room a subgraph's box leaves around its contents, in px. The top is the
+ * title bar (28) plus a gap (16) to match the bottom. Shared with the compound
+ * layout, which draws the boxes itself.
+ */
+export const SUBGRAPH_PADDING = { top: 44, left: 16, bottom: 16, right: 16 }
+
+const reversedCache = new WeakMap<MermaidGraph, Set<number>>()
+
+/**
+ * Indices of the edges handed to ELK reversed, so the layout breaks cycles the
+ * way mermaid.js (dagre) does: see `findBackEdgeIndexes`. `elkToPositioned`
+ * flips each one's points back so they still run source to target.
+ *
+ * Flowcharts only. State diagrams have their own cycle breaking (above), and a
+ * graph with a subgraph direction override goes through hop edges and ports
+ * that this does not rewrite.
+ */
+export function edgesReversedForLayout(
+  graph: MermaidGraph,
+  hints?: LayoutHints,
+): Set<number> {
+  // Worked out once per graph object, by whichever of `mermaidToElk` (which
+  // has the hints) and `elkToPositioned` (which doesn't need them) asks first.
+  let set = reversedCache.get(graph)
+  if (!set) {
+    set =
+      isStateGraph(graph) || hasAnyDirectionOverride(graph.subgraphs)
+        ? new Set()
+        : findBackEdgeIndexes(graph, hints?.walkOrder)
+    reversedCache.set(graph, set)
+  }
+  return set
+}
+
+/**
+ * Source position of a root-level state or composite: the index of the first
+ * edge that names it. A composite no edge names itself falls back to the first
+ * edge naming a state inside it. Items no edge mentions rank last, keeping
+ * their relative order.
+ */
+function firstMentionRank(graph: MermaidGraph, ids: Set<string>): number {
+  for (let i = 0; i < graph.edges.length; i++) {
+    const e = graph.edges[i]!
+    if (ids.has(e.source) || ids.has(e.target)) return i
+  }
+  return Number.POSITIVE_INFINITY
+}
+
 /**
  * Convert a Mermaid direction to an ELK direction, flowchart/state-style
  * (no direction at all → `DOWN`; see `ELK_DIRECTION_FALLBACK`).
@@ -156,7 +264,7 @@ const ROOT_CONTAINER = ' root'
  * compound node's own `elk.direction`) for exactly the diagrams that need
  * `SEPARATE` the most.
  */
-function hasAnyDirectionOverride(subgraphs: MermaidSubgraph[]): boolean {
+export function hasAnyDirectionOverride(subgraphs: MermaidSubgraph[]): boolean {
   for (const sg of subgraphs) {
     if (sg.direction !== undefined) return true
     if (hasAnyDirectionOverride(sg.children)) return true
@@ -231,10 +339,12 @@ function commonPrefixLength(a: string[], b: string[]): number {
  */
 export function mermaidToElk(
   graph: MermaidGraph,
-  opts: Required<
+  givenOpts: Required<
     Pick<RenderOptions, 'font' | 'padding' | 'nodeSpacing' | 'layerSpacing'>
   > & { fontSizes: FontSizes },
+  hints?: LayoutHints,
 ): ElkGraphNode {
+  const opts = givenOpts
   // Collect all node IDs that belong to subgraphs
   const subgraphNodeIds = new Set<string>()
   const subgraphIds = new Set<string>()
@@ -325,6 +435,12 @@ export function mermaidToElk(
     'elk.layered.compaction.postCompaction.strategy':
       'LEFT_RIGHT_CONSTRAINT_LOCKING',
     'elk.layered.considerModelOrder.strategy': 'NODES_AND_EDGES',
+    // Every layer keeps the nodes in the order the graph lists them: the
+    // compound layout relies on it to keep a subgraph's nodes together.
+    ...(hints?.forceNodeOrder
+      ? { 'elk.layered.crossingMinimization.forceNodeModelOrder': 'true' }
+      : {}),
+    ...(isStateGraph(graph) ? STATE_LAYOUT_OPTIONS : {}),
     'elk.layered.wrapping.strategy': 'OFF',
     // Use SEPARATE when subgraphs have direction overrides (enables proper direction handling)
     // Use INCLUDE_CHILDREN otherwise (simpler cross-hierarchy edge routing)
@@ -332,7 +448,6 @@ export function mermaidToElk(
       ? 'SEPARATE'
       : 'INCLUDE_CHILDREN',
   }
-
   // Ports to declare on each subgraph's ELK node, keyed by subgraph ID.
   const portsBySubgraph = new Map<string, Set<string>>()
   // Hop/bridge edges to inject into each container's own `edges` array.
@@ -432,7 +547,19 @@ export function mermaidToElk(
         node.shape,
         opts.fontSizes.nodeLabel,
       )
-      rootChildren.push(buildElkLeafNode(id, size, node.label))
+      const fixedWidth = hints?.fixedWidths?.get(id)
+      if (fixedWidth !== undefined) size.width = fixedWidth
+      const leaf = buildElkLeafNode(id, size, node.label)
+      // A top-level start `[*]` marks where reading starts: pin it to the
+      // first layer so a back-edge can't drag it into the middle. The end
+      // marker stays free (see STATE_MARKER_LAYER_CONSTRAINT).
+      const pin = isStateGraph(graph)
+        ? STATE_MARKER_LAYER_CONSTRAINT[node.shape]
+        : undefined
+      if (pin !== undefined) {
+        leaf.layoutOptions = { 'elk.layered.layering.layerConstraint': pin }
+      }
+      rootChildren.push(leaf)
     }
   }
 
@@ -455,12 +582,17 @@ export function mermaidToElk(
   // Deliberately scoped to *only* the sibling-subgraph reversal, not a
   // wholesale "all clusters before all leaves" reordering (which mermaid's
   // own mechanism also does, globally): moving the whole subgraphs group
-  // ahead of top-level leaf nodes changed which edge in a cycle ELK treats
-  // as a feedback edge for a sample mixing top-level leaves and a
-  // subgraph in a cyclic flow (e.g. "CI/CD Pipeline"), reordering the
-  // entire rank structure rather than just left-right sibling position —
-  // a much bigger, unreviewed blast radius than the reported bug needs.
-  for (const sg of [...graph.subgraphs].reverse()) {
+  // ahead of top-level leaf nodes changes which edge in a cycle ELK treats
+  // as a feedback edge. Cycles in a flowchart are broken before ELK sees
+  // them (`edgesReversedForLayout`), so this ordering no longer decides that.
+  const stateGraph = isStateGraph(graph)
+  const leafCount = rootChildren.length
+  // State diagrams read in source order, so composites keep forward
+  // declaration order and are interleaved with the leaves below.
+  const subgraphOrder = stateGraph
+    ? graph.subgraphs
+    : [...graph.subgraphs].reverse()
+  for (const sg of subgraphOrder) {
     rootChildren.push(
       subgraphToElk(
         sg,
@@ -473,22 +605,50 @@ export function mermaidToElk(
       ),
     )
   }
+  if (stateGraph && graph.subgraphs.length > 0) {
+    // ELK's MODEL_ORDER cycle breaking and crossing minimisation follow the
+    // child order, so a composite must sit at its first-mention position
+    // among its siblings rather than after every leaf (#1287). Array#sort is
+    // stable, so equal ranks keep leaves-then-composites order.
+    const rank = rootChildren.map((child, i) => {
+      if (i < leafCount) return firstMentionRank(graph, new Set([child.id]))
+      const sg = graph.subgraphs[i - leafCount]!
+      const own = firstMentionRank(graph, new Set([sg.id]))
+      if (own !== Number.POSITIVE_INFINITY) return own
+      const members = new Set<string>()
+      collectAllMemberNodeIds(sg, members)
+      return firstMentionRank(graph, members)
+    })
+    const order = rootChildren
+      .map((_, i) => i)
+      .sort((a, b) => rank[a]! - rank[b]! || a - b)
+    const sorted = order.map((i) => rootChildren[i]!)
+    rootChildren.splice(0, rootChildren.length, ...sorted)
+  }
 
   // Add root-level edges. Self-loops (edge.source === edge.target) are
   // excluded — ELK has no native self-loop layout and produces a degenerate
   // zero-length-span polyline for them; from-elk.ts synthesizes a proper
   // side loop for these once node positions are known instead.
+  const reversed = edgesReversedForLayout(graph, hints)
   for (const { index, edge } of edgesBySubgraph.get(null)!) {
     if (edge.source === edge.target) continue
-    rootEdges.push(
-      buildElkEdge({
-        id: `e${index}`,
-        source: edge.source,
-        target: edge.target,
-        label: edge.label,
-        labelStyle: edgeLabelStyle(opts),
-      }),
-    )
+    if (hints?.detachedEdges?.has(index)) continue
+    const elkEdge = buildElkEdge({
+      id: `e${index}`,
+      source: reversed.has(index) ? edge.target : edge.source,
+      target: reversed.has(index) ? edge.source : edge.target,
+      label: edge.label,
+      labelStyle: edgeLabelStyle(opts),
+    })
+    if (hints?.looseEdges?.has(index)) {
+      // Priority 0: the straightening pass leaves this edge alone.
+      elkEdge.layoutOptions = {
+        ...elkEdge.layoutOptions,
+        'elk.layered.priority.straightness': '0',
+      }
+    }
+    rootEdges.push(elkEdge)
   }
 
   if (hasDirectionOverride) {
@@ -506,8 +666,8 @@ export function mermaidToElk(
       rootEdges.push(
         buildElkEdge({
           id: `e${index}`,
-          source: edge.source,
-          target: edge.target,
+          source: reversed.has(index) ? edge.target : edge.source,
+          target: reversed.has(index) ? edge.source : edge.target,
           label: edge.label,
           labelStyle: edgeLabelStyle(opts),
         }),
@@ -567,8 +727,7 @@ function subgraphToElk(
     direction: directionToElk(effectiveDirection),
     nodeSpacing: opts.nodeSpacing,
     layerSpacing: opts.layerSpacing,
-    // Top = headerHeight(28) + gap(16) to match bottom padding
-    padding: { top: 44, left: 16, bottom: 16, right: 16 },
+    padding: SUBGRAPH_PADDING,
   })
 
   // Ports, built before children/edges since they don't depend on them.
@@ -619,13 +778,14 @@ function subgraphToElk(
   // Self-loops are excluded — see the matching comment in mermaidToElk.
   const edges: ElkExtendedEdge[] = []
   const internalEdges = edgesBySubgraph.get(sg.id) ?? []
+  const reversed = edgesReversedForLayout(graph)
   for (const { index, edge } of internalEdges) {
     if (edge.source === edge.target) continue
     edges.push(
       buildElkEdge({
         id: `e${index}`,
-        source: edge.source,
-        target: edge.target,
+        source: reversed.has(index) ? edge.target : edge.source,
+        target: reversed.has(index) ? edge.source : edge.target,
         label: edge.label,
         labelStyle: edgeLabelStyle(opts),
       }),

package/src/layout-engine.ts

@@ -30,11 +30,17 @@ import type {
   PositionedGraph,
   FlowchartRenderOptions,
 } from '@zombie-mermaid/core'
+import { withoutOwnClusterEdges } from '@zombie-mermaid/core'
 import { elkLayoutSync } from './elk-instance.ts'
 import { resolveFontSizes } from './styles.ts'
 import { DEFAULTS } from './layout-engine/constants.ts'
 import { mermaidToElk } from './layout-engine/to-elk.ts'
 import { elkToPositioned } from './layout-engine/from-elk.ts'
+import {
+  canLayOutFlat,
+  layoutCompoundFlat,
+} from './layout-engine/compound-flat.ts'
+import type { LayoutHints } from './layout-engine/layout-hints.ts'
 
 // ============================================================================
 // Public API
@@ -47,17 +53,52 @@ import { elkToPositioned } from './layout-engine/from-elk.ts'
 export function layoutGraphSync(
   graph: MermaidGraph,
   options: FlowchartRenderOptions = {},
+): PositionedGraph {
+  return layoutWithHints(graph, options)
+}
+
+/** One layout run, with the hints the compound layout gives it. */
+function layoutWithHints(
+  graph: MermaidGraph,
+  options: FlowchartRenderOptions,
+  hints?: LayoutHints,
 ): PositionedGraph {
   const opts = {
     ...DEFAULTS,
     ...options,
     fontSizes: resolveFontSizes(options.fontSizes),
   }
-  const elkGraph = mermaidToElk(graph, opts)
+  const elkGraph = mermaidToElk(graph, opts, hints)
   const result = elkLayoutSync(elkGraph, options.layoutCache)
   return elkToPositioned(result, graph, opts.mergeEdges)
 }
 
+/**
+ * Lay out a flowchart, with its subgraphs arranged the way mermaid.js arranges
+ * them (see `layout-engine/compound-flat.ts`). Anything that layout doesn't
+ * handle, or can't make fit, is laid out by `layoutGraphSync`, so this is a
+ * drop-in for it wherever the graph is a flowchart. Other diagram types that
+ * share the engine (state, architecture) keep using `layoutGraphSync`.
+ */
+export function layoutFlowchartSync(
+  rawGraph: MermaidGraph,
+  options: FlowchartRenderOptions = {},
+): PositionedGraph {
+  // Real mermaid.js draws no line for an edge between a node and a subgraph
+  // containing it (#1310), so it is not laid out or rendered here either.
+  const graph = withoutOwnClusterEdges(rawGraph)
+  if (canLayOutFlat(graph)) {
+    const fontSizes = resolveFontSizes(options.fontSizes)
+    const flat = layoutCompoundFlat(
+      graph,
+      (g, hints) => layoutWithHints(g, options, hints),
+      fontSizes,
+    )
+    if (flat) return flat
+  }
+  return layoutGraphSync(graph, options)
+}
+
 /**
  * Convert MermaidGraph to ELK format (for benchmarking conversion overhead).
  */

package/src/registry.ts

@@ -81,9 +81,9 @@ import { layoutClassDiagramSync } from './class/layout.ts'
 import { renderClassSvg } from './class/renderer.ts'
 import { layoutC4DiagramSync } from './c4/layout.ts'
 import { renderC4Svg } from './c4/renderer.ts'
-import { layoutGraphSync } from './layout-engine.ts'
+import { layoutFlowchartSync, layoutGraphSync } from './layout-engine.ts'
 import { renderSvg as renderFlowchartSvg } from './renderer.ts'
-import { parseMermaid } from '../../../src/parser.ts'
+import { parseMermaid } from '@zombie-mermaid/mermaid-parser'
 
 /**
  * Parameters shared by every per-type SVG renderer today, factored out of
@@ -309,7 +309,7 @@ const flowchartModule: DiagramModule<MermaidGraph, PositionedFlowchart> = {
     // see the doc comment on `PositionedFlowchart` above.
     const graph = withDirectionOverride(diagram, options.direction)
     return {
-      graph: layoutGraphSync(graph, options),
+      graph: layoutFlowchartSync(graph, options),
       curve: options.curve ?? diagram.initConfig?.curve ?? 'linear',
     }
   },

package/src/renderer.ts

@@ -30,6 +30,7 @@ import {
   ARROW_HEAD,
 } from './styles.ts'
 import { pointsToPath } from './edge-curves.ts'
+import { edgeCrossesTitle, titleGapMask, titleTextBoxes } from './title-gaps.ts'
 
 // ============================================================================
 // SVG renderer — converts a PositionedGraph into an SVG string.
@@ -143,6 +144,19 @@ export function renderSvg(
   for (const color of customStrokeColors) {
     parts.push(arrowMarkerDefsForColor(color))
   }
+  // An edge that crosses a subgraph's title text is not painted over the text
+  // (#1239). The mask is only emitted when some edge does, so a diagram with
+  // no such edge is unchanged.
+  const titleBoxes = titleTextBoxes(graph.groups, fontSizes)
+  const crossingEdges = new Set(
+    graph.edges.filter((e) => edgeCrossesTitle(e, titleBoxes)),
+  )
+  let titleGapMaskId: string | undefined
+  if (crossingEdges.size > 0) {
+    const mask = titleGapMask(titleBoxes, graph.width, graph.height)
+    titleGapMaskId = mask.id
+    parts.push(mask.markup)
+  }
   parts.push('</defs>')
 
   // 1. Subgraph backgrounds (group rectangles with header bands)
@@ -153,7 +167,14 @@ export function renderSvg(
   // 2. Edges (paths — rendered behind nodes)
   // Each edge is a <path> with semantic data-* attributes
   for (const edge of graph.edges) {
-    parts.push(renderEdge(edge, curve, animationEnabled))
+    parts.push(
+      renderEdge(
+        edge,
+        curve,
+        animationEnabled,
+        crossingEdges.has(edge) ? titleGapMaskId : undefined,
+      ),
+    )
   }
 
   // 3. Edge labels (positioned at midpoint of edge)
@@ -315,6 +336,7 @@ function renderEdge(
   edge: PositionedEdge,
   curve: CurveStyle,
   animationEnabled: boolean = true,
+  titleGapMaskId?: string,
 ): string {
   if (edge.points.length < 2) return ''
 
@@ -402,7 +424,9 @@ function renderEdge(
   return (
     f`<${curved ? 'path' : 'polyline'} ${dataAttrs.join(' ')} ${geometry} ` +
     f`fill="none" stroke="${strokeColor}" ` +
-    f`stroke-width="${strokeWidth}"${dashArray}${animatedDash}${markers} />`
+    f`stroke-width="${strokeWidth}"${dashArray}${animatedDash}${markers}` +
+    (titleGapMaskId ? f` mask="url(#${titleGapMaskId})"` : '') +
+    ' />'
   )
 }
 

package/src/sequence/layout.ts

@@ -10,6 +10,7 @@ import type {
   PositionedParticipantBox,
 } from '@zombie-mermaid/mermaid-parser'
 import type { RenderOptions, SequenceRenderOptions } from '@zombie-mermaid/core'
+import { measureMultilineText } from '@zombie-mermaid/core'
 import { estimateTextWidth, FONT_WEIGHTS, resolveFontSizes } from '../styles.ts'
 
 // ============================================================================
@@ -77,6 +78,32 @@ export function boxLabelHeight(labelFontSize: number): number {
   return labelFontSize + 8
 }
 
+/**
+ * Distance from the bottom of a stick-figure (`actor`) icon to the vertical
+ * centre of its label. Shared with the renderer so the label lands where the
+ * layout reserved room for it.
+ */
+export const ACTOR_LABEL_OFFSET = 14
+
+/** Clearance kept between an actor label and what sits below it, in px. */
+const ACTOR_LABEL_CLEARANCE = 4
+
+/**
+ * Distance from the bottom of a stick-figure icon to the bottom of its
+ * (possibly multi-line) label. Only `actor` participants draw a label below
+ * the icon; a `participant` box holds its label inside.
+ */
+function actorLabelBottom(
+  label: string,
+  fontSize: number,
+  fontWeight: number,
+): number {
+  return (
+    ACTOR_LABEL_OFFSET +
+    measureMultilineText(label, fontSize, fontWeight).height / 2
+  )
+}
+
 /** Resolved sequence-layout config — same shape as {@link SEQ} but mutable numbers. */
 type SeqConfig = { [K in keyof typeof SEQ]: number }
 
@@ -194,8 +221,32 @@ export function layoutSequenceDiagram(
     return positioned
   })
 
-  // 3. Stack messages vertically
-  let messageY = actorY + seq.actorHeight + seq.headerGap
+  // 3. Stack messages vertically. A stick-figure actor's label sits below its
+  //    icon, in the gap before the first message; widen the gap so the label
+  //    (and the first message's own label above its arrow) never touch.
+  //    Participants created mid-diagram are placed at their creating message
+  //    instead, so they don't take part in the header.
+  const actorLabelBottoms = diagram.actors.map((a) =>
+    a.type === 'actor'
+      ? actorLabelBottom(a.label, fontSizes.nodeLabel, FONT_WEIGHTS.nodeLabel)
+      : 0,
+  )
+  const headerLabelBottom = Math.max(
+    0,
+    ...diagram.actors.map((a, i) =>
+      a.createdAt === undefined ? actorLabelBottoms[i]! : 0,
+    ),
+  )
+  const firstMessageLabelRoom = fontSizes.edgeLabel + 12
+  let messageY =
+    actorY +
+    seq.actorHeight +
+    Math.max(
+      seq.headerGap,
+      headerLabelBottom > 0
+        ? headerLabelBottom + ACTOR_LABEL_CLEARANCE + firstMessageLabelRoom
+        : 0,
+    )
   const messages: PositionedMessage[] = []
 
   // Pre-scan blocks to determine which message indices need extra vertical
@@ -292,7 +343,9 @@ export function layoutSequenceDiagram(
     { startY: number; depth: number }[]
   >()
   const activations: Activation[] = []
-  const nestingOffset = 4 // Horizontal offset per nesting level
+  // Horizontal offset per nesting level: half a bar, as official Mermaid does,
+  // so a nested bar overlaps its parent by half instead of hiding behind it.
+  const nestingOffset = seq.activationWidth / 2
 
   /** Open an activation bar on `actorId` at row `y` (stacks for nesting). */
   function startActivation(actorId: string, y: number): void {
@@ -320,6 +373,7 @@ export function layoutSequenceDiagram(
       topY: startY,
       bottomY: y,
       width: seq.activationWidth,
+      depth,
     })
   }
 
@@ -488,10 +542,17 @@ export function layoutSequenceDiagram(
         topY: startY,
         bottomY: messageY - seq.messageRowHeight / 2,
         width: seq.activationWidth,
+        depth,
       })
     }
   }
 
+  // Paint outer bars before the bars nested inside them. Bars are pushed in
+  // close order, so an inner one otherwise precedes (and is covered by) its
+  // parent, which closes later. Array#sort is stable, so equal depths keep
+  // their order.
+  activations.sort((a, b) => a.depth - b.depth)
+
   // 4. Position blocks (loop/alt/opt)
   const blocks: PositionedBlock[] = diagram.blocks.map((block) => {
     // Block spans from the Y of startIndex to endIndex messages
@@ -664,7 +725,14 @@ export function layoutSequenceDiagram(
     const lifeline: Lifeline = {
       actorId: a.id,
       x: actorCenterX[i]!,
-      topY: actors[i]!.y + seq.actorHeight,
+      // A stick-figure actor's label sits on the lifeline's axis just below
+      // the icon, so the line starts under it rather than through it.
+      topY:
+        actors[i]!.y +
+        seq.actorHeight +
+        (actorLabelBottoms[i]! > 0
+          ? actorLabelBottoms[i]! + ACTOR_LABEL_CLEARANCE
+          : 0),
       bottomY:
         destroyedAt === undefined
           ? diagramBottom - seq.padding