agentic-mermaid 0.1.1 → 0.2.0

package/docs/design/system/architecture.mmd

@@ -1,29 +0,0 @@
-graph TD
-  SRC["Mermaid source text"] --> NORM["normalize source<br/>frontmatter · %%init%% · config"]
-  NORM --> DET{"detect diagram type"}
-  DET --> REG["FamilyPlugin registry<br/>detect · parse · layout · renderSvg · renderAscii<br/>serialize · mutate · verify"]
-
-  subgraph SVGSTACK["SVG stack · renderMermaidSVG"]
-    direction TB
-    L1["source-context layout hook<br/>parse → config middleware → layout"] --> CTX["RenderContext<br/>positioned · colors · options"]
-    CTX --> O1["SVG string"]
-  end
-
-  subgraph ASCIISTACK["ASCII stack · renderMermaidASCII"]
-    direction TB
-    L2["renderAscii hook"] --> GRID["grid geometry<br/>AsciiGraph · Canvas · A* pathfinder"]
-    GRID --> O2["text grid"]
-  end
-
-  subgraph AGENTSTACK["Agent stack · parse / mutate / verify"]
-    direction TB
-    VD["ValidDiagram · DiagramBody<br/>structured | opaque"] --> RL["RenderedLayout"]
-  end
-
-  REG -->|"SVG hooks"| L1
-  REG -->|"ASCII / unicode hook"| L2
-  REG -->|"agent hooks"| VD
-
-  REG -.same 12 families.-> FAM
-  FAM["12 diagram families<br/>flowchart · sequence · class · er · gantt<br/>pie · journey · timeline · quadrant · xychart · architecture · state"]
-  FAM --> CORE["shared core types · types.ts<br/>NodeShape · EdgeStyle · MermaidGraph · RouteClass"]

package/docs/design/system/architecture.svg

@@ -1,137 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1381.6179999999997 963.882" width="1381.6179999999997" height="963.882" style="--bg:#FFFFFF;--fg:#27272A;--font:Inter;background:#FFFFFF">
-<style>
-  @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&amp;display=swap');
-  text { font-family: var(--font, 'Inter'), system-ui, sans-serif; }
-  svg {
-    /* Derived from --bg and --fg (overridable via --line, --accent, etc.) */
-    --_text:          #27272A;
-    --_text-sec:      #575759;
-    --_text-muted:    #707072;
-    --_text-faint:    #8a8a8c;
-    --_line:          #939395;
-    --_arrow:         #47474a;
-    --_node-fill:     #f9f9f9;
-    --_node-stroke:   #d4d4d4;
-    --_group-fill:    #FFFFFF;
-    --_group-hdr:     #f4f4f4;
-    --_inner-stroke:  #e5e5e5;
-    --_key-badge:     #e9e9ea;
-  }
-</style>
-<defs>
-  <marker id="arrowhead" markerWidth="8" markerHeight="5" refX="7" refY="2.5" orient="auto">
-    <polygon points="0 0, 8 2.5, 0 5" fill="#47474a" stroke="#47474a" stroke-width="0.75" stroke-linejoin="round" />
-  </marker>
-  <marker id="arrowhead-start" markerWidth="8" markerHeight="5" refX="7" refY="2.5" orient="auto-start-reverse">
-    <polygon points="0 0, 8 2.5, 0 5" fill="#47474a" stroke="#47474a" stroke-width="0.75" stroke-linejoin="round" />
-  </marker>
-</defs>
-<g class="subgraph" data-id="SVGSTACK" data-region="subgraph" data-label="SVG stack · renderMermaidSVG">
-  <rect x="479.8599999999998" y="616.282" width="273.279" height="300.5" rx="0" ry="0" fill="#FFFFFF" stroke="#d4d4d4" stroke-width="1" />
-  <path d="M479.8599999999998,616.282 H753.1389999999998 V644.282 H479.8599999999998 Z" fill="#f4f4f4" stroke="#d4d4d4" stroke-width="1" />
-  <text x="491.8599999999998" y="630.282" font-size="12" font-weight="600" fill="#575759" dy="4.199999999999999">SVG stack · renderMermaidSVG</text>
-</g>
-<g class="subgraph" data-id="ASCIISTACK" data-region="subgraph" data-label="ASCII stack · renderMermaidASCII">
-  <rect x="781.1389999999998" y="640.2819999999999" width="288.09899999999993" height="283.6" rx="0" ry="0" fill="#FFFFFF" stroke="#d4d4d4" stroke-width="1" />
-  <path d="M781.1389999999998,640.2819999999999 H1069.2379999999998 V668.2819999999999 H781.1389999999998 Z" fill="#f4f4f4" stroke="#d4d4d4" stroke-width="1" />
-  <text x="793.1389999999998" y="654.2819999999999" font-size="12" font-weight="600" fill="#575759" dy="4.199999999999999">ASCII stack · renderMermaidASCII</text>
-</g>
-<g class="subgraph" data-id="AGENTSTACK" data-region="subgraph" data-label="Agent stack · parse / mutate / verify">
-  <rect x="1097.2379999999998" y="616.282" width="244.37999999999997" height="198.70000000000002" rx="0" ry="0" fill="#FFFFFF" stroke="#d4d4d4" stroke-width="1" />
-  <path d="M1097.2379999999998,616.282 H1341.6179999999997 V644.282 H1097.2379999999998 Z" fill="#f4f4f4" stroke="#d4d4d4" stroke-width="1" />
-  <text x="1109.2379999999998" y="630.282" font-size="12" font-weight="600" fill="#575759" dy="4.199999999999999">Agent stack · parse / mutate / verify</text>
-</g>
-<polyline class="edge" data-from="SRC" data-to="NORM" data-style="solid" data-arrow-start="false" data-arrow-end="true" data-marker-end="arrow" points="925.1884999999996,76.9 925.1884999999997,124.9" fill="none" stroke="#939395" stroke-width="1" marker-end="url(#arrowhead)" />
-<polyline class="edge" data-from="NORM" data-to="DET" data-style="solid" data-arrow-start="false" data-arrow-end="true" data-marker-end="arrow" points="925.1884999999997,178.70000000000002 925.1884999999997,226.70000000000002" fill="none" stroke="#939395" stroke-width="1" marker-end="url(#arrowhead)" />
-<polyline class="edge" data-from="DET" data-to="REG" data-style="solid" data-arrow-start="false" data-arrow-end="true" data-marker-end="arrow" points="925.1884999999997,405.28200000000004 925.1884999999997,453.28200000000004" fill="none" stroke="#939395" stroke-width="1" marker-end="url(#arrowhead)" />
-<polyline class="edge" data-from="FAM" data-to="CORE" data-style="solid" data-arrow-start="false" data-arrow-end="true" data-marker-end="arrow" points="249.9299999999999,110.7 249.9299999999999,158.7" fill="none" stroke="#939395" stroke-width="1" marker-end="url(#arrowhead)" />
-<polyline class="edge" data-from="REG" data-to="L1" data-style="solid" data-arrow-start="false" data-arrow-end="true" data-marker-end="arrow" data-label="SVG hooks" points="842.0829999999997,523.982 842.0829999999997,535.9820000000001 616.4994999999998,535.9820000000001 616.4994999999998,672.2819999999999" fill="none" stroke="#939395" stroke-width="1" marker-end="url(#arrowhead)" />
-<polyline class="edge" data-from="REG" data-to="L2" data-style="solid" data-arrow-start="false" data-arrow-end="true" data-marker-end="arrow" data-label="ASCII / unicode hook" points="925.1884999999997,523.982 925.1884999999997,672.2819999999999" fill="none" stroke="#939395" stroke-width="1" marker-end="url(#arrowhead)" />
-<polyline class="edge" data-from="REG" data-to="VD" data-style="solid" data-arrow-start="false" data-arrow-end="true" data-marker-end="arrow" data-label="agent hooks" points="1008.2939999999996,523.982 1008.2939999999998,535.9820000000001 1219.4279999999997,535.9820000000001 1219.4279999999999,672.2819999999999" fill="none" stroke="#939395" stroke-width="1" marker-end="url(#arrowhead)" />
-<polyline class="edge" data-from="L1" data-to="CTX" data-style="solid" data-arrow-start="false" data-arrow-end="true" data-marker-end="arrow" points="616.4994999999998,726.082 616.4994999999998,765.6320000000001" fill="none" stroke="#939395" stroke-width="1" marker-end="url(#arrowhead)" />
-<polyline class="edge" data-from="CTX" data-to="O1" data-style="solid" data-arrow-start="false" data-arrow-end="true" data-marker-end="arrow" points="616.4994999999998,819.432 616.4994999999998,867.432" fill="none" stroke="#939395" stroke-width="1" marker-end="url(#arrowhead)" />
-<polyline class="edge" data-from="L2" data-to="GRID" data-style="solid" data-arrow-start="false" data-arrow-end="true" data-marker-end="arrow" points="925.1884999999997,709.1819999999999 925.1884999999997,765.6320000000001" fill="none" stroke="#939395" stroke-width="1" marker-end="url(#arrowhead)" />
-<polyline class="edge" data-from="GRID" data-to="O2" data-style="solid" data-arrow-start="false" data-arrow-end="true" data-marker-end="arrow" points="925.1884999999997,819.4320000000001 925.1884999999997,867.432" fill="none" stroke="#939395" stroke-width="1" marker-end="url(#arrowhead)" />
-<polyline class="edge" data-from="VD" data-to="RL" data-style="solid" data-arrow-start="false" data-arrow-end="true" data-marker-end="arrow" points="1219.4279999999999,726.082 1219.4279999999999,765.6320000000001" fill="none" stroke="#939395" stroke-width="1" marker-end="url(#arrowhead)" />
-<g class="edge-label" data-from="REG" data-to="L1" data-label="SVG hooks">
-  <rect class="edge-label-halo" x="576.9994999999998" y="538.9820000000001" width="78.51599999999999" height="38.3" rx="4" ry="4" fill="#FFFFFF" stroke="none" />
-  <rect x="580.9994999999998" y="542.9820000000001" width="70.51599999999999" height="30.3" rx="2" ry="2" fill="#FFFFFF" stroke="#e5e5e5" stroke-width="1" />
-  <text x="616.2574999999998" y="558.1320000000001" text-anchor="middle" font-size="11" font-weight="400" fill="#575759" dy="3.8499999999999996">SVG hooks</text>
-</g>
-<g class="edge-label" data-from="REG" data-to="L2" data-label="ASCII / unicode hook">
-  <rect class="edge-label-halo" x="864.1884999999997" y="562.982" width="121.878" height="38.3" rx="4" ry="4" fill="#FFFFFF" stroke="none" />
-  <rect x="868.1884999999997" y="566.982" width="113.878" height="30.3" rx="2" ry="2" fill="#FFFFFF" stroke="#e5e5e5" stroke-width="1" />
-  <text x="925.1274999999997" y="582.132" text-anchor="middle" font-size="11" font-weight="400" fill="#575759" dy="3.8499999999999996">ASCII / unicode hook</text>
-</g>
-<g class="edge-label" data-from="REG" data-to="VD" data-label="agent hooks">
-  <rect class="edge-label-halo" x="1177.4279999999997" y="538.9820000000001" width="83.268" height="38.3" rx="4" ry="4" fill="#FFFFFF" stroke="none" />
-  <rect x="1181.4279999999997" y="542.9820000000001" width="75.268" height="30.3" rx="2" ry="2" fill="#FFFFFF" stroke="#e5e5e5" stroke-width="1" />
-  <text x="1219.0619999999997" y="558.1320000000001" text-anchor="middle" font-size="11" font-weight="400" fill="#575759" dy="3.8499999999999996">agent hooks</text>
-</g>
-<g class="node" data-id="SRC" data-label="Mermaid source text" data-shape="rectangle">
-  <rect x="844.5629999999996" y="40" width="161.251" height="36.900000000000006" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="925.1884999999996" y="58.45" text-anchor="middle" font-size="13" font-weight="500" fill="#27272A" dy="4.55">Mermaid source text</text>
-</g>
-<g class="node" data-id="NORM" data-label="normalize source
-frontmatter · %%init%% · config" data-shape="rectangle">
-  <rect x="817.5164999999997" y="124.9" width="215.34399999999997" height="53.800000000000004" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="925.1884999999997" y="151.8" text-anchor="middle" font-size="13" font-weight="500" fill="#27272A"><tspan x="925.1884999999997" dy="-3.9000000000000012">normalize source</tspan><tspan x="925.1884999999997" dy="16.900000000000002">frontmatter · %%init%% · config</tspan></text>
-</g>
-<g class="node" data-id="DET" data-label="detect diagram type" data-shape="diamond">
-  <polygon points="925.1884999999997,226.7 1014.4794999999997,315.991 925.1884999999997,405.282 835.8974999999998,315.991" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="925.1884999999997" y="315.991" text-anchor="middle" font-size="13" font-weight="500" fill="#27272A" dy="4.55">detect diagram type</text>
-</g>
-<g class="node" data-id="REG" data-label="FamilyPlugin registry
-detect · parse · layout · renderSvg · renderAscii
-serialize · mutate · verify" data-shape="rectangle">
-  <rect x="758.9774999999997" y="453.28200000000004" width="332.42199999999997" height="70.7" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="925.1884999999997" y="488.63200000000006" text-anchor="middle" font-size="13" font-weight="500" fill="#27272A"><tspan x="925.1884999999997" dy="-12.350000000000001">FamilyPlugin registry</tspan><tspan x="925.1884999999997" dy="16.900000000000002">detect · parse · layout · renderSvg · renderAscii</tspan><tspan x="925.1884999999997" dy="16.900000000000002">serialize · mutate · verify</tspan></text>
-</g>
-<g class="node" data-id="L1" data-label="source-context layout hook
-parse → config middleware → layout" data-shape="rectangle">
-  <rect x="495.8599999999998" y="672.2819999999999" width="241.27899999999997" height="53.800000000000004" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="616.4994999999998" y="699.1819999999999" text-anchor="middle" font-size="13" font-weight="500" fill="#27272A"><tspan x="616.4994999999998" dy="-3.9000000000000012">source-context layout hook</tspan><tspan x="616.4994999999998" dy="16.900000000000002">parse → config middleware → layout</tspan></text>
-</g>
-<g class="node" data-id="CTX" data-label="RenderContext
-positioned · colors · options" data-shape="rectangle">
-  <rect x="512.5324999999998" y="765.6320000000001" width="207.934" height="53.800000000000004" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="616.4994999999998" y="792.532" text-anchor="middle" font-size="13" font-weight="500" fill="#27272A"><tspan x="616.4994999999998" dy="-3.9000000000000012">RenderContext</tspan><tspan x="616.4994999999998" dy="16.900000000000002">positioned · colors · options</tspan></text>
-</g>
-<g class="node" data-id="O1" data-label="SVG string" data-shape="rectangle">
-  <rect x="564.0319999999998" y="867.432" width="104.93499999999999" height="36.900000000000006" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="616.4994999999998" y="885.8820000000001" text-anchor="middle" font-size="13" font-weight="500" fill="#27272A" dy="4.55">SVG string</text>
-</g>
-<g class="node" data-id="L2" data-label="renderAscii hook" data-shape="rectangle">
-  <rect x="852.7139999999997" y="672.2819999999999" width="144.949" height="36.900000000000006" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="925.1884999999997" y="690.732" text-anchor="middle" font-size="13" font-weight="500" fill="#27272A" dy="4.55">renderAscii hook</text>
-</g>
-<g class="node" data-id="GRID" data-label="grid geometry
-AsciiGraph · Canvas · A* pathfinder" data-shape="rectangle">
-  <rect x="797.1389999999998" y="765.6320000000001" width="256.09899999999993" height="53.800000000000004" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="925.1884999999997" y="792.532" text-anchor="middle" font-size="13" font-weight="500" fill="#27272A"><tspan x="925.1884999999997" dy="-3.9000000000000012">grid geometry</tspan><tspan x="925.1884999999997" dy="16.900000000000002">AsciiGraph · Canvas · A* pathfinder</tspan></text>
-</g>
-<g class="node" data-id="O2" data-label="text grid" data-shape="rectangle">
-  <rect x="880.8719999999997" y="867.432" width="88.633" height="36.900000000000006" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="925.1884999999997" y="885.8820000000001" text-anchor="middle" font-size="13" font-weight="500" fill="#27272A" dy="4.55">text grid</text>
-</g>
-<g class="node" data-id="VD" data-label="ValidDiagram · DiagramBody
-structured | opaque" data-shape="rectangle">
-  <rect x="1113.2379999999998" y="672.2819999999999" width="212.37999999999997" height="53.800000000000004" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="1219.4279999999999" y="699.1819999999999" text-anchor="middle" font-size="13" font-weight="500" fill="#27272A"><tspan x="1219.4279999999999" dy="-3.9000000000000012">ValidDiagram · DiagramBody</tspan><tspan x="1219.4279999999999" dy="16.900000000000002">structured | opaque</tspan></text>
-</g>
-<g class="node" data-id="RL" data-label="RenderedLayout" data-shape="rectangle">
-  <rect x="1148.0649999999998" y="765.6320000000001" width="142.726" height="36.900000000000006" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="1219.4279999999999" y="784.0820000000001" text-anchor="middle" font-size="13" font-weight="500" fill="#27272A" dy="4.55">RenderedLayout</text>
-</g>
-<g class="node" data-id="FAM" data-label="12 diagram families
-flowchart · sequence · class · er · gantt
-pie · journey · timeline · quadrant · xychart · architecture · state" data-shape="rectangle">
-  <rect x="40" y="40" width="419.8599999999998" height="70.7" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="249.9299999999999" y="75.35" text-anchor="middle" font-size="13" font-weight="500" fill="#27272A"><tspan x="249.9299999999999" dy="-12.350000000000001">12 diagram families</tspan><tspan x="249.9299999999999" dy="16.900000000000002">flowchart · sequence · class · er · gantt</tspan><tspan x="249.9299999999999" dy="16.900000000000002">pie · journey · timeline · quadrant · xychart · architecture · state</tspan></text>
-</g>
-<g class="node" data-id="CORE" data-label="shared core types · types.ts
-NodeShape · EdgeStyle · MermaidGraph · RouteClass" data-shape="rectangle">
-  <rect x="67.78749999999991" y="158.7" width="364.28499999999997" height="53.800000000000004" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="249.9299999999999" y="185.6" text-anchor="middle" font-size="13" font-weight="500" fill="#27272A"><tspan x="249.9299999999999" dy="-3.9000000000000012">shared core types · types.ts</tspan><tspan x="249.9299999999999" dy="16.900000000000002">NodeShape · EdgeStyle · MermaidGraph · RouteClass</tspan></text>
-</g>
-</svg>

package/docs/design/system/layout-guarantees-and-robustness.md

@@ -1,351 +0,0 @@
-# Layout guarantees and robustness — what we can promise, and how
-
-A literature + industry synthesis answering one question: **which layout
-invariants can we guarantee in 100% of inputs and keep robust under fuzzing, and
-which are provably impossible to guarantee — so we must optimize-and-certify
-instead?** It was produced by a fan-out of research sub-agents over the academic
-graph-drawing / map-labeling literature and the engineering practice of yFiles,
-Graphviz, ELK, OGDF, Adaptagrams/libavoid, cola.js, tldraw, Excalidraw, and
-draw.io/mxGraph. Citations are at the end.
-
-This doc is the *map*. The route-engine details live in
-[`route-contracts.md`](./route-contracts.md); the quality metrics in
-[`layout-rubric.md`](./layout-rubric.md).
-
-## TL;DR
-
-The field partitions drawing properties into two kinds, and we must treat them
-differently:
-
-| Kind | Examples | Best achievable | Our use |
-| --- | --- | --- | --- |
-| **Conventions / feasibility** (membership predicates) | orthogonality, port-exactness, no node overlap, monotone flow, axis-alignment, determinism, lane-distinctness | **100%, by construction**, usually polynomial | the **hard** rubric invariants (must be 0) |
-| **Aesthetic optima** | min crossings, min bends (free embedding), min area, max symmetry | **NP-hard — no 100% guarantee**; optimize then certify the value achieved | the **soft** rubric metrics (ratcheted) |
-| **Label placement** (in between) | place every label cleanly without moving nodes | **NP-hard** (Kakoulis–Tollis ELP; Marks–Shieber: poly ⇔ P=NP). Algorithms **maximize placed labels and may drop/overlap some** | `findLabelSlot` + certify-or-fallback |
-
-So "100% + fuzz-robust" is reachable **only when reframed**: not "always produce
-the optimal/clean drawing" (impossible for the NP-hard ones) but *"always satisfy
-the hard conventions — by construction, or by a checker that vetoes and falls
-back — while optimizing the soft aesthetics and honestly certifying the value we
-hit."* That is the architecture we already have; the research says where to
-tighten it.
-
-## The robustness mechanism (why fuzzing keeps finding 1–2px bugs)
-
-Our recurring failures — labels grazing nodes, collinear edges merging, endpoints
-just off a port at 1–2px — are the textbook symptom of **floating-point
-geometric predicates returning inconsistent signs near degeneracy** (Kettner,
-Mehlhorn, Pion, Schirra, Yap 2008). The cure is the Exact-Geometric-Computation
-paradigm, **not** more fuzzing (Dijkstra: testing shows presence, never absence):
-
-1. **Exact discrete predicates.** Evaluate the *decisions* — does this label pill
-   overlap this node? is this endpoint on this port? are these two segments
-   collinear-and-overlapping? does this segment pass through this shape? — in
-   **integer arithmetic on snapped coordinates with one fixed tie-break**
-   (Simulation of Simplicity), not against scattered ε. The *coordinates* being
-   slightly off is harmless; the *branch decisions* being wrong is catastrophic
-   and self-reinforcing. This collapses the near-degenerate class fuzzing keeps
-   surfacing and makes producer and checker bit-identical. (Yap EGC; Shewchuk
-   adaptive predicates; CGAL's "exact predicates, inexact constructions";
-   Edelsbrunner–Mücke; Hobby snap-rounding.) Today these decisions are spread
-   across tolerances (`EPS`, `GRAZE`, `TOL`, `BOUNDS_TOL`, `PORT_TOLERANCE`) — the
-   symptom, not the cure.
-2. **One independent, total checker on every output** that re-derives each hard
-   invariant from rendered geometry alone and *vetoes* a violating layout,
-   falling back to a safe route. [`layout-rubric.ts`](../../../src/layout-rubric.ts)
-   already does this right for outlines (it reimplements each shape's outline so a
-   port regression can't hide itself); the **route** checker is weaker — its audits
-   reuse the producer's own `directLaneBlockers`/`tryStraighten`, so a bug there is
-   invisible to it. (Certifying algorithms: McConnell–Mehlhorn–Näher–Schweitzer
-   2011; checker-only formal verification: Alkassar–Böhme–Mehlhorn–Rizkallah 2011.)
-3. **Exhaustive small-scope enumeration** (all non-isomorphic graphs ≤ 5–6 nodes ×
-   shapes × 4 directions) is a *complete* proof in-scope — the real "ever" — with
-   fuzzing relegated to the large-graph tail (small-scope hypothesis, Jackson 2006).
-
-## The three problems, with verdicts
-
-### 1. A label displaces the node off its port → 100% solvable by construction
-
-Industry is **unanimous**: every hand-authored editor — tldraw, Excalidraw,
-draw.io/mxGraph, yFiles' generic labeler — **decouples labels; node positions are
-never perturbed by a label.** The two systems that reserve in-band label space
-(Graphviz's `label` dummy-node; yFiles' integrated mode) *both document it as
-distorting the layout* — Graphviz's FAQ: edge labels as dummy nodes "can
-dramatically distort the layout," and `xlabel` (post-layout placement) is offered
-as the escape hatch. That `xlabel` is our `APL_DECOUPLE_LABELS`.
-
-**Verdict: making "a label can never move a node" a structural invariant is
-correct, and the literature says make decoupling the default.** Already built and
-validated (fixes the sym A→B port and the minimal repro, zero corpus-quality cost,
-deterministic). The only blocker to default-on is problem 2.
-
-### 2. Label on a shared trunk (the bent-duplicate regressions) → split verdict
-
-Two problems under one error code:
-
-- **(a) the two edges share a trunk** — the universal industry solution is a
-  *dedicated duplicate-edge spreading pass*: mxParallelEdgeLayout (bucket by a
-  **direction-independent edge key**, fan into lanes by perpendicular offset,
-  default spacing 20), yFiles' ParallelEdgeRouter (leading-edge + parallel
-  reinsertion). With **distinct fixed ports per parallel edge** (Spönemann's
-  FIXED_POS port-constraint hierarchy — which `allocateRoutePorts` already plans
-  slots for) the edges become non-collinear at both ends **by construction**.
-  100%-achievable; the current pass just carves out *labeled* bent duplicates —
-  exactly the fuzz regression.
-- **(b) the label finding a private segment** — the NP-hard half. We **cannot**
-  guarantee a clean placement always *exists* (Kakoulis–Tollis: maximize placed
-  labels, may drop some). But we **can enforce the invariant** as
-  *certify-or-fallback*: if no edge-private labelable segment survives laning, the
-  route contract **vetoes that geometry and falls back** (reserved label corridor /
-  boundary-label leader à la Bekos et al. / suppress). The *output* invariant "no
-  label on a shared trunk" becomes total via the checker's veto.
-
-**Verdict: port-exactness + lane separation = 100% by construction;
-clean-label-placement = not guaranteed (NP-hard) but enforceable as
-certified-or-safe-fallback.** Extend the duplicate-lane assignment to cover
-labeled bent duplicates (keyed by unordered pair), then veto-and-fallback for the
-residue. This unblocks decoupling-by-default.
-
-### 3. Bundling adds bends without removing crossings → can never be 100%; gate it
-
-The visualization literature is flat: edge bundling (Holten 2006; Holten–van Wijk
-2009) **reduces visual clutter but does not reduce the number of crossings, and
-adds curvature/ambiguity.** Bundling an already-crossing-free fan is all cost, no
-benefit (our observed defect: `bundleEdgePaths` on shared-hub fans, +bends, 0
-crossings removed). Bundling is irreducibly a heuristic — never a 100% guarantee.
-
-**Verdict: add a net-benefit gate** (the hyperedge-routing cost view): only keep a
-bundle when it does not increase total bends without removing a crossing; never
-bundle a crossing-free fan. The `simplifyPolyline` bend count + a member-vs-member
-crossing count make a heuristic *safe* ("bundling never worsens crossings or
-bends"), which itself *is* a 100%-guaranteeable property.
-
-### 3a. The justified / symmetric bend — not every bend is a defect
-
-The aesthetic hierarchy distinguishes a *justified* bend from an *unjustified*
-one. A bend that is part of a **symmetric convergence** — a fan-out/fan-in bundle,
-or a **co-ranked mixed-label fan-in**'s converging dogleg — is "as good as" a
-straight line and is **not penalized**: the bend is structurally necessary to
-converge (N spokes cannot merge into one node without a turn), and the symmetry it
-buys offsets the small bend cost — the idiom every reference layered drawer uses,
-and the one our own fan-out emitter (`applySymmetricFanoutEmissions`) already
-relies on. Only *unjustified / lone* bends cost.
-
-The rubric encodes this exactly: a bend on a `bundle`-certified edge is excluded
-from `totalBends`/`maxBendsPerEdge` — the **same** edges `findRouteHitches` skips
-— so the soft bend penalty and the HARD hitch-invariant agree on what is
-justified, while an off-lane jog with a clear straight lane (`hitches`) or a bend
-on a `straight`-certified edge (`unexplainedBends`) stays a HARD violation.
-
-This dissolves an apparent conflict. A **mixed-label fan-in** (a hub fed by both a
-labelled and an unlabelled edge) used to land asymmetric: ELK reserves an
-inline-label dummy rank for the labelled edge only, so its source ranked one layer
-early and the hub could not be squared up. The fix (default; `APL_NO_CORANK_FANIN`
-to disable) gives each unlabelled sibling a layout-only balancing label so all the
-sources **co-rank**, then centres the hub on their barycentre; the spokes converge
-as symmetric doglegs (`markCorankFanInBundles` re-routes them port-to-port and
-marks them bundle-owned). That *bends the labelled spoke*, which the older
-"labelled source exits straight at its mid-port" contract forbade — but under the
-symmetric-bend principle that is a **corrected contract, not a regression**: the
-spoke still exits at the source mid-port, it just bends to converge. The
-labelled-source-straightening pass (`alignLabeledSourcePort`) accordingly *yields*
-to a fan-in hub and still straightens only a labelled source into a single-input
-target.
-
-## The bigger architectural opportunity (larger scope, separate track)
-
-Much of the 16-pass whack-a-mole re-derives by hand what an exact solver one stage
-upstream already owns:
-
-- ELK already runs **Brandes–Köpf** (correct-by-construction coordinate
-  assignment), then we override it with **6 node-moving heuristic passes**.
-  Switching to `NETWORK_SIMPLEX` placement + `nodeFlexibility: PORT_POSITION` (or
-  BK + `edgeStraightening: IMPROVE_STRAIGHTNESS`) folds **port-exactness +
-  straightness into the placement solve** — potentially retiring several passes.
-- An **exact orthogonal router** (libavoid: A\* over an orthogonal visibility
-  graph, *provably* bend-and-length-optimal per connector, object-avoiding by
-  construction — Wybrow–Marriott–Stuckey 2009) would make
-  `diagonalSegments`/`edgeThroughNode`/`unexplainedBends` zero **by construction**.
-- **Constraint solvers** (VPSC / IPSep-CoLa) guarantee non-overlap + alignment +
-  directed-flow as *hard* constraints — but only when satisfiable; over-constrained
-  systems degrade (silently, in WebCola). Net: they convert open-ended
-  geometry-repair bugs into *one* characterizable failure mode (constraint
-  infeasibility) you fuzz once.
-- **Exact ILP/SAT/SMT is disqualified** for us: NP-hard, tens of nodes, runtime
-  *nondeterministic* (one SAT layout solver's UNSAT proofs: median 4 min, max
-  23 h) — fatal to deterministic real-time. Lone exception: Tamassia
-  min-cost-flow bend-minimization is poly + deterministic but only for a *fixed*
-  embedding (a full Topology-Shape-Metrics rewrite).
-
-## Per-invariant verdict table
-
-| Invariant | Status | Mechanism |
-| --- | --- | --- |
-| Determinism | **Guaranteed by construction** | pure functions, fixed orderings, integer predicates |
-| Port-exactness | **Guaranteeable by construction** (currently optimize-and-certify) | emit endpoints from `shapePorts`/`diamondFacetPorts` + grid-snap; FIXED_POS ports |
-| Axis-alignment / no diagonals | **Guaranteed by construction** | emit only axis-aligned segments |
-| No edge-through-node / no hitch | **Optimize-and-certify** (feasible ⇒ achievable) | straighten then independent checker; on reject keep the ELK route |
-| No node overlap | **Guaranteeable by construction** | separation constraints (VPSC) — when satisfiable |
-| No-label-occlusion | **Optimize-and-certify** (NP-hard) | maximize placed; veto-and-fallback (never draw occluding) |
-| No-label-on-shared-trunk | **Optimize-and-certify** (NP-hard) | duplicate-lane construction + veto-and-fallback |
-| Min crossings / bends / area | **Provably impossible to guarantee** | NP-hard; certify "no worse than input, count = N", never "minimum" |
-
-## Prioritized roadmap
-
-1. **Minimal (recommended first):** extend duplicate-lane repair to labeled bent
-   duplicates + veto-and-fallback → flip `APL_DECOUPLE_LABELS` to default-on; add
-   the net-benefit gate to `bundleEdgePaths`. Retires problems 1 and 3, enforces
-   problem 2. Lowest risk; ships the validated decoupling win.
-2. **Robustness hardening:** exact integer predicates on snapped coordinates +
-   one independent total checker run on every output. Attacks the 1–2px fuzz class
-   at the root.
-3. **Upstream re-architecture:** ELK placement strategy + libavoid-style exact
-   router + a VPSC post-pass. Biggest payoff, biggest scope.
-
-## Honest bottom line on "100%"
-
-- **Achievable and worth driving to zero by construction + checking:**
-  determinism, port-exactness, axis-alignment, no-edge-through-node,
-  no-unexplained-bend, no-hitch, no-node-overlap (these are *conventions /
-  feasibility*).
-- **Achievable only as "certified-clean-or-explicit-fallback":**
-  no-label-occlusion, no-label-on-shared-trunk (NP-hard placement — you cannot
-  have fixed-position-AND-always-clean for every input).
-- **Provably impossible to guarantee as a minimum:** crossings, bends, area, edge
-  length (NP-hard). Saying so plainly is part of dimension-7 "trust."
-
-The path to "no fuzz-surfaced geometric violation, ever" runs through **exact
-predicates + an independent, mandatory checker + exhaustive small-scope
-verification**, with fuzzing relegated to adversarial tail-coverage — not through
-a search for a complete construction that the literature proves does not exist.
-
-## Citations
-
-**Aesthetic invariants & complexity.** Di Battista, Eades, Tamassia, Tollis,
-*Graph Drawing*, Prentice Hall 1999; Tamassia (ed.), *Handbook of Graph Drawing
-and Visualization*, CRC 2013. Garey & Johnson, "Crossing Number is NP-Complete,"
-*SIAM J. Alg. Disc. Meth.* 4(3), 1983. Eades & Wormald, "Edge crossings in
-drawings of bipartite graphs," *Algorithmica* 11, 1994. Tamassia, "On embedding a
-graph in the grid with the minimum number of bends," *SIAM J. Comput.* 16(3),
-1987. Garg & Tamassia, "On the computational complexity of upward and rectilinear
-planarity testing," *SIAM J. Comput.* 31(2), 2001. Sugiyama, Tagawa, Toda, *IEEE
-TSMC* SMC-11(2), 1981. Brandes & Köpf, "Fast and simple horizontal coordinate
-assignment," GD 2001 (LNCS 2265; erratum arXiv:2008.01252). Purchase, "Metrics for
-graph drawing aesthetics," *JVLC* 13(5), 2002.
-
-**Label placement.** Kakoulis & Tollis, "Labeling Algorithms," ch. 15 in the
-Handbook (CRC 2013); "On the Complexity of the Edge Label Placement Problem,"
-*Comput. Geom.* 18(1), 2001 (ELP NP-hard, reduction from 3-SAT); "A Unified
-Approach to Automatic Label Placement," *IJCGA* 13(1), 2003 (conflict-graph +
-bipartite matching, maximize placed). Marks & Shieber, "The Computational
-Complexity of Cartographic Label Placement," Harvard TR-05-91, 1991 (NP-complete;
-optimal ⇔ P=NP). Formann & Wagner, SoCG 1991. van Kreveld, Strijk, Wolff, "Point
-labeling with sliding labels," *Comput. Geom.* 13, 1999 (slider models, PTAS).
-Bekos, Kaufmann, Symvonis, Wolff, "Boundary Labeling," *Comput. Geom.* 36(3), 2007
-(crossing-free, all-labels, poly-time for one-/two-opposite-sided — the escape
-hatch); Kindermann et al., "Multi-Sided Boundary Labeling," *Algorithmica* 76(1),
-2016. Binucci et al., "Orthogonal drawings of graphs with vertex and edge labels,"
-*Comput. Geom.* 32(2), 2005 (ILP, no-overlap by enlarging the drawing).
-
-**Routing, ports, parallel edges.** Wybrow, Marriott, Stuckey, "Orthogonal
-Connector Routing," GD 2009 (libavoid; per-connector bend/length optimal);
-"Orthogonal Hyperedge Routing," Diagrams 2012. Spönemann et al., "Port Constraints
-in Hierarchical Layout of Data Flow Diagrams," GD 2009 (FREE/FIXED_SIDE/
-FIXED_ORDER/FIXED_POS). Rüegg et al., "Size- and Port-Aware Horizontal Node
-Coordinate Assignment," GD 2015. Gansner, Koutsofios, North, Vo, "A Technique for
-Drawing Directed Graphs," *IEEE TSE* 19(3), 1993 (edge label = virtual node).
-Holten, "Hierarchical Edge Bundles," *IEEE InfoVis* 2006; Holten & van Wijk,
-"Force-Directed Edge Bundling," *EuroVis* 2009 (bundling does not reduce
-crossings).
-
-**Constraint-based layout.** Dwyer, Koren, Marriott, "IPSep-CoLa," *IEEE TVCG*
-12(5), 2006 (hard separation constraints by gradient projection); Dwyer, Marriott,
-Stuckey, "Fast Node Overlap Removal," GD 2005 (VPSC, O(n log n)); Dwyer & Koren,
-"Dig-CoLa," InfoVis 2005; Hoffswell, Borning, Heer, "SetCoLa," EuroVis 2018
-(WebCola constraints degrade silently when infeasible).
-
-**Robustness / exactness / verification.** Kettner, Mehlhorn, Pion, Schirra, Yap,
-"Classroom examples of robustness problems in geometric computations," *Comput.
-Geom.* 40(1), 2008. Yap & Dubé, "The exact computation paradigm," 1995. Shewchuk,
-"Adaptive precision floating-point arithmetic and fast robust geometric
-predicates," *DCG* 18(3), 1997. Edelsbrunner & Mücke, "Simulation of Simplicity,"
-*ACM TOG* 9(1), 1990. Hobby, "Practical segment intersection with finite precision
-output," *Comput. Geom.* 13, 1999. Fabri & Pion, "CGAL," ACM SIGSPATIAL 2009
-(EPICK/EPECK). McConnell, Mehlhorn, Näher, Schweitzer, "Certifying algorithms,"
-*Computer Science Review* 5(2), 2011. Alkassar, Böhme, Mehlhorn, Rizkallah,
-"Verification of certifying computations," CAV 2011. Chen, Cheung, Yiu,
-"Metamorphic testing," HKUST-CS98-01, 1998. Jackson, *Software Abstractions*, MIT
-Press, 2006 (small-scope hypothesis).
-
-**Industry practice surveyed.** yFiles (integrated vs. generic labeling;
-`integratedEdgeLabeling` default false; ParallelEdgeRouter), Graphviz (`label`
-dummy-node vs. `xlabel`/`forcelabels`; `concentrate`), ELK (`LabelDummyInserter`/
-`Switcher`/`Remover`; BK vs. NETWORK_SIMPLEX placement), OGDF (ELabelInterface),
-Adaptagrams/libavoid + cola.js, tldraw (`normalizedAnchor`/`isPrecise`/elbow
-arrows), Excalidraw (`FixedPointBinding`), draw.io/mxGraph (`exitX`/`entryX` fixed
-connection points; `mxParallelEdgeLayout` spacing).
-
-## Empirical addendum — what we actually measured
-
-The roadmap above lists three theory-backed candidate fixes. We implemented and
-measured each against our own rubric (`bun run track`, corpus-wide column totals;
-the bar is **HARD must stay 0** and a soft net-improvement). **All four levers we
-could test as bounded changes were neutral-or-regressive on this corpus** — the
-current pipeline is already near a local optimum. Reference (current shipping,
-Brandes–Köpf BALANCED + the 6 node passes): **HARD 0, offCardinal 70, bends 351,
-strtDeficit 74, crossings 1** over 74 tracked diagrams.
-
-| Experiment | offCardinal | bends | strtDeficit | crossings | Verdict |
-| --- | --- | --- | --- | --- | --- |
-| **HEAD** (BK BALANCED + 6 passes) | 70 | 351 | 74 | **1** | reference |
-| Bundling net-benefit gate (bends+crossings) | — | — | — | — | wash; trades bend wins for `offCardinal`/sym regressions → reverted |
-| Flip `APL_DECOUPLE_LABELS` default | (6↑ / 23↓ vs baseline incl. **+2 crossings**) | | | | net-regressive; opt-in confirmed correct |
-| **Network-simplex** + `favorStraightEdges` | 64 | 354 | 71 | **3** | lateral: cardinal/straight ↓ but **+2 crossings** |
-| Network-simplex + `nodeFlexibility=PORT_POSITION` | 64 | 354 | 71 | 3 | **no-op** — inert against our `FIXED_SIDE` ports |
-| BK + `bk.edgeStraightening=IMPROVE_STRAIGHTNESS` | 70 | 351 | 74 | 1 | **no-op** — already BK's default |
-| Independent hard-invariant gate (corpus + fuzz) | 70 | 351 | 74 | 1 | **shipped** — additive test, zero geometry change |
-| Exact integer-snap predicate in `simplifyPolyline` | 70 | **349** | 75 | **3** | **HARD 0→1** (off circle outline) + crossings → reverted |
-
-**Conclusions.**
-
-1. **No ELK placement strategy beats the current pipeline.** Network-simplex
-   reorders enough to add crossings (1→3) on an already-near-crossing-free corpus;
-   `PORT_POSITION` flexibility is inert because our ports are `FIXED_SIDE` with an
-   explicit index. The 6 downstream node passes are doing real, near-optimal work
-   that no placement config replicates.
-2. **The decoupling default-flip and the bundling gate both regress the rubric** —
-   the band-aids the research recommended are net-negative *here*, because our
-   post-ELK passes already extract the straightness/symmetry/cardinality that
-   decoupling and naive bundling give up.
-3. **The "sandy ε foundation" hypothesis was wrong — measured.** Converting the
-   shared collinearity predicate in `simplifyPolyline` to an exact integer-snapped
-   orientation determinant (the EGC recommendation) *regressed*: it broke a hard
-   invariant (an endpoint flattened off a **circle outline**) and added crossings,
-   because a fixed 1px decision grid is a *scale-independent* predicate while the
-   existing `|cross| < EPS` is *scale-appropriate* (it only removes float-noise
-   collinearity, ~1e-4 px on long segments) — and our curved-shape endpoints carry
-   load-bearing sub-pixel precision. The scattered ε's are not actually
-   inconsistent in value (the axis test is `0.01` everywhere); the heuristic
-   "fighting" is genuine multi-objective tension (straightness vs symmetry vs
-   cardinality — NP-hard trade-offs), not predicate inconsistency. So exact
-   predicates do **not** unblock the symmetry/decoupling regressions.
-4. **The one delivered win is the independent hard-invariant gate**
-   (`property-hard-invariants.test.ts`): the rubric oracle run over the full
-   flowchart corpus + fuzz, asserting zero hard violations. It is purely additive
-   (no geometry change) and is the safety net that lets new placement/routing
-   heuristics be added aggressively — any hard-invariant regression now fails
-   loudly and immediately. The symmetry/port fix itself remains a **placement
-   heuristic on the pipeline** (as `12ba4e6` already did for fan-out D/E
-   equalization), now protected by that gate — not a foundation rewrite.
-5. **The genuine remaining structural win is still the exact-router rewrite**
-   (libavoid-style A\* over an orthogonal visibility graph) — but its upside is
-   bounded (corpus already at crossings = 1) against a multi-week, high-risk
-   rewrite, so it is a deliberate future bet, not a quick fix.
-
-**Bottom line:** the pipeline is at a well-tuned local optimum; every bounded
-"improve/exactify/re-architect" lever we measured was neutral-or-regressive. The
-durable value is (a) this map of what does and doesn't work, and (b) the independent
-gate that makes the next targeted placement heuristic safe to add.
-
-Method/scripts for reproduction live in the session scratchpad; re-run
-`bun run track` and sum the `off/bend/strt/xing` columns to reproduce the table.