@zombie-mermaid/svg-renderer 4.2.3 → 5.0.0

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

@@ -1,329 +0,0 @@
-/**
- * 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/jog-straightening.ts

@@ -1,52 +0,0 @@
-/**
- * Straighten sub-pixel jogs in orthogonal edge routes.
- *
- * ELK spreads parallel edges across each node's side relative to that node's
- * own width, so two edges between differently sized, centered nodes leave and
- * arrive at slightly different offsets. The route then runs straight, steps
- * sideways by a fraction of a pixel, and runs straight again — a visible kink
- * that also tilts the arrowhead off the edge's axis (#1388).
- */
-
-import type { Point } from '@zombie-mermaid/core'
-
-/** Largest sideways step, in px, treated as an artifact rather than a bend. */
-const MAX_JOG = 1.5
-
-/** Slack for deciding two coordinates are "the same" run. */
-const EPS = 0.01
-
-/**
- * Collapse `run, tiny step, run` into one straight run along the shared axis.
- * Pattern (vertical form): A-B vertical, B-C horizontal with |dx| <= MAX_JOG,
- * C-D vertical. Returns a new array; the input is not mutated.
- */
-export function straightenTinyJogs(points: Point[]): Point[] {
-  const out = points.map((p) => ({ ...p }))
-  let i = 0
-  while (i + 3 < out.length) {
-    const [a, b, c, d] = [out[i]!, out[i + 1]!, out[i + 2]!, out[i + 3]!]
-    const vertical =
-      Math.abs(a.x - b.x) < EPS &&
-      Math.abs(c.x - d.x) < EPS &&
-      Math.abs(b.y - c.y) < EPS &&
-      Math.abs(b.x - c.x) <= MAX_JOG &&
-      Math.abs(b.x - c.x) >= EPS
-    const horizontal =
-      Math.abs(a.y - b.y) < EPS &&
-      Math.abs(c.y - d.y) < EPS &&
-      Math.abs(b.x - c.x) < EPS &&
-      Math.abs(b.y - c.y) <= MAX_JOG &&
-      Math.abs(b.y - c.y) >= EPS
-    if (vertical) {
-      const x = (a.x + d.x) / 2
-      out.splice(i, 4, { x, y: a.y }, { x, y: d.y })
-    } else if (horizontal) {
-      const y = (a.y + d.y) / 2
-      out.splice(i, 4, { x: a.x, y }, { x: d.x, y })
-    } else {
-      i++
-    }
-  }
-  return out
-}

package/src/layout-engine/layer-alignment.ts

@@ -1,174 +0,0 @@
-/**
- * Layer alignment — snap same-layer nodes to a uniform position.
- * Split out of layout-engine.ts as a self-contained post-processing pass
- * over a PositionedGraph's nodes/edges.
- */
-
-import type {
-  PositionedNode,
-  PositionedEdge,
-  Direction,
-} from '@zombie-mermaid/core'
-import { DEFAULTS } from './constants.ts'
-
-/**
- * ELK's orthogonal edge routing staggers nodes within the same layer to create
- * space for edge bends. This post-processing step groups nodes into layers and
- * snaps them to the same flow-axis coordinate (Y for TD/TB, X for LR/RL).
- *
- * Grouping uses proximity along the flow axis: within a layer, ELK's stagger
- * is always less than layerSpacing (bounded by edge routing channels), while
- * adjacent layers are separated by at least layerSpacing + nodeHeight.
- * A threshold of 0.75 * layerSpacing cleanly separates these cases.
- *
- * Directly connected nodes (sharing an edge) are never merged into the same
- * layer group as an additional safety check.
- *
- * Edge endpoints connected to shifted nodes are adjusted proportionally.
- * Intermediate bend points are left unchanged — edge bundling or clipping
- * will recalculate them afterwards.
- */
-// Audited for issue #100 (non-null assertions): every `!` in this file is
-// a bounds-checked array access, each backed by an explicit check earlier
-// in the same scope — `sorted[0]!` and the `sorted[i]!`/`sorted[i - 1]!`
-// loop-index accesses below are guaranteed by the `nodes.length === 0`
-// early return plus the `for (let i = 1; i < sorted.length; ...)` loop
-// bound; `edge.points[0]!`, `edge.points[1]!`, and the
-// `edge.points[edge.points.length - 1]!` / `[edge.points.length - 2]!`
-// pairs are guaranteed by the `edge.points.length < 2` early `continue`
-// (and, redundantly, the `edge.points.length > 1` checks right above each
-// access). This is the same idiom already accepted as justified elsewhere
-// in this codebase (see src/parser.ts, PR #158, and this directory's
-// edge-bundling.ts/from-elk.ts audit, PR #150, which didn't reach this
-// file). `noUncheckedIndexedAccess` can't see any of these guarantees,
-// but removing the `!` would only replace a proven-safe assertion with an
-// unreachable guard. Left as-is; no behavior change.
-export function alignLayerNodes(
-  nodes: PositionedNode[],
-  edges: PositionedEdge[],
-  direction: Direction,
-): void {
-  if (nodes.length === 0) return
-
-  const isHorizontal = direction === 'LR' || direction === 'RL'
-
-  // Build set of directly-connected node pairs.
-  // Nodes connected by an edge must not be merged into the same layer.
-  const connectedPairs = new Set<string>()
-  for (const edge of edges) {
-    connectedPairs.add(`${edge.source}:${edge.target}`)
-    connectedPairs.add(`${edge.target}:${edge.source}`)
-  }
-
-  // ELK's stagger creates small gaps between adjacent nodes in the same layer
-  // (typically edgeEdge spacing = 12px per routing channel). Adjacent layers
-  // are separated by at least layerSpacing (48px). We use single-linkage
-  // clustering: a node joins the current layer if the gap from the previous
-  // node (in sorted order) is within threshold, AND it has no direct edge to
-  // any node already in the layer.
-  const THRESHOLD = DEFAULTS.layerSpacing * 0.6
-
-  // Sort nodes by flow-axis position
-  const sorted = [...nodes].sort((a, b) =>
-    isHorizontal ? a.x - b.x : a.y - b.y,
-  )
-
-  const layers: PositionedNode[][] = []
-  let currentLayer: PositionedNode[] = [sorted[0]!]
-
-  for (let i = 1; i < sorted.length; i++) {
-    const pos = isHorizontal ? sorted[i]!.x : sorted[i]!.y
-    const prevPos = isHorizontal ? sorted[i - 1]!.x : sorted[i - 1]!.y
-    // Single-linkage: compare with previous node, not layer start
-    const gap = pos - prevPos
-    // Check if this node is connected to any node already in the current layer
-    const hasEdgeToLayer = currentLayer.some((n) =>
-      connectedPairs.has(`${n.id}:${sorted[i]!.id}`),
-    )
-    if (gap <= THRESHOLD && !hasEdgeToLayer) {
-      currentLayer.push(sorted[i]!)
-    } else {
-      layers.push(currentLayer)
-      currentLayer = [sorted[i]!]
-    }
-  }
-  layers.push(currentLayer)
-
-  // Snap each layer's nodes to the layer's center position
-  const deltas = new Map<string, number>() // nodeId → shift amount
-
-  for (const layer of layers) {
-    if (layer.length <= 1) continue
-
-    const positions = layer.map((n) => (isHorizontal ? n.x : n.y))
-    const min = Math.min(...positions)
-    const max = Math.max(...positions)
-    if (max - min <= 1) continue // Already aligned
-
-    // Use the center of the range as the snap target
-    const target = (min + max) / 2
-
-    for (const node of layer) {
-      const oldPos = isHorizontal ? node.x : node.y
-      const delta = target - oldPos
-      if (Math.abs(delta) > 0.5) {
-        if (isHorizontal) {
-          node.x = target
-        } else {
-          node.y = target
-        }
-        deltas.set(node.id, delta)
-      }
-    }
-  }
-
-  if (deltas.size === 0) return
-
-  // Adjust edge endpoints to match shifted node positions
-  for (const edge of edges) {
-    if (edge.points.length < 2) continue
-
-    const srcDelta = deltas.get(edge.source)
-    const tgtDelta = deltas.get(edge.target)
-
-    if (srcDelta != null) {
-      // Shift first point and any subsequent points in the initial vertical/horizontal run
-      const first = edge.points[0]!
-      if (isHorizontal) {
-        first.x += srcDelta
-        // Shift second point if it's part of a straight vertical exit
-        if (
-          edge.points.length > 1 &&
-          edge.points[1]!.x === first.x - srcDelta
-        ) {
-          edge.points[1]!.x += srcDelta
-        }
-      } else {
-        first.y += srcDelta
-        if (
-          edge.points.length > 1 &&
-          edge.points[1]!.y === first.y - srcDelta
-        ) {
-          edge.points[1]!.y += srcDelta
-        }
-      }
-    }
-
-    if (tgtDelta != null) {
-      const last = edge.points[edge.points.length - 1]!
-      if (isHorizontal) {
-        last.x += tgtDelta
-        if (edge.points.length > 1) {
-          const prev = edge.points[edge.points.length - 2]!
-          if (prev.x === last.x - tgtDelta) prev.x += tgtDelta
-        }
-      } else {
-        last.y += tgtDelta
-        if (edge.points.length > 1) {
-          const prev = edge.points[edge.points.length - 2]!
-          if (prev.y === last.y - tgtDelta) prev.y += tgtDelta
-        }
-      }
-    }
-  }
-}

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

@@ -1,27 +0,0 @@
-/**
- * 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
-}