Diagram Readability (v0.25.0): grid, guarded orthogonal routing, connection editing, Templates and node outlines #344

Summary

Diagrams become hard to read as they grow: connections run through nodes, labels sit on nodes and on each other, ports that should line up are a few pixels apart, and nothing snaps to the grid the canvas already draws. This umbrella issue tracks the whole Diagram Readability migration. Its six steps ship together as one release, v0.25.0, so that coordinates, routes, Templates, node outlines and the visual baselines change once rather than several times. The release notes, the change declaration and the baselines are settled once, after the last step.

Current state (main 10098d6, every Template in all 18 languages)

• The canvas draws a 16 px dot grid, but nothing snaps to it: positions are stored as floats, new nodes get a random ±40 px jitter, arrow keys move 5 / 20 px.
• Ports sit at the centre of each side, and a node's height depends on its text, so the same node's ports move between languages.
• A connection is a Bézier curve that ignores nodes unless it is switched to the orthogonal router, which avoids other nodes' boxes but not labels and not the connection's own end nodes; when it finds no path it draws a plain L / Z through whatever is in the way.
• Labels sit at the middle of their connection with no collision handling.
• Summed over the 18 languages, Early MMO (97 nodes, 144 connections) has 1,632 lines through nodes, 336 labels on nodes, 235 labels on labels and 83 near-miss jogs; its nodes overlap each other in seven long languages. The 3-zone gacha is nearly clean only because its 77 routes and 12 waypoints were tuned by hand. The three small Templates are clean apart from about one 1 px jog per language.

Measured direction

• Curves everywhere make the complex Templates worse (MMO: 2,341 lines through nodes).
• Today's router everywhere cuts lines through nodes by 76 % but leaves the labels and sends backward connections through their own end node.
• The guarded orthogonal route (labels placed in free slots, a reroute around a label kept only when it is not worse) gives, on the grid, MMO 388 lines through nodes, 17 labels on nodes, 0 labels on labels, 0 jogs; Gacha matches its hand-tuned routes without waypoints. Every line through a node that remains is a router fallback.
• It raises crossings and bends in MMO on today's layout; the Template re-placement has to bring them back.

Decisions (2026-10-09)

• Ports: the resource port row sits 28 px below the node's top whatever its height or language; the node grows downward; the drawn port is projected onto the outline, the routing lane is on the 16 px grid.
• Re-placement: an ordinary document, file or share link with an older layoutVersion is re-placed once, deterministically, when it is opened, before its history starts (not an undo entry), from a canonical geometry that does not depend on the language or on font measurement; the new layoutVersion is stored. A position chosen freely with Alt is kept. Tidy to grid re-places the current document as one undo step. Bundled Templates are re-placed and reviewed in their source.
• Records are not converted: revision and proposal payloads always keep their recorded coordinates, and a Project autosave based on a revision is not converted either. Tidy to grid on such a document changes only the current document, as one cosmetic change and one undo step; the base revision and the proposal source stay as recorded, so Review shows the real layout differences.
• Rows 8–16 px apart merge only when the nodes are directly connected by a flow or in the same logical layer, without reversing an order or creating an overlap; otherwise the next grid row.
• Default shape: the guarded orthogonal route for new and converted connections; node avoidance before label avoidance; no fallback through a node (search again with less clearance, then a safe outer detour); labels in free slots; unrelated connections pay a cost for sharing a trunk.
• Modifiers: Alt = free move for nodes, selections and frames; Ctrl / Command = move a frame only (Alt's role before); Shift = multi-selection and the large keyboard step, unchanged.
• Acceptance: node and label collisions go down and, for every Template, crossings and shared trunks are not worse than today.

Connection shapes and route editing

• Auto orthogonal (the guarded router) is the default; Curved (today's Bézier) and Straight (a direct line) are choices; Manual orthogonal keeps the author's bend points.
• Editing an automatic route by hand turns it into Manual orthogonal; Reset to automatic returns it to the router's route.
• Bend points snap to the 16 px grid, Alt moves one freely; each add, move or delete is one undo step; nothing changes a route while the canvas is locked.
• Shapes and bend points are saved in files and share links and never change the engine digest or a simulation result.
• The phone draws every route but offers no route editing.
• Bundled Templates use automatic routes, with a manual bend point only where the router cannot resolve a case.
• Out of scope for v0.25.0: editing Bézier control points, and further line decorations.

Steps (all in v0.25.0)

• Step 1: grid, fixed port row, snapping and modifiers, layoutVersion with the one-time conversion, Tidy to grid.
• Step 2: automatic orthogonal routing and label placement (own end nodes as obstacles, no node-crossing fallback, label slots, guarded label obstacles, trunk cost).
• Step 3: connection shape choice and manual route editing.
• Step 4: re-place and review all five bundled Templates, with room for each node's widest language.
• Step 5: node outline and text containment (fix(canvas): text stays inside the Pool, Source, Drain, Converter and Gate outlines at every width #337) on that base, keeping the 28 px port row.
• Step 6: an automated collision check for connections, labels and outlines over all 18 languages, then the final baselines.

Compatibility

The file gains layoutVersion. Ordinary documents are converted once on open; the conversion moves positions and connection routes; it never changes the engine digest or any simulation result. Off-grid positions remain valid input. The visual baselines are reviewed as one exact list, once, before they are updated.

Out of scope

• Automatic layout from scratch (ranking, layering): the author's arrangement is kept.
• Phone-specific layout (phone geometry is identical to desktop).