@zombie-mermaid/svg-renderer 3.2.0 → 4.0.0

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

@@ -50,10 +50,11 @@ export type ElkDirection = 'DOWN' | 'UP' | 'LEFT' | 'RIGHT'
  * - **C4** — `DOWN`. `C4Diagram.direction` is never set by the parser (C4
  *   sources have no direction statement), only by `RenderOptions.direction`,
  *   so an unset one is the top-down layout every C4 diagram is drawn in.
- * - **ER** — `RIGHT`. An ER diagram's `direction` is optional
+ * - **ER** — `DOWN`. 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
+ *   `direction` statement, and official Mermaid lays those out top-to-bottom
+ *   (#1250; this renderer used to lay them out left-to-right).
+ *   `direction TB`/`LR`/`BT`/`RL` in the source (or
  *   `RenderOptions.direction`, applied via `withDirectionOverride`) still
  *   wins over it.
  *
@@ -67,7 +68,7 @@ export const ELK_DIRECTION_FALLBACK = {
   flowchart: 'DOWN',
   state: 'DOWN',
   class: 'DOWN',
-  er: 'RIGHT',
+  er: 'DOWN',
   c4: 'DOWN',
 } as const satisfies Record<string, ElkDirection>
 

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

@@ -22,6 +22,7 @@ import { clipEdgeToShape } from '../shape-clipping.ts'
 import { DEFAULTS } from './constants.ts'
 import { alignLayerNodes } from './layer-alignment.ts'
 import { bundleEdgePaths } from './edge-bundling.ts'
+import { edgesReversedForLayout } from './to-elk.ts'
 import {
   extractEdgePoints,
   extractEdgeLabelPosition,
@@ -527,7 +528,11 @@ function extractEdgesRecursively(
       style: originalEdge.style,
       hasArrowStart: originalEdge.hasArrowStart,
       hasArrowEnd: originalEdge.hasArrowEnd,
-      points: orthogonalPoints,
+      // An edge laid out reversed (see `edgesReversedForLayout`) comes back
+      // running target to source; flip it so it runs source to target again.
+      points: edgesReversedForLayout(graph).has(edgeIndex)
+        ? [...orthogonalPoints].reverse()
+        : orthogonalPoints,
       labelPosition,
       inlineStyle: resolveEdgeStyle(edgeIndex, graph),
       id: originalEdge.id,
@@ -740,7 +745,7 @@ function collectAllSubgraphIds(sg: MermaidSubgraph, out: Set<string>): void {
  * Resolve inline styles for an edge from linkStyles map.
  * Default link style is applied first, then index-specific overrides.
  */
-function resolveEdgeStyle(
+export function resolveEdgeStyle(
   edgeIndex: number,
   graph: MermaidGraph,
 ): Record<string, string> | undefined {

package/src/layout-engine/inner-edges.ts

@@ -0,0 +1,329 @@
+/**
+ * Routes an edge between two members of a subgraph through the inside of its
+ * box.
+ *
+ * `compound-flat.ts` keeps outsiders out of a box with invisible spine nodes in
+ * the layers where the subgraph has no member. An edge from one member to
+ * another that spans such a layer has to get past the spine, and ELK sends it
+ * round the outside, which drags its end node, and so the box, sideways. These
+ * edges are left out of the layout and drawn afterwards by `routeInnerEdge`,
+ * which runs them down a channel between the members.
+ *
+ * Everything is worked out as (a, c): `a` along the flow, increasing with it,
+ * and `c` across it. For `TD` that is (y, x); `BT` negates `a`, `LR` is (x, y).
+ */
+
+import type { Direction, Point, PositionedNode } from '@zombie-mermaid/core'
+
+/** Room kept between a route and the nodes it passes, in px. */
+const CLEARANCE = 10
+
+/** Least distance between two routes that run side by side, in px. */
+const PARALLEL_GAP = 14
+
+/** How far an edge runs out of a node before turning, in px. */
+const STUB = 14
+
+/** Room kept between a route and the box's border, in px. */
+const BORDER_INSET = 10
+
+/** Cost of each bend, in px of extra length, so a straighter route wins. */
+const BEND_COST = 24
+
+/** Extra cost of leaving a decision by its bottom vertex, in px. */
+const DECISION_STEM = 400
+
+/** Shapes whose whole edge is a straight side an edge can leave from anywhere. */
+const FLAT_SIDED = new Set(['rectangle', 'rounded', 'subroutine'])
+
+interface Span {
+  a0: number
+  a1: number
+  c0: number
+  c1: number
+}
+
+interface Pt {
+  a: number
+  c: number
+}
+
+interface Frame {
+  span: (box: BoxLike) => Span
+  toPoint: (p: Pt) => Point
+}
+
+type BoxLike = { x: number; y: number; width: number; height: number }
+
+function frameFor(direction: Direction): Frame {
+  const vertical =
+    direction === 'TD' || direction === 'TB' || direction === 'BT'
+  const flip = direction === 'BT' || direction === 'RL'
+  const sign = flip ? -1 : 1
+  return {
+    span: (b) => {
+      const [p0, p1] = vertical ? [b.y, b.y + b.height] : [b.x, b.x + b.width]
+      const a0 = sign * p0
+      const a1 = sign * p1
+      return {
+        a0: Math.min(a0, a1),
+        a1: Math.max(a0, a1),
+        c0: vertical ? b.x : b.y,
+        c1: vertical ? b.x + b.width : b.y + b.height,
+      }
+    },
+    toPoint: ({ a, c }) =>
+      vertical ? { x: c, y: sign * a } : { x: sign * a, y: c },
+  }
+}
+
+/** Whether the segment `p`-`q` (one axis only) passes through the inside of `s`. */
+function crosses(p: Pt, q: Pt, s: Span): boolean {
+  const aLo = Math.min(p.a, q.a)
+  const aHi = Math.max(p.a, q.a)
+  const cLo = Math.min(p.c, q.c)
+  const cHi = Math.max(p.c, q.c)
+  return aHi > s.a0 && aLo < s.a1 && cHi > s.c0 && cLo < s.c1
+}
+
+const grow = (s: Span, by: number): Span => ({
+  a0: s.a0 - by,
+  a1: s.a1 + by,
+  c0: s.c0 - by,
+  c1: s.c1 + by,
+})
+
+/** The (a, c) of a point in `frame`. */
+function toPt(frame: Frame, p: Point): Pt {
+  const s = frame.span({ x: p.x, y: p.y, width: 0, height: 0 })
+  return { a: s.a0, c: s.c0 }
+}
+
+/** Whether the segment `p`-`q` runs beside a segment of `path`, closer than `PARALLEL_GAP`. */
+function runsAlong(p: Pt, q: Pt, path: readonly Pt[]): boolean {
+  const flowwise = p.c === q.c
+  for (let i = 1; i < path.length; i++) {
+    const r = path[i - 1]!
+    const t = path[i]!
+    if ((r.c === t.c) !== flowwise) continue
+    if (flowwise) {
+      const apart = Math.abs(p.c - r.c)
+      const shared =
+        Math.min(Math.max(p.a, q.a), Math.max(r.a, t.a)) -
+        Math.max(Math.min(p.a, q.a), Math.min(r.a, t.a))
+      if (apart < PARALLEL_GAP && shared > 0) return true
+    } else {
+      const apart = Math.abs(p.a - r.a)
+      const shared =
+        Math.min(Math.max(p.c, q.c), Math.max(r.c, t.c)) -
+        Math.max(Math.min(p.c, q.c), Math.min(r.c, t.c))
+      if (apart < PARALLEL_GAP && shared > 0) return true
+    }
+  }
+  return false
+}
+
+/** The path with repeated points and points in the middle of a straight run removed. */
+function simplify(path: Pt[]): Pt[] {
+  const out: Pt[] = []
+  for (const p of path) {
+    const last = out[out.length - 1]
+    if (last && last.a === p.a && last.c === p.c) continue
+    out.push(p)
+  }
+  for (let i = out.length - 2; i > 0; i--) {
+    const prev = out[i - 1]!
+    const here = out[i]!
+    const next = out[i + 1]!
+    const straight =
+      (prev.a === here.a && here.a === next.a) ||
+      (prev.c === here.c && here.c === next.c)
+    if (straight) out.splice(i, 1)
+  }
+  return out
+}
+
+const length = (path: Pt[]): number => {
+  let total = 0
+  for (let i = 1; i < path.length; i++) {
+    total +=
+      Math.abs(path[i]!.a - path[i - 1]!.a) +
+      Math.abs(path[i]!.c - path[i - 1]!.c)
+  }
+  return total
+}
+
+/**
+ * A route for the edge from `source` to `target`, both inside `bounds` (their
+ * subgraph's box), kept clear of `others`. The cheapest of a straight line, a
+ * Z for an edge that runs with the flow, and a hook out of the side of the
+ * source and up the side of the target for one that runs against it. `undefined`
+ * if nothing fits.
+ */
+export function routeInnerEdge(
+  source: PositionedNode,
+  target: PositionedNode,
+  others: readonly PositionedNode[],
+  bounds: BoxLike,
+  direction: Direction,
+  drawn: readonly (readonly Point[])[] = [],
+): Point[] | undefined {
+  const frame = frameFor(direction)
+  const S = frame.span(source)
+  const T = frame.span(target)
+  const forward = S.a1 <= T.a0
+  const backward = T.a1 <= S.a0
+  if (!forward && !backward) return undefined
+
+  const inner = frame.span(bounds)
+  const room: Span = {
+    a0: inner.a0 + BORDER_INSET,
+    a1: inner.a1 - BORDER_INSET,
+    c0: inner.c0 + BORDER_INSET,
+    c1: inner.c1 - BORDER_INSET,
+  }
+  const before = drawn.map((path) => path.map((p) => toPt(frame, p)))
+  const blocks = others.map((n) => grow(frame.span(n), CLEARANCE))
+  const mid = (s: Span): number => (s.c0 + s.c1) / 2
+  const midA = (s: Span): number => (s.a0 + s.a1) / 2
+  const flat = (n: PositionedNode): boolean => FLAT_SIDED.has(n.shape)
+
+  /** Whether every segment is clear of the nodes, the ends touch only their own node, and it stays in the box. */
+  const valid = (path: Pt[]): boolean => {
+    for (const p of path) {
+      if (p.a < room.a0 || p.a > room.a1 || p.c < room.c0 || p.c > room.c1) {
+        return false
+      }
+    }
+    for (let i = 1; i < path.length; i++) {
+      const p = path[i - 1]!
+      const q = path[i]!
+      if (p.a !== q.a && p.c !== q.c) return false
+      if (blocks.some((b) => crosses(p, q, b))) return false
+      if (crosses(p, q, S) || crosses(p, q, T)) return false
+      if (before.some((path) => runsAlong(p, q, path))) return false
+    }
+    return true
+  }
+
+  // Cross-flow positions worth trying: where the two nodes are, and just clear
+  // of every node and the box's border.
+  const candidates = new Set<number>([mid(S), mid(T), room.c0, room.c1])
+  for (const b of blocks) {
+    candidates.add(b.c0 - 1)
+    candidates.add(b.c1 + 1)
+  }
+  for (const s of [S, T]) {
+    candidates.add(s.c0 - CLEARANCE)
+    candidates.add(s.c1 + CLEARANCE)
+  }
+  const within = (n: PositionedNode, s: Span, c: number): boolean =>
+    flat(n) ? c >= s.c0 + 4 && c <= s.c1 - 4 : Math.abs(c - mid(s)) < 0.5
+
+  const routes: Pt[][] = []
+  if (forward) {
+    const gap = (T.a0 - S.a1) / 2
+    const a1 = S.a1 + Math.min(STUB, gap)
+    const a2 = T.a0 - Math.min(STUB, gap)
+    for (const c of candidates) {
+      if (within(source, S, c) && within(target, T, c)) {
+        routes.push([
+          { a: S.a1, c },
+          { a: T.a0, c },
+        ])
+      }
+      // A Z, or an L-shaped pair of turns when one end can take the edge off centre.
+      routes.push([
+        { a: S.a1, c: mid(S) },
+        { a: a1, c: mid(S) },
+        { a: a1, c },
+        { a: a2, c },
+        { a: a2, c: mid(T) },
+        { a: T.a0, c: mid(T) },
+      ])
+      if (within(target, T, c)) {
+        routes.push([
+          { a: S.a1, c: mid(S) },
+          { a: a1, c: mid(S) },
+          { a: a1, c },
+          { a: T.a0, c },
+        ])
+      }
+      if (within(source, S, c)) {
+        routes.push([
+          { a: S.a1, c },
+          { a: a2, c },
+          { a: a2, c: mid(T) },
+          { a: T.a0, c: mid(T) },
+        ])
+      }
+      // Out of the source's side and down: for a decision, whose other
+      // branches leave by the bottom.
+      const side = c >= S.c1 ? S.c1 : c <= S.c0 ? S.c0 : undefined
+      if (side !== undefined) {
+        const down = within(target, T, c)
+          ? [{ a: T.a0, c }]
+          : [
+              { a: a2, c },
+              { a: a2, c: mid(T) },
+              { a: T.a0, c: mid(T) },
+            ]
+        routes.push([{ a: midA(S), c: side }, { a: midA(S), c }, ...down])
+      }
+    }
+  } else {
+    for (const c of candidates) {
+      const side = c >= T.c1 ? T.c1 : c <= T.c0 ? T.c0 : undefined
+      if (side === undefined) continue
+      // Out of the source's back, up, and into the target's side.
+      if (within(source, S, c)) {
+        routes.push([
+          { a: S.a0, c },
+          { a: midA(T), c },
+          { a: midA(T), c: side },
+        ])
+      }
+      // Out of the source's side, along, up, and into the target's side.
+      const out = side === T.c1 ? S.c1 : S.c0
+      routes.push([
+        { a: midA(S), c: out },
+        { a: midA(S), c },
+        { a: midA(T), c },
+        { a: midA(T), c: side },
+      ])
+    }
+  }
+
+  let best: Pt[] | undefined
+  let bestCost = Number.POSITIVE_INFINITY
+  for (const route of routes) {
+    const path = simplify(route)
+    if (path.length < 2 || !valid(path)) continue
+    // A decision's branches fan out of its sides; leaving by the bottom only
+    // when nothing else fits.
+    const stem =
+      source.shape === 'diamond' && path[0]!.a === S.a1 ? DECISION_STEM : 0
+    const cost = length(path) + BEND_COST * (path.length - 2) + stem
+    if (cost < bestCost) {
+      best = path
+      bestCost = cost
+    }
+  }
+  return best?.map(frame.toPoint)
+}
+
+/** The middle of a path's longest segment, where an edge label sits. */
+export function labelSpot(points: readonly Point[]): Point {
+  let best = { x: points[0]!.x, y: points[0]!.y }
+  let longest = -1
+  for (let i = 1; i < points.length; i++) {
+    const p = points[i - 1]!
+    const q = points[i]!
+    const len = Math.abs(q.x - p.x) + Math.abs(q.y - p.y)
+    if (len > longest) {
+      longest = len
+      best = { x: (p.x + q.x) / 2, y: (p.y + q.y) / 2 }
+    }
+  }
+  return best
+}

package/src/layout-engine/layout-hints.ts

@@ -0,0 +1,27 @@
+/**
+ * Extra instructions a caller can give the layout pipeline for one run, for
+ * things a `MermaidGraph` has no way to say. Used by the compound layout
+ * (`compound-flat.ts`), which adds invisible helper nodes and edges to the
+ * graph and has to size, order and weight them.
+ */
+export interface LayoutHints {
+  /** Node widths in px, used instead of the size worked out from the label. */
+  fixedWidths?: ReadonlyMap<string, number>
+  /**
+   * Indices of edges that only shape the layout and are never drawn. They are
+   * not straightened, so they can't drag the nodes they join into line.
+   */
+  looseEdges?: ReadonlySet<number>
+  /**
+   * Indices of real edges to leave out of the layout. The caller draws them
+   * itself, so ELK doesn't route them round the helper nodes.
+   */
+  detachedEdges?: ReadonlySet<number>
+  /**
+   * The order a back-edge search starts from, when it must differ from the
+   * graph's node order (which is also the order ELK is given the nodes in).
+   */
+  walkOrder?: readonly string[]
+  /** Keep every layer's nodes in the order the graph lists them. */
+  forceNodeOrder?: boolean
+}

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,100 @@ 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).
+ *
+ * - `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 +252,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 +327,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 +423,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 +436,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 +535,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)
     }
   }
 
@@ -460,7 +575,14 @@ export function mermaidToElk(
   // 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()) {
+  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 +595,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 +656,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 +717,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 +768,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),
       }),