@zombie-mermaid/svg-renderer 2.2.1

package/src/edge-curves.ts

@@ -0,0 +1,204 @@
+// ============================================================================
+// zombie-mermaid — edge path interpolation (Mermaid's `flowchart.curve`)
+//
+// ELK routes an edge as a list of bend points. How those points are joined
+// into a drawn line is a separate, purely presentational choice, which
+// Mermaid exposes as `%%{init: {"flowchart": {"curve": "basis"}}}%%`.
+//
+// Every curve here consumes the same routed points, so switching styles never
+// changes where an edge goes — only how it looks getting there.
+// ============================================================================
+
+import type { Point, CurveStyle } from '@zombie-mermaid/core'
+
+/** `M x y` for the first point. */
+function moveTo(p: Point): string {
+  return `M ${p.x} ${p.y}`
+}
+
+/** Straight segments through every point — the historical default. */
+function linearPath(points: Point[]): string {
+  return (
+    moveTo(points[0]!) +
+    points
+      .slice(1)
+      .map((p) => ` L ${p.x} ${p.y}`)
+      .join('')
+  )
+}
+
+/**
+ * Uniform cubic B-spline, matching d3's `curveBasis` (what Mermaid uses for
+ * `basis`).
+ *
+ * A B-spline is *approximating*, not interpolating: it passes through neither
+ * the interior points nor, without the endpoint handling below, the ends. The
+ * first and last points are therefore emitted explicitly so an edge still
+ * touches the nodes it connects — otherwise it would visibly detach.
+ *
+ * This is a direct port of d3's `Basis` curve rather than a lookalike, so a
+ * diagram rendered here traces the same path Mermaid would draw. For each
+ * point d3 emits one cubic whose controls are the thirds between the two
+ * preceding points and whose end is the B-spline knot `(p0 + 4p1 + p2) / 6`;
+ * it leads in at `(5p0 + p1) / 6` and closes with a final cubic against a
+ * repeated last point, then a line to it.
+ */
+function basisPath(points: Point[]): string {
+  if (points.length < 3) return linearPath(points)
+
+  const last = points[points.length - 1]!
+  const parts: string[] = [moveTo(points[0]!)]
+
+  /** One B-spline segment across three successive control points. */
+  const segment = (p0: Point, p1: Point, p2: Point): string =>
+    ` C ${(2 * p0.x + p1.x) / 3} ${(2 * p0.y + p1.y) / 3},` +
+    ` ${(p0.x + 2 * p1.x) / 3} ${(p0.y + 2 * p1.y) / 3},` +
+    ` ${(p0.x + 4 * p1.x + p2.x) / 6} ${(p0.y + 4 * p1.y + p2.y) / 6}`
+
+  // Lead-in to the first knot, one sixth of the way along the opening leg.
+  parts.push(
+    ` L ${(5 * points[0]!.x + points[1]!.x) / 6}` +
+      ` ${(5 * points[0]!.y + points[1]!.y) / 6}`,
+  )
+
+  for (let i = 2; i < points.length; i++) {
+    parts.push(segment(points[i - 2]!, points[i - 1]!, points[i]!))
+  }
+
+  // d3 closes by feeding the last point twice, then drawing to it.
+  parts.push(segment(points[points.length - 2]!, last, last))
+  parts.push(` L ${last.x} ${last.y}`)
+
+  return parts.join('')
+}
+
+/**
+ * Straight runs joined by rounded corners. Mermaid calls this `natural`.
+ *
+ * NOTE: this is deliberately *not* d3's interpolating natural cubic spline.
+ * ELK routes edges orthogonally, so every bend is a right angle, and at a
+ * right angle the tangent of any C1-smooth interpolating spline is the
+ * average of the two segment directions — i.e. diagonal. The curve must then
+ * arrive at the corner travelling diagonally while approaching from directly
+ * above, so it bulges sideways past the straight line. Two mirrored edges
+ * leaving one decision node turned that bulge into a visible teardrop loop.
+ * Scaling the tangents down shrinks the overshoot but cannot remove it; it is
+ * a property of interpolating a 90° corner smoothly.
+ *
+ * Rounding the corners instead gives a smooth path that never overshoots and
+ * stays visually distinct from `basis`, which cuts corners far more deeply.
+ * The trade is that the path passes *near* each bend rather than exactly
+ * through it — documented in docs/diagrams.md.
+ */
+function naturalPath(points: Point[]): string {
+  if (points.length < 3) return linearPath(points)
+
+  /** Largest corner radius, in px. Kept small so edges stay readable. */
+  const MAX_RADIUS = 12
+
+  const parts: string[] = [moveTo(points[0]!)]
+
+  for (let i = 1; i < points.length - 1; i++) {
+    const prev = points[i - 1]!
+    const corner = points[i]!
+    const next = points[i + 1]!
+
+    const inLen = Math.hypot(corner.x - prev.x, corner.y - prev.y)
+    const outLen = Math.hypot(next.x - corner.x, next.y - corner.y)
+
+    // A zero-length leg means duplicated routed points; there is no corner
+    // to round, so pass straight through.
+    if (inLen === 0 || outLen === 0) {
+      parts.push(` L ${corner.x} ${corner.y}`)
+      continue
+    }
+
+    // Never consume more than half of either adjacent leg, so neighbouring
+    // corners cannot overlap and invert the path.
+    const radius = Math.min(MAX_RADIUS, inLen / 2, outLen / 2)
+
+    const startX = corner.x - ((corner.x - prev.x) / inLen) * radius
+    const startY = corner.y - ((corner.y - prev.y) / inLen) * radius
+    const endX = corner.x + ((next.x - corner.x) / outLen) * radius
+    const endY = corner.y + ((next.y - corner.y) / outLen) * radius
+
+    // Straight up to the fillet, then a quadratic through the corner.
+    parts.push(` L ${startX} ${startY}`)
+    parts.push(` Q ${corner.x} ${corner.y}, ${endX} ${endY}`)
+  }
+
+  const last = points[points.length - 1]!
+  parts.push(` L ${last.x} ${last.y}`)
+
+  return parts.join('')
+}
+
+/**
+ * Right-angle staircase between consecutive points.
+ *
+ * `where` picks when the step happens: at the midpoint (`step`), immediately
+ * (`stepBefore`), or at the end of the run (`stepAfter`) — matching d3's
+ * curveStep family.
+ *
+ * The final segment is deliberately left straight, running along the original
+ * approach direction. An SVG marker with `orient="auto"` takes its angle from
+ * the last path segment, so a staircase that ends on a horizontal leg points
+ * the arrowhead sideways into the target node instead of at it. Keeping the
+ * last leg means the arrow still aims the way the routed edge does.
+ */
+function stepPath(points: Point[], where: 'mid' | 'before' | 'after'): string {
+  const parts: string[] = [moveTo(points[0]!)]
+  const lastIndex = points.length - 1
+
+  for (let i = 0; i < lastIndex; i++) {
+    const a = points[i]!
+    const b = points[i + 1]!
+
+    if (i === lastIndex - 1) {
+      parts.push(` L ${b.x} ${b.y}`)
+      break
+    }
+
+    if (where === 'before') {
+      parts.push(` L ${a.x} ${b.y} L ${b.x} ${b.y}`)
+    } else if (where === 'after') {
+      parts.push(` L ${b.x} ${a.y} L ${b.x} ${b.y}`)
+    } else {
+      const midY = (a.y + b.y) / 2
+      parts.push(` L ${a.x} ${midY} L ${b.x} ${midY} L ${b.x} ${b.y}`)
+    }
+  }
+
+  return parts.join('')
+}
+
+/**
+ * Build the `d` attribute for an edge's routed points under `curve`.
+ *
+ * A path with fewer than two points cannot be drawn; the caller already skips
+ * those, but this degrades to an empty string rather than emitting `M`
+ * followed by nothing.
+ */
+export function pointsToPath(
+  points: Point[],
+  curve: CurveStyle = 'linear',
+): string {
+  if (points.length === 0) return ''
+  if (points.length === 1) return moveTo(points[0]!)
+
+  switch (curve) {
+    case 'basis':
+      return basisPath(points)
+    case 'natural':
+      return naturalPath(points)
+    case 'step':
+      return stepPath(points, 'mid')
+    case 'stepBefore':
+      return stepPath(points, 'before')
+    case 'stepAfter':
+      return stepPath(points, 'after')
+    case 'linear':
+    default:
+      return linearPath(points)
+  }
+}

package/src/elk-instance.ts

@@ -0,0 +1,292 @@
+/**
+ * Shared ELK instance singleton.
+ *
+ * Uses elk.bundled.js (pure synchronous JS, ~1.6 MB) for all environments.
+ * The singleton is created lazily on first use and cached forever.
+ *
+ * ELK's FakeWorker wraps both postMessage and onmessage in setTimeout(0),
+ * making the normal API fully async. To bypass this:
+ *   1. During construction, we capture setTimeout(0) callbacks and flush them
+ *      synchronously — this registers the layout algorithms immediately.
+ *   2. For layout calls, we call dispatcher.saveDispatch() directly (skipping
+ *      the FakeWorker's postMessage setTimeout) and intercept the result via
+ *      rawWorker.onmessage (which the dispatcher calls synchronously).
+ */
+
+import type { ELK, ElkNode } from 'elkjs'
+import ELKBundled from 'elkjs/lib/elk.bundled.js'
+import type { LayoutCache } from '@zombie-mermaid/core'
+
+/** The message envelope ELK's FakeWorker passes to `dispatcher.saveDispatch()`
+ * to request a layout run. Mirrors the shape elk-worker.min.js expects on
+ * `data` for a `cmd: 'layout'` request — not part of elkjs's public types. */
+interface ElkWorkerRequest {
+  id: number
+  cmd: 'layout'
+  graph: ElkNode
+}
+
+/** The message envelope ELK's dispatcher passes back to `onmessage` once a
+ * layout run completes. Mirrors elk-worker.min.js's response shape for a
+ * `cmd: 'layout'` request — not part of elkjs's public types. */
+interface ElkWorkerResponse {
+  id: number
+  data?: ElkNode
+  error?: unknown
+}
+
+interface RawFakeWorker {
+  postMessage(msg: unknown): void
+  onmessage: ((e: { data: ElkWorkerResponse }) => void) | null
+  dispatcher: {
+    saveDispatch(msg: { data: ElkWorkerRequest }): void
+  }
+}
+
+/**
+ * The shape of elkjs's bundled `ELK` instance that actually exists at
+ * runtime, including the internal `worker` handle. elkjs's public `ELK`
+ * type (from `elk-api.d.ts`) only declares `layout`/`knownLayout*`/
+ * `terminateWorker` — it deliberately doesn't expose worker internals,
+ * since those aren't a supported API. We rely on them anyway (see file
+ * header), so this extends the public type with the internal piece we
+ * touch instead of casting through `unknown`.
+ */
+interface ElkBundledInternal extends ELK {
+  worker: { worker: RawFakeWorker }
+}
+
+let elk: ELK | null = null
+let rawWorker: RawFakeWorker | null = null
+
+// ============================================================================
+// Opt-in layout cache
+// ============================================================================
+
+/**
+ * `LayoutCache`'s shape lives in `@zombie-mermaid/core`'s `types.ts`
+ * because `RenderOptions.layoutCache` references it and `core` must not
+ * type-import this package (zombie-mermaid#625). Re-exported here so this
+ * module stays the single import site for everything layout-cache-related,
+ * exactly as before the split.
+ */
+export type { LayoutCache }
+
+/**
+ * Concrete shape of a `LayoutCache`, restated locally.
+ *
+ * `core`'s `LayoutCache` interface marks `map`/`maxSize` `@internal`
+ * (see the comment on that interface in packages/core/src/types.ts), so
+ * api-extractor strips them from `@zombie-mermaid/core`'s *published*
+ * `dist/index.d.ts` — deliberately, so they stay invisible to
+ * `@zombie-mermaid/core` consumers and to `zombie-mermaid`'s own public
+ * types (which re-export `LayoutCache` from this package). As of #769,
+ * `@zombie-mermaid/core` is a real, independently-built dependency of this
+ * package rather than bundled source, so this module now resolves
+ * `LayoutCache` through that same trimmed public declaration too — same as
+ * any other consumer. This module is the one place, in or out of `core`,
+ * that actually builds and mutates those fields (`createLayoutCache()`
+ * below; the cache read/evict logic in `elkLayoutSync()`), so it restates
+ * the concrete shape here — kept in sync by hand with `core`'s source of
+ * truth — rather than either widening `core`'s public surface or fighting
+ * api-extractor's trimming in the build config to get it back.
+ */
+interface LayoutCacheShape {
+  map: Map<string, ElkNode>
+  maxSize: number
+}
+
+const DEFAULT_LAYOUT_CACHE_SIZE = 20
+
+/**
+ * Create a new opt-in layout cache with a bounded size (default 20
+ * entries). Once full, the least-recently-used entry is evicted to make
+ * room for a new one.
+ *
+ * Pass the result to `elkLayoutSync()` directly, or via
+ * `RenderOptions.layoutCache` (threaded through by `layoutGraphSync()`,
+ * `layoutClassDiagramSync()`, and `layoutErDiagramSync()`) to memoize
+ * layout across repeated renders of the same diagram + options.
+ */
+export function createLayoutCache(
+  maxSize: number = DEFAULT_LAYOUT_CACHE_SIZE,
+): LayoutCache {
+  if (!Number.isInteger(maxSize) || maxSize < 1) {
+    throw new Error(
+      `createLayoutCache: maxSize must be a positive integer, got ${maxSize}`,
+    )
+  }
+  // Typed as the concrete shape first (see `LayoutCacheShape` above), then
+  // returned as the public, trimmed `LayoutCache` — a plain widening
+  // assignment, not a cast.
+  const cache: LayoutCacheShape = { map: new Map(), maxSize }
+  return cache
+}
+
+/**
+ * Deterministically serialize a value for use as a cache key, sorting
+ * object keys recursively so two structurally-equal ELK input graphs
+ * always produce an identical string regardless of property-insertion
+ * order. Plain `JSON.stringify()` does not guarantee that — and this
+ * function is the only thing standing between a cache hit and returning
+ * some *other* diagram's layout, so it can't be allowed to drift with
+ * insertion order.
+ *
+ * The ELK input graph built by `mermaidToElk()` is plain JSON (arrays,
+ * plain objects, strings, numbers, booleans — the shape ELK's own JSON
+ * schema requires) with every render option that affects layout already
+ * baked in (direction, spacing, per-subgraph overrides, etc.), so
+ * serializing the graph itself is a complete and correct cache key: equal
+ * serialized input always means equal ELK output, since ELK layout is a
+ * pure function of its input graph.
+ */
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`
+  }
+  if (value !== null && typeof value === 'object') {
+    const record = value as Record<string, unknown>
+    const keys = Object.keys(record).sort()
+    const entries = keys.map(
+      (key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`,
+    )
+    return `{${entries.join(',')}}`
+  }
+  return JSON.stringify(value)
+}
+
+/**
+ * Ensure the ELK singleton exists.
+ *
+ * Patches setTimeout during construction to capture and synchronously flush
+ * the algorithm registration callback that ELK queues via setTimeout(0).
+ * Without this, layout calls fail with "algorithm not found" until the
+ * next macrotask.
+ */
+function ensureElk(): RawFakeWorker {
+  if (elk && rawWorker) return rawWorker
+
+  // Capture setTimeout(0) callbacks queued during ELK construction
+  const pending: (() => void)[] = []
+  const origSetTimeout = globalThis.setTimeout
+  // @ts-expect-error — simplified signature for our interception, not
+  // assignment-compatible with the full `typeof setTimeout` overload set
+  globalThis.setTimeout = (fn: () => void, delay?: number) => {
+    if (delay === 0) {
+      pending.push(fn)
+      return 0
+    }
+    return origSetTimeout(fn, delay)
+  }
+
+  // Bun defines `self` (= globalThis) but not `document`, which tricks
+  // elk-worker.min.js into taking the Web Worker branch instead of the
+  // CJS branch. Temporarily hide `self` so it exports {Worker: FakeWorker}.
+  // `lib` in tsconfig.json is `["ESNext"]` (no `dom`), so `self`/`document`
+  // aren't ambiently declared on `globalThis` — narrow to just the two
+  // properties this probe touches instead of a blanket `Record`.
+  const g = globalThis as { self?: unknown; document?: unknown }
+  const hadSelf = 'self' in g
+  const origSelf = g.self
+  if (hadSelf && typeof g.document === 'undefined') {
+    delete g.self
+  }
+
+  elk = new ELKBundled()
+  if (!elk) {
+    // Unreachable — `new ELKBundled()` always returns an instance — but
+    // makes the invariant explicit rather than letting the cast below
+    // silently paper over a null `elk` if that ever stopped being true.
+    throw new Error('ELKBundled construction unexpectedly produced no instance')
+  }
+
+  // Restore self
+  if (hadSelf) g.self = origSelf
+
+  // Restore setTimeout immediately
+  globalThis.setTimeout = origSetTimeout
+
+  // Flush captured callbacks synchronously — registers layout algorithms
+  pending.forEach((fn) => fn())
+
+  // Cache the raw FakeWorker for elkLayoutSync()
+  rawWorker = (elk as ElkBundledInternal).worker.worker
+  return rawWorker
+}
+
+/**
+ * Run ELK layout synchronously.
+ *
+ * Bypasses BOTH of ELK's setTimeout(0) wrappers:
+ *   - FakeWorker.postMessage wraps dispatch in setTimeout(0) — bypassed by
+ *     calling dispatcher.saveDispatch() directly
+ *   - PromisedWorker.onmessage wraps receive in setTimeout(0) — bypassed by
+ *     replacing rawWorker.onmessage with a direct interceptor
+ *
+ * @param cache - Optional opt-in layout cache (see `createLayoutCache()`).
+ *   When provided, a cache hit returns the previous result without running
+ *   ELK layout again. Omitted/undefined preserves the original
+ *   always-recompute behavior exactly.
+ */
+export function elkLayoutSync(graph: ElkNode, cache?: LayoutCache): ElkNode {
+  // `cache`, when provided, is always an object this module itself built
+  // via `createLayoutCache()` above — never anything constructed outside
+  // this package. Restated as the concrete shape here (see
+  // `LayoutCacheShape`'s doc comment) since the public `LayoutCache` type
+  // this parameter is declared with intentionally hides `map`/`maxSize`.
+  const internalCache = cache as LayoutCacheShape | undefined
+  const cacheKey = internalCache ? stableStringify(graph) : undefined
+  if (internalCache && cacheKey !== undefined) {
+    const cached = internalCache.map.get(cacheKey)
+    if (cached) {
+      // Mark as most-recently-used: Map iteration order follows insertion
+      // order, so a delete+re-set moves this entry to the end — which is
+      // what the LRU eviction below relies on to find the *least*
+      // recently used entry (the current first key).
+      internalCache.map.delete(cacheKey)
+      internalCache.map.set(cacheKey, cached)
+      return cached
+    }
+  }
+
+  const worker = ensureElk()
+
+  let result: ElkNode | undefined
+  let error: unknown
+
+  // Replace onmessage to intercept the result synchronously
+  // (the dispatcher calls this directly, without setTimeout)
+  const origOnmessage = worker.onmessage
+  worker.onmessage = (answer: { data: ElkWorkerResponse }) => {
+    if (answer.data.error) {
+      error = answer.data.error
+    } else {
+      result = answer.data.data
+    }
+  }
+
+  // Call dispatcher.saveDispatch directly — bypasses FakeWorker.postMessage's
+  // setTimeout(0) wrapper. The dispatcher processes the layout synchronously
+  // and calls rawWorker.onmessage with the result.
+  worker.dispatcher.saveDispatch({
+    data: { id: 0, cmd: 'layout', graph },
+  })
+
+  // Restore original handler
+  worker.onmessage = origOnmessage
+
+  if (error) throw error
+  if (!result) throw new Error('ELK layout did not return synchronously')
+
+  if (internalCache && cacheKey !== undefined) {
+    internalCache.map.set(cacheKey, result)
+    if (internalCache.map.size > internalCache.maxSize) {
+      // Map iteration order is insertion order, so the first key is the
+      // least recently used (see the recency bump on hit, above).
+      const oldestKey = internalCache.map.keys().next().value
+      if (oldestKey !== undefined) internalCache.map.delete(oldestKey)
+    }
+  }
+
+  return result
+}

package/src/er/layout.ts

@@ -0,0 +1,200 @@
+/**
+ * ER diagram layout engine (ELK.js).
+ *
+ * Each entity box has:
+ *   1. Header (entity name)
+ *   2. Attribute rows (type, name, keys)
+ */
+
+import type { ElkNode, ElkExtendedEdge } from 'elkjs'
+import type {
+  ErDiagram,
+  ErEntity,
+  PositionedErDiagram,
+  PositionedErEntity,
+  PositionedErRelationship,
+} from '@zombie-mermaid/mermaid-parser'
+import type { ErRenderOptions } from '@zombie-mermaid/core'
+import {
+  estimateTextWidth,
+  estimateMonoTextWidth,
+  FONT_WEIGHTS,
+  resolveFontSizes,
+} from '../styles.ts'
+import { elkLayoutSync } from '../elk-instance.ts'
+import { extractEdgePoints } from '../layout-engine/elk-adapter-utils.ts'
+import {
+  ELK_DIRECTION_FALLBACK,
+  baseElkLayoutOptions,
+  buildElkEdge,
+  buildElkLeafNode,
+  directionToElk,
+} from '../layout-engine/elk-graph-builder.ts'
+
+/** Layout constants for ER diagrams */
+const ER = {
+  padding: 40,
+  boxPadX: 14,
+  headerHeight: 34,
+  rowHeight: 22,
+  minWidth: 140,
+  attrFontSize: 11,
+  attrFontWeight: 400,
+  nodeSpacing: 70,
+  layerSpacing: 90,
+} as const
+
+type EntitySizeMap = Map<string, { width: number; height: number }>
+
+/** Build ELK graph and size map from an ER diagram. */
+function buildErElkGraph(
+  diagram: ErDiagram,
+  options: ErRenderOptions,
+): { elkGraph: ElkNode; entitySizes: EntitySizeMap } {
+  const entitySizes: EntitySizeMap = new Map()
+  const fontSizes = resolveFontSizes(options.fontSizes)
+
+  for (const entity of diagram.entities) {
+    const headerTextW = estimateTextWidth(
+      entity.label,
+      fontSizes.nodeLabel,
+      FONT_WEIGHTS.nodeLabel,
+    )
+    let maxAttrW = 0
+    for (const attr of entity.attributes) {
+      const attrText = `${attr.type}  ${attr.name}${attr.keys.length > 0 ? '  ' + attr.keys.join(',') : ''}`
+      const w = estimateMonoTextWidth(attrText, ER.attrFontSize)
+      if (w > maxAttrW) maxAttrW = w
+    }
+    const width = Math.max(
+      ER.minWidth,
+      headerTextW + ER.boxPadX * 2,
+      maxAttrW + ER.boxPadX * 2,
+    )
+    const height =
+      ER.headerHeight + Math.max(entity.attributes.length, 1) * ER.rowHeight
+    entitySizes.set(entity.id, { width, height })
+  }
+
+  // Iterate entitySizes directly (populated above, in diagram.entities order)
+  // rather than looking each entity back up by id — sidesteps needing an
+  // assertion or invariant check for a lookup that can't actually miss.
+  const children: ElkNode[] = []
+  for (const [id, size] of entitySizes) {
+    children.push(buildElkLeafNode(id, size))
+  }
+
+  // ER edge labels carry no per-label layout options — placement is set
+  // once on the root graph below (`elk.edgeLabels.placement: CENTER`).
+  const labelStyle = { fontSize: fontSizes.edgeLabel }
+
+  const edges: ElkExtendedEdge[] = []
+  for (const [i, rel] of diagram.relationships.entries()) {
+    edges.push(
+      buildElkEdge({
+        id: `e${i}`,
+        source: rel.entity1,
+        target: rel.entity2,
+        label: rel.label,
+        labelStyle,
+      }),
+    )
+  }
+
+  const elkGraph: ElkNode = {
+    id: 'root',
+    layoutOptions: {
+      ...baseElkLayoutOptions({
+        // A source with no `direction` statement lays out left-to-right —
+        // ER's own default, unlike flowchart/class's DOWN. See
+        // ELK_DIRECTION_FALLBACK.
+        direction: directionToElk(diagram.direction, ELK_DIRECTION_FALLBACK.er),
+        nodeSpacing: ER.nodeSpacing,
+        layerSpacing: ER.layerSpacing,
+        padding: ER.padding,
+      }),
+      'elk.edgeLabels.placement': 'CENTER',
+    },
+    children,
+    edges,
+  }
+
+  return { elkGraph, entitySizes }
+}
+
+/** Extract positioned entities and relationships from ELK result. */
+function extractErLayout(
+  result: ElkNode,
+  diagram: ErDiagram,
+  entitySizes: EntitySizeMap,
+): PositionedErDiagram {
+  const entityLookup = new Map<string, ErEntity>()
+  for (const entity of diagram.entities) entityLookup.set(entity.id, entity)
+
+  const positionedEntities: PositionedErEntity[] = []
+  for (const child of result.children ?? []) {
+    const entity = entityLookup.get(child.id)
+    if (entity) {
+      const size = entitySizes.get(entity.id)
+      if (!size) {
+        // Unreachable — entitySizes is populated for every diagram.entities
+        // entry, and entityLookup/entity.id come from that same list.
+        /* v8 ignore next */
+        throw new Error(`Missing computed size for entity "${entity.id}"`)
+      }
+      positionedEntities.push({
+        id: entity.id,
+        label: entity.label,
+        attributes: entity.attributes,
+        x: child.x ?? 0,
+        y: child.y ?? 0,
+        width: child.width ?? size.width,
+        height: child.height ?? size.height,
+        headerHeight: ER.headerHeight,
+        rowHeight: ER.rowHeight,
+      })
+    }
+  }
+
+  const relationships: PositionedErRelationship[] = []
+  for (const [i, elkEdge] of (result.edges ?? []).entries()) {
+    // diagram.relationships[i] is guaranteed by construction: buildErElkGraph
+    // creates exactly one ELK edge per relationship, in the same order.
+    const rel = diagram.relationships[i]!
+
+    const points = extractEdgePoints(elkEdge)
+
+    relationships.push({
+      entity1: rel.entity1,
+      entity2: rel.entity2,
+      cardinality1: rel.cardinality1,
+      cardinality2: rel.cardinality2,
+      label: rel.label,
+      identifying: rel.identifying,
+      points,
+    })
+  }
+
+  return {
+    width: result.width ?? 600,
+    height: result.height ?? 400,
+    entities: positionedEntities,
+    relationships,
+  }
+}
+
+/**
+ * Lay out a parsed ER diagram using ELK.js (synchronous).
+ */
+export function layoutErDiagramSync(
+  diagram: ErDiagram,
+  options: ErRenderOptions = {},
+): PositionedErDiagram {
+  if (diagram.entities.length === 0) {
+    return { width: 0, height: 0, entities: [], relationships: [] }
+  }
+
+  const { elkGraph, entitySizes } = buildErElkGraph(diagram, options)
+  const result = elkLayoutSync(elkGraph, options.layoutCache)
+  return extractErLayout(result, diagram, entitySizes)
+}