@zombie-mermaid/svg-renderer 4.2.2 → 5.0.0

package/src/edge-curves.ts

@@ -1,205 +0,0 @@
-// ============================================================================
-// 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'
-import { f } from '@zombie-mermaid/core'
-
-/** `M x y` for the first point. */
-function moveTo(p: Point): string {
-  return f`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) => f` 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 =>
-    f` C ${(2 * p0.x + p1.x) / 3} ${(2 * p0.y + p1.y) / 3},` +
-    f` ${(p0.x + 2 * p1.x) / 3} ${(p0.y + 2 * p1.y) / 3},` +
-    f` ${(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(
-    f` L ${(5 * points[0]!.x + points[1]!.x) / 6}` +
-      f` ${(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(f` 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(f` 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(f` L ${startX} ${startY}`)
-    parts.push(f` Q ${corner.x} ${corner.y}, ${endX} ${endY}`)
-  }
-
-  const last = points[points.length - 1]!
-  parts.push(f` 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(f` L ${b.x} ${b.y}`)
-      break
-    }
-
-    if (where === 'before') {
-      parts.push(f` L ${a.x} ${b.y} L ${b.x} ${b.y}`)
-    } else if (where === 'after') {
-      parts.push(f` L ${b.x} ${a.y} L ${b.x} ${b.y}`)
-    } else {
-      const midY = (a.y + b.y) / 2
-      parts.push(f` 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

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