agentic-mermaid 0.1.2 → 0.3.0

package/docs/mermaid-layout-complaints.md

@@ -0,0 +1,851 @@
+# Mermaid layout complaints: catalog, root causes, and coverage
+
+Status: evidence and capability-coverage scorecard, not a roadmap or backlog.
+`TODO.md` is the sole authority for scheduled work. Historical issues and specs
+below retain candidate contract evidence only; they do not schedule
+implementation unless a stable root TODO item promotes them.
+
+This document maps what users actually complain about in Mermaid's layout →
+why those failures happen → which Agentic Mermaid work addresses each one
+(landed, retained as candidate evidence, or deliberately out of scope). It is
+the durable version of a June 2026 research pass and should be updated when
+complaint-relevant work lands.
+
+Companions:
+
+- [`issue-derived-test-cases.md`](./issue-derived-test-cases.md) — fixture-level
+  coverage map for specific upstream issues.
+- [`quality.md`](./quality.md) — the project's definition of "good looking" and
+  its metric gates.
+- [Issue #25](https://github.com/adewale/agentic-mermaid/issues/25) and
+  [issue #26](https://github.com/adewale/agentic-mermaid/issues/26) — the
+  principled routing/contract specs that several entries below point into.
+- [PR #24](https://github.com/adewale/agentic-mermaid/pull/24) — the Gantt
+  spec and implementation, the model for chart-family layout contracts.
+- [Issue #41](https://github.com/adewale/agentic-mermaid/issues/41) — the
+  diagram-family citizenship matrix that now keeps supported families honest
+  about parser, serializer, renderer, verifier, and test obligations.
+
+Method: complaint evidence was gathered in June 2026 from the
+`mermaid-js/mermaid` tracker (reaction counts "R" are as of that date), Hacker
+News, Reddit, comparison blogs, and Mermaid's own documentation. Root-cause
+evidence comes from the graph-drawing literature, competing products'
+documentation, diagram interchange standards, and the recorded history of the
+three codebases this project descends from (Mermaid, `mermaid-ascii`,
+`beautiful-mermaid`).
+
+Status legend used below:
+
+| Status | Meaning |
+|---|---|
+| **landed** | shipped in this repo with tests |
+| **partial** | some of the complaint class is covered, the rest is not |
+| **candidate evidence** | described in a historical issue/spec, but unscheduled unless promoted to root `TODO.md` |
+| **out of scope** | deliberately not addressed; the reason is stated |
+
+---
+
+## Part 1 — The complaint catalog
+
+Thirteen recurring complaint classes, ordered roughly by loudness. Each entry
+names its root causes (`R1`–`R5`, defined in Part 2) and its fixture/test
+coverage in this repo.
+
+### C1. No manual positioning
+
+Mermaid is auto-layout only: no coordinates, no pinning, no post-hoc nudge.
+When the engine makes a bad call, the sanctioned workaround is invisible
+`~~~` links — Mermaid's own docs describe them as the way "to alter the
+default positioning of a node," and GitLab maintains a handbook page of such
+tricks. This is the loudest and oldest theme.
+
+- Evidence: [mermaid#270](https://github.com/mermaid-js/mermaid/issues/270)
+  (11R, open since 2016),
+  [mermaid#2483](https://github.com/mermaid-js/mermaid/issues/2483) (12R),
+  [mermaid#5420 "Add positioning for elk layout renderer"](https://github.com/mermaid-js/mermaid/issues/5420)
+  (47R, zero comments — pure demand). HN: "if you don't like the way the
+  diagram is visually laid out there's not really an easy way to change it"
+  ([41262756](https://news.ycombinator.com/item?id=41262756)).
+- Root cause: R3 (missing control surface).
+- Status here: **manual coordinates and post-hoc nudging remain out of scope.**
+  `BUILD-24` now owns a narrower response: typed, deterministic structural
+  constraints for rank/layer, adjacency, and edge-length preference. They are
+  render/mutation metadata, not Agentic-only Mermaid syntax, and therefore do
+  not contradict #25's rule against inventing route syntax. Deterministic
+  quality measurement and route certificates remain the feedback loop; the
+  hints let an agent state topology-preserving intent without deleting a real
+  edge. This still does not provide arbitrary node coordinates or dragging.
+
+### C2. Layout collapses at scale
+
+Past roughly 20–50 nodes: whitespace oceans, extreme aspect ratios, nodes
+unreadably small once the diagram is fit to screen.
+
+- Evidence: [mermaid#1984 "Massive whitespace"](https://github.com/mermaid-js/mermaid/issues/1984)
+  (39R, open since 2021),
+  [mermaid#3262](https://github.com/mermaid-js/mermaid/issues/3262),
+  [mermaid#2807 "ER graphs tend to get REALLY wide"](https://github.com/mermaid-js/mermaid/issues/2807)
+  (19R). HN: "more and more acres of white space"
+  ([30781954](https://news.ycombinator.com/item?id=30781954)).
+- Root cause: R1 (layered-algorithm sprawl), aggravated in Mermaid by R4
+  (dagre, fixed spacing constants).
+- Fixture/test: `whitespaceBalance` (5–55% band) and `aspectRatio` (0.2–5.0
+  band) in `src/agent/quality.ts` flag both failure directions;
+  `eval/layout-compare/` reports deltas corpus-wide. Generated 20/50/100-node
+  flowchart corpora now assert finite aspect ratios and non-degenerate
+  whitespace in `src/__tests__/agent-quality.test.ts`.
+- Status here: **partial — detection only.** Nothing in the backlog improves
+  large-graph compaction, and the source-order priority can *worsen* width:
+  `docs/quality.md` documents the Auth Flow trade, and
+  `src/__tests__/agent-auth-flow.test.ts` pins quality with a widened aspect
+  band (`[0.2, 7]`) for exactly that reason. One candidate mitigation that
+  needs no syntax invention: the standards-era answer to oversized charts
+  was never better compaction but **decomposition** — ANSI X3.5/ISO 5807
+  prescribe named on-page/off-page connectors to split a chart when it
+  outgrows a page or lines would cross. The agent-loop analogue: when
+  `checkQuality` flags an oversized diagram, propose or perform splitting
+  into multiple linked diagrams through the existing mutation API. Mermaid
+  has no continuation concept (users fake it with duplicated nodes), so
+  this would be a differentiator rather than a compatibility surface.
+
+### C3. Subgraphs: direction ignored, titles overlapped, clusters colliding
+
+The most-reacted pure layout bug in Mermaid's tracker. `direction` inside a
+subgraph is silently ignored the moment any inner node links outside —
+documented as a limitation, unfixed since 2021. Titles get covered by nodes;
+sibling clusters overlap.
+
+- Evidence: [mermaid#2509](https://github.com/mermaid-js/mermaid/issues/2509)
+  (189R, 50 comments),
+  [mermaid#3806 title overlap](https://github.com/mermaid-js/mermaid/issues/3806)
+  (54R), [mermaid#4990 cluster overlap](https://github.com/mermaid-js/mermaid/issues/4990)
+  (32R), [mermaid#287](https://github.com/mermaid-js/mermaid/issues/287) (29R).
+- Root cause: R1 (compound layout is genuinely hard), R4 (dagre's cluster
+  support is weak; title boxes not reserved during layout).
+- Fixture/test: `src/__tests__/subgraph-direction.test.ts` pins SVG geometry
+  for `direction TB` inside an LR flowchart *with an external link to an
+  inner node* — the exact mermaid#2509 case — plus ASCII one-row inner LR
+  layout, and container edges attaching to the subgraph border without
+  phantom node boxes (BUILD-14), in both Unicode and 7-bit ASCII, nested,
+  labeled/styled, and multi-edge variants. Group titles reserve layout space
+  via the header-aware `elk.padding` in `src/layout-engine.ts`; breaches are
+  a Tier 1 `GROUP_BREACH` warning.
+- Status here: **landed** (PRs #17, #21, #22). Residual: cross-hierarchy and
+  container-edge *route classes* — making the SVG router treat boundary
+  edges semantically rather than via representative children — remain candidate
+  contract evidence in #25 §8.3 and #26 workstream 2, not scheduled work.
+
+### C4. Erratic edge routing: avoidable crossings, overlaps, doglegs
+
+Here and in the scorecard, **C4 means complaint category 4**, not Mermaid's C4
+diagram family.
+
+Edges cross when they obviously need not, overlap each other or pass through
+nodes, and acquire small unexplained doglegs ("hitches"). Users untangle by
+trial-and-error reordering of source lines.
+
+- Evidence: [mermaid#6476 "Unnecessary crossing"](https://github.com/mermaid-js/mermaid/issues/6476),
+  [mermaid#5601 planar graphs rendered non-planar](https://github.com/mermaid-js/mermaid/issues/5601),
+  [mermaid#1006](https://github.com/mermaid-js/mermaid/issues/1006) ("it often
+  really handles edges in an erradic way" — closed *Wont Fix*),
+  [mermaid#5060](https://github.com/mermaid-js/mermaid/issues/5060),
+  [mermaid#2792 edges overlap boxes](https://github.com/mermaid-js/mermaid/issues/2792).
+- Root cause: R1 (crossing minimization is NP-hard, solved per-layer by
+  heuristic; routing is a late phase that cannot revisit placement), R4
+  (dagre routes splines without obstacle avoidance), R5 (post-layout passes
+  move geometry without rerouting).
+- Fixture/test: the worked example is issue #25's login/MFA flow. Rendered
+  with the current engine (June 2026, ASCII):
+
+  ```
+  | User |---->| Login Page |<No->| Valid Credentials? |-Yes>| MFA Enabled? |----No-->| Create Session |  Yes-+--| Code Valid? |
+  ...                                                               |                         +-----No-------+         |
+  ...                                                               +------Yes------>| Enter MFA Code |----------------+
+  ```
+
+  `F --> G` (`Code Valid?` → `Create Session`) runs backwards; the `No`
+  feedback loops read ambiguously inline. Yet `verifyMermaid` returns
+  `ok: true` with zero warnings, and every perceptual metric passes except
+  aspect ratio (6.23 vs the 5.0 band): `edgeCrossings: 0`,
+  `labelLegibility: 1`. That is the measured gap between today's generic
+  metrics and the visible failure — the gap #25/#26 exist to close.
+  Current coverage: `edgeCrossings` gate (≤5% of edge pairs),
+  `ROUTE_SELF_CROSS` Tier 2 warning, edge-vs-node collision heuristics in
+  `src/__tests__/layout-quality-heuristics.test.ts`, deterministic FIFO A*
+  tie-breaking in the ASCII pathfinder
+  (`src/__tests__/ascii-pathfinder-determinism.test.ts`).
+- Status here: **partial today, with the route-contract core landed and the
+  broader program retained as candidate evidence.** #25 defines route classes
+  (`primary-forward`/`feedback`/fan trunks/…), the straight-primary and
+  hitch invariants (§11.1–11.2), the certifying simplifier (§12), and the
+  hard rule "no node-coordinate mutation after route extraction unless all
+  incident routes are rerouted or recertified" (§9). The current tests now
+  include route-certificate geometry and property coverage across dotted,
+  thick, bidirectional, marker, and labeled edge forms. The still-open
+  route/port issues (#32, #35, #38 and the #26 umbrella) retain unscheduled
+  evidence; any implementation or cross-renderer adoption requires promotion
+  to root `TODO.md`.
+
+### C5. Edge labels overlap edges, nodes, and each other
+
+Mermaid places labels at edge midpoints with no collision handling: labels
+sit on other edges, get struck through by their own line, or detach from the
+edge they describe.
+
+- Evidence: [mermaid#490](https://github.com/mermaid-js/mermaid/issues/490)
+  (2017 — labels struck through by their own edge, asking for "integrated
+  logic which tries to avoid lines going over the texts": literally the
+  integrated-labeling concept yFiles ships, see R3),
+  [mermaid#2131 mis-aligned state labels](https://github.com/mermaid-js/mermaid/issues/2131),
+  [mermaid#2525 "messages appear with line through them"](https://github.com/mermaid-js/mermaid/issues/2525),
+  [mermaid#1233](https://github.com/mermaid-js/mermaid/issues/1233).
+- Root cause: R1 (label placement is NP-hard and classically solved *after*
+  layout; dagre models labels as mid-edge dummy nodes), R4/R5 (renderers do
+  not collision-check label boxes afterwards).
+- Fixture/test: this engine passes edge labels into layout as first-class
+  inline ELK labels (`elk.edgeLabels.inline: 'true'`,
+  `src/layout-engine.ts`), so they reserve space instead of being overlaid;
+  `labelEdgeProximity` (≥4px to any non-attached node, other edge-label
+  box, or other edge path) gates regressions in the graph families, and the
+  2026-07 overlap audit added a cross-family occlusion gate
+  (`eval/overlap-audit` + `label-overlap-gate.test.ts`: curated corpus at
+  zero label/box overlap findings, per-family fuzz ratchets) after finding
+  label collisions the proximity metric alone had missed in five families.
+  ASCII branch labels are pinned to sibling branch segments, not shared
+  trunks: `src/__tests__/ascii-fanout-trunk-labeled.test.ts`,
+  `ascii-pathfinder-trunk.test.ts`, plus exact goldens under
+  `src/__tests__/testdata/{ascii,unicode}/`.
+- Status here: **partial.** Landed: label-aware layout + proximity gate +
+  ASCII branch-label placement. Specced: the label invariant (#25 §11.4 —
+  labels are obstacles *and* capacity constraints; trunks may not host
+  per-sibling labels) and label-capacity checks before straightening (§12).
+
+### C6. No rank/order control; tiny edits reshuffle the diagram
+
+Users cannot say "these two nodes at the same level" or "keep my declared
+order," and adding one edge can scramble a previously good layout — which
+also makes diagrams churn across edits.
+
+- Evidence: [mermaid#3723 same-rank request](https://github.com/mermaid-js/mermaid/issues/3723)
+  (86R — the most-upvoted open layout-control ask),
+  [mermaid#815 "Maintain the order of the nodes"](https://github.com/mermaid-js/mermaid/issues/815)
+  (45R), [mermaid#2834](https://github.com/mermaid-js/mermaid/issues/2834),
+  [mermaid#6527 "flowchart-elk … reshuffled every time you add a node"](https://github.com/mermaid-js/mermaid/issues/6527).
+- Root cause: R3 (no constraint surface) over R1 (layered layouts are
+  input-order sensitive unless order is made an explicit objective).
+- Fixture/test: source order *is* the constraint surface here:
+  `elk.layered.considerModelOrder.strategy: NODES_AND_EDGES`,
+  `cycleBreaking.strategy: MODEL_ORDER`, and
+  `crossingMinimization.forceNodeModelOrder: true`
+  (`src/layout-engine.ts`) make author order the layout's primary input.
+  `src/__tests__/agent-auth-flow.test.ts` asserts the primary LR chain stays
+  in source order (`A < B < … < H` by x-center) and feedback edges route
+  backwards — the mermaid#5227 "backwards arrows" class. Edit stability is
+  the determinism guarantee plus typed mutation: a one-op change re-lays-out
+  as a pure function of the new source
+  (`src/__tests__/agent-determinism.test.ts`). The same file now pins
+  edit-stability for small source mutations: label edits, inserted nodes,
+  appended leaves, style-only changes, and feedback-edge additions must
+  preserve the left-to-right order of the unchanged primary chain.
+- Status here: **partial.** Landed: deterministic source-order layout (the
+  practical answer to #815/#6527). Not offered: an explicit same-rank
+  constraint (#3723's literal ask) — that is C1's policy decision again.
+  Graphviz has had `rank=same` since the 1990s (see R3); if Mermaid core
+  ever standardizes an equivalent, this fork's policy is to follow, not
+  invent.
+
+### C7. "It's just ugly": dated default aesthetics
+
+An aesthetic judgment independent of geometric correctness: default colors,
+shapes, curves, and contrast read as dated next to D2 or hand-drawn
+diagrams; some embeddings are unreadable (dark-theme contrast).
+
+- Evidence: HN "why does it have to be so ugly"
+  ([30339032](https://news.ycombinator.com/item?id=30339032)); "Both PlantUML
+  and Mermaid mostly produce (Mermaid more) ugly-looking diagrams"
+  ([33704875](https://news.ycombinator.com/item?id=33704875));
+  [Cursor forum on unreadable contrast](https://forum.cursor.com/t/mermaid-diagrams-are-hard-to-read-poor-contrast/153850).
+- Root cause: R5 (renderer/theming defaults, not the layout algorithm).
+  Mermaid's v11 `handDrawn`/`neo` "looks" are its own remediation.
+- Fixture/test: inherited from upstream Beautiful Mermaid: two-color theme
+  derivation, 21 built-in themes, Shiki/VS Code theme compatibility. Fork
+  additions: Style + Palette stacks, Tufte/Salmon theme families (PR #10),
+  auto-contrast on custom fills
+  (upstream #115 class) pinned by
+  `src/__tests__/renderer-contrast.test.ts`.
+- Status here: **landed** (largely upstream's credit; see
+  [`comparison.md`](./comparison.md)).
+
+### C8. Text clipped, overflowing, or hand-wrapped
+
+Node boxes don't reliably fit their text. In Mermaid the classic causes are
+HTML labels in `foreignObject` (SVG exports drop them), browser font metrics
+at layout time, and no width budget for CJK/long words.
+
+- Evidence: [mermaid#58](https://github.com/mermaid-js/mermaid/issues/58)
+  ("Generated SVG works poorly outside web browsers" — opened December
+  2014, six weeks after Mermaid's first release, still open),
+  [mermaid#2688 foreignObject](https://github.com/mermaid-js/mermaid/issues/2688)
+  (24R), [mermaid#790](https://github.com/mermaid-js/mermaid/issues/790),
+  [mermaid#4918](https://github.com/mermaid-js/mermaid/issues/4918),
+  [mermaid#7359 Korean clipped on export](https://github.com/mermaid-js/mermaid/issues/7359);
+  GitLab converted diagrams to tables rather than fight it
+  ([gitlab#583608](https://gitlab.com/gitlab-org/gitlab/-/issues/583608)).
+- Root cause: R5 (browser-first text pipeline), R2 for the ASCII lineage
+  (`string.length` width assumptions on fullwidth text).
+- Fixture/test: structurally avoided here — text is plain SVG `<text>`
+  measured by deterministic metrics (`src/text-metrics.ts`), never
+  `foreignObject`; PNG embeds pinned fonts (DejaVu default plus the built-in style faces) so rasterization cannot
+  font-substitute. Guards: Tier 1 `LABEL_OVERFLOW`, `labelLegibility` ≥85%
+  gate, CJK fullwidth handling
+  (`src/__tests__/ascii-cjk-width.test.ts`, upstream #119 class), ER/class
+  label truncation fixes with exact goldens (upstream #121 class,
+  `er-integration.test.ts`, `class-integration.test.ts`).
+- Status here: **landed**, with an honest gap: the 7px/char SVG heuristic is
+  approximate (`docs/quality.md`), and the shared text-measurement contract
+  that would unify SVG/ASCII/quality measurement (CJK, emoji, ambiguous
+  width) remains candidate evidence in #26 workstream 8. Regression coverage
+  now includes
+  emoji-presentation selectors and East Asian ambiguous-width symbols, so
+  common Unicode labels cannot silently drift between SVG metrics and
+  terminal-width assumptions.
+
+### C9. Stuck on dagre; ELK bolted on as an escape hatch
+
+The meta-complaint: Mermaid's default engine is dagre — widely described as
+abandoned — and the community's fix (ELK) is opt-in, a separate package,
+unavailable in GitHub's native rendering, and not itself a cure-all.
+
+- Evidence: "Dagre is pretty good but I think ELK is better and Dagre has
+  been abandoned"
+  ([r/programming](https://www.reddit.com/r/programming/comments/z1qoxc/d2_is_now_open_source_a_new_modern_language_that/ixlwqce/));
+  Mermaid docs: "The elk renderer is better for larger and/or more complex
+  diagrams" ([flowchart docs](https://mermaid.js.org/syntax/flowchart.html));
+  HN: "the layout renderer is pretty bad … the layout algorithm is so bad"
+  ([41277795](https://news.ycombinator.com/item?id=41277795)).
+- Root cause: R4.
+- Status here: **landed structurally.** ELK layered is this engine's only
+  graph layout (synchronous bundled `elkjs`, `src/elk-instance.ts`), with
+  pinned options (`src/layout-engine.ts`) and #25 §10 as the documented
+  option policy — node placement is Brandes–Köpf, the same default
+  Mermaid's own ELK package exposes via `nodePlacementStrategy`, so
+  opting into `flowchart-elk` in Mermaid lands on the placement family this
+  engine uses by default. Two honest caveats: (1) ELK is not a panacea — upstream
+  #83 (TD flowcharts flipping horizontal) was *ELK cycle-breaking* behavior,
+  countered here by model-order options; (2) none of this changes what
+  GitHub/GitLab render natively (see Part 4).
+
+### C10. Self-loops and back-edges render awkwardly
+
+A node linking to itself draws a kinked doubled-back path; loops in flows
+take long unexplained detours.
+
+- Evidence: [mermaid#6336](https://github.com/mermaid-js/mermaid/issues/6336)
+  (31R; the issue contrasts Graphviz doing it "So much more natural"),
+  [mermaid#6049](https://github.com/mermaid-js/mermaid/issues/6049) (11R —
+  also a version regression: "pretty" in 11.0.2, "Ugly since 11.1.1").
+- Root cause: R1/R4 (layered frameworks have no native self-loop concept;
+  the route is synthesized late).
+- Fixture/test: ASCII self-loops currently render compactly (verified June
+  2026: `B --> B` draws a tight two-cell side loop). `ROUTE_SELF_CROSS`
+  (Tier 2) and self-loop clearance heuristics
+  (`layout-quality-heuristics.test.ts`) guard regressions. SVG self-loop
+  port policy (N/S side by clearance) is #25 §8.1; mermaid#6049 is listed as
+  candidate fixture evidence in [`issue-derived-test-cases.md`](./issue-derived-test-cases.md).
+- Status here: **partial** (ASCII decent + guarded; SVG semantics retained as
+  candidate evidence, not scheduled).
+
+### C11. Unstable output across versions and renderers
+
+The same source renders differently in the live editor, CLI, GitHub, and
+Obsidian, and upgrades silently regress committed diagrams.
+
+- Evidence: [mermaid#5813 v11 regression](https://github.com/mermaid-js/mermaid/issues/5813)
+  (28R), [mermaid#1485 live editor vs CLI](https://github.com/mermaid-js/mermaid/issues/1485),
+  [mermaid#5969 editor silently uses ELK](https://github.com/mermaid-js/mermaid/issues/5969),
+  [gitlab#583608](https://gitlab.com/gitlab-org/gitlab/-/issues/583608),
+  [Obsidian forum "Mermaid arrows are a mess"](https://forum.obsidian.md/t/mermaid-arrows-are-a-mess/104633).
+- Root cause: R5 (browser/CSS/version-coupled rendering) plus R1 (layout
+  sensitivity amplifies small engine changes into big visual diffs).
+- Fixture/test: this is the fork's categorical answer rather than a
+  mitigation. Byte-identical output across runs, processes, and runtimes is
+  CI-gated (`agent-determinism.test.ts`); ASCII output is hash-stable across
+  the full 271-entry docs corpus (`ascii-determinism.test.ts`); PNG bytes
+  are pinned via exact-version resvg + bundled fonts
+  (`agent-png-determinism.test.ts`). Intentional layout changes must pass
+  the before/after comparison harness (`eval/layout-compare/`,
+  regressions-first verdicts) and update exact goldens — so every visual
+  change is deliberate, evidenced, and reviewed.
+- Status here: **landed.** No Mermaid-syntax renderer we know of makes this
+  guarantee.
+
+### C12. Sequence-diagram alignment and overlap
+
+Sequence diagrams (bespoke layouter in Mermaid, not dagre) have their own
+class: uncontrollable/overlapping activations, off-center `alt`/`loop`
+titles, notes colliding with lifelines.
+
+- Evidence: [mermaid#1765 activations](https://github.com/mermaid-js/mermaid/issues/1765)
+  (28R), [mermaid#3216](https://github.com/mermaid-js/mermaid/issues/3216),
+  [mermaid#7651](https://github.com/mermaid-js/mermaid/issues/7651),
+  [mermaid#7682](https://github.com/mermaid-js/mermaid/issues/7682).
+- Root cause: R5 (hand-rolled per-family geometry, no shared invariants) +
+  R3 (no spacing overrides).
+- Fixture/test: layout geometry tests exist
+  (`src/__tests__/sequence-layout.test.ts`, `ascii-sequence-blocks.test.ts`)
+  and the sequence `RenderedLayout` adapter feeds the generic metrics.
+  Sequence property coverage now checks activation spans, note stacking and
+  bounds, and block/divider containment/non-overlap geometry over generated
+  activation/note/block combinations. The broader productized verifier set
+  — lifeline x-order, message y-order, activation span containment, and
+  note/block containment as user-facing warnings — remains #25 §14.2 and
+  #26 workstream 11.
+- Status here: **partial, with first family-specific properties landed.**
+
+### C13. Chart families: hard-coded geometry breaks on real data
+
+Gantt axis dates overlap on long ranges, pie titles/labels clip, and radar axis
+labels compress. These are
+not dagre problems — each chart type has bespoke geometry with no collision
+handling.
+
+- Evidence: [mermaid#1301 gantt axis overlap](https://github.com/mermaid-js/mermaid/issues/1301)
+  (23R), [mermaid#6232 pie title cut off](https://github.com/mermaid-js/mermaid/issues/6232),
+  and [mermaid#7683 radar labels clipped](https://github.com/mermaid-js/mermaid/issues/7683).
+- Root cause: R5 (per-family renderer-first geometry; semantics inferred at
+  draw time — the exact anti-pattern #26's guiding principle names).
+- Fixture/test: pie and quadrant landed source-level with geometry tests
+  (PR #22; quadrant point placement verified against the upstream Mermaid
+  reference). Gantt is now implemented from PR #24's principled model — a
+  pure, clock-free schedule resolver *before* layout, family validators
+  (deterministic task intervals, milestone zero-width markers,
+  non-overlapping compact rows) designed against precisely the mermaid#1301
+  class. Mindmap now has deterministic tree geometry; Radar has deterministic
+  radial layout, bounded labels, ring ticks, and cross-format render contracts.
+- Status here: **covered for every registered chart family**; remaining work is
+  tracked as family-specific quality improvement, not missing Radar support.
+
+---
+
+## Part 2 — Root causes
+
+Five root causes explain the catalog. R1–R3 apply to every auto-layout
+text-to-diagram tool, including this one; R4–R5 are specific lineages.
+
+### R1. The layered framework solves NP-hard problems in irreversible phases
+
+Every engine in this story — dagre, ELK, dot — descends from the layered
+method of
+[Sugiyama, Tagawa & Toda 1981](https://doi.org/10.1109/TSMC.1981.4308636)
+(IEEE Trans. SMC-11(2)), extended since into the standard pipeline: break a
+directed graph drawing into sequential phases (cycle removal → layer
+assignment → crossing minimization → coordinate assignment → edge
+routing). The framework is powerful and is the right baseline for flow-like
+diagrams, but it has three structural consequences users experience
+directly:
+
+1. **The subproblems are intractable, so every phase is heuristic.**
+   Crossing number is NP-complete
+   ([Garey & Johnson 1983](https://dl.acm.org/doi/10.1137/0604033), SIAM
+   J. Alg. Disc. Meth. 4(3)); crossing minimization stays NP-complete even
+   for two layers with one layer's order already fixed
+   ([Eades & Wormald 1994](https://link.springer.com/article/10.1007/BF01187020),
+   Algorithmica 11(4)) — the exact subproblem inside every layered engine;
+   label placement is NP-complete even in simple variants
+   ([Marks & Shieber 1991](https://dash.harvard.edu/entities/publication/73120379-247a-6bd4-e053-0100007fdf3b),
+   Harvard TR-05-91), and edge-label placement specifically is NP-hard
+   ([Kakoulis & Tollis 2001](https://www.sciencedirect.com/science/article/pii/S0925772100000250),
+   Comput. Geom. 18(1)). No engine "chooses" the avoidable crossing in
+   complaint C4 — it fails to find the better optimum it cannot afford to
+   search for.
+2. **Phases cannot revisit earlier decisions.** Layering fixes ranks before
+   crossing minimization sees them; coordinates are assigned before routing.
+   A route that needs a node nudged one lane over cannot get it. This is
+   the literature's own characterization of the framework's failure mode —
+   "decisions made at previous steps influence later steps and yet cannot
+   be undone"
+   ([Healy & Nikolov, *Handbook of Graph Drawing and Visualization* ch. 13](https://cs.brown.edu/people/rtamassi/gdhandbook/chapters/hierarchical.pdf));
+   "since layer assignment and crossing reduction are realized as
+   independent steps, the resulting drawing might have many unnecessary
+   crossings caused by an unfortunate layer assignment"
+   ([Chimani, Gutwenger, Mutzel & Wong, JGAA 15(1), 2011](https://jgaa.info/index.php/jgaa/article/view/paper220/2748)).
+   It is why locally-reasonable pipelines emit globally wrong results — the
+   "hitch" of issue #25 is a phase-boundary artifact, and #25 §2 names it a
+   *contract failure*: nothing in the pipeline encodes "this edge should be
+   straight when its lane is clear" as an invariant any phase must preserve.
+3. **Labels and shapes are afterthoughts in the classic formulation.**
+   Labels enter as dummy nodes or post-hoc annotations (C5); non-rectangular
+   shapes are approximated by their bounding boxes until a final clipping
+   pass (#25 principle 6).
+
+Empirical work confirms users are right to care:
+[Purchase 1997](https://link.springer.com/chapter/10.1007/3-540-63938-1_67)
+(Graph Drawing, LNCS 1353) found reducing edge crossings "by far the most
+important" aesthetic for human comprehension, with bend minimization also
+significant — exactly the two artifacts the phase structure produces.
+Compound (subgraph) layout multiplies the difficulty: nested clusters with
+cross-cluster edges constrain layering and crossing minimization
+simultaneously
+([Sander 1996](https://publikationen.sulb.uni-saarland.de/bitstream/20.500.11880/25862/1/tr-A03-96.pdf),
+TR A/03/96, Universität des Saarlandes), which is why C3 is hard for
+everyone — and weak cluster handling is dagre's most visible gap (open for
+years in its own tracker:
+[dagre#125](https://github.com/dagrejs/dagre/issues/125),
+[dagre#238](https://github.com/dagrejs/dagre/issues/238)).
+
+### R2. Greedy per-edge grid routing in the ASCII lineage
+
+[`mermaid-ascii`](https://github.com/AlexanderGrooff/mermaid-ascii)
+(Alexander Grooff, Go) works in three stages — parse, map components onto a
+character grid, route each edge independently by pathfinding — and this
+repo's ASCII engine is a TypeScript port of it
+(`src/ascii/edge-routing.ts` is "ported from
+AlexanderGrooff/mermaid-ascii cmd/direction.go + cmd/mapping_edge.go").
+Per-edge greedy routing with no shared intent produces the ASCII-specific
+complaint classes visible in both trackers: in the original,
+single-edge-per-node-pair limits, floating arrowheads on labeled
+back-edges, and East Asian width breakage
+([mermaid-ascii#56](https://github.com/AlexanderGrooff/mermaid-ascii/issues/56),
+[#63](https://github.com/AlexanderGrooff/mermaid-ascii/issues/63),
+[#59](https://github.com/AlexanderGrooff/mermaid-ascii/issues/59)); in
+this lineage, equal-cost path nondeterminism, labels landing on shared
+detours instead of their own branch (upstream #111/#112), fan-in groups
+merging into ambiguous trunks (#68/#69), connectors floating off node
+borders, phantom boxes for subgraph-id endpoints, and fullwidth/CJK text
+breaking column math (#119, #121) — inherited and then fixed here
+case-by-case. The durable fix is the same as for R1: route intent shared
+across edges before geometry (#25 §13 — ASCII consumes route classes;
+trunks, reserved feedback channels, label capacity).
+
+### R3. Layout is authored content everywhere except text-to-diagram tools
+
+The standards world treats positions as part of the artifact:
+[OMG Diagram Definition](https://www.omg.org/spec/DD/) distinguishes
+"graphical information … users have control over, such as position of
+nodes and line routing points," which is "captured for interchange between
+tools," from styling fixed by the notation — and its predecessor UML DI
+spec states the failure mode plainly: without diagram interchange, "all
+diagram information is lost" when a model moves between tools. BPMN DI is a
+normative part of BPMN 2.0
+([ISO/IEC 19510](https://www.iso.org/standard/62652.html)): "the
+interchange of laid out shapes and edges," carrying shape bounds and edge
+waypoints. UML 2.5 normatively defines notation but is silent on layout,
+delegating persistence to the DD-based UML DI annex. Even drafting
+conventions were standardized:
+[ANSI X3.5-1970 §4.4.1](https://www.bitsavers.org/pdf/ansi/X3/X3.005-1970_Flowchart_Symbols_and_Their_Usage_in_Information_Processing.pdf)
+is normative that "normal direction of flow is from left to right and top
+to bottom," with arrowheads *required* only on reverse-direction lines —
+and its successor [ISO 5807:1985](https://www.iso.org/standard/11955.html)
+keeps the conditional-arrowhead rule (§9.3.1: "solid or open arrowheads
+shall be added to indicate direction of flow where necessary (see
+10.2.1.2)"; clause 10 "Conventions" carries the direction rules). Issue
+#25's primary-forward/feedback route classes are that half-century-old
+convention, restated as a checkable invariant — and the same convention
+family yields further validator candidates (unlabeled decision branches;
+single-entry/labeled-exit analysis), tracked in
+[`issue-derived-test-cases.md`](./issue-derived-test-cases.md).
+
+Mature tools likewise expose constraint surfaces. Graphviz dot has had
+[`rank=same`/`min`/`max`](https://graphviz.org/docs/attrs/rank/),
+[compass-point ports](https://graphviz.org/docs/attr-types/portPos/)
+(`a:port:nw -> b`), per-edge
+[`constraint`](https://graphviz.org/docs/attrs/constraint/)/[`weight`](https://graphviz.org/docs/attrs/weight/)
+knobs, and obstacle-avoiding spline routing
+([`splines=true`: "edges are drawn as splines routed around nodes"](https://graphviz.org/docs/attrs/splines/))
+since the 1990s. D2 ships [`near`](https://d2lang.com/tour/positions/)
+(anchor a shape near a named other shape),
+[grid diagrams](https://d2lang.com/tour/grid-diagrams/) for exact
+row/column placement, and the architecture-tuned
+[TALA engine](https://d2lang.com/tour/tala/) — "first-class consideration
+for containers," position locking via `top`/`left`, per-container
+direction, dynamic label positioning (and, honestly documented, its own
+instability: a small label change "can cascade into an entirely different
+layout"). yFiles distinguishes post-hoc "generic" labeling from
+[*integrated* labeling computed during layout](https://docs.yworks.com/yfiles-html/dguide/layout/label_placement.html),
+which "prevent[s] label overlaps completely."
+
+Text-to-diagram tools deliberately drop that half of the artifact: source
+in, geometry recomputed every render, nothing persisted, no constraints.
+That is the actual root of C1 and C6 — not dagre. It is also a real trade
+(zero-friction authoring, diffable sources, no stale coordinates), which is
+why this project keeps the contract but changes who absorbs the cost: the
+layout is a *deterministic function* of source (C6, C11), its quality is
+*measurable* (`checkQuality`), and its decisions are to become
+*explainable* (#25 certificates) — so an editing program gets back the
+agency a human loses by not being able to drag nodes.
+
+### R4. dagre: a partial dot port, frozen
+
+Mermaid (2014, Knut Sveidqvist) was built browser-first on d3 + dagre-d3;
+layout was delegated wholesale to dagre, Chris Pettitt's JavaScript
+implementation of the Sugiyama/dot pipeline — a delegation Mermaid's
+maintainer named himself when opening
+[mermaid#867 "Support multiple layout algorithms"](https://github.com/mermaid-js/mermaid/issues/867)
+in 2019: "Currently the layout mechanism mermaid is using is a dagre
+algorithm."
+
+What dagre ports — and what it omits — maps directly onto the catalog. The
+dot paper
+([Gansner, Koutsofios, North & Vo 1993](https://www.graphviz.org/documentation/TSE93.pdf),
+IEEE TSE 19(3)) is a *four*-pass algorithm: ranking, ordering, coordinates,
+then a spline-routing pass that computes piecewise-Bézier edges inside a
+feasible region so they avoid node obstacles — the paper explicitly calls
+out tools that "make no attempt to avoid situations where line segments
+overlap unrelated nodes." dot also guarantees that edge labels, modeled as
+virtual nodes, "never overlap other nodes, edges or labels," and exposes
+rank constraints. dagre implements the first three passes (its coordinate
+assignment is
+[Brandes & Köpf 2001](https://link.springer.com/chapter/10.1007/3-540-45848-4_3),
+in `lib/position/bk.js`) and then stops: there is no routing phase at all —
+edges are interpolated through dummy-node points.
+[dagre-d3#291](https://github.com/dagrejs/dagre-d3/issues/291) is the
+user-visible result, and complaint categories C4/C5 are the Mermaid-visible
+results. Cluster
+support follows Sander/Forster on paper (per
+[dagre's wiki](https://github.com/dagrejs/dagre/wiki)) but fails on nesting
+and compound edges in practice
+([dagre#125](https://github.com/dagrejs/dagre/issues/125),
+[dagre#238](https://github.com/dagrejs/dagre/issues/238)) — C3. dot-style
+rank constraints existed in early dagre, were dropped in the 0.7 rewrite,
+and the restoration request —
+[dagre#159 "Add back support for rank constraints"](https://github.com/dagrejs/dagre/issues/159)
+— has been open since November 2014.
+
+The "abandoned" framing needs one nuance. D2's engine-comparison page
+states ["Unmaintained. Development stopped in 2018"](https://d2lang.com/tour/dagre/)
+("battle tested (thanks to MermaidJS, which exclusively uses Dagre for its
+flowcharts)"; cons include "makes some inexplicable edge routing decisions
+occasionally"), and that was accurate for the era it described — but the
+`@dagrejs` org resumed releases in 2023 (1.0.0 May 2023; 3.0.0 March 2026).
+What has *not* changed is the feature picture: no routing phase, no ports,
+rank constraints still unrestored after a decade, and Mermaid ships the
+dormant `dagre-d3` line via the `dagre-d3-es` fork.
+
+Mermaid's own remediations concede the diagnosis. The migration ask —
+[mermaid#1969 "Migrate flowchart from dagre to elkjs"](https://github.com/mermaid-js/mermaid/issues/1969)
+(2021: dagre draws "edges … through other blocks instead of around them")
+— was answered by the maintainer himself with the experimental
+`flowchart-elk` renderer in v9.4.0 (February 2023), then v11.0.0 (August
+2024) made layout pluggable with ELK as the opt-in
+[`@mermaid-js/layout-elk`](https://www.npmjs.com/package/@mermaid-js/layout-elk)
+package ("better for larger and/or more complex diagrams," per its own
+docs) — selected via frontmatter `config.layout`, and per the
+[syntax reference](https://mermaid.js.org/intro/syntax-reference.html)
+"currently … supported for flowcharts and state diagrams" only. The
+edge-overlap ask
+[mermaid#1006](https://github.com/mermaid-js/mermaid/issues/1006) was
+closed *Wont Fix*. GitHub's native rendering still runs the dagre default —
+so most readers see the unfixed engine (complaint categories C2, C3, C4, C9),
+and even opted-in users get the better engine for two of ~25 families. PlantUML made the
+opposite bet decades earlier: it
+[delegates class/state/component/usecase layout to Graphviz dot](https://plantuml.com/graphviz-dot),
+inheriting dot's router and rank constraints along with its weaknesses.
+
+This engine's answer is architectural: ELK layered
+([Schulze, Spönemann & von Hanxleden 2014](https://www.sciencedirect.com/science/article/abs/pii/S1045926X13000943),
+JVLC 25(2) — the port-constraint extension of Sugiyama) as the only graph
+engine, bundled synchronously, with model-order options pinned so source
+order drives cycle breaking and crossing minimization
+([`considerModelOrder`](https://eclipse.dev/elk/reference/options/org-eclipse-elk-layered-considerModelOrder-strategy.html):
+"preserves the order of nodes and edges in the model file if this does not
+lead to additional edge crossings"; the backing paper is Domrös &
+von Hanxleden, IVAPP 2022). ELK brings the port constraints
+(`FIXED_SIDE`/`FIXED_ORDER`/`FIXED_POS`) that #25 §8 builds on and dagre
+never had, plus compound layout and an optional libavoid-based
+obstacle-avoiding router. It is not sufficient by itself: upstream #83
+showed ELK's default cycle breaking flipping TD diagrams horizontal until
+model order was enforced; ELK's own docs restrict what composes with
+`INCLUDE_CHILDREN` hierarchy handling (which is why
+`src/layout-engine.ts` falls back to `SEPARATE` when a subgraph overrides
+direction); and ELK still knows nothing about *semantic* edge roles, which
+is exactly the intent layer #25 adds.
+
+### R5. Renderer-first semantics, in three generations
+
+The recurring design flaw across all three codebases is the one #26's
+guiding principle names: *the renderer is the first place semantics are
+guessed.*
+
+- **Mermaid (November 2014–):** born, per its own 0.1.0 README, to "avoid
+  heavy tools like Visio" with "a simple markdown-like script language" —
+  the design optimized authoring friction, not layout quality. Per-family
+  Jison grammars feed per-family bespoke renderers (the sequence renderer
+  uses no layout engine at all — hand-maintained vertical-position
+  bookkeeping, hence C12); text is measured via the browser DOM with HTML
+  labels in `foreignObject` — the C8 export-clipping family, first reported
+  six weeks after the first release
+  ([mermaid#58](https://github.com/mermaid-js/mermaid/issues/58), December
+  2014, still open) — styling is coupled to page CSS, chart geometry is
+  hard-coded per type with no collision handling (C13), and there is no IR
+  contract between parse and render, so every embedder/version pair renders
+  differently (C11).
+- **`mermaid-ascii`:** grid geometry computed during drawing; labels and
+  containers handled by local painter logic (R2).
+- **`beautiful-mermaid` (Craft/Luki Labs, January 2026):** re-implemented
+  rendering as synchronous zero-DOM TypeScript with bundled elkjs (run
+  synchronously via a worker bypass, `src/elk-instance.ts`) — fixing C8 and
+  the browser half of C11 — but kept lenient line-by-line regex parsers
+  (the ER cardinality parser silently dropped valid relationships — upstream
+  #124, fixed here in PR #17) and accumulated post-ELK geometry passes:
+  layer alignment introduced in upstream v1.0.1 ("Layout quality
+  improvements and layer alignment"), edge-point orthogonalization, and
+  post-routing shape clipping. Each pass is locally reasonable; together
+  they move geometry after routes are extracted, which is #25's diagnosed
+  source of hitches and stale bends (§2, §9).
+
+This fork's trajectory is the inversion of that flaw: parse to a typed
+model, derive layout intent, compute geometry, certify, then render —
+with renderers as projections of shared intent rather than the place where
+intent is invented.
+
+### Root causes → historical issue #26 workstream evidence
+
+This crosswalk preserves the research decomposition only. It does not make the
+issue workstreams an active schedule; root `TODO.md` must own any promoted work.
+
+| Root cause | #26 workstream(s) |
+|---|---|
+| R1 phase separation, no invariants | WS1 layout-intent/certificates; WS4 certifying simplifier |
+| R1 labels as afterthoughts | WS8 text-measurement contract; #25 §11.4 label invariant |
+| R1 compound difficulty | WS2 route classes (`cross-hierarchy`, `container-edge`) |
+| R2 greedy grid routing | WS6 ASCII/Unicode as first-class projections of route intent |
+| R3 no control surface | WS14 analysis outputs (explain, don't invent syntax); #25 certificates |
+| R4 rectangular/port-less model | WS3 semantic ports and shape-aware anchors |
+| R5 renderer-first semantics | WS5 Gantt resolver model (landed); WS7 class/ER contracts; WS10 region tree; WS13 preservation ladder |
+| Unreviewable visual change (meta) | WS12 reproducible before/after evidence |
+| Generic metrics miss failures (meta, complaint C4 worked example) | WS11 family-specific validators |
+
+---
+
+## Part 3 — Coverage scorecard
+
+| # | Complaint | Loudest evidence | Status here | Key references |
+|---|---|---|---|---|
+| C1 | Manual positioning | mermaid#5420 (47R), #270 (2016–) | **out of scope** by policy | #25 OQ2; agent loop as substitute |
+| C2 | Scale collapse | mermaid#1984 (39R) | **partial** (detection only) | `quality.ts` bands; `eval/layout-compare/` |
+| C3 | Subgraphs | mermaid#2509 (189R) | **landed** | `subgraph-direction.test.ts`; PRs #17/#21/#22 |
+| C4 | Erratic routing | mermaid#6476, #5601 | **partial**; candidate fix evidence only | #25 §11–12; MFA worked example above |
+| C5 | Edge-label overlap | mermaid#2131 | **partial** | inline ELK labels; `labelEdgeProximity`; #25 §11.4 |
+| C6 | Order control / edit stability | mermaid#3723 (86R), #815 (45R) | **partial** | model-order ELK opts; `agent-auth-flow.test.ts`; edit-stability tests |
+| C7 | Default aesthetics | HN 30339032 | **landed** (upstream + fork) | theming; Style + Palette; contrast tests |
+| C8 | Text clipping | mermaid#2688 (24R) | **landed** | zero-DOM text; `LABEL_OVERFLOW`; CJK tests; WS8 candidate evidence |
+| C9 | dagre stagnation | Mermaid docs' own ELK advice | **landed** structurally | `layout-engine.ts`; `elk-instance.ts`; #25 §10 |
+| C10 | Self-loops | mermaid#6336 (31R) | **partial** | clearance heuristics; #25 §8.1 candidate evidence |
+| C11 | Version/renderer instability | mermaid#5813 (28R) | **landed** | determinism suite; `eval/layout-compare/`; goldens |
+| C12 | Sequence alignment | mermaid#1765 (28R) | **partial**; first properties landed | #25 §14.2; #26 WS11; `sequence-layout.test.ts` |
+| C13 | Chart-family geometry | mermaid#1301 (23R) | **partial** | PR #24 (gantt); pie/quadrant/gantt geometry tests |
+
+---
+
+## Part 4 — What this project deliberately does not address
+
+Stated plainly so the scorecard cannot oversell:
+
+1. **Manual positioning (C1).** Arbitrary coordinates and post-layout nudging
+   remain deliberately unsupported. `BUILD-24` schedules only typed structural
+   auto-layout constraints (rank, adjacency, short-edge preference), without
+   inventing Mermaid source syntax. If Mermaid core standardizes compatible
+   source hints, this fork can map them into the same typed contract.
+2. **Large-diagram compaction (C2).** Detection exists; no compaction work
+   is scheduled. Source-order priority can make wide diagrams wider — the
+   Auth Flow aspect band in `agent-auth-flow.test.ts` is widened to 7
+   because of it. The only candidate direction on record is the
+   decomposition idea noted in C2, which sidesteps compaction rather than
+   solving it.
+3. **Reach.** Most complainers experience Mermaid through GitHub/GitLab/
+   Notion native rendering, which no fork renderer can change. Work here
+   applies to diagrams rendered through this stack (agent pipelines, CI,
+   terminals, the editor) plus whatever is upstreamed per the
+   [upstreaming strategy](./fork-differences.md#upstreaming-strategy).
+4. **Family coverage.** The checked runtime registry is the source of truth for
+   supported families. Every registered family, including Radar, is rendered and
+   characterized; Mermaid families outside that registry remain unsupported.
+5. **Metric honesty.** Today's perceptual metrics pass diagrams whose
+   routing is visibly wrong (complaint C4 worked example). Unless and until the
+   #25 certificate and #26 family-validator candidates are promoted in root
+   `TODO.md` and land, `verify.ok` + `checkQuality` must not be read as "looks
+   right" — `docs/quality.md` already says this; the MFA fixture proves it.
+
+---
+
+## Sources
+
+Complaint evidence (June 2026): the `mermaid-js/mermaid` issues linked
+inline above; Mermaid flowchart docs
+(<https://mermaid.js.org/syntax/flowchart.html>); Hacker News items linked
+inline; the GitLab handbook Mermaid-layout page
+(<https://handbook.gitlab.com/handbook/tools-and-tips/mermaid/>);
+diagrams.so's diagram-as-code comparison
+(<https://diagrams.so/learn/diagram-as-code-comparison>).
+
+Literature (all verified June 2026; venue/page details via dblp or
+publisher pages):
+
+- Sugiyama, Tagawa & Toda, "Methods for Visual Understanding of
+  Hierarchical System Structures," IEEE Trans. SMC-11(2), 1981.
+  <https://doi.org/10.1109/TSMC.1981.4308636>
+- Garey & Johnson, "Crossing Number is NP-Complete," SIAM J. Algebraic
+  Discrete Methods 4(3), 1983. <https://dl.acm.org/doi/10.1137/0604033>
+- Eades & Wormald, "Edge crossings in drawings of bipartite graphs,"
+  Algorithmica 11(4), 1994.
+  <https://link.springer.com/article/10.1007/BF01187020>
+- Marks & Shieber, "The Computational Complexity of Cartographic Label
+  Placement," Harvard TR-05-91, 1991.
+  <https://dash.harvard.edu/entities/publication/73120379-247a-6bd4-e053-0100007fdf3b>
+- Kakoulis & Tollis, "On the complexity of the Edge Label Placement
+  problem," Comput. Geom. 18(1), 2001.
+  <https://www.sciencedirect.com/science/article/pii/S0925772100000250>
+- Gansner, Koutsofios, North & Vo, "A Technique for Drawing Directed
+  Graphs," IEEE TSE 19(3), 1993.
+  <https://www.graphviz.org/documentation/TSE93.pdf>
+- Brandes & Köpf, "Fast and Simple Horizontal Coordinate Assignment,"
+  GD 2001, LNCS 2265.
+  <https://link.springer.com/chapter/10.1007/3-540-45848-4_3> (authors'
+  2020 erratum: <https://arxiv.org/abs/2008.01252>)
+- Schulze, Spönemann & von Hanxleden, "Drawing layered graphs with port
+  constraints," JVLC 25(2), 2014.
+  <https://www.sciencedirect.com/science/article/abs/pii/S1045926X13000943>
+- Domrös & von Hanxleden, "Preserving Order during Crossing Minimization
+  in Sugiyama Layouts," IVAPP 2022.
+  <https://www.scitepress.org/Papers/2022/108338/108338.pdf>
+- Purchase, "Which aesthetic has the greatest effect on human
+  understanding?", GD 1997, LNCS 1353.
+  <https://link.springer.com/chapter/10.1007/3-540-63938-1_67>
+- Sander, "Layout of Compound Directed Graphs," TR A/03/96, Universität
+  des Saarlandes, 1996.
+  <https://publikationen.sulb.uni-saarland.de/bitstream/20.500.11880/25862/1/tr-A03-96.pdf>
+- Wybrow, Marriott & Stuckey, "Orthogonal Connector Routing," GD 2009
+  (libavoid). <https://users.monash.edu/~mwybrow/papers/wybrow-gd-2009.pdf>
+
+Products: Graphviz attribute docs (`rank`, `portPos`, `splines`,
+`constraint`, `weight`, linked inline); D2/Terrastruct docs (TALA, `near`,
+grid diagrams, dagre/ELK engine pages, linked inline); yFiles automatic
+label placement
+(<https://docs.yworks.com/yfiles-html/dguide/layout/label_placement.html>);
+PlantUML–Graphviz delegation (<https://plantuml.com/graphviz-dot>);
+Mermaid v11.0.0 release
+(<https://github.com/mermaid-js/mermaid/releases/tag/v11.0.0>) and
+`@mermaid-js/layout-elk`
+(<https://www.npmjs.com/package/@mermaid-js/layout-elk>); ELK option
+reference (<https://eclipse.dev/elk/reference.html>) and the ELK overview
+paper (<https://arxiv.org/abs/2311.00533>).
+
+Standards: OMG Diagram Definition v1.1 (<https://www.omg.org/spec/DD/>);
+BPMN 2.0.2 (<https://www.omg.org/spec/BPMN/2.0.2/>) / ISO/IEC 19510:2013
+(<https://www.iso.org/standard/62652.html>); UML 2.5.1
+(<https://www.omg.org/spec/UML/2.5.1/About-UML>); ISO 5807:1985
+(<https://www.iso.org/standard/11955.html>); ANSI X3.5-1970 (scan:
+<https://www.bitsavers.org/pdf/ansi/X3/X3.005-1970_Flowchart_Symbols_and_Their_Usage_in_Information_Processing.pdf>).
+
+Origins: Mermaid 0.1.0 (November 2014, Knut Sveidqvist;
+<https://github.com/mermaid-js/mermaid/releases/tag/0.1.0> — the 0.1.0
+README credits d3 and dagre-d3 and states the Visio-avoidance motive);
+dagre (Chris Pettitt; wiki reading list
+<https://github.com/dagrejs/dagre/wiki>; rank-constraint regression
+dagre#159; `@dagrejs` revival releases 2023–2026); `mermaid-ascii`
+(Alexander Grooff, <https://github.com/AlexanderGrooff/mermaid-ascii>;
+Show HN October 2024 <https://news.ycombinator.com/item?id=41847407>);
+`beautiful-mermaid` (Luki Labs/Craft, npm January 2026; HN thread
+<https://news.ycombinator.com/item?id=46804828>; upstream v1.0.1
+layout/layer-alignment commit; upstream issues
+#63/#68/#69/#83/#89/#98/#111/#112/#113/#115/#119/#121/#124).