feat(library): improve automatic edge routing

[FelixTJDietrich]

Summary

Automatic edges now coordinate endpoint sides, connection points, and orthogonal paths to produce cleaner diagrams with fewer avoidable bends, overlaps, and crossings. Pinned endpoints and hand-placed bends remain authoritative, while nearby automatic edges can still rebalance around them.

The change also makes routing responsive and consistent across the product:

• the first solve and diagrams with fewer than 32 edges remain synchronous; later dense solves use a backpressured Web Worker that retains only the newest unserialized snapshot and adapts its preview cadence to observed throughput;
• drag previews project or reuse accepted geometry while the latest exact result is computed, and stale Worker results cannot replace settled geometry;
• line jumps follow the routes actually on screen, so bridge arcs stay attached to their edge during a drag and at the preview-to-settled handoff instead of floating over routes that already moved;
• replacing the model increments a routing epoch that discards any in-flight solve for the previous model, so a fresh diagram can never briefly flash the old one's routes;
• on load and on model replacement, edges stay unmounted until the first exact generation is measured, removing the brief straight-then-relayout flash;
• releasing a drag prioritizes the newest exact snapshot, then transitions from the preview to the accepted route unless reduced motion is requested;
• SVG export waits for accepted routing geometry instead of a fixed delay;
• required-interface sockets, package bounds, shared junctions, and legacy diagram imports use the same geometry contracts;
• node and edge action toolbars use the existing React Flow toolbar primitives with accessible, full-size controls;
• the five bundled design-pattern templates start from reviewed automatic layouts;
• server-side consumers can normalize diagrams through the DOM-free @tumaet/apollon/model entry.

Release note

Library: Create cleaner diagrams with automatic edges that balance connection points, reduce collisions with nodes and nearby edges, and stay responsive while you drag, without losing pinned endpoints, hand-placed bends, aligned component interfaces, or compatibility with older diagrams; embedding apps can also normalize diagrams in server-side code through the new @tumaet/apollon/model entry.

Web app: Start every bundled design-pattern template in a clean, visually balanced editing state, with stable shared hierarchy trunks and automatic routing preserved for associations.

Implementation notes

Routing is a bounded, deterministic pipeline rather than one global optimization:

Stage	Responsibility
Node-local coordination	Propose sides and balanced connection-point ordering
Joint endpoint/path search	Choose endpoint candidates and an obstacle/edge-aware orthogonal path
Route-set repair	Try bounded ordering variants for interacting edges and keep strict improvements
Rendering	Preserve manual topology, project live previews, and publish accepted geometry

Routing authority remains explicit:

• no custom anchors or points: automatic routing owns the edge;
• sourceAnchor or targetAnchor: that endpoint remains pinned while generated geometry adapts;
• non-empty points: the authored bend topology remains authoritative.

Search work is capped to protect interaction latency. If a joint search exceeds its bound, the solver retries the selected endpoint pair on a smaller graph and then uses deterministic obstacle-derived fallbacks ranked by hard crossings first. This is a deliberate degradation path, not a claim that every pathological diagram has a globally optimal route.

For dense interactive diagrams, the main thread owns one latest snapshot and the Worker owns at most one in-flight solve. Serialization is deferred to a later task and occurs only when the Worker can accept work, avoiding both an obsolete request queue and main-thread cloning on every pointer frame. Preview cadence adapts between 40 and 160 ms from measured round-trip time. Independent input, dispatch, and acceptance revisions verify that release settles the latest authored state.

The /model export has its own documentation, Node 22 smoke test, complete runtime-graph check, declaration isolation check, and 8 kB size budget. Its current normalization chunk is 4.73 kB compressed and does not pull React or XYFlow into server code.

Bundle budgets pass, but the main entry and routing Worker are intentionally close to their limits: 116.97/118 kB and 38.38/40 kB respectively. The export entry is 413.41/700 kB.

Steps for testing

1. Create several automatic edges on one node side and confirm their connection points spread into balanced gaps.
2. Pin one endpoint, then move its node and nearby nodes; the pin should stay fixed while the generated route adapts.
3. Add and drag a manual bend; its topology should remain authoritative without a jump on release.
4. Exercise a diagram with at least 32 edges and drag continuously; incident edges should follow immediately, other routes should update during the gesture, and the newest exact route should settle after release.
5. Repeat the dense drag with reduced motion enabled; the accepted route should appear without a settlement animation.
6. Open component, deployment, and package diagrams; verify interface sockets and package connections meet the visible shapes correctly.
7. Import representative v3 and early-v4 diagrams, create each bundled design-pattern template, and export a diagram as SVG.
8. In Node, import importDiagram from @tumaet/apollon/model and normalize a saved model without browser globals.

Validation completed on 60bfaf92:

• pnpm lint && pnpm format:check && pnpm build && pnpm test
• library tests: 1,724 passed, 1 skipped
• production-built edge-routing performance suite: Chromium 4/4 and Firefox 4/4
• repeated continuous-drag freshness run: Chromium 3/3
• focused Worker and execution-equivalence tests: 25/25
• pnpm knip
• pnpm dlx publint from library/
• pnpm --filter @tumaet/apollon size
• node scripts/check-model-entry.mjs
• node scripts/check-doc-snippets.mjs (39 checked examples)

Screenshots / screencasts

Flowchart routing:

Component routing with required-interface sockets:

Bridge template:

Checklist

• Linked to a related issue — not applicable; no issue was identified
• Added user-voice changesets for the library and web app
• PR title's feat type matches the primary user-visible change
• Tests added or updated
• Ran pnpm lint && pnpm format:check && pnpm build && pnpm test locally — green
• Documentation updated
• Screenshots attached

[Claudia-Anthropica]

@FelixTJDietrich The original cache and bundle feedback remains resolved, and the focused routing tests, library build, and size gates all pass. However, the replacement connection preview regresses the exact native target-handle handoff for non-central handles, so straight-hook edges can still jump on commit; I reopened the existing thread with details.

[Claudia-Anthropica]

@FelixTJDietrich The exact native handle is now preserved, but the new native-target gate also claims invalid target candidates and breaks the continuous use-case fallback. The required E2E fails deterministically on both attempts because the committed endpoint is 8.54 px from the snap circle, so native handoff needs validity/connectability gating before this is ready.

[Claudia-Anthropica]

@FelixTJDietrich All previous feedback is addressed, and the focused use-case preview/commit plus package geometry regressions pass locally. Nice work.

[Claudia-Anthropica]

@FelixTJDietrich All previous feedback remains addressed, and the shared toolbar follow-up builds cleanly with all seven focused interaction tests passing. Nice work.

[Claudia-Anthropica]

@FelixTJDietrich All previous feedback remains addressed, and the focused worker execution, DOM-free model entry, size gates, and reduced-motion release regression pass on this head. Nice work.

[Claudia-Anthropica]

@FelixTJDietrich All previous feedback remains addressed, and the focused routing-generation store suites pass on the first-exact-generation follow-up. Nice work.

[Claudia-Anthropica]

@FelixTJDietrich All previous feedback remains addressed, and the three cleanup/fix commits leave those invariants intact with green CI. Nice work.

[Claudia-Anthropica]

@FelixTJDietrich All previous feedback remains addressed, and the focused tag-picker test passes with the restored paint and tag trigger tooltips. Nice work.

[Claudia-Anthropica]

@FelixTJDietrich All previous feedback remains addressed, and the Worker-settlement E2E passes with the gentler polling. The remaining Node 22 failure is an unrelated 504 while downloading libvips. Nice work.