@peter.prib/renderengine 0.2.6 → 0.2.10

package/src/charting/diagrams/EdgeGeometry.js

@@ -1,553 +1,578 @@
-import { NodeGeometry } from './NodeGeometry.js';
-
-const SIDE_VECTORS = { top: [0, -1], right: [1, 0], bottom: [0, 1], left: [-1, 0] };
-
-/**
- * EdgeGeometry — pure, stateless helpers for graph edge anchors, routing,
- * waypoints, and path generation.
- *
- * These used to live on RenderEngine; they are collected here so diagram
- * classes can compute edge geometry without going through the engine façade.
- */
-export class EdgeGeometry {
-    /** Pure. The point (and outward unit normal) where an edge attaches to a
-     *  node's bounding box for a given `side`: 'top'/'right'/'bottom'/'left'
-     *  pins the anchor to a fixed spot on the node — it stays there as the
-     *  node moves, instead of sliding around the node to keep facing whatever
-     *  it's connected to. `'auto'` (default) keeps that older sliding
-     *  behavior, using `ux,uy` (a unit vector already pointing at the other
-     *  endpoint) as the direction to project out to the node's edge.
-     *
-     *  `rectBoundary` (true for `shape:'rect'`/`'table'`, false otherwise —
-     *  see computeEdgePath's callers) picks WHICH boundary 'auto' projects
-     *  onto: for a circle/person node (always drawn as a true circle, square
-     *  bounding box or not) a fixed-radius circle is exactly its visible
-     *  edge, but for a rect/table node that same circle radius (using the
-     *  LARGER of w/h) massively overshoots a box that's wide but short —
-     *  visually "the line stops in empty space well outside the rectangle"
-     *  instead of touching it. `rectBoundary` instead finds where the ray
-     *  from centre exits the actual w x h box (whichever of the top/bottom
-     *  or left/right edges it reaches first). */
-    static edgeAnchor(pos, size, side, ux, uy, rectBoundary, shapeType = null) {
-        const hw = size.w / 2, hh = size.h / 2;
-        switch (side) {
-            case 'top': return { x: pos.x, y: pos.y - hh, nx: 0, ny: -1 };
-            case 'bottom': return { x: pos.x, y: pos.y + hh, nx: 0, ny: 1 };
-            case 'left': return { x: pos.x - hw, y: pos.y, nx: -1, ny: 0 };
-            case 'right': return { x: pos.x + hw, y: pos.y, nx: 1, ny: 0 };
-            default: {
-                if (rectBoundary) {
-                    const tx = ux !== 0 ? hw / Math.abs(ux) : Infinity;
-                    const ty = uy !== 0 ? hh / Math.abs(uy) : Infinity;
-                    const t = Math.min(tx, ty);
-                    const safeT = Number.isFinite(t) ? t : 0;
-                    return { x: pos.x + ux * safeT, y: pos.y + uy * safeT, nx: ux, ny: uy };
-                }
-                // Diamond-specific anchoring: find intersection with actual diamond edges
-                if (shapeType === 'diamond') {
-                    const t = EdgeGeometry._diamondBoundaryT(ux, uy, hw, hh);
-                    return { x: pos.x + ux * t, y: pos.y + uy * t, nx: ux, ny: uy };
-                }
-                // Default circle-based anchoring for other shapes
-                const r = Math.max(size.w, size.h) / 2;
-                return { x: pos.x + ux * r, y: pos.y + uy * r, nx: ux, ny: uy };
-            }
-        }
-    }
-
-    /** Pure. Given a unit direction vector (ux, uy) and diamond half-dimensions (hw, hh),
-     *  find the distance t such that (t*ux, t*uy) intersects the diamond's perimeter.
-     *  Diamond vertices are at (±hw, 0) and (0, ±hh), with perimeter equation |x|/hw + |y|/hh = 1.
-     *  For a ray at (t*ux, t*uy): t*(|ux|/hw + |uy|/hh) = 1  =>  t = 1 / (|ux|/hw + |uy|/hh) */
-    static _diamondBoundaryT(ux, uy, hw, hh) {
-        const absUx = Math.abs(ux), absUy = Math.abs(uy);
-        if (absUx === 0 && absUy === 0) return 0; // Coincident nodes
-        const denom = (absUx / hw) + (absUy / hh);
-        return denom > 0 ? 1 / denom : Math.max(hw, hh);
-    }
-
-    /** Pure. Anchor for one end of an edge. A node that knows its own outline
-     *  supplies `info.boundaryPoint(dx, dy) → {x, y}` (DiagramEditor templates
-     *  do, rotation included), and the anchor is where the ray toward the other
-     *  end — or out of the pinned side — meets it. Otherwise falls back to the
-     *  shape-class model in edgeAnchor. */
-    static nodeAnchor(info, pos, size, side, ux, uy, rectBoundary) {
-        if (typeof info?.boundaryPoint !== 'function') {
-            return EdgeGeometry.edgeAnchor(pos, size, side, ux, uy, rectBoundary, info?.shape);
-        }
-        const [nx, ny] = SIDE_VECTORS[side] ?? [ux, uy];
-        const p = info.boundaryPoint(nx, ny);
-        return { x: p.x, y: p.y, nx, ny };
-    }
-
-    /** Pure. The side of a `size.w × size.h` node at `pos` that faces
-     *  `toward`, comparing offsets relative to the node's proportions so a wide
-     *  box prefers its long sides. */
-    static facingSide(pos, size, toward) {
-        const dx = toward.x - pos.x, dy = toward.y - pos.y;
-        if (Math.abs(dx) / (size.w || 1) >= Math.abs(dy) / (size.h || 1)) return dx >= 0 ? 'right' : 'left';
-        return dy >= 0 ? 'bottom' : 'top';
-    }
-
-    /** Pure. Unit directions in which a path arrives at each end, pointing
-     *  into the node: `start` runs from the path's next point toward its first
-     *  point, `end` from the previous point toward its last. Works for every
-     *  path computeEdgePath emits (absolute M/L/C): the neighbouring coordinate
-     *  pair is the adjacent vertex or bezier control point, both tangent to
-     *  the end. Coincident points are skipped; {x:0,y:0} if all coincide. */
-    static endDirections(d) {
-        const nums = (d || '').match(/-?\d*\.?\d+(?:e[-+]?\d+)?/gi)?.map(Number) ?? [];
-        const pts = [];
-        for (let i = 0; i + 1 < nums.length; i += 2) pts.push({ x: nums[i], y: nums[i + 1] });
-        const toward = (tip, others) => {
-            for (const p of others) {
-                const dx = tip.x - p.x, dy = tip.y - p.y, len = Math.hypot(dx, dy);
-                if (len > 1e-9) return { x: dx / len, y: dy / len };
-            }
-            return { x: 0, y: 0 };
-        };
-        if (!pts.length) return { start: { x: 0, y: 0 }, end: { x: 0, y: 0 } };
-        return {
-            start: toward(pts[0], pts.slice(1)),
-            end: toward(pts[pts.length - 1], pts.slice(0, -1).reverse()),
-        };
-    }
-
-    /** Pure. 'h' when `side` pins the anchor to a vertical edge of the node's
-     *  box (left/right — the line touches it moving horizontally), 'v' for
-     *  top/bottom, null for 'auto' (no fixed orientation to route around). */
-    static edgeSideOrientation(side) {
-        if (side === 'left' || side === 'right') return 'h';
-        if (side === 'top' || side === 'bottom') return 'v';
-        return null;
-    }
-
-    /** Pure. Cubic-bezier path between two pinned/auto anchors, leaving and
-     *  arriving along each anchor's own normal (`nx,ny`) so a pinned side
-     *  produces a visibly perpendicular exit/entry instead of a straight
-     *  dog-leg. The generalized shape of the table-link curve in
-     *  computeEdgePath, usable for any node pair. */
-    static curvedEdgePath(a1, a2) {
-        const dist = Math.hypot(a2.x - a1.x, a2.y - a1.y) || 1;
-        const k = Math.min(dist * 0.5, 80);
-        const c1x = a1.x + a1.nx * k, c1y = a1.y + a1.ny * k;
-        const c2x = a2.x + a2.nx * k, c2y = a2.y + a2.ny * k;
-        return { x1: a1.x, y1: a1.y, x2: a2.x, y2: a2.y, d: `M${a1.x},${a1.y} C${c1x},${c1y} ${c2x},${c2y} ${a2.x},${a2.y}` };
-    }
-
-    /** Pure. Right-angle (Manhattan) path between two anchors. When a side is
-     *  pinned, the segment touching that anchor is forced to the matching
-     *  orientation (horizontal for left/right, vertical for top/bottom); with
-     *  both anchors 'auto' it just bends along whichever axis has the bigger
-     *  gap. Mixed orientations (e.g. source pinned right, target pinned top)
-     *  get a single-corner elbow instead of the usual midpoint jog, since a
-     *  midpoint jog can't satisfy two different orientations at once.
-     *
-     *  With `obstacles` (array of {x,y,r} nodes), routes around blocking obstacles
-     *  using axis-aligned detour lanes. No avoidance for mixed-orientation elbows;
-     *  those are rare and have degenerate geometry. */
-    static orthogonalEdgePath(a1, a2, sourceSide, targetSide, obstacles = []) {
-        const so = EdgeGeometry.edgeSideOrientation(sourceSide);
-        const to = EdgeGeometry.edgeSideOrientation(targetSide);
-        let d;
-        if (so && to && so !== to) {
-            const corner = so === 'h' ? { x: a2.x, y: a1.y } : { x: a1.x, y: a2.y };
-            d = `M${a1.x},${a1.y} L${corner.x},${corner.y} L${a2.x},${a2.y}`;
-        } else {
-            const horizontalFirst = so ? so === 'h' : (to ? to === 'h' : Math.abs(a2.x - a1.x) >= Math.abs(a2.y - a1.y));
-            const blocking = EdgeGeometry.findBlockingObstacles(a1, a2, obstacles);
-
-            if (blocking.length === 0) {
-                // No obstacles — use the plain midpoint jog
-                if (horizontalFirst) {
-                    const midX = (a1.x + a2.x) / 2;
-                    d = `M${a1.x},${a1.y} L${midX},${a1.y} L${midX},${a2.y} L${a2.x},${a2.y}`;
-                } else {
-                    const midY = (a1.y + a2.y) / 2;
-                    d = `M${a1.x},${a1.y} L${a1.x},${midY} L${a2.x},${midY} L${a2.x},${a2.y}`;
-                }
-            } else {
-                // Route around the obstacle cluster with a detour lane
-                const bounds = EdgeGeometry.obstacleClusterBounds(blocking);
-                if (horizontalFirst) {
-                    const naturalY = (a1.y + a2.y) / 2;
-                    const routeY = naturalY < bounds.minY ? bounds.minY - 12 : bounds.maxY + 12;
-                    d = `M${a1.x},${a1.y} L${a1.x},${routeY} L${a2.x},${routeY} L${a2.x},${a2.y}`;
-                } else {
-                    const naturalX = (a1.x + a2.x) / 2;
-                    const routeX = naturalX < bounds.minX ? bounds.minX - 12 : bounds.maxX + 12;
-                    d = `M${a1.x},${a1.y} L${routeX},${a1.y} L${routeX},${a2.y} L${a2.x},${a2.y}`;
-                }
-            }
-        }
-        return { x1: a1.x, y1: a1.y, x2: a2.x, y2: a2.y, d };
-    }
-
-    /** Pure. True if the segment a1->a2 passes within `circle.r` of `circle`'s
-     *  centre (see pointToSegmentDist2 for the underlying clamped-distance math). */
-    static segmentIntersectsCircle(a1, a2, circle) {
-        return EdgeGeometry.pointToSegmentDist2(a1, a2, circle.x, circle.y) < circle.r * circle.r;
-    }
-
-    /** Pure. Find all obstacles that block the direct line from a1 to a2.
-     *  Returns array of blocking obstacles, sorted by their position along the line. */
-    static findBlockingObstacles(a1, a2, obstacles = []) {
-        return obstacles
-            .filter(o => EdgeGeometry.segmentIntersectsCircle(a1, a2, o))
-            .sort((o1, o2) => {
-                const dx = a2.x - a1.x, dy = a2.y - a1.y;
-                const len2 = dx * dx + dy * dy;
-                const t1 = ((o1.x - a1.x) * dx + (o1.y - a1.y) * dy) / len2;
-                const t2 = ((o2.x - a1.x) * dx + (o2.y - a1.y) * dy) / len2;
-                return t1 - t2;
-            });
-    }
-
-    /** Pure. Compute bounding box around a cluster of obstacles with clearance margin. */
-    static obstacleClusterBounds(obstacles, margin = 12) {
-        let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
-        for (const o of obstacles) {
-            minX = Math.min(minX, o.x - o.r - margin);
-            minY = Math.min(minY, o.y - o.r - margin);
-            maxX = Math.max(maxX, o.x + o.r + margin);
-            maxY = Math.max(maxY, o.y + o.r + margin);
-        }
-        return { minX, minY, maxX, maxY };
-    }
-
-    /** Pure. Route around a cluster of obstacles by computing two waypoints (above/below or left/right).
-     *  Returns array of waypoints to thread between source and target anchors. */
-    static routeAroundCluster(a1, a2, obstacles) {
-        const bounds = EdgeGeometry.obstacleClusterBounds(obstacles);
-        const dx = a2.x - a1.x, dy = a2.y - a1.y;
-        const isHorizontal = Math.abs(dx) >= Math.abs(dy);
-
-        // Choose routing direction: if more horizontal, route above/below; else left/right
-        if (isHorizontal) {
-            // Route vertically around the cluster
-            const side = a1.y < bounds.minY ? -1 : 1; // above if source is above, else below
-            const routeY = side > 0 ? bounds.maxY : bounds.minY;
-            const midX = (bounds.minX + bounds.maxX) / 2;
-            return [
-                { x: midX, y: a1.y },      // move horizontally to cluster's horizontal center
-                { x: midX, y: routeY },    // move vertically around cluster
-            ];
-        } else {
-            // Route horizontally around the cluster
-            const side = a1.x < bounds.minX ? -1 : 1; // left if source is left, else right
-            const routeX = side > 0 ? bounds.maxX : bounds.minX;
-            const midY = (bounds.minY + bounds.maxY) / 2;
-            return [
-                { x: a1.x, y: midY },      // move vertically to cluster's vertical center
-                { x: routeX, y: midY },    // move horizontally around cluster
-            ];
-        }
-    }
-
-    /** Pure. Straight line between two anchors, unless `obstacles` (other
-     *  nodes as {x,y,r}, source/target already excluded by the caller) puts
-     *  one in the way. Routes around single obstacles with a perpendicular
-     *  waypoint; routes around clusters by threading around the bounding box.
-     *  Degrades to a plain straight line on an uncrowded graph.
-     *
-     *  Note: This is 'polyline' routing only. 'curved' and 'orthogonal' modes
-     *  currently do not have obstacle avoidance — they route directly regardless
-     *  of obstacles. A caller needing avoidance on those modes should either:
-     *  1. Switch to 'polyline' routing, or
-     *  2. Manually add waypoints (edge.waypoints) to the edge data. */
-    static polylineEdgePath(a1, a2, obstacles = []) {
-        const blocking = EdgeGeometry.findBlockingObstacles(a1, a2, obstacles);
-        if (blocking.length === 0) {
-            return { x1: a1.x, y1: a1.y, x2: a2.x, y2: a2.y, d: `M${a1.x},${a1.y} L${a2.x},${a2.y}` };
-        }
-
-        let waypoints;
-        if (blocking.length === 1) {
-            // Single obstacle: use perpendicular offset (original behavior)
-            const o = blocking[0];
-            const dx = a2.x - a1.x, dy = a2.y - a1.y;
-            const len = Math.hypot(dx, dy) || 1;
-            const px = -dy / len, py = dx / len;
-            const len2 = len * len;
-            const t = ((o.x - a1.x) * dx + (o.y - a1.y) * dy) / len2;
-            const footX = a1.x + dx * t, footY = a1.y + dy * t;
-            const cross = dx * (o.y - a1.y) - dy * (o.x - a1.x);
-            const side = cross >= 0 ? -1 : 1;
-            const clearance = o.r + 12;
-            waypoints = [{ x: footX + px * clearance * side, y: footY + py * clearance * side }];
-        } else {
-            // Multiple obstacles: route around the cluster
-            waypoints = EdgeGeometry.routeAroundCluster(a1, a2, blocking);
-        }
-
-        const points = [a1, ...waypoints, a2];
-        const d = points.map((pt, i) => `${i === 0 ? 'M' : 'L'}${pt.x},${pt.y}`).join(' ');
-        return { x1: a1.x, y1: a1.y, x2: a2.x, y2: a2.y, d };
-    }
-
-    /** Pure. Given `points` (an ordered polyline — anchor, any existing
-     *  waypoints, anchor), finds which SEGMENT a click at `(x,y)` landed
-     *  closest to and returns that segment's starting index. Since
-     *  `points[0]` is the source anchor (not a stored waypoint), segment `i`
-     *  is exactly where a new `edge.waypoints[i]` belongs (`Array.splice(i, 0,
-     *  point)`) — see the double-click-to-add-a-bend handler in
-     *  RenderEngine's drag listeners. */
-    static nearestSegmentInsertIndex(points, x, y) {
-        let bestIdx = 0, bestDist2 = Infinity;
-        for (let i = 0; i < points.length - 1; i++) {
-            const dist2 = EdgeGeometry.pointToSegmentDist2(points[i], points[i + 1], x, y);
-            if (dist2 < bestDist2) { bestDist2 = dist2; bestIdx = i; }
-        }
-        return bestIdx;
-    }
-
-    /** Pure. Detect if two line segments intersect. Returns intersection point if they do, null otherwise.
-     *  Used for edge-crossing visualization. */
-    static lineSegmentIntersection(p1, p2, p3, p4) {
-        const x1 = p1.x, y1 = p1.y, x2 = p2.x, y2 = p2.y;
-        const x3 = p3.x, y3 = p3.y, x4 = p4.x, y4 = p4.y;
-
-        const denom = (x1 - x2) * (y3 - y4) - (y1 - y2) * (x3 - x4);
-        if (Math.abs(denom) < 1e-10) return null; // parallel or coincident
-
-        const t = ((x1 - x3) * (y3 - y4) - (y1 - y3) * (x3 - x4)) / denom;
-        const u = -((x1 - x2) * (y1 - y3) - (y1 - y2) * (x1 - x3)) / denom;
-
-        if (t > 0 && t < 1 && u > 0 && u < 1) {
-            return { x: x1 + t * (x2 - x1), y: y1 + t * (y2 - y1) };
-        }
-        return null;
-    }
-
-    /** Pure. Find all crossing points between a given edge path and an array of other edge paths.
-     *  Returns array of {x, y, angle} crossing points. */
-    static findEdgeCrossings(edgePath, otherEdgePaths) {
-        const crossings = [];
-        const points = EdgeGeometry.pathToPoints(edgePath);
-
-        for (const otherPath of otherEdgePaths) {
-            const otherPoints = EdgeGeometry.pathToPoints(otherPath);
-            for (let i = 0; i < points.length - 1; i++) {
-                for (let j = 0; j < otherPoints.length - 1; j++) {
-                    const intersection = EdgeGeometry.lineSegmentIntersection(
-                        points[i], points[i + 1],
-                        otherPoints[j], otherPoints[j + 1]
-                    );
-                    if (intersection) {
-                        const angle = Math.atan2(
-                            points[i + 1].y - points[i].y,
-                            points[i + 1].x - points[i].x
-                        );
-                        crossings.push({ ...intersection, angle });
-                    }
-                }
-            }
-        }
-        return crossings;
-    }
-
-    /** Pure. Convert SVG path string to array of points (samples bezier curves).
-     *  Used for edge-crossing detection. */
-    static pathToPoints(pathStr) {
-        const points = [];
-        const tokens = pathStr.match(/[MmLlCc]|[+-]?[\d.]+/g) || [];
-        let current = { x: 0, y: 0 };
-        let i = 0;
-
-        while (i < tokens.length) {
-            const cmd = tokens[i];
-            if (cmd === 'M' || cmd === 'm') {
-                i++;
-                const x = Number(tokens[i++]), y = Number(tokens[i++]);
-                current = cmd === 'M' ? { x, y } : { x: current.x + x, y: current.y + y };
-                points.push({ ...current });
-            } else if (cmd === 'L' || cmd === 'l') {
-                i++;
-                const x = Number(tokens[i++]), y = Number(tokens[i++]);
-                current = cmd === 'L' ? { x, y } : { x: current.x + x, y: current.y + y };
-                points.push({ ...current });
-            } else if (cmd === 'C' || cmd === 'c') {
-                i++;
-                const coords = [];
-                while (i < tokens.length && !/[MmLlCc]/.test(tokens[i])) {
-                    coords.push(Number(tokens[i++]));
-                }
-                const p0 = current;
-                const p1 = cmd === 'C' ? { x: coords[0], y: coords[1] } : { x: current.x + coords[0], y: current.y + coords[1] };
-                const p2 = cmd === 'C' ? { x: coords[2], y: coords[3] } : { x: current.x + coords[2], y: current.y + coords[3] };
-                const p3 = cmd === 'C' ? { x: coords[4], y: coords[5] } : { x: current.x + coords[4], y: current.y + coords[5] };
-
-                for (let s = 1; s <= 8; s++) {
-                    const t = s / 8;
-                    const mt = 1 - t;
-                    const pt = {
-                        x: mt * mt * mt * p0.x + 3 * mt * mt * t * p1.x + 3 * mt * t * t * p2.x + t * t * t * p3.x,
-                        y: mt * mt * mt * p0.y + 3 * mt * mt * t * p1.y + 3 * mt * t * t * p2.y + t * t * t * p3.y,
-                    };
-                    points.push(pt);
-                }
-                current = p3;
-            } else {
-                i++;
-            }
-        }
-        return points;
-    }
-
-    /** Pure. Returns a NEW `edge.waypoints` array with one more point added
-     *  at `point`, landing in the segment nearest it along the current route
-     *  sourcePos -> ...edge.waypoints -> targetPos (see nearestSegmentInsertIndex).
-     *  Used by the edge context menu's "Add Waypoint Here" — hand-routing used
-     *  to be reachable by double-clicking the edge line itself, but that
-     *  gesture now opens `onEdgeDoubleClick`'s properties dialog instead, so
-     *  adding a bend point moved to the context menu. */
-    static edgeWaypointsWithInsertion(edge, sourcePos, targetPos, point) {
-        const points = [sourcePos, ...(edge.waypoints || []), targetPos];
-        const insertIdx = EdgeGeometry.nearestSegmentInsertIndex(points, point.x, point.y);
-        const waypoints = edge.waypoints ? [...edge.waypoints] : [];
-        waypoints.splice(insertIdx, 0, { x: point.x, y: point.y });
-        return waypoints;
-    }
-
-    /** Pure. Squared distance from `(x,y)` to the closest point on segment
-     *  a->b (clamped to the segment, not the infinite line) — shared by
-     *  segmentIntersectsCircle's threshold test and nearestSegmentInsertIndex's
-     *  plain distance comparison. */
-    static pointToSegmentDist2(a, b, x, y) {
-        const dx = b.x - a.x, dy = b.y - a.y;
-        const len2 = dx * dx + dy * dy || 1;
-        let t = ((x - a.x) * dx + (y - a.y) * dy) / len2;
-        t = Math.max(0, Math.min(1, t));
-        const cx = a.x + dx * t, cy = a.y + dy * t;
-        return (x - cx) * (x - cx) + (y - cy) * (y - cy);
-    }
-
-    /** Pure. Approximate squared distance from `(x,y)` to the polyline or
-     *  cubic-bezier path described by an SVG `d` attribute. Straight, polyline,
-     *  orthogonal and waypoint paths are checked exactly segment-by-segment;
-     *  cubic beziers are sampled into short line segments so the result is
-     *  accurate enough for a generous hit-test tolerance without parsing
-     *  arbitrary SVG path syntax. */
-    static pathDistance2(d, x, y) {
-        const tokens = (d || '').match(/[MmLlCc]|-?\d+(?:\.\d+)?/g) || [];
-        let min = Infinity, current = { x: 0, y: 0 };
-        let i = 0;
-        while (i < tokens.length) {
-            const cmd = tokens[i];
-            if (/[MmLl]/.test(cmd)) {
-                i++;
-                while (i < tokens.length && !/[MmLlCc]/.test(tokens[i])) {
-                    const px = Number(tokens[i]), py = Number(tokens[i + 1]);
-                    if (Number.isFinite(px) && Number.isFinite(py)) {
-                        if (cmd === 'M' || cmd === 'L') {
-                            min = Math.min(min, EdgeGeometry.pointToSegmentDist2(current, { x: px, y: py }, x, y));
-                            current = { x: px, y: py };
-                        } else if (cmd === 'm' || cmd === 'l') {
-                            min = Math.min(min, EdgeGeometry.pointToSegmentDist2(current, { x: current.x + px, y: current.y + py }, x, y));
-                            current = { x: current.x + px, y: current.y + py };
-                        }
-                    }
-                    i += 2;
-                }
-            } else if (cmd === 'C' || cmd === 'c') {
-                i++;
-                const coords = [];
-                while (i < tokens.length && !/[MmLlCc]/.test(tokens[i])) {
-                    coords.push(Number(tokens[i]));
-                    i++;
-                }
-                // Read cubic bezier triplets: c1x c1y c2x c2y x y
-                for (let k = 0; k + 5 < coords.length; k += 6) {
-                    const p0 = current;
-                    const p1 = cmd === 'C'
-                        ? { x: coords[k], y: coords[k + 1] }
-                        : { x: current.x + coords[k], y: current.y + coords[k + 1] };
-                    const p2 = cmd === 'C'
-                        ? { x: coords[k + 2], y: coords[k + 3] }
-                        : { x: current.x + coords[k + 2], y: current.y + coords[k + 3] };
-                    const p3 = cmd === 'C'
-                        ? { x: coords[k + 4], y: coords[k + 5] }
-                        : { x: current.x + coords[k + 4], y: current.y + coords[k + 5] };
-                    let prev = p0;
-                    for (let s = 1; s <= 8; s++) {
-                        const t = s / 8;
-                        const mt = 1 - t;
-                        const pt = {
-                            x: mt * mt * mt * p0.x + 3 * mt * mt * t * p1.x + 3 * mt * t * t * p2.x + t * t * t * p3.x,
-                            y: mt * mt * mt * p0.y + 3 * mt * mt * t * p1.y + 3 * mt * t * t * p2.y + t * t * t * p3.y,
-                        };
-                        min = Math.min(min, EdgeGeometry.pointToSegmentDist2(prev, pt, x, y));
-                        prev = pt;
-                    }
-                    current = p3;
-                }
-            } else {
-                i++;
-            }
-        }
-        return min;
-    }
-
-    /** Pure. One edge's full geometry: `{x1,y1,x2,y2,d}` — `x1,y1`/`x2,y2` are
-     *  each anchor's final attach point (for label placement), `d` the SVG
-     *  path. Table-to-table FK links keep their own fixed left/right-column
-     *  bezier (`isTableLink`, unaffected by `routing`/side pinning). Explicit
-     *  `edge.waypoints` (see nearestSegmentInsertIndex) beat every auto
-     *  routing style, threading the line through them in order. Otherwise, an
-     *  edge picks its routing from `edge.routing` (falls back to
-     *  `defaultRouting`) and its anchor sides from
-     *  `edge.sourceSide`/`edge.targetSide` ('top'|'right'|'bottom'|'left',
-     *  default 'auto') — the single source of truth both the initial draw
-     *  (graphDiagram) and live drag frames call, so they can't drift apart. */
-    static computeEdgePath(sourceInfo, sourcePos, sourceSize, targetInfo, targetPos, targetSize, edge, defaultRouting = 'straight', obstacles = []) {
-        const isTableLink = sourceInfo?.shape === 'table' && targetInfo?.shape === 'table'
-            && edge.fromCol != null && edge.toCol != null;
-        if (isTableLink) {
-            const y1 = NodeGeometry.tableColumnY(sourceInfo, sourcePos, sourceSize, edge.fromCol);
-            const x1 = sourcePos.x + sourceSize.w / 2;
-            const y2 = NodeGeometry.tableColumnY(targetInfo, targetPos, targetSize, edge.toCol);
-            const x2 = targetPos.x - targetSize.w / 2;
-            const mx = (x1 + x2) / 2;
-            return { x1, y1, x2, y2, d: `M${x1},${y1} C${mx},${y1} ${mx},${y2} ${x2},${y2}` };
-        }
-
-        const sourceSide = edge.sourceSide || 'auto';
-        const targetSide = edge.targetSide || 'auto';
-        // 'auto' clips to the real box edge for rect/table nodes (see
-        // edgeAnchor's own doc comment) — a fixed circular radius is only
-        // correct for shapes actually drawn as a circle (circle/person).
-        const sourceRectBoundary = sourceInfo?.shape === 'rect' || sourceInfo?.shape === 'table';
-        const targetRectBoundary = targetInfo?.shape === 'rect' || targetInfo?.shape === 'table';
-
-        // Explicit waypoints (dragged/inserted by the user, or supplied by the
-        // caller) beat every auto-routing style: the line threads straight
-        // through each one in order, and an 'auto' anchor points at the
-        // nearest waypoint rather than at the other node.
-        if (edge.waypoints && edge.waypoints.length) {
-            const first = edge.waypoints[0], last = edge.waypoints[edge.waypoints.length - 1];
-            const d1x = first.x - sourcePos.x, d1y = first.y - sourcePos.y, dist1 = Math.hypot(d1x, d1y) || 1;
-            const d2x = targetPos.x - last.x, d2y = targetPos.y - last.y, dist2 = Math.hypot(d2x, d2y) || 1;
-            const wa1 = EdgeGeometry.nodeAnchor(sourceInfo, sourcePos, sourceSize, sourceSide, d1x / dist1, d1y / dist1, sourceRectBoundary);
-            const wa2 = EdgeGeometry.nodeAnchor(targetInfo, targetPos, targetSize, targetSide, -d2x / dist2, -d2y / dist2, targetRectBoundary);
-            const points = [wa1, ...edge.waypoints, wa2];
-            const d = points.map((pt, i) => `${i === 0 ? 'M' : 'L'}${pt.x},${pt.y}`).join(' ');
-            return { x1: wa1.x, y1: wa1.y, x2: wa2.x, y2: wa2.y, d };
-        }
-
-        const routing = edge.routing || defaultRouting;
-        const dx0 = targetPos.x - sourcePos.x, dy0 = targetPos.y - sourcePos.y;
-        const dist0 = Math.hypot(dx0, dy0) || 1;
-        const ux = dx0 / dist0, uy = dy0 / dist0;
-        const a1 = EdgeGeometry.nodeAnchor(sourceInfo, sourcePos, sourceSize, sourceSide, ux, uy, sourceRectBoundary);
-        const a2 = EdgeGeometry.nodeAnchor(targetInfo, targetPos, targetSize, targetSide, -ux, -uy, targetRectBoundary);
-
-        switch (routing) {
-            case 'orthogonal': return EdgeGeometry.orthogonalEdgePath(a1, a2, sourceSide, targetSide, obstacles);
-            case 'curved': return EdgeGeometry.curvedEdgePath(a1, a2);
-            case 'polyline': return EdgeGeometry.polylineEdgePath(a1, a2, obstacles);
-            case 'straight':
-            default:
-                return { x1: a1.x, y1: a1.y, x2: a2.x, y2: a2.y, d: `M${a1.x},${a1.y} L${a2.x},${a2.y}` };
-        }
-    }
-}
+import { NodeGeometry } from './NodeGeometry.js';
+
+const SIDE_VECTORS = { top: [0, -1], right: [1, 0], bottom: [0, 1], left: [-1, 0] };
+
+/**
+ * EdgeGeometry — pure, stateless helpers for graph edge anchors, routing,
+ * waypoints, and path generation.
+ *
+ * These used to live on RenderEngine; they are collected here so diagram
+ * classes can compute edge geometry without going through the engine façade.
+ */
+export class EdgeGeometry {
+    /** Pure. The point (and outward unit normal) where an edge attaches to a
+     *  node's bounding box for a given `side`: 'top'/'right'/'bottom'/'left'
+     *  pins the anchor to a fixed spot on the node — it stays there as the
+     *  node moves, instead of sliding around the node to keep facing whatever
+     *  it's connected to. `'auto'` (default) keeps that older sliding
+     *  behavior, using `ux,uy` (a unit vector already pointing at the other
+     *  endpoint) as the direction to project out to the node's edge.
+     *
+     *  `rectBoundary` (true for `shape:'rect'`/`'table'`, false otherwise —
+     *  see computeEdgePath's callers) picks WHICH boundary 'auto' projects
+     *  onto: for a circle/person node (always drawn as a true circle, square
+     *  bounding box or not) a fixed-radius circle is exactly its visible
+     *  edge, but for a rect/table node that same circle radius (using the
+     *  LARGER of w/h) massively overshoots a box that's wide but short —
+     *  visually "the line stops in empty space well outside the rectangle"
+     *  instead of touching it. `rectBoundary` instead finds where the ray
+     *  from centre exits the actual w x h box (whichever of the top/bottom
+     *  or left/right edges it reaches first). */
+    static edgeAnchor(pos, size, side, ux, uy, rectBoundary, shapeType = null) {
+        const hw = size.w / 2, hh = size.h / 2;
+        switch (side) {
+            case 'top': return { x: pos.x, y: pos.y - hh, nx: 0, ny: -1 };
+            case 'bottom': return { x: pos.x, y: pos.y + hh, nx: 0, ny: 1 };
+            case 'left': return { x: pos.x - hw, y: pos.y, nx: -1, ny: 0 };
+            case 'right': return { x: pos.x + hw, y: pos.y, nx: 1, ny: 0 };
+            default: {
+                if (rectBoundary) {
+                    const tx = ux !== 0 ? hw / Math.abs(ux) : Infinity;
+                    const ty = uy !== 0 ? hh / Math.abs(uy) : Infinity;
+                    const t = Math.min(tx, ty);
+                    const safeT = Number.isFinite(t) ? t : 0;
+                    return { x: pos.x + ux * safeT, y: pos.y + uy * safeT, nx: ux, ny: uy };
+                }
+                // Diamond-specific anchoring: find intersection with actual diamond edges
+                if (shapeType === 'diamond') {
+                    const t = EdgeGeometry._diamondBoundaryT(ux, uy, hw, hh);
+                    return { x: pos.x + ux * t, y: pos.y + uy * t, nx: ux, ny: uy };
+                }
+                // Any other shape: where the ray meets its glyph's outline (an ellipse its curve, a box its box).
+                const outline = shapeType ? NodeGeometry.outline(shapeType, size) : null;
+                const t = outline ? EdgeGeometry.rayPolygonT(ux, uy, outline) : null;
+                if (t !== null) return { x: pos.x + ux * t, y: pos.y + uy * t, nx: ux, ny: uy };
+                // No outline to meet: a circle as wide as the node.
+                const r = Math.max(size.w, size.h) / 2;
+                return { x: pos.x + ux * r, y: pos.y + uy * r, nx: ux, ny: uy };
+            }
+        }
+    }
+
+    /**
+     * Pure. How far along the ray from (0, 0) in direction (ux, uy) it first
+     * leaves a closed polygon centred there (a glyph's outline), or null when it
+     * meets none of its sides.
+     * @param {Array<[number, number]>} points
+     */
+    static rayPolygonT(ux, uy, points) {
+        let best = null;
+        for (let i = 0; i < points.length; i++) {
+            const [ax, ay] = points[i];
+            const [bx, by] = points[(i + 1) % points.length];
+            const ex = bx - ax, ey = by - ay;
+            const denom = ux * ey - uy * ex;
+            if (Math.abs(denom) < 1e-12) continue;   // parallel to this side
+            const t = (ax * ey - ay * ex) / denom;    // along the ray
+            const s = (ax * uy - ay * ux) / denom;    // along the side
+            if (t > 1e-9 && s >= -1e-9 && s <= 1 + 1e-9 && (best === null || t < best)) best = t;
+        }
+        return best;
+    }
+
+    /** Pure. Given a unit direction vector (ux, uy) and diamond half-dimensions (hw, hh),
+     *  find the distance t such that (t*ux, t*uy) intersects the diamond's perimeter.
+     *  Diamond vertices are at (±hw, 0) and (0, ±hh), with perimeter equation |x|/hw + |y|/hh = 1.
+     *  For a ray at (t*ux, t*uy): t*(|ux|/hw + |uy|/hh) = 1  =>  t = 1 / (|ux|/hw + |uy|/hh) */
+    static _diamondBoundaryT(ux, uy, hw, hh) {
+        const absUx = Math.abs(ux), absUy = Math.abs(uy);
+        if (absUx === 0 && absUy === 0) return 0; // Coincident nodes
+        const denom = (absUx / hw) + (absUy / hh);
+        return denom > 0 ? 1 / denom : Math.max(hw, hh);
+    }
+
+    /** Pure. Anchor for one end of an edge. A node that knows its own outline
+     *  supplies `info.boundaryPoint(dx, dy) → {x, y}` (DiagramEditor templates
+     *  do, rotation included), and the anchor is where the ray toward the other
+     *  end — or out of the pinned side — meets it. Otherwise falls back to the
+     *  shape-class model in edgeAnchor. */
+    static nodeAnchor(info, pos, size, side, ux, uy, rectBoundary) {
+        if (typeof info?.boundaryPoint !== 'function') {
+            return EdgeGeometry.edgeAnchor(pos, size, side, ux, uy, rectBoundary, info?.shape);
+        }
+        const [nx, ny] = SIDE_VECTORS[side] ?? [ux, uy];
+        const p = info.boundaryPoint(nx, ny);
+        return { x: p.x, y: p.y, nx, ny };
+    }
+
+    /** Pure. The side of a `size.w × size.h` node at `pos` that faces
+     *  `toward`, comparing offsets relative to the node's proportions so a wide
+     *  box prefers its long sides. */
+    static facingSide(pos, size, toward) {
+        const dx = toward.x - pos.x, dy = toward.y - pos.y;
+        if (Math.abs(dx) / (size.w || 1) >= Math.abs(dy) / (size.h || 1)) return dx >= 0 ? 'right' : 'left';
+        return dy >= 0 ? 'bottom' : 'top';
+    }
+
+    /** Pure. Unit directions in which a path arrives at each end, pointing
+     *  into the node: `start` runs from the path's next point toward its first
+     *  point, `end` from the previous point toward its last. Works for every
+     *  path computeEdgePath emits (absolute M/L/C): the neighbouring coordinate
+     *  pair is the adjacent vertex or bezier control point, both tangent to
+     *  the end. Coincident points are skipped; {x:0,y:0} if all coincide. */
+    static endDirections(d) {
+        const nums = (d || '').match(/-?\d*\.?\d+(?:e[-+]?\d+)?/gi)?.map(Number) ?? [];
+        const pts = [];
+        for (let i = 0; i + 1 < nums.length; i += 2) pts.push({ x: nums[i], y: nums[i + 1] });
+        const toward = (tip, others) => {
+            for (const p of others) {
+                const dx = tip.x - p.x, dy = tip.y - p.y, len = Math.hypot(dx, dy);
+                if (len > 1e-9) return { x: dx / len, y: dy / len };
+            }
+            return { x: 0, y: 0 };
+        };
+        if (!pts.length) return { start: { x: 0, y: 0 }, end: { x: 0, y: 0 } };
+        return {
+            start: toward(pts[0], pts.slice(1)),
+            end: toward(pts[pts.length - 1], pts.slice(0, -1).reverse()),
+        };
+    }
+
+    /** Pure. 'h' when `side` pins the anchor to a vertical edge of the node's
+     *  box (left/right — the line touches it moving horizontally), 'v' for
+     *  top/bottom, null for 'auto' (no fixed orientation to route around). */
+    static edgeSideOrientation(side) {
+        if (side === 'left' || side === 'right') return 'h';
+        if (side === 'top' || side === 'bottom') return 'v';
+        return null;
+    }
+
+    /** Pure. Cubic-bezier path between two pinned/auto anchors, leaving and
+     *  arriving along each anchor's own normal (`nx,ny`) so a pinned side
+     *  produces a visibly perpendicular exit/entry instead of a straight
+     *  dog-leg. The generalized shape of the table-link curve in
+     *  computeEdgePath, usable for any node pair. */
+    static curvedEdgePath(a1, a2) {
+        const dist = Math.hypot(a2.x - a1.x, a2.y - a1.y) || 1;
+        const k = Math.min(dist * 0.5, 80);
+        const c1x = a1.x + a1.nx * k, c1y = a1.y + a1.ny * k;
+        const c2x = a2.x + a2.nx * k, c2y = a2.y + a2.ny * k;
+        return { x1: a1.x, y1: a1.y, x2: a2.x, y2: a2.y, d: `M${a1.x},${a1.y} C${c1x},${c1y} ${c2x},${c2y} ${a2.x},${a2.y}` };
+    }
+
+    /** Pure. Right-angle (Manhattan) path between two anchors. When a side is
+     *  pinned, the segment touching that anchor is forced to the matching
+     *  orientation (horizontal for left/right, vertical for top/bottom); with
+     *  both anchors 'auto' it just bends along whichever axis has the bigger
+     *  gap. Mixed orientations (e.g. source pinned right, target pinned top)
+     *  get a single-corner elbow instead of the usual midpoint jog, since a
+     *  midpoint jog can't satisfy two different orientations at once.
+     *
+     *  With `obstacles` (array of {x,y,r} nodes), routes around blocking obstacles
+     *  using axis-aligned detour lanes. No avoidance for mixed-orientation elbows;
+     *  those are rare and have degenerate geometry. */
+    static orthogonalEdgePath(a1, a2, sourceSide, targetSide, obstacles = []) {
+        const so = EdgeGeometry.edgeSideOrientation(sourceSide);
+        const to = EdgeGeometry.edgeSideOrientation(targetSide);
+        let d;
+        if (so && to && so !== to) {
+            const corner = so === 'h' ? { x: a2.x, y: a1.y } : { x: a1.x, y: a2.y };
+            d = `M${a1.x},${a1.y} L${corner.x},${corner.y} L${a2.x},${a2.y}`;
+        } else {
+            const horizontalFirst = so ? so === 'h' : (to ? to === 'h' : Math.abs(a2.x - a1.x) >= Math.abs(a2.y - a1.y));
+            const blocking = EdgeGeometry.findBlockingObstacles(a1, a2, obstacles);
+
+            if (blocking.length === 0) {
+                // No obstacles — use the plain midpoint jog
+                if (horizontalFirst) {
+                    const midX = (a1.x + a2.x) / 2;
+                    d = `M${a1.x},${a1.y} L${midX},${a1.y} L${midX},${a2.y} L${a2.x},${a2.y}`;
+                } else {
+                    const midY = (a1.y + a2.y) / 2;
+                    d = `M${a1.x},${a1.y} L${a1.x},${midY} L${a2.x},${midY} L${a2.x},${a2.y}`;
+                }
+            } else {
+                // Route around the obstacle cluster with a detour lane
+                const bounds = EdgeGeometry.obstacleClusterBounds(blocking);
+                if (horizontalFirst) {
+                    const naturalY = (a1.y + a2.y) / 2;
+                    const routeY = naturalY < bounds.minY ? bounds.minY - 12 : bounds.maxY + 12;
+                    d = `M${a1.x},${a1.y} L${a1.x},${routeY} L${a2.x},${routeY} L${a2.x},${a2.y}`;
+                } else {
+                    const naturalX = (a1.x + a2.x) / 2;
+                    const routeX = naturalX < bounds.minX ? bounds.minX - 12 : bounds.maxX + 12;
+                    d = `M${a1.x},${a1.y} L${routeX},${a1.y} L${routeX},${a2.y} L${a2.x},${a2.y}`;
+                }
+            }
+        }
+        return { x1: a1.x, y1: a1.y, x2: a2.x, y2: a2.y, d };
+    }
+
+    /** Pure. True if the segment a1->a2 passes within `circle.r` of `circle`'s
+     *  centre (see pointToSegmentDist2 for the underlying clamped-distance math). */
+    static segmentIntersectsCircle(a1, a2, circle) {
+        return EdgeGeometry.pointToSegmentDist2(a1, a2, circle.x, circle.y) < circle.r * circle.r;
+    }
+
+    /** Pure. Find all obstacles that block the direct line from a1 to a2.
+     *  Returns array of blocking obstacles, sorted by their position along the line. */
+    static findBlockingObstacles(a1, a2, obstacles = []) {
+        return obstacles
+            .filter(o => EdgeGeometry.segmentIntersectsCircle(a1, a2, o))
+            .sort((o1, o2) => {
+                const dx = a2.x - a1.x, dy = a2.y - a1.y;
+                const len2 = dx * dx + dy * dy;
+                const t1 = ((o1.x - a1.x) * dx + (o1.y - a1.y) * dy) / len2;
+                const t2 = ((o2.x - a1.x) * dx + (o2.y - a1.y) * dy) / len2;
+                return t1 - t2;
+            });
+    }
+
+    /** Pure. Compute bounding box around a cluster of obstacles with clearance margin. */
+    static obstacleClusterBounds(obstacles, margin = 12) {
+        let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+        for (const o of obstacles) {
+            minX = Math.min(minX, o.x - o.r - margin);
+            minY = Math.min(minY, o.y - o.r - margin);
+            maxX = Math.max(maxX, o.x + o.r + margin);
+            maxY = Math.max(maxY, o.y + o.r + margin);
+        }
+        return { minX, minY, maxX, maxY };
+    }
+
+    /** Pure. Route around a cluster of obstacles by computing two waypoints (above/below or left/right).
+     *  Returns array of waypoints to thread between source and target anchors. */
+    static routeAroundCluster(a1, a2, obstacles) {
+        const bounds = EdgeGeometry.obstacleClusterBounds(obstacles);
+        const dx = a2.x - a1.x, dy = a2.y - a1.y;
+        const isHorizontal = Math.abs(dx) >= Math.abs(dy);
+
+        // Choose routing direction: if more horizontal, route above/below; else left/right
+        if (isHorizontal) {
+            // Route vertically around the cluster
+            const side = a1.y < bounds.minY ? -1 : 1; // above if source is above, else below
+            const routeY = side > 0 ? bounds.maxY : bounds.minY;
+            const midX = (bounds.minX + bounds.maxX) / 2;
+            return [
+                { x: midX, y: a1.y },      // move horizontally to cluster's horizontal center
+                { x: midX, y: routeY },    // move vertically around cluster
+            ];
+        } else {
+            // Route horizontally around the cluster
+            const side = a1.x < bounds.minX ? -1 : 1; // left if source is left, else right
+            const routeX = side > 0 ? bounds.maxX : bounds.minX;
+            const midY = (bounds.minY + bounds.maxY) / 2;
+            return [
+                { x: a1.x, y: midY },      // move vertically to cluster's vertical center
+                { x: routeX, y: midY },    // move horizontally around cluster
+            ];
+        }
+    }
+
+    /** Pure. Straight line between two anchors, unless `obstacles` (other
+     *  nodes as {x,y,r}, source/target already excluded by the caller) puts
+     *  one in the way. Routes around single obstacles with a perpendicular
+     *  waypoint; routes around clusters by threading around the bounding box.
+     *  Degrades to a plain straight line on an uncrowded graph.
+     *
+     *  Note: This is 'polyline' routing only. 'curved' and 'orthogonal' modes
+     *  currently do not have obstacle avoidance — they route directly regardless
+     *  of obstacles. A caller needing avoidance on those modes should either:
+     *  1. Switch to 'polyline' routing, or
+     *  2. Manually add waypoints (edge.waypoints) to the edge data. */
+    static polylineEdgePath(a1, a2, obstacles = []) {
+        const blocking = EdgeGeometry.findBlockingObstacles(a1, a2, obstacles);
+        if (blocking.length === 0) {
+            return { x1: a1.x, y1: a1.y, x2: a2.x, y2: a2.y, d: `M${a1.x},${a1.y} L${a2.x},${a2.y}` };
+        }
+
+        let waypoints;
+        if (blocking.length === 1) {
+            // Single obstacle: use perpendicular offset (original behavior)
+            const o = blocking[0];
+            const dx = a2.x - a1.x, dy = a2.y - a1.y;
+            const len = Math.hypot(dx, dy) || 1;
+            const px = -dy / len, py = dx / len;
+            const len2 = len * len;
+            const t = ((o.x - a1.x) * dx + (o.y - a1.y) * dy) / len2;
+            const footX = a1.x + dx * t, footY = a1.y + dy * t;
+            const cross = dx * (o.y - a1.y) - dy * (o.x - a1.x);
+            const side = cross >= 0 ? -1 : 1;
+            const clearance = o.r + 12;
+            waypoints = [{ x: footX + px * clearance * side, y: footY + py * clearance * side }];
+        } else {
+            // Multiple obstacles: route around the cluster
+            waypoints = EdgeGeometry.routeAroundCluster(a1, a2, blocking);
+        }
+
+        const points = [a1, ...waypoints, a2];
+        const d = points.map((pt, i) => `${i === 0 ? 'M' : 'L'}${pt.x},${pt.y}`).join(' ');
+        return { x1: a1.x, y1: a1.y, x2: a2.x, y2: a2.y, d };
+    }
+
+    /** Pure. Given `points` (an ordered polyline — anchor, any existing
+     *  waypoints, anchor), finds which SEGMENT a click at `(x,y)` landed
+     *  closest to and returns that segment's starting index. Since
+     *  `points[0]` is the source anchor (not a stored waypoint), segment `i`
+     *  is exactly where a new `edge.waypoints[i]` belongs (`Array.splice(i, 0,
+     *  point)`) — see the double-click-to-add-a-bend handler in
+     *  RenderEngine's drag listeners. */
+    static nearestSegmentInsertIndex(points, x, y) {
+        let bestIdx = 0, bestDist2 = Infinity;
+        for (let i = 0; i < points.length - 1; i++) {
+            const dist2 = EdgeGeometry.pointToSegmentDist2(points[i], points[i + 1], x, y);
+            if (dist2 < bestDist2) { bestDist2 = dist2; bestIdx = i; }
+        }
+        return bestIdx;
+    }
+
+    /** Pure. Detect if two line segments intersect. Returns intersection point if they do, null otherwise.
+     *  Used for edge-crossing visualization. */
+    static lineSegmentIntersection(p1, p2, p3, p4) {
+        const x1 = p1.x, y1 = p1.y, x2 = p2.x, y2 = p2.y;
+        const x3 = p3.x, y3 = p3.y, x4 = p4.x, y4 = p4.y;
+
+        const denom = (x1 - x2) * (y3 - y4) - (y1 - y2) * (x3 - x4);
+        if (Math.abs(denom) < 1e-10) return null; // parallel or coincident
+
+        const t = ((x1 - x3) * (y3 - y4) - (y1 - y3) * (x3 - x4)) / denom;
+        const u = -((x1 - x2) * (y1 - y3) - (y1 - y2) * (x1 - x3)) / denom;
+
+        if (t > 0 && t < 1 && u > 0 && u < 1) {
+            return { x: x1 + t * (x2 - x1), y: y1 + t * (y2 - y1) };
+        }
+        return null;
+    }
+
+    /** Pure. Find all crossing points between a given edge path and an array of other edge paths.
+     *  Returns array of {x, y, angle} crossing points. */
+    static findEdgeCrossings(edgePath, otherEdgePaths) {
+        const crossings = [];
+        const points = EdgeGeometry.pathToPoints(edgePath);
+
+        for (const otherPath of otherEdgePaths) {
+            const otherPoints = EdgeGeometry.pathToPoints(otherPath);
+            for (let i = 0; i < points.length - 1; i++) {
+                for (let j = 0; j < otherPoints.length - 1; j++) {
+                    const intersection = EdgeGeometry.lineSegmentIntersection(
+                        points[i], points[i + 1],
+                        otherPoints[j], otherPoints[j + 1]
+                    );
+                    if (intersection) {
+                        const angle = Math.atan2(
+                            points[i + 1].y - points[i].y,
+                            points[i + 1].x - points[i].x
+                        );
+                        crossings.push({ ...intersection, angle });
+                    }
+                }
+            }
+        }
+        return crossings;
+    }
+
+    /** Pure. Convert SVG path string to array of points (samples bezier curves).
+     *  Used for edge-crossing detection. */
+    static pathToPoints(pathStr) {
+        const points = [];
+        const tokens = pathStr.match(/[MmLlCc]|[+-]?[\d.]+/g) || [];
+        let current = { x: 0, y: 0 };
+        let i = 0;
+
+        while (i < tokens.length) {
+            const cmd = tokens[i];
+            if (cmd === 'M' || cmd === 'm') {
+                i++;
+                const x = Number(tokens[i++]), y = Number(tokens[i++]);
+                current = cmd === 'M' ? { x, y } : { x: current.x + x, y: current.y + y };
+                points.push({ ...current });
+            } else if (cmd === 'L' || cmd === 'l') {
+                i++;
+                const x = Number(tokens[i++]), y = Number(tokens[i++]);
+                current = cmd === 'L' ? { x, y } : { x: current.x + x, y: current.y + y };
+                points.push({ ...current });
+            } else if (cmd === 'C' || cmd === 'c') {
+                i++;
+                const coords = [];
+                while (i < tokens.length && !/[MmLlCc]/.test(tokens[i])) {
+                    coords.push(Number(tokens[i++]));
+                }
+                const p0 = current;
+                const p1 = cmd === 'C' ? { x: coords[0], y: coords[1] } : { x: current.x + coords[0], y: current.y + coords[1] };
+                const p2 = cmd === 'C' ? { x: coords[2], y: coords[3] } : { x: current.x + coords[2], y: current.y + coords[3] };
+                const p3 = cmd === 'C' ? { x: coords[4], y: coords[5] } : { x: current.x + coords[4], y: current.y + coords[5] };
+
+                for (let s = 1; s <= 8; s++) {
+                    const t = s / 8;
+                    const mt = 1 - t;
+                    const pt = {
+                        x: mt * mt * mt * p0.x + 3 * mt * mt * t * p1.x + 3 * mt * t * t * p2.x + t * t * t * p3.x,
+                        y: mt * mt * mt * p0.y + 3 * mt * mt * t * p1.y + 3 * mt * t * t * p2.y + t * t * t * p3.y,
+                    };
+                    points.push(pt);
+                }
+                current = p3;
+            } else {
+                i++;
+            }
+        }
+        return points;
+    }
+
+    /** Pure. Returns a NEW `edge.waypoints` array with one more point added
+     *  at `point`, landing in the segment nearest it along the current route
+     *  sourcePos -> ...edge.waypoints -> targetPos (see nearestSegmentInsertIndex).
+     *  Used by the edge context menu's "Add Waypoint Here" — hand-routing used
+     *  to be reachable by double-clicking the edge line itself, but that
+     *  gesture now opens `onEdgeDoubleClick`'s properties dialog instead, so
+     *  adding a bend point moved to the context menu. */
+    static edgeWaypointsWithInsertion(edge, sourcePos, targetPos, point) {
+        const points = [sourcePos, ...(edge.waypoints || []), targetPos];
+        const insertIdx = EdgeGeometry.nearestSegmentInsertIndex(points, point.x, point.y);
+        const waypoints = edge.waypoints ? [...edge.waypoints] : [];
+        waypoints.splice(insertIdx, 0, { x: point.x, y: point.y });
+        return waypoints;
+    }
+
+    /** Pure. Squared distance from `(x,y)` to the closest point on segment
+     *  a->b (clamped to the segment, not the infinite line) — shared by
+     *  segmentIntersectsCircle's threshold test and nearestSegmentInsertIndex's
+     *  plain distance comparison. */
+    static pointToSegmentDist2(a, b, x, y) {
+        const dx = b.x - a.x, dy = b.y - a.y;
+        const len2 = dx * dx + dy * dy || 1;
+        let t = ((x - a.x) * dx + (y - a.y) * dy) / len2;
+        t = Math.max(0, Math.min(1, t));
+        const cx = a.x + dx * t, cy = a.y + dy * t;
+        return (x - cx) * (x - cx) + (y - cy) * (y - cy);
+    }
+
+    /** Pure. Approximate squared distance from `(x,y)` to the polyline or
+     *  cubic-bezier path described by an SVG `d` attribute. Straight, polyline,
+     *  orthogonal and waypoint paths are checked exactly segment-by-segment;
+     *  cubic beziers are sampled into short line segments so the result is
+     *  accurate enough for a generous hit-test tolerance without parsing
+     *  arbitrary SVG path syntax. */
+    static pathDistance2(d, x, y) {
+        const tokens = (d || '').match(/[MmLlCc]|-?\d+(?:\.\d+)?/g) || [];
+        let min = Infinity, current = { x: 0, y: 0 };
+        let i = 0;
+        while (i < tokens.length) {
+            const cmd = tokens[i];
+            if (/[MmLl]/.test(cmd)) {
+                i++;
+                while (i < tokens.length && !/[MmLlCc]/.test(tokens[i])) {
+                    const px = Number(tokens[i]), py = Number(tokens[i + 1]);
+                    if (Number.isFinite(px) && Number.isFinite(py)) {
+                        if (cmd === 'M' || cmd === 'L') {
+                            min = Math.min(min, EdgeGeometry.pointToSegmentDist2(current, { x: px, y: py }, x, y));
+                            current = { x: px, y: py };
+                        } else if (cmd === 'm' || cmd === 'l') {
+                            min = Math.min(min, EdgeGeometry.pointToSegmentDist2(current, { x: current.x + px, y: current.y + py }, x, y));
+                            current = { x: current.x + px, y: current.y + py };
+                        }
+                    }
+                    i += 2;
+                }
+            } else if (cmd === 'C' || cmd === 'c') {
+                i++;
+                const coords = [];
+                while (i < tokens.length && !/[MmLlCc]/.test(tokens[i])) {
+                    coords.push(Number(tokens[i]));
+                    i++;
+                }
+                // Read cubic bezier triplets: c1x c1y c2x c2y x y
+                for (let k = 0; k + 5 < coords.length; k += 6) {
+                    const p0 = current;
+                    const p1 = cmd === 'C'
+                        ? { x: coords[k], y: coords[k + 1] }
+                        : { x: current.x + coords[k], y: current.y + coords[k + 1] };
+                    const p2 = cmd === 'C'
+                        ? { x: coords[k + 2], y: coords[k + 3] }
+                        : { x: current.x + coords[k + 2], y: current.y + coords[k + 3] };
+                    const p3 = cmd === 'C'
+                        ? { x: coords[k + 4], y: coords[k + 5] }
+                        : { x: current.x + coords[k + 4], y: current.y + coords[k + 5] };
+                    let prev = p0;
+                    for (let s = 1; s <= 8; s++) {
+                        const t = s / 8;
+                        const mt = 1 - t;
+                        const pt = {
+                            x: mt * mt * mt * p0.x + 3 * mt * mt * t * p1.x + 3 * mt * t * t * p2.x + t * t * t * p3.x,
+                            y: mt * mt * mt * p0.y + 3 * mt * mt * t * p1.y + 3 * mt * t * t * p2.y + t * t * t * p3.y,
+                        };
+                        min = Math.min(min, EdgeGeometry.pointToSegmentDist2(prev, pt, x, y));
+                        prev = pt;
+                    }
+                    current = p3;
+                }
+            } else {
+                i++;
+            }
+        }
+        return min;
+    }
+
+    /** Pure. One edge's full geometry: `{x1,y1,x2,y2,d}` — `x1,y1`/`x2,y2` are
+     *  each anchor's final attach point (for label placement), `d` the SVG
+     *  path. Table-to-table FK links keep their own fixed left/right-column
+     *  bezier (`isTableLink`, unaffected by `routing`/side pinning). Explicit
+     *  `edge.waypoints` (see nearestSegmentInsertIndex) beat every auto
+     *  routing style, threading the line through them in order. Otherwise, an
+     *  edge picks its routing from `edge.routing` (falls back to
+     *  `defaultRouting`) and its anchor sides from
+     *  `edge.sourceSide`/`edge.targetSide` ('top'|'right'|'bottom'|'left',
+     *  default 'auto') — the single source of truth both the initial draw
+     *  (graphDiagram) and live drag frames call, so they can't drift apart. */
+    static computeEdgePath(sourceInfo, sourcePos, sourceSize, targetInfo, targetPos, targetSize, edge, defaultRouting = 'straight', obstacles = []) {
+        const isTableLink = sourceInfo?.shape === 'table' && targetInfo?.shape === 'table'
+            && edge.fromCol != null && edge.toCol != null;
+        if (isTableLink) {
+            const y1 = NodeGeometry.tableColumnY(sourceInfo, sourcePos, sourceSize, edge.fromCol);
+            const x1 = sourcePos.x + sourceSize.w / 2;
+            const y2 = NodeGeometry.tableColumnY(targetInfo, targetPos, targetSize, edge.toCol);
+            const x2 = targetPos.x - targetSize.w / 2;
+            const mx = (x1 + x2) / 2;
+            return { x1, y1, x2, y2, d: `M${x1},${y1} C${mx},${y1} ${mx},${y2} ${x2},${y2}` };
+        }
+
+        const sourceSide = edge.sourceSide || 'auto';
+        const targetSide = edge.targetSide || 'auto';
+        // 'auto' clips to the real box edge for rect/table nodes (see
+        // edgeAnchor's own doc comment) — a fixed circular radius is only
+        // correct for shapes actually drawn as a circle (circle/person).
+        const sourceRectBoundary = sourceInfo?.shape === 'rect' || sourceInfo?.shape === 'table';
+        const targetRectBoundary = targetInfo?.shape === 'rect' || targetInfo?.shape === 'table';
+
+        // Explicit waypoints (dragged/inserted by the user, or supplied by the
+        // caller) beat every auto-routing style: the line threads straight
+        // through each one in order, and an 'auto' anchor points at the
+        // nearest waypoint rather than at the other node.
+        if (edge.waypoints && edge.waypoints.length) {
+            const first = edge.waypoints[0], last = edge.waypoints[edge.waypoints.length - 1];
+            const d1x = first.x - sourcePos.x, d1y = first.y - sourcePos.y, dist1 = Math.hypot(d1x, d1y) || 1;
+            const d2x = targetPos.x - last.x, d2y = targetPos.y - last.y, dist2 = Math.hypot(d2x, d2y) || 1;
+            const wa1 = EdgeGeometry.nodeAnchor(sourceInfo, sourcePos, sourceSize, sourceSide, d1x / dist1, d1y / dist1, sourceRectBoundary);
+            const wa2 = EdgeGeometry.nodeAnchor(targetInfo, targetPos, targetSize, targetSide, -d2x / dist2, -d2y / dist2, targetRectBoundary);
+            const points = [wa1, ...edge.waypoints, wa2];
+            const d = points.map((pt, i) => `${i === 0 ? 'M' : 'L'}${pt.x},${pt.y}`).join(' ');
+            return { x1: wa1.x, y1: wa1.y, x2: wa2.x, y2: wa2.y, d };
+        }
+
+        const routing = edge.routing || defaultRouting;
+        const dx0 = targetPos.x - sourcePos.x, dy0 = targetPos.y - sourcePos.y;
+        const dist0 = Math.hypot(dx0, dy0) || 1;
+        const ux = dx0 / dist0, uy = dy0 / dist0;
+        const a1 = EdgeGeometry.nodeAnchor(sourceInfo, sourcePos, sourceSize, sourceSide, ux, uy, sourceRectBoundary);
+        const a2 = EdgeGeometry.nodeAnchor(targetInfo, targetPos, targetSize, targetSide, -ux, -uy, targetRectBoundary);
+
+        switch (routing) {
+            case 'orthogonal': return EdgeGeometry.orthogonalEdgePath(a1, a2, sourceSide, targetSide, obstacles);
+            case 'curved': return EdgeGeometry.curvedEdgePath(a1, a2);
+            case 'polyline': return EdgeGeometry.polylineEdgePath(a1, a2, obstacles);
+            case 'straight':
+            default:
+                return { x1: a1.x, y1: a1.y, x2: a2.x, y2: a2.y, d: `M${a1.x},${a1.y} L${a2.x},${a2.y}` };
+        }
+    }
+}