feat: grid-aligned connection handles that scale with node size and zoom

[FelixTJDietrich]

Summary

When a node grows, five connection points per side stops being enough, and the old points sat in a cosmetic 20–80 % band rather than at the places people aim for. This PR reworks node connection handles so the available connection points scale with the node and the zoom level, and so the centre and true corners of every side are always easy to hit.

It replaces the legacy fixed 9-slot / staged-arc model with a single, pure anchor model: every endpoint is stored as a compact side:ratio value (e.g. r:0.500), and all connection geometry — the visible handles, drop/reconnect snapping, the drag-time grid overlay — is derived from that one source of truth. The change is a net ~1,600 lines deleted while adding a small, well-tested lib/nodes/handles/ module.

What you get as a user:

• More points that scale with size — each side always offers its centre and corners; long sides also get quarter points.
• A magnetic grid while connecting — drag a connection toward a node and a 5 px grid appears on the targeted side, snapping the endpoint exactly onto the canvas grid. Density adapts to zoom (finest 5 px when zoomed in, coarser when zoomed out) so points never overlap.
• Centre & corners first — snapping prioritises centre > corner > quarter > grid, so the obvious targets are the easiest to land on.
• Existing diagrams keep working — saved v2/v3/v4 diagrams are migrated automatically on import; no edge is ever dropped.

Release note

Connecting edges is now easier and more precise: every node side offers its centre and corners (plus quarter points on longer sides), the available points scale with node size and zoom, and a magnetic grid appears while you drag a connection so you can snap an edge exactly onto the canvas grid. Existing diagrams keep all their connections.

Implementation notes

New module — library/lib/nodes/handles/

• anchorModel.ts — pure, no React/DOM. Owns the side:ratio encoding, key-handle sets (keyHandlesForSide), grid quantization (quantizeRatio), the zoom level-of-detail (effectiveStepPx, visibleKeyRatios, snap radius), and snapToAnchor (priority centre > corner > quarter > grid). Drives canvas, snapping, ghost overlay, and any headless export from one place.
• nodeHandleConfig.ts — per-node-type config (key / center / none, ellipse shape, excludeCorners) keyed by node-type string. Used by both rendering and drop resolution, so they can't drift apart. This also generalises the existing NSEW restriction for circles/diamonds/interfaces.
• ConnectHandles.tsx — renders the (≤ 5/side) visible key handles plus visibility:hidden "addressable anchor" handles for any saved edge that references a non-key ratio. This is the safety net: React Flow resolves an edge endpoint from a measured DOM handle, so every persisted anchor must have one — otherwise the edge silently disappears.
• GridGhostLayer.tsx — the magnetic grid + snap dot shown during a drag (useConnection + ViewportPortal), mounted once in App.tsx.
• migrateLegacyHandle.ts — maps every legacy named handle to a side:ratio anchor; chained into EdgeTransformer, the single import chokepoint for all diagram versions.

Design decisions (and trade-offs)

• Kept DOM-backed handles + React Flow's native reconnect, rather than moving to floating edges. Verified against @xyflow/system: getEdgePosition resolves endpoints from measured DOM handles, so floating edges would mean rewriting all 13 edge types and replacing native reconnect — a separate, larger project. Deferred deliberately.
• 3-decimal ratios (not 2). A 2-decimal ratio drifts up to a full 5 px grid cell on nodes wider than ~200 px (common class boxes) and makes re-saves non-idempotent; 3 decimals round-trip exactly to ~5,000 px. There's a regression test pinning this.
• True corners (0/1) replace the old 20 %/80 % band — this is the "easy to hit the corner" ask, and it means corner-anchored edges shift slightly outward (see the heads-up below).

Server image export. Headless SVG/PNG/PDF export seeds React Flow's handle bounds from node.handles (jsdom can't measure the DOM). The server hard-coded those with the old id scheme, so once edges migrated to side:ratio anchors the exported edges (and their labels) dropped. The server now builds its render handles from the library's anchor model via a new buildServerRenderHandles export — one handle per anchor each edge references — so the export matches the canvas. This is covered by the existing server svg-export integration suite (caught the regression; now green) and a new unit test, and ships with its own @tumaet/server changeset.

Loading a model into the editor. Loading a saved diagram straight into the editor (new ApollonEditor({ model }), editor.model = …, or the standalone /local page) bypassed importDiagram, so its edges kept legacy handle ids while nodes now render side:ratio anchors — React Flow then dropped the edges. Migration now runs in the store's bulk-ingestion path (normalizeEdgeForStore, used by setNodesAndEdges), so every load path keeps its edges. Verified by a new store unit test; this was the cause of the initial e2e failures.

Self-review: I ran an adversarial review of the implementation and fixed one real bug it surfaced (the 5 px round-trip drift above) plus two minor parse/centre edge cases, then locked them with tests.

Important

Visual-regression baselines must be refreshed in this PR. Because corner anchors moved from the old 20 %/80 % band to the true corners, edge endpoints shift slightly across all diagram types and templates. Per the per-PR baseline policy, the rendering PR refreshes its own baselines — I could not regenerate them in my environment (it needs the Playwright Docker image), so this is the main outstanding task before merge.

Steps for testing

Library unit + build (all green locally):

cd library
pnpm exec vitest run     # 1020 passing
pnpm run build
pnpm run lint            # 0 errors

In the editor:

1. Add a class node and widen it — confirm the top/bottom sides show corners, centre and quarter points; left/right show corners + centre.
2. Zoom out — connection points thin out from quarters → corners → centre so they never overlap; the centre always stays. Zoom back in to get them back.
3. Start dragging a connection toward a node — a 5 px magnetic grid appears on the nearest side with a snap dot; release to drop the edge exactly on a grid point.
4. Connect to the centre and to a corner of a side — both should be effortless targets.
5. Open an existing/older diagram (v2/v3/v4) — every edge still connects; nothing is dropped.
6. Circles / diamonds / interfaces (BPMN events, flowchart decision, activity initial/final, Petri net) still connect only at side centres.

Screenshots / screencasts

Connection points scale with node size — every side always offers its centre and corners; longer sides also gain quarter points.

Zoom-aware level of detail — zooming out thins points (quarters → corners → centre) so they never overlap; the centre always stays.

Magnetic grid while connecting — dragging a connection reveals the 5px grid on the targeted side and snaps the edge onto it.

Note

These are figures rendered from the actual anchor-model geometry (keyHandlesForSide, visibleKeyRatios, effectiveStepPx, anchorPoint) — so handle counts, positions and zoom thinning are exactly what the code produces — styled to match the editor (each node corner is a single handle). They are not live app captures; an interactive screencast can still be added by a maintainer running the editor locally.

Checklist

• Linked to a related issue — no open tracking issue exists; this supersedes the connection-handle model introduced in feat(edges): better step bending, waypoint drag, and React Flow reconnection #710 and preserves the behaviours from the (already-closed) fix: restrict component interface connectors to NSEW #597 (NSEW restriction) and Connectors connecting interface and components should have straight line when possible #278 (straight lines).
• Added a changeset whose summary is written in the user's voice
• PR title's Conventional Commit type (feat) matches the kind of change
• Tests added or updated — new anchorModel + migrateLegacyHandle unit suites, updated edgeUtils/EdgeTransformer/legacyIosMigration, new node-anchor-resolution e2e
• Documentation updated — n/a (no dedicated docs page for connection handles)
• Screenshots / figures attached (rendered from the real anchor-model geometry; live screencast optional, see note)

Note

The standalone Playwright e2e specs could not be executed in my environment; they are included and will run in CI. Local verification was via the library's unit suite (1020 tests), tsc, build, and lint.

---

Note

Heads-up — one unrelated commit. lint-and-format-check was already failing on main: two communication-edge-label files from #645 (EdgeMultipleLabels.tsx, messageLayout.test.ts) landed mis-formatted. Since that check blocks CI here, this PR includes a separate style: commit that reformats them (line-wrapping only, no behaviour change). Happy to split it out if you'd prefer it as its own PR.