@graph-artifact/core 0.1.13 → 0.1.15

package/dist/layout/edges/buildEdges.js

@@ -13,11 +13,16 @@
  */
 import { MarkerType } from '@xyflow/react';
 import { intersectNode } from '../intersect/index.js';
-import { waypointsDeviate, shortenPathEnd, shortenPathStart, generateSmoothPath, generateRoundedPath, computeLabelPosition, } from './paths.js';
+import { waypointsDeviate, shortenPathEnd, shortenPathStart, generateBasisPath, generateRoundedPath, computeLabelPosition, } from './paths.js';
 import { classifyEdge, edgeStyleForType } from './classify.js';
 // ─── Constants ──────────────────────────────────────────────────────────────
 const MARKER_SHORTENING = 6; // shorten path end so arrowhead tip sits at the boundary
-const ER_PATH_GAP = 8; // hard visual clearance from ER node boundary
+// ER edge strokes render below card nodes (default zIndex ordering).
+// The cardinality symbols render in EdgeLabelRenderer (above nodes),
+// so we just need a small gap so the line stops before the card border.
+const ER_ENDPOINT_GAP = 4;
+const DEBUG_ER = false;
+const DEBUG_SUBGRAPH_EDGES = false;
 function clamp255(v) {
     return Math.max(0, Math.min(255, Math.round(v)));
 }
@@ -78,6 +83,308 @@ function pointInsideNodeBounds(point, node, epsilon = 0.5) {
         point.y >= top - epsilon &&
         point.y <= bottom + epsilon);
 }
+/**
+ * Check if a point is outside a rectangular boundary (top-left origin).
+ * Used for subgraph boundary detection.
+ */
+function pointOutsideRect(bounds, point) {
+    return (point.x < bounds.x ||
+        point.x > bounds.x + bounds.width ||
+        point.y < bounds.y ||
+        point.y > bounds.y + bounds.height);
+}
+/**
+ * Compute intersection of a line segment with a rectangular boundary.
+ * Returns the point where the line crosses the rect edge.
+ */
+function lineRectIntersection(bounds, outside, inside) {
+    const left = bounds.x;
+    const right = bounds.x + bounds.width;
+    const top = bounds.y;
+    const bottom = bounds.y + bounds.height;
+    const dx = inside.x - outside.x;
+    const dy = inside.y - outside.y;
+    let t = 1;
+    // Check each edge
+    if (dx !== 0) {
+        if (dx > 0) {
+            // Entering from left
+            const tLeft = (left - outside.x) / dx;
+            if (tLeft > 0 && tLeft < t)
+                t = tLeft;
+        }
+        else {
+            // Entering from right
+            const tRight = (right - outside.x) / dx;
+            if (tRight > 0 && tRight < t)
+                t = tRight;
+        }
+    }
+    if (dy !== 0) {
+        if (dy > 0) {
+            // Entering from top
+            const tTop = (top - outside.y) / dy;
+            if (tTop > 0 && tTop < t)
+                t = tTop;
+        }
+        else {
+            // Entering from bottom
+            const tBottom = (bottom - outside.y) / dy;
+            if (tBottom > 0 && tBottom < t)
+                t = tBottom;
+        }
+    }
+    return {
+        x: outside.x + dx * t,
+        y: outside.y + dy * t,
+    };
+}
+/**
+ * Trim a path at a subgraph boundary, forcing exit from bottom or entry from top.
+ * This is an enhanced version of Mermaid's cutPathAtIntersect that ensures
+ * edges use the correct boundary edge (top for incoming, bottom for outgoing).
+ *
+ * @param points - The path waypoints
+ * @param subgraphBounds - The subgraph boundary rectangle (top-left origin)
+ * @param isOutgoing - true if edge exits FROM subgraph (use bottom), false if enters TO subgraph (use top)
+ */
+function cutPathAtSubgraphBoundary(points, subgraphBounds, isOutgoing, otherNodePos) {
+    if (points.length < 2)
+        return points;
+    const subgraphBottom = subgraphBounds.y + subgraphBounds.height;
+    const subgraphTop = subgraphBounds.y;
+    const subgraphCenterX = subgraphBounds.x + subgraphBounds.width / 2;
+    const subgraphLeft = subgraphBounds.x;
+    const subgraphRight = subgraphBounds.x + subgraphBounds.width;
+    // Use the actual node position if available, otherwise fall back to waypoint
+    const getDestination = () => {
+        if (otherNodePos) {
+            return {
+                x: otherNodePos.x + otherNodePos.width / 2,
+                y: otherNodePos.y + otherNodePos.height / 2,
+            };
+        }
+        return points[points.length - 1];
+    };
+    const getSource = () => {
+        if (otherNodePos) {
+            return {
+                x: otherNodePos.x + otherNodePos.width / 2,
+                y: otherNodePos.y + otherNodePos.height / 2,
+            };
+        }
+        return points[0];
+    };
+    if (isOutgoing) {
+        // Edge exits FROM subgraph - need to route around the subgraph
+        const exitPoint = { x: subgraphCenterX, y: subgraphBottom };
+        const destination = getDestination();
+        // Determine if target is below the subgraph or to the side
+        const targetBelowSubgraph = destination.y > subgraphBottom + 10;
+        const targetLeftOfSubgraph = destination.x < subgraphLeft - 10;
+        const targetRightOfSubgraph = destination.x > subgraphRight + 10;
+        if (DEBUG_SUBGRAPH_EDGES) {
+            console.log(`  cutPath: exitPoint=(${exitPoint.x.toFixed(0)}, ${exitPoint.y.toFixed(0)})`);
+            console.log(`  cutPath: destination=(${destination.x.toFixed(0)}, ${destination.y.toFixed(0)})`);
+            console.log(`  cutPath: targetBelow=${targetBelowSubgraph}, left=${targetLeftOfSubgraph}, right=${targetRightOfSubgraph}`);
+        }
+        // Route down from bottom, then to target
+        const clearanceY = subgraphBottom + 40; // Go 40px below subgraph before turning
+        if (targetBelowSubgraph) {
+            // Target is below - go straight down then to target
+            if (Math.abs(destination.x - subgraphCenterX) < 30) {
+                // Target is roughly centered below - direct path down
+                return [exitPoint, { x: subgraphCenterX, y: clearanceY }, destination];
+            }
+            else {
+                // Target is offset - route down then over
+                const turnPoint = { x: destination.x, y: clearanceY };
+                return [exitPoint, { x: subgraphCenterX, y: clearanceY }, turnPoint, destination];
+            }
+        }
+        else if (targetLeftOfSubgraph || targetRightOfSubgraph) {
+            // Target is to the side and NOT below - need to route around and up/over
+            const sideX = targetLeftOfSubgraph
+                ? subgraphLeft - 40 // Go left of subgraph
+                : subgraphRight + 40; // Go right of subgraph
+            // Route: exit bottom → drop down → go to side → go up/over to target
+            const dropPoint = { x: subgraphCenterX, y: clearanceY };
+            const cornerPoint = { x: sideX, y: clearanceY };
+            const approachPoint = { x: sideX, y: destination.y };
+            return [exitPoint, dropPoint, cornerPoint, approachPoint, destination];
+        }
+        else {
+            // Target is within subgraph horizontal bounds but not below (above or overlapping)
+            // Route down and around - go down, then out to the side, then to target
+            const dropPoint = { x: subgraphCenterX, y: clearanceY };
+            const sideX = destination.x < subgraphCenterX ? subgraphLeft - 40 : subgraphRight + 40;
+            const cornerPoint = { x: sideX, y: clearanceY };
+            const approachPoint = { x: sideX, y: destination.y };
+            return [exitPoint, dropPoint, cornerPoint, approachPoint, destination];
+        }
+    }
+    else {
+        // Edge enters TO subgraph - route to top
+        const entryPoint = { x: subgraphCenterX, y: subgraphTop };
+        const source = getSource();
+        const sourceAboveSubgraph = source.y < subgraphTop - 10;
+        const sourceLeftOfSubgraph = source.x < subgraphLeft - 10;
+        const sourceRightOfSubgraph = source.x > subgraphRight + 10;
+        const approachY = subgraphTop - 40;
+        if (sourceAboveSubgraph) {
+            // Source is above - can come straight down
+            if (Math.abs(source.x - subgraphCenterX) < 30) {
+                return [source, { x: subgraphCenterX, y: approachY }, entryPoint];
+            }
+            else {
+                // Source is offset above - route over then down
+                const turnPoint = { x: subgraphCenterX, y: approachY };
+                return [source, { x: source.x, y: approachY }, turnPoint, entryPoint];
+            }
+        }
+        else if (sourceLeftOfSubgraph || sourceRightOfSubgraph) {
+            // Source is to the side - route around to top
+            const sideX = sourceLeftOfSubgraph ? subgraphLeft - 40 : subgraphRight + 40;
+            return [source, { x: sideX, y: source.y }, { x: sideX, y: approachY }, { x: subgraphCenterX, y: approachY }, entryPoint];
+        }
+        else {
+            // Source is within subgraph bounds - shouldn't happen but handle gracefully
+            return [source, { x: subgraphCenterX, y: approachY }, entryPoint];
+        }
+    }
+}
+/**
+ * Build a path from a subgraph boundary (outgoing) to a target node.
+ * - If target is clearly ABOVE subgraph (back-edge): exit from TOP
+ * - Otherwise: exit from BOTTOM and route to target
+ * @param edgeOffset - Edge index for spreading
+ * @param totalEdges - Total number of outgoing edges (for spreading calculation)
+ */
+function buildSubgraphOutgoingPath(subgraphBounds, targetCenter, targetShape, borderRadius, edgeOffset = 0, totalEdges = 1) {
+    const subgraphTop = subgraphBounds.y;
+    const subgraphBottom = subgraphBounds.y + subgraphBounds.height;
+    const subgraphCenterX = subgraphBounds.x + subgraphBounds.width / 2;
+    const subgraphLeft = subgraphBounds.x;
+    const subgraphRight = subgraphBounds.x + subgraphBounds.width;
+    // Only treat as "above" if target is significantly above the subgraph top
+    // This identifies true back-edges (like logout → Idle)
+    const targetIsAbove = targetCenter.y + targetCenter.height / 2 < subgraphTop - 20;
+    if (targetIsAbove) {
+        // Target is above - exit from top (back-edge case like logout → Idle)
+        // Use RIGHT portion of top to avoid incoming edges on left
+        const spreadWidth = subgraphBounds.width * 0.3;
+        const slotSpacing = totalEdges > 1 ? spreadWidth / (totalEdges - 1) : 0;
+        const startX = subgraphCenterX + subgraphBounds.width * 0.1;
+        const exitX = totalEdges > 1 ? startX + edgeOffset * slotSpacing : startX + spreadWidth / 2;
+        const exitPoint = { x: exitX, y: subgraphTop };
+        const targetIntersect = intersectNode(targetCenter, exitPoint, targetShape, borderRadius);
+        // Smooth curved path up to target
+        const totalDY = subgraphTop - targetIntersect.y;
+        const totalDX = targetIntersect.x - exitX;
+        const waypoints = [
+            exitPoint,
+            // First control: rise up vertically a bit
+            { x: exitX, y: subgraphTop - totalDY * 0.3 },
+            // Second control: start curving toward target
+            { x: exitX + totalDX * 0.3, y: subgraphTop - totalDY * 0.5 },
+            // Third control: continue curving
+            { x: exitX + totalDX * 0.7, y: subgraphTop - totalDY * 0.7 },
+            targetIntersect,
+        ];
+        return shortenPathEnd(waypoints, MARKER_SHORTENING);
+    }
+    else {
+        // Target is below OR beside - always exit from BOTTOM
+        // Exit from the position closest to target (clamped to subgraph bounds)
+        const margin = 20;
+        const minExitX = subgraphLeft + margin;
+        const maxExitX = subgraphRight - margin;
+        // Aim toward target X, but stay within subgraph bounds
+        let exitX = Math.max(minExitX, Math.min(maxExitX, targetCenter.x));
+        // Add small offset for multiple edges to prevent overlap
+        exitX += edgeOffset * 15;
+        exitX = Math.max(minExitX, Math.min(maxExitX, exitX));
+        const exitPoint = { x: exitX, y: subgraphBottom };
+        const targetIntersect = intersectNode(targetCenter, exitPoint, targetShape, borderRadius);
+        // Check if target is actually below or beside
+        const targetIsBelow = targetCenter.y - targetCenter.height / 2 > subgraphBottom - 10;
+        if (targetIsBelow) {
+            // Smooth curved path down to target
+            // Use gradual control points for soft Bezier-like curve
+            const totalDY = targetIntersect.y - subgraphBottom;
+            const totalDX = targetIntersect.x - exitX;
+            const waypoints = [
+                exitPoint,
+                // First control: drop down vertically a bit
+                { x: exitX, y: subgraphBottom + totalDY * 0.3 },
+                // Second control: start moving toward target
+                { x: exitX + totalDX * 0.3, y: subgraphBottom + totalDY * 0.5 },
+                // Third control: continue curving
+                { x: exitX + totalDX * 0.7, y: subgraphBottom + totalDY * 0.7 },
+                targetIntersect,
+            ];
+            return shortenPathEnd(waypoints, MARKER_SHORTENING);
+        }
+        else {
+            // Target is beside - route down then around with smooth curves
+            const targetIsLeft = targetCenter.x < subgraphCenterX;
+            const routeX = targetIsLeft ? subgraphLeft - 40 - edgeOffset * 15 : subgraphRight + 40 + edgeOffset * 15;
+            const clearanceY = subgraphBottom + 25;
+            // Create smooth curve with gradual transitions
+            const waypoints = [
+                exitPoint,
+                // Gentle drop
+                { x: exitX, y: subgraphBottom + 10 },
+                // Curve toward route X
+                { x: (exitX + routeX) / 2, y: clearanceY },
+                { x: routeX, y: clearanceY },
+                // Curve toward target Y
+                { x: routeX, y: (clearanceY + targetCenter.y) / 2 },
+                { x: routeX, y: targetCenter.y },
+                targetIntersect,
+            ];
+            return shortenPathEnd(waypoints, MARKER_SHORTENING);
+        }
+    }
+}
+/**
+ * Build a path from a source node to a subgraph boundary (incoming).
+ * Always enters at TOP of subgraph (like a regular node in TB layout).
+ * Uses LEFT portion of top edge (outgoing edges use RIGHT portion).
+ * @param edgeOffset - Horizontal offset to spread multiple edges apart
+ * @param totalEdges - Total number of incoming edges (for spreading calculation)
+ */
+function buildSubgraphIncomingPath(sourceCenter, sourceShape, subgraphBounds, borderRadius, edgeOffset = 0, totalEdges = 1) {
+    const subgraphTop = subgraphBounds.y;
+    const subgraphCenterX = subgraphBounds.x + subgraphBounds.width / 2;
+    const subgraphCenterY = subgraphBounds.y + subgraphBounds.height / 2;
+    // Spread edges across LEFT portion of top (outgoing uses RIGHT portion)
+    const spreadWidth = subgraphBounds.width * 0.3;
+    const slotSpacing = totalEdges > 1 ? spreadWidth / (totalEdges - 1) : 0;
+    // Start from center-left of top edge
+    const startX = subgraphCenterX - subgraphBounds.width * 0.1 - spreadWidth;
+    const entryX = totalEdges > 1 ? startX + edgeOffset * slotSpacing : subgraphCenterX - subgraphBounds.width * 0.15;
+    // Entry point at top of subgraph
+    const entryPoint = { x: entryX, y: subgraphTop };
+    // Compute intersection with source node boundary by aiming toward subgraph center
+    // This ensures the edge exits from the correct side of the source node
+    const subgraphCenter = { x: subgraphCenterX, y: subgraphCenterY };
+    const sourceIntersect = intersectNode(sourceCenter, subgraphCenter, sourceShape, borderRadius);
+    // Smooth curved path from source to entry point
+    const totalDY = entryPoint.y - sourceIntersect.y;
+    const totalDX = entryPoint.x - sourceIntersect.x;
+    const waypoints = [
+        sourceIntersect,
+        // First control: drop down from source
+        { x: sourceIntersect.x, y: sourceIntersect.y + totalDY * 0.3 },
+        // Second control: start curving toward entry
+        { x: sourceIntersect.x + totalDX * 0.3, y: sourceIntersect.y + totalDY * 0.5 },
+        // Third control: continue curving
+        { x: sourceIntersect.x + totalDX * 0.7, y: sourceIntersect.y + totalDY * 0.7 },
+        entryPoint,
+    ];
+    return waypoints;
+}
 function chooseSourceAimPoint(center, points) {
     const first = points[0];
     if (!first || points.length < 2)
@@ -108,12 +415,156 @@ function chooseTargetAimPoint(center, points) {
         Math.abs(turnDx) > Math.abs(turnDy) * 1.25;
     return lateralThenVerticalNearTarget ? prev : last;
 }
+/**
+ * Spread multiple edges arriving at the same node around its perimeter.
+ * Returns a map of edgeIndex → offset angle (radians) to apply to the intersection.
+ */
+function computeEndpointSpread(edgesByTarget) {
+    const spreadOffsets = new Map();
+    const SPREAD_ANGLE = 0.15; // radians (~8.5 degrees) between adjacent edges
+    for (const [, edges] of edgesByTarget) {
+        if (edges.length <= 1)
+            continue;
+        // Sort edges by approach angle
+        edges.sort((a, b) => a.angle - b.angle);
+        // Group edges with similar angles (within 0.2 radians / ~11 degrees)
+        const groups = [];
+        let currentGroup = [edges[0]];
+        for (let i = 1; i < edges.length; i++) {
+            const angleDiff = edges[i].angle - edges[i - 1].angle;
+            if (angleDiff < 0.2) {
+                currentGroup.push(edges[i]);
+            }
+            else {
+                groups.push(currentGroup);
+                currentGroup = [edges[i]];
+            }
+        }
+        groups.push(currentGroup);
+        // Spread edges within each group
+        for (const group of groups) {
+            if (group.length <= 1)
+                continue;
+            const centerIndex = (group.length - 1) / 2;
+            for (let i = 0; i < group.length; i++) {
+                const offset = (i - centerIndex) * SPREAD_ANGLE;
+                spreadOffsets.set(group[i].edgeIndex, offset);
+            }
+        }
+    }
+    return spreadOffsets;
+}
+/**
+ * Apply an angular offset to an intersection point, moving it along the node boundary.
+ */
+function offsetIntersectionByAngle(intersection, nodeCenter, angleOffset, nodeShape) {
+    if (Math.abs(angleOffset) < 0.001)
+        return intersection;
+    // Calculate current angle from node center to intersection
+    const dx = intersection.x - nodeCenter.x;
+    const dy = intersection.y - nodeCenter.y;
+    const currentAngle = Math.atan2(dy, dx);
+    // Apply offset
+    const newAngle = currentAngle + angleOffset;
+    // Project a point outward from center at new angle
+    const projectedPoint = {
+        x: nodeCenter.x + Math.cos(newAngle) * 1000,
+        y: nodeCenter.y + Math.sin(newAngle) * 1000,
+    };
+    // Recalculate intersection with node boundary at new angle
+    return intersectNode(nodeCenter, projectedPoint, nodeShape, 0);
+}
+/**
+ * Offset a label position perpendicular to the edge direction.
+ * This helps separate overlapping labels when multiple edges have similar paths.
+ */
+function offsetLabelPerpendicular(labelPos, edgeStart, edgeEnd, offset) {
+    if (Math.abs(offset) < 0.001)
+        return labelPos;
+    // Calculate edge direction
+    const dx = edgeEnd.x - edgeStart.x;
+    const dy = edgeEnd.y - edgeStart.y;
+    const len = Math.hypot(dx, dy);
+    if (len < 1)
+        return labelPos;
+    // Calculate perpendicular direction (rotate 90 degrees)
+    const perpX = -dy / len;
+    const perpY = dx / len;
+    // Apply offset (use offset * 12 to get visible separation)
+    return {
+        x: labelPos.x + perpX * offset * 12,
+        y: labelPos.y + perpY * offset * 12,
+    };
+}
 // ─── Edge Builder ───────────────────────────────────────────────────────────
 export function buildEdges(parsedEdges, positions, _handles, direction, theme, diamondEdgeHandles, edgeWaypoints, nodeShapes) {
     const markerSize = theme.edgeDefaults.markerSize;
     const isVertical = direction === 'TB' || direction === 'BT';
     const cardBorderRadius = parseInt(theme.radius.lg, 10) || 8;
     const branchPalette = buildBranchPalette(theme.color.orange1, theme.color.orange2, theme.color.orange3);
+    const erGap = ER_ENDPOINT_GAP;
+    // Pre-compute edge endpoint spreading for nodes with multiple incoming edges
+    const edgesByTarget = new Map();
+    const edgesBySource = new Map();
+    parsedEdges.forEach((edge, i) => {
+        const sourcePos = positions.get(edge.sourceSubgraphId ?? edge.source);
+        const targetPos = positions.get(edge.targetSubgraphId ?? edge.target);
+        if (!sourcePos || !targetPos)
+            return;
+        // Skip subgraph edges - they use different logic
+        if (edge.sourceSubgraphId || edge.targetSubgraphId)
+            return;
+        const sourceCenter = {
+            x: sourcePos.x + sourcePos.width / 2,
+            y: sourcePos.y + sourcePos.height / 2,
+            width: sourcePos.width,
+            height: sourcePos.height,
+        };
+        const targetCenter = {
+            x: targetPos.x + targetPos.width / 2,
+            y: targetPos.y + targetPos.height / 2,
+            width: targetPos.width,
+            height: targetPos.height,
+        };
+        // Angle from target to source (approach angle)
+        const approachAngle = Math.atan2(sourceCenter.y - targetCenter.y, sourceCenter.x - targetCenter.x);
+        // Angle from source to target (departure angle)
+        const departureAngle = Math.atan2(targetCenter.y - sourceCenter.y, targetCenter.x - sourceCenter.x);
+        const targetKey = edge.targetSubgraphId ?? edge.target;
+        const targetEdges = edgesByTarget.get(targetKey) ?? [];
+        targetEdges.push({ edgeIndex: i, angle: approachAngle, sourceCenter });
+        edgesByTarget.set(targetKey, targetEdges);
+        const sourceKey = edge.sourceSubgraphId ?? edge.source;
+        const sourceEdges = edgesBySource.get(sourceKey) ?? [];
+        sourceEdges.push({ edgeIndex: i, angle: departureAngle, sourceCenter: targetCenter });
+        edgesBySource.set(sourceKey, sourceEdges);
+    });
+    const targetSpreadOffsets = computeEndpointSpread(edgesByTarget);
+    const sourceSpreadOffsets = computeEndpointSpread(edgesBySource);
+    // Detect bidirectional edge pairs (A→B and B→A) for label separation
+    // These edges have opposite directions so they won't be caught by the angle-based spreading
+    const bidirectionalLabelOffset = new Map();
+    const edgePairKey = (a, b) => a < b ? `${a}:${b}` : `${b}:${a}`;
+    const edgePairs = new Map(); // pairKey → [edgeIndex1, edgeIndex2, ...]
+    parsedEdges.forEach((edge, i) => {
+        if (edge.sourceSubgraphId || edge.targetSubgraphId)
+            return;
+        const key = edgePairKey(edge.source, edge.target);
+        const existing = edgePairs.get(key) ?? [];
+        existing.push(i);
+        edgePairs.set(key, existing);
+    });
+    // For each pair with multiple edges, assign alternating offsets
+    for (const [, indices] of edgePairs) {
+        if (indices.length <= 1)
+            continue;
+        const centerIndex = (indices.length - 1) / 2;
+        indices.forEach((edgeIdx, i) => {
+            // Offset alternates: -1, +1 for pair; -1.5, 0, +1.5 for triple, etc.
+            const offset = (i - centerIndex) * 1.5;
+            bidirectionalLabelOffset.set(edgeIdx, offset);
+        });
+    }
     // Build handle slot maps for forward edges
     const forwardBySource = new Map();
     const forwardByTarget = new Map();
@@ -148,6 +599,21 @@ export function buildEdges(parsedEdges, positions, _handles, direction, theme, d
     const SIDE_SLOTS = 5;
     const backSourceCounters = new Map();
     const backTargetCounters = new Map();
+    // Track subgraph edge counts for spreading
+    const subgraphOutgoingCounts = new Map();
+    const subgraphIncomingCounts = new Map();
+    // Pre-count edges per subgraph to compute offsets
+    for (const edge of parsedEdges) {
+        if (edge.sourceSubgraphId) {
+            subgraphOutgoingCounts.set(edge.sourceSubgraphId, (subgraphOutgoingCounts.get(edge.sourceSubgraphId) ?? 0) + 1);
+        }
+        if (edge.targetSubgraphId) {
+            subgraphIncomingCounts.set(edge.targetSubgraphId, (subgraphIncomingCounts.get(edge.targetSubgraphId) ?? 0) + 1);
+        }
+    }
+    // Track current index for each subgraph to assign offsets
+    const subgraphOutgoingIndex = new Map();
+    const subgraphIncomingIndex = new Map();
     return parsedEdges.map((edge, i) => {
         const sourcePos = positions.get(edge.sourceSubgraphId ?? edge.source);
         const targetPos = positions.get(edge.targetSubgraphId ?? edge.target);
@@ -164,15 +630,79 @@ export function buildEdges(parsedEdges, positions, _handles, direction, theme, d
         // so no path shortening needed.
         const isErEdge = edge.cardSource || edge.cardTarget;
         const isMindmapEdge = !!edge.noArrow;
-        const shortenEnd = isErEdge ? ER_PATH_GAP : (isMindmapEdge ? 0 : MARKER_SHORTENING);
-        const shortenStart = isErEdge ? ER_PATH_GAP : 0;
+        const shortenEnd = isErEdge ? erGap : (isMindmapEdge ? 0 : MARKER_SHORTENING);
+        const shortenStart = isErEdge ? erGap : 0;
         // Track path endpoints + angles for ER cardinality symbols
         let pathStart;
         let pathEnd;
         let startAngle = 0; // angle toward source node (radians)
         let endAngle = 0; // angle toward target node (radians)
         let routePointsForLive;
-        if (waypoints && waypoints.points.length > 0 && sourcePos && targetPos) {
+        // Special handling for subgraph edges - build path from scratch
+        if (edge.sourceSubgraphId && sourcePos && targetPos) {
+            const subgraphBounds = positions.get(edge.sourceSubgraphId);
+            if (subgraphBounds) {
+                // Compute offset to spread multiple edges from same subgraph
+                const totalOutgoing = subgraphOutgoingCounts.get(edge.sourceSubgraphId) ?? 1;
+                const currentIndex = subgraphOutgoingIndex.get(edge.sourceSubgraphId) ?? 0;
+                subgraphOutgoingIndex.set(edge.sourceSubgraphId, currentIndex + 1);
+                // Center the offsets: for 3 edges, offsets are -1, 0, 1
+                const edgeOffset = currentIndex - Math.floor((totalOutgoing - 1) / 2);
+                if (DEBUG_SUBGRAPH_EDGES) {
+                    console.log(`[SUBGRAPH OUTGOING] ${edge.source} → ${edge.target} (label: ${edge.label})`);
+                    console.log(`  subgraphBounds: x=${subgraphBounds.x.toFixed(0)}, y=${subgraphBounds.y.toFixed(0)}, w=${subgraphBounds.width.toFixed(0)}, h=${subgraphBounds.height.toFixed(0)}`);
+                    console.log(`  targetPos: x=${targetPos.x.toFixed(0)}, y=${targetPos.y.toFixed(0)}, w=${targetPos.width.toFixed(0)}, h=${targetPos.height.toFixed(0)}`);
+                    console.log(`  edgeOffset: ${edgeOffset} (${currentIndex + 1} of ${totalOutgoing})`);
+                }
+                const targetCenter = {
+                    x: targetPos.x + targetPos.width / 2,
+                    y: targetPos.y + targetPos.height / 2,
+                    width: targetPos.width,
+                    height: targetPos.height,
+                };
+                // Build path from subgraph boundary to target
+                const pathPoints = buildSubgraphOutgoingPath(subgraphBounds, targetCenter, targetShape, cardBorderRadius, currentIndex, totalOutgoing);
+                if (DEBUG_SUBGRAPH_EDGES) {
+                    console.log(`  pathPoints:`, JSON.stringify(pathPoints.map(p => `(${p.x.toFixed(0)},${p.y.toFixed(0)})`)));
+                }
+                labelPos = computeLabelPosition(pathPoints);
+                svgPath = generateBasisPath(pathPoints);
+                routePointsForLive = pathPoints;
+                pathStart = pathPoints[0];
+                pathEnd = pathPoints[pathPoints.length - 1];
+                startAngle = Math.atan2(pathPoints[0].y - pathPoints[1].y, pathPoints[0].x - pathPoints[1].x);
+                endAngle = Math.atan2(pathPoints[pathPoints.length - 1].y - pathPoints[pathPoints.length - 2].y, pathPoints[pathPoints.length - 1].x - pathPoints[pathPoints.length - 2].x);
+            }
+        }
+        else if (edge.targetSubgraphId && sourcePos && targetPos) {
+            const subgraphBounds = positions.get(edge.targetSubgraphId);
+            if (subgraphBounds) {
+                // Compute offset to spread multiple edges entering same subgraph
+                const totalIncoming = subgraphIncomingCounts.get(edge.targetSubgraphId) ?? 1;
+                const currentIndex = subgraphIncomingIndex.get(edge.targetSubgraphId) ?? 0;
+                subgraphIncomingIndex.set(edge.targetSubgraphId, currentIndex + 1);
+                if (DEBUG_SUBGRAPH_EDGES) {
+                    console.log(`[SUBGRAPH INCOMING] ${edge.source} → ${edge.target} (label: ${edge.label})`);
+                    console.log(`  edgeIndex: ${currentIndex} of ${totalIncoming}`);
+                }
+                const sourceCenter = {
+                    x: sourcePos.x + sourcePos.width / 2,
+                    y: sourcePos.y + sourcePos.height / 2,
+                    width: sourcePos.width,
+                    height: sourcePos.height,
+                };
+                // Build path from source to subgraph boundary
+                const pathPoints = buildSubgraphIncomingPath(sourceCenter, sourceShape, subgraphBounds, cardBorderRadius, currentIndex, totalIncoming);
+                labelPos = computeLabelPosition(pathPoints);
+                svgPath = generateBasisPath(pathPoints);
+                routePointsForLive = pathPoints;
+                pathStart = pathPoints[0];
+                pathEnd = pathPoints[pathPoints.length - 1];
+                startAngle = Math.atan2(pathPoints[0].y - pathPoints[1].y, pathPoints[0].x - pathPoints[1].x);
+                endAngle = Math.atan2(pathPoints[pathPoints.length - 1].y - pathPoints[pathPoints.length - 2].y, pathPoints[pathPoints.length - 1].x - pathPoints[pathPoints.length - 2].x);
+            }
+        }
+        else if (waypoints && waypoints.points.length > 0 && sourcePos && targetPos) {
             const sourceCenter = {
                 x: sourcePos.x + sourcePos.width / 2,
                 y: sourcePos.y + sourcePos.height / 2,
@@ -189,20 +719,47 @@ export function buildEdges(parsedEdges, positions, _handles, direction, theme, d
             // Determine if dagre's waypoints deviate from a straight source→target line.
             // Back/lateral edges always use waypoints (they need routing to avoid overlap).
             // Forward edges use waypoints only if they deviate significantly from straight.
-            // For ER, always keep dagre waypoint routing so curves stay natural.
-            // The straight-forward shortcut makes ER edges look too angular.
-            const isSimpleForward = !isErEdge && !edge.noArrow && edgeClass === 'forward' && !waypointsDeviate(rawPoints, 20);
+            // ER edges also use the simple path when waypoints are nearly straight — this
+            // ensures the path endpoints match the measured node boundaries rather than
+            // relying on dagre waypoints (which may be stale after relayout).
+            const isSimpleForward = !edge.noArrow && edgeClass === 'forward' && !waypointsDeviate(rawPoints, 20);
             if (isSimpleForward) {
                 // Simple forward edge: straight line from source boundary to target boundary.
-                const startIntersect = intersectNode(sourceCenter, targetCenter, sourceShape, isErEdge ? cardBorderRadius : 0);
-                const endIntersect = intersectNode(targetCenter, sourceCenter, targetShape, isErEdge ? cardBorderRadius : 0);
+                let startIntersect = intersectNode(sourceCenter, targetCenter, sourceShape, isErEdge ? cardBorderRadius : 0);
+                let endIntersect = intersectNode(targetCenter, sourceCenter, targetShape, isErEdge ? cardBorderRadius : 0);
+                // Apply endpoint spreading for nodes with multiple edges
+                const sourceSpreadOffset = sourceSpreadOffsets.get(i);
+                const targetSpreadOffset = targetSpreadOffsets.get(i);
+                if (sourceSpreadOffset !== undefined) {
+                    startIntersect = offsetIntersectionByAngle(startIntersect, sourceCenter, sourceSpreadOffset, sourceShape);
+                }
+                if (targetSpreadOffset !== undefined) {
+                    endIntersect = offsetIntersectionByAngle(endIntersect, targetCenter, targetSpreadOffset, targetShape);
+                }
+                if (DEBUG_ER && isErEdge) {
+                    console.log(`[ER SIMPLE] ${edge.source} → ${edge.target}`);
+                    console.log(`  sourcePos: top=${sourcePos.y}, height=${sourcePos.height}, bottom=${sourcePos.y + sourcePos.height}`);
+                    console.log(`  sourceCenter: (${sourceCenter.x}, ${sourceCenter.y}), w=${sourceCenter.width}, h=${sourceCenter.height}`);
+                    console.log(`  startIntersect: (${startIntersect.x}, ${startIntersect.y})`);
+                    console.log(`  targetPos: top=${targetPos.y}, height=${targetPos.height}`);
+                    console.log(`  endIntersect: (${endIntersect.x}, ${endIntersect.y})`);
+                    console.log(`  [DEBUG] positions map size: ${positions.size}, positions source entry:`, positions.get(edge.source));
+                    console.log(`  sourceSpreadOffset: ${sourceSpreadOffset}, targetSpreadOffset: ${targetSpreadOffset}`);
+                }
                 let finalPoints = [startIntersect, endIntersect];
                 finalPoints = shortenPathStart(finalPoints, shortenStart);
                 finalPoints = shortenPathEnd(finalPoints, shortenEnd);
                 if (isErEdge) {
-                    finalPoints = clampErEndpoints(finalPoints, sourceCenter, targetCenter, sourceShape, targetShape, cardBorderRadius, ER_PATH_GAP);
+                    finalPoints = clampErEndpoints(finalPoints, sourceCenter, targetCenter, sourceShape, targetShape, cardBorderRadius, erGap);
                 }
                 labelPos = computeLabelPosition(finalPoints);
+                // Offset label perpendicular to edge direction for overlapping edges
+                const combinedSpreadOffset = (sourceSpreadOffset ?? 0) + (targetSpreadOffset ?? 0);
+                const biDirOffset = bidirectionalLabelOffset.get(i) ?? 0;
+                const totalLabelOffset = combinedSpreadOffset + biDirOffset;
+                if (totalLabelOffset !== 0) {
+                    labelPos = offsetLabelPerpendicular(labelPos, finalPoints[0], finalPoints[finalPoints.length - 1], totalLabelOffset);
+                }
                 svgPath = `M${finalPoints[0].x},${finalPoints[0].y}L${finalPoints[1].x},${finalPoints[1].y}`;
                 routePointsForLive = finalPoints;
                 // Compute endpoint angles for ER cardinality symbols
@@ -221,22 +778,44 @@ export function buildEdges(parsedEdges, positions, _handles, direction, theme, d
                 // Dagre waypoints are based on estimated node sizes. After React Flow
                 // measurement, ER/Class nodes can be taller; trim any near-end waypoints
                 // that now fall inside source/target node bounds to prevent edge overlap.
-                while (innerPoints.length > 0 && pointInsideNodeBounds(innerPoints[0], sourceCenter)) {
+                const trimEps = isErEdge ? (erGap + 0.5) : 0.5;
+                while (innerPoints.length > 0 && pointInsideNodeBounds(innerPoints[0], sourceCenter, trimEps)) {
                     innerPoints.shift();
                 }
-                while (innerPoints.length > 0 && pointInsideNodeBounds(innerPoints[innerPoints.length - 1], targetCenter)) {
+                while (innerPoints.length > 0 && pointInsideNodeBounds(innerPoints[innerPoints.length - 1], targetCenter, trimEps)) {
                     innerPoints.pop();
                 }
                 if (innerPoints.length === 0) {
-                    const startIntersect = intersectNode(sourceCenter, targetCenter, sourceShape, isErEdge ? cardBorderRadius : 0);
-                    const endIntersect = intersectNode(targetCenter, sourceCenter, targetShape, isErEdge ? cardBorderRadius : 0);
+                    let startIntersect = intersectNode(sourceCenter, targetCenter, sourceShape, isErEdge ? cardBorderRadius : 0);
+                    let endIntersect = intersectNode(targetCenter, sourceCenter, targetShape, isErEdge ? cardBorderRadius : 0);
+                    // Apply endpoint spreading for nodes with multiple edges
+                    const sourceSpreadOffset = sourceSpreadOffsets.get(i);
+                    const targetSpreadOffset = targetSpreadOffsets.get(i);
+                    if (sourceSpreadOffset !== undefined) {
+                        startIntersect = offsetIntersectionByAngle(startIntersect, sourceCenter, sourceSpreadOffset, sourceShape);
+                    }
+                    if (targetSpreadOffset !== undefined) {
+                        endIntersect = offsetIntersectionByAngle(endIntersect, targetCenter, targetSpreadOffset, targetShape);
+                    }
+                    if (DEBUG_ER && isErEdge) {
+                        console.log(`[ER TRIMMED-TO-DIRECT] ${edge.source} → ${edge.target}`);
+                        console.log(`  sourcePos: top=${sourcePos.y}, height=${sourcePos.height}, bottom=${sourcePos.y + sourcePos.height}`);
+                        console.log(`  startIntersect: (${startIntersect.x}, ${startIntersect.y})`);
+                    }
                     let finalPoints = [startIntersect, endIntersect];
                     finalPoints = shortenPathStart(finalPoints, shortenStart);
                     finalPoints = shortenPathEnd(finalPoints, shortenEnd);
                     if (isErEdge) {
-                        finalPoints = clampErEndpoints(finalPoints, sourceCenter, targetCenter, sourceShape, targetShape, cardBorderRadius, ER_PATH_GAP);
+                        finalPoints = clampErEndpoints(finalPoints, sourceCenter, targetCenter, sourceShape, targetShape, cardBorderRadius, erGap);
                     }
                     labelPos = computeLabelPosition(finalPoints);
+                    // Offset label perpendicular to edge direction for overlapping edges
+                    const combinedSpreadOffset = (sourceSpreadOffset ?? 0) + (targetSpreadOffset ?? 0);
+                    const biDirOffset = bidirectionalLabelOffset.get(i) ?? 0;
+                    const totalLabelOffset = combinedSpreadOffset + biDirOffset;
+                    if (totalLabelOffset !== 0) {
+                        labelPos = offsetLabelPerpendicular(labelPos, finalPoints[0], finalPoints[finalPoints.length - 1], totalLabelOffset);
+                    }
                     svgPath = `M${finalPoints[0].x},${finalPoints[0].y}L${finalPoints[1].x},${finalPoints[1].y}`;
                     routePointsForLive = finalPoints;
                     pathStart = finalPoints[0];
@@ -245,21 +824,48 @@ export function buildEdges(parsedEdges, positions, _handles, direction, theme, d
                     endAngle = Math.atan2(finalPoints[finalPoints.length - 1].y - finalPoints[finalPoints.length - 2].y, finalPoints[finalPoints.length - 1].x - finalPoints[finalPoints.length - 2].x);
                 }
                 else {
-                    const sourceAim = isErEdge ? chooseSourceAimPoint(sourceCenter, innerPoints) : innerPoints[0];
-                    const targetAim = isErEdge ? chooseTargetAimPoint(targetCenter, innerPoints) : innerPoints[innerPoints.length - 1];
-                    const startIntersect = intersectNode(sourceCenter, sourceAim, sourceShape, isErEdge ? cardBorderRadius : 0);
-                    const endIntersect = intersectNode(targetCenter, targetAim, targetShape, isErEdge ? cardBorderRadius : 0);
+                    // For non-simple routes, compute intersections using the actual waypoint
+                    // directions, not a chosen "aim point" that may be far from the entry angle.
+                    const firstInner = innerPoints[0];
+                    const lastInner = innerPoints[innerPoints.length - 1];
+                    let startIntersect = intersectNode(sourceCenter, firstInner, sourceShape, isErEdge ? cardBorderRadius : 0);
+                    let endIntersect = intersectNode(targetCenter, lastInner, targetShape, isErEdge ? cardBorderRadius : 0);
+                    // Apply endpoint spreading for nodes with multiple edges (smaller offset for routed edges)
+                    const sourceSpreadOffset = sourceSpreadOffsets.get(i);
+                    const targetSpreadOffset = targetSpreadOffsets.get(i);
+                    if (sourceSpreadOffset !== undefined) {
+                        startIntersect = offsetIntersectionByAngle(startIntersect, sourceCenter, sourceSpreadOffset * 0.5, sourceShape);
+                    }
+                    if (targetSpreadOffset !== undefined) {
+                        endIntersect = offsetIntersectionByAngle(endIntersect, targetCenter, targetSpreadOffset * 0.5, targetShape);
+                    }
+                    if (DEBUG_ER && isErEdge) {
+                        console.log(`[ER COMPLEX] ${edge.source} → ${edge.target}`);
+                        console.log(`  sourcePos: top=${sourcePos.y}, height=${sourcePos.height}, bottom=${sourcePos.y + sourcePos.height}`);
+                        console.log(`  sourceCenter: (${sourceCenter.x}, ${sourceCenter.y})`);
+                        console.log(`  firstInner waypoint: (${firstInner.x}, ${firstInner.y})`);
+                        console.log(`  startIntersect: (${startIntersect.x}, ${startIntersect.y})`);
+                        console.log(`  Is startIntersect.y inside node? ${startIntersect.y < sourcePos.y + sourcePos.height ? 'YES - BUG!' : 'no'}`);
+                    }
                     let finalPoints = [startIntersect, ...innerPoints, endIntersect];
                     finalPoints = shortenPathStart(finalPoints, shortenStart);
                     finalPoints = shortenPathEnd(finalPoints, shortenEnd);
                     if (isErEdge) {
-                        finalPoints = clampErEndpoints(finalPoints, sourceCenter, targetCenter, sourceShape, targetShape, cardBorderRadius, ER_PATH_GAP);
+                        finalPoints = clampErEndpoints(finalPoints, sourceCenter, targetCenter, sourceShape, targetShape, cardBorderRadius, erGap);
                     }
                     labelPos = computeLabelPosition(finalPoints);
+                    // Offset label perpendicular to edge direction for overlapping edges (smaller factor for routed)
+                    const combinedSpreadOffset = ((sourceSpreadOffset ?? 0) + (targetSpreadOffset ?? 0)) * 0.5;
+                    const biDirOffset = bidirectionalLabelOffset.get(i) ?? 0;
+                    const totalLabelOffset = combinedSpreadOffset + biDirOffset;
+                    if (totalLabelOffset !== 0) {
+                        labelPos = offsetLabelPerpendicular(labelPos, finalPoints[0], finalPoints[finalPoints.length - 1], totalLabelOffset);
+                    }
                     // For ER, keep middle smoothing but force straight start/end segments.
                     // This stabilizes endpoint tangent (for cardinality symbols) and
                     // prevents spline overshoot from visually re-entering node bounds.
                     if (edge.noArrow) {
+                        // Mindmap edges: rounded corners for organic feel
                         if (finalPoints.length === 3) {
                             const [p0, c, p2] = finalPoints;
                             svgPath = `M${p0.x},${p0.y}Q${c.x},${c.y},${p2.x},${p2.y}`;
@@ -269,7 +875,11 @@ export function buildEdges(parsedEdges, positions, _handles, direction, theme, d
                         }
                     }
                     else {
-                        svgPath = generateSmoothPath(finalPoints, !!isErEdge);
+                        // All edges (including ER): B-spline for smooth, flowing curves.
+                        // B-splines approximate control points rather than passing through them,
+                        // which naturally smooths out dagre's sharp orthogonal waypoints.
+                        // The function ensures exact start/end points for proper node connection.
+                        svgPath = generateBasisPath(finalPoints);
                     }
                     routePointsForLive = finalPoints;
                     // Compute endpoint angles for ER cardinality symbols
@@ -280,10 +890,57 @@ export function buildEdges(parsedEdges, positions, _handles, direction, theme, d
                 }
             }
         }
+        // Fallback: if no waypoints were provided or path wasn't computed,
+        // generate a simple direct path from source to target boundary.
+        if (svgPath === '' && sourcePos && targetPos) {
+            const sourceCenter = {
+                x: sourcePos.x + sourcePos.width / 2,
+                y: sourcePos.y + sourcePos.height / 2,
+                width: sourcePos.width,
+                height: sourcePos.height,
+            };
+            const targetCenter = {
+                x: targetPos.x + targetPos.width / 2,
+                y: targetPos.y + targetPos.height / 2,
+                width: targetPos.width,
+                height: targetPos.height,
+            };
+            let startIntersect = intersectNode(sourceCenter, targetCenter, sourceShape, 0);
+            let endIntersect = intersectNode(targetCenter, sourceCenter, targetShape, 0);
+            // Apply endpoint spreading for nodes with multiple edges
+            const sourceSpreadOffset = sourceSpreadOffsets.get(i);
+            const targetSpreadOffset = targetSpreadOffsets.get(i);
+            if (sourceSpreadOffset !== undefined) {
+                startIntersect = offsetIntersectionByAngle(startIntersect, sourceCenter, sourceSpreadOffset, sourceShape);
+            }
+            if (targetSpreadOffset !== undefined) {
+                endIntersect = offsetIntersectionByAngle(endIntersect, targetCenter, targetSpreadOffset, targetShape);
+            }
+            let finalPoints = [startIntersect, endIntersect];
+            finalPoints = shortenPathEnd(finalPoints, MARKER_SHORTENING);
+            labelPos = computeLabelPosition(finalPoints);
+            // Offset label perpendicular to edge direction for overlapping edges
+            const combinedSpreadOffset = (sourceSpreadOffset ?? 0) + (targetSpreadOffset ?? 0);
+            const biDirOffset = bidirectionalLabelOffset.get(i) ?? 0;
+            const totalLabelOffset = combinedSpreadOffset + biDirOffset;
+            if (totalLabelOffset !== 0) {
+                labelPos = offsetLabelPerpendicular(labelPos, finalPoints[0], finalPoints[finalPoints.length - 1], totalLabelOffset);
+            }
+            svgPath = `M${finalPoints[0].x},${finalPoints[0].y}L${finalPoints[1].x},${finalPoints[1].y}`;
+        }
         // ── Handle assignment ──
         let sourceHandle;
         let targetHandle;
-        if (isErEdge && sourcePos && targetPos) {
+        // Subgraph edges: force top/bottom handles so edges enter/exit subgraphs vertically
+        const isSubgraphSource = !!edge.sourceSubgraphId;
+        const isSubgraphTarget = !!edge.targetSubgraphId;
+        if ((isSubgraphSource || isSubgraphTarget) && sourcePos && targetPos) {
+            // Edges to/from subgraphs should use vertical (forward-style) handles
+            // Source exits from bottom, target enters from top
+            sourceHandle = 'fw-source-0';
+            targetHandle = 'fw-target-0';
+        }
+        else if (isErEdge && sourcePos && targetPos) {
             // ER-specific handle strategy:
             // prefer side handles for lateral/diagonal links, top/bottom for vertical links.
             const srcCX = sourcePos.x + sourcePos.width / 2;
@@ -371,8 +1028,7 @@ export function buildEdges(parsedEdges, positions, _handles, direction, theme, d
             labelBgBorderRadius: theme.edgeDefaults.labelBgBorderRadius,
             sourceHandle,
             targetHandle,
-            // Keep edges above subgraph backgrounds but below regular nodes.
-            // (Regular nodes set zIndex=10; subgraphs set zIndex=0.)
+            // Default: edges above subgraph backgrounds but below nodes.
             zIndex: 1,
             data: {
                 svgPath,