@synergenius/flow-weaver 0.33.0 → 0.33.2

package/dist/diagram/orthogonal-router.js

@@ -1,163 +1,51 @@
 /**
  * Orthogonal connection router for SVG diagram rendering.
  *
- * Ported from the original React-based editor's orthogonalRouter.ts.
- * Removed gl-matrix dependency — uses plain [number, number] tuples.
- *
- * Features:
- * - L-shape and S-shape routing with rounded corners
- * - Node collision avoidance via inflated bounding boxes
- * - Track allocator prevents parallel connections from overlapping
- * - Crossing minimization (evaluates up to 11 candidates per allocation)
- * - Per-port-index stub spacing
- * - Waypoint simplification (collinear removal, jog collapse)
- * - Backward/self connection escape routing
+ * 1-1 port of the platform's orthogonalRouter.ts.
+ * Only change: removed gl-matrix dependency — uses plain [number, number] tuples.
  */
-// Minimum spacing between parallel horizontal segments (px)
 const TRACK_SPACING = 15;
-// Clearance from inflated box edges when routing around nodes (px).
 const EDGE_OFFSET = 5;
-// ─── Track allocator ───
-// Maximum free candidates to evaluate in each direction for crossing minimization.
-const MAX_CANDIDATES = 5;
+// Nudge the initial candidate Y downward so paths prefer routing below obstacles.
+const BELOW_BIAS = 40;
+// ─── Track Allocator ───
+/**
+ * Prevents connections from running on the same horizontal track.
+ * Create one instance per render batch and pass it to all routing calls.
+ * Tracks are snapped to TRACK_SPACING grid; only connections whose X corridors
+ * overlap can conflict.
+ */
 export class TrackAllocator {
-    claims = [];
-    verticalClaims = [];
-    /** Check if a Y value is too close to any claimed segment whose X range overlaps. */
-    isOccupied(xMin, xMax, y) {
-        for (const c of this.claims) {
-            if (c.xMin < xMax && c.xMax > xMin && Math.abs(c.y - y) < TRACK_SPACING) {
-                return true;
-            }
-        }
-        return false;
-    }
-    /** Check if an X value is too close to any claimed vertical segment whose Y range overlaps. */
-    isOccupiedVertical(yMin, yMax, x) {
-        for (const c of this.verticalClaims) {
-            if (c.yMin < yMax && c.yMax > yMin && Math.abs(c.x - x) < TRACK_SPACING) {
-                return true;
-            }
-        }
-        return false;
-    }
-    /** Check if a horizontal segment at Y passes through any inflated node box. */
-    isBlockedByNode(xMin, xMax, y, boxes) {
-        for (const box of boxes) {
-            if (xMin < box.right && xMax > box.left && y >= box.top && y <= box.bottom) {
-                return true;
-            }
-        }
-        return false;
-    }
-    /** Check if a vertical segment at X passes through any inflated node box. */
-    isBlockedByNodeVertical(yMin, yMax, x, boxes) {
-        for (const box of boxes) {
-            if (x >= box.left && x <= box.right && yMin < box.bottom && yMax > box.top) {
-                return true;
-            }
-        }
-        return false;
-    }
-    /** Count claimed vertical segments that a horizontal segment at Y would cross. */
-    countHorizontalCrossings(xMin, xMax, y) {
-        let count = 0;
-        for (const c of this.verticalClaims) {
-            if (c.x > xMin && c.x < xMax && y >= c.yMin && y <= c.yMax) {
-                count++;
-            }
-        }
-        return count;
-    }
-    /** Count claimed horizontal segments that a vertical segment at X would cross. */
-    countVerticalCrossings(yMin, yMax, x) {
-        let count = 0;
-        for (const c of this.claims) {
-            if (c.y > yMin && c.y < yMax && x >= c.xMin && x <= c.xMax) {
-                count++;
-            }
-        }
-        return count;
-    }
-    /**
-     * Find the nearest free Y to candidateY in the given X range, preferring fewer crossings.
-     * When nodeBoxes is provided, candidates inside inflated node boxes are rejected (hard constraint).
-     */
-    findFreeY(xMin, xMax, candidateY, nodeBoxes) {
-        const isFree = (y) => !this.isOccupied(xMin, xMax, y) &&
-            (!nodeBoxes || !this.isBlockedByNode(xMin, xMax, y, nodeBoxes));
-        if (isFree(candidateY))
-            return candidateY;
-        const candidates = [];
-        for (let offset = TRACK_SPACING; offset < 800 && candidates.length < MAX_CANDIDATES * 2; offset += TRACK_SPACING) {
-            const above = candidateY - offset;
-            if (isFree(above)) {
-                candidates.push({ y: above, dist: offset });
-            }
-            const below = candidateY + offset;
-            if (isFree(below)) {
-                candidates.push({ y: below, dist: offset });
-            }
-        }
-        if (candidates.length === 0)
-            return candidateY;
-        let bestY = candidates[0].y;
-        let bestCrossings = this.countHorizontalCrossings(xMin, xMax, candidates[0].y);
-        let bestDist = candidates[0].dist;
-        for (let i = 1; i < candidates.length; i++) {
-            const c = candidates[i];
-            const crossings = this.countHorizontalCrossings(xMin, xMax, c.y);
-            if (crossings < bestCrossings || (crossings === bestCrossings && c.dist < bestDist)) {
-                bestY = c.y;
-                bestCrossings = crossings;
-                bestDist = c.dist;
-            }
-        }
-        return bestY;
-    }
-    /**
-     * Find the nearest free X to candidateX in the given Y range, preferring fewer crossings.
-     * When nodeBoxes is provided, candidates inside inflated node boxes are rejected (hard constraint).
-     */
-    findFreeX(yMin, yMax, candidateX, nodeBoxes) {
-        const isFree = (x) => !this.isOccupiedVertical(yMin, yMax, x) &&
-            (!nodeBoxes || !this.isBlockedByNodeVertical(yMin, yMax, x, nodeBoxes));
-        if (isFree(candidateX))
-            return candidateX;
-        const candidates = [];
-        for (let offset = TRACK_SPACING; offset < 800 && candidates.length < MAX_CANDIDATES * 2; offset += TRACK_SPACING) {
-            const left = candidateX - offset;
-            if (isFree(left)) {
-                candidates.push({ x: left, dist: offset });
-            }
-            const right = candidateX + offset;
-            if (isFree(right)) {
-                candidates.push({ x: right, dist: offset });
-            }
-        }
-        if (candidates.length === 0)
-            return candidateX;
-        let bestX = candidates[0].x;
-        let bestCrossings = this.countVerticalCrossings(yMin, yMax, candidates[0].x);
-        let bestDist = candidates[0].dist;
-        for (let i = 1; i < candidates.length; i++) {
-            const c = candidates[i];
-            const crossings = this.countVerticalCrossings(yMin, yMax, c.x);
-            if (crossings < bestCrossings || (crossings === bestCrossings && c.dist < bestDist)) {
-                bestX = c.x;
-                bestCrossings = crossings;
-                bestDist = c.dist;
+    claims = new Map();
+    claim(xMin, xMax, candidateY) {
+        const snap = (y) => Math.round(y / TRACK_SPACING) * TRACK_SPACING;
+        const overlaps = (slot) => {
+            const intervals = this.claims.get(slot);
+            if (!intervals)
+                return false;
+            return intervals.some(([a, b]) => xMin < b && xMax > a);
+        };
+        const take = (slot) => {
+            if (!this.claims.has(slot))
+                this.claims.set(slot, []);
+            const slotClaims = this.claims.get(slot);
+            if (slotClaims)
+                slotClaims.push([xMin, xMax]);
+            return slot;
+        };
+        const base = snap(candidateY);
+        // Search outward, preferring below (positive direction) on each step.
+        for (let i = 0; i < 60; i++) {
+            const below = base + i * TRACK_SPACING;
+            if (!overlaps(below))
+                return take(below);
+            if (i > 0) {
+                const above = base - i * TRACK_SPACING;
+                if (!overlaps(above))
+                    return take(above);
             }
         }
-        return bestX;
-    }
-    /** Claim a horizontal segment so later connections avoid it. */
-    claim(xMin, xMax, y) {
-        this.claims.push({ xMin, xMax, y });
-    }
-    /** Claim a vertical segment so later connections avoid it. */
-    claimVertical(yMin, yMax, x) {
-        this.verticalClaims.push({ yMin, yMax, x });
+        return candidateY;
     }
 }
 // ─── Node avoidance helpers ───
@@ -209,7 +97,8 @@ function findClearY(xMin, xMax, candidateY, boxes) {
     if (bestDist === Infinity) {
         const allMin = Math.min(...edges) - EDGE_OFFSET * 2;
         const allMax = Math.max(...edges) + EDGE_OFFSET * 2;
-        bestY = Math.abs(allMin - candidateY) <= Math.abs(allMax - candidateY) ? allMin : allMax;
+        bestY = Math.abs(allMin - candidateY) < Math.abs(allMax - candidateY) ? allMin : allMax;
+        // Verify the extreme fallback is actually clear; search outward if not
         if (isBlocked(bestY)) {
             for (let offset = TRACK_SPACING; offset < 800; offset += TRACK_SPACING) {
                 if (!isBlocked(bestY - offset)) {
@@ -227,6 +116,7 @@ function findClearY(xMin, xMax, candidateY, boxes) {
 }
 /**
  * Find an X clear of node boxes for a vertical segment spanning [yMin, yMax].
+ * Mirror of findClearY for the vertical axis.
  */
 function findClearX(yMin, yMax, candidateX, boxes) {
     const isBlocked = (x) => boxes.some((box) => x >= box.left && x <= box.right && yMin < box.bottom && yMax > box.top);
@@ -259,6 +149,7 @@ function findClearX(yMin, yMax, candidateX, boxes) {
         const allMin = Math.min(...edges) - EDGE_OFFSET * 2;
         const allMax = Math.max(...edges) + EDGE_OFFSET * 2;
         bestX = Math.abs(allMin - candidateX) <= Math.abs(allMax - candidateX) ? allMin : allMax;
+        // Verify the extreme fallback is actually clear; search outward if not
         if (isBlocked(bestX)) {
             for (let offset = TRACK_SPACING; offset < 800; offset += TRACK_SPACING) {
                 if (!isBlocked(bestX - offset)) {
@@ -275,7 +166,9 @@ function findClearX(yMin, yMax, candidateX, boxes) {
     return bestX;
 }
 // ─── Waypoint utilities ───
+// Minimum segment length: segments shorter than this are collapsed.
 const MIN_SEGMENT_LENGTH = 3;
+// Minimum acceptable vertical/horizontal jog height/width.
 const JOG_THRESHOLD = 10;
 /** Remove collinear, duplicate, tiny-jog, and very-short-segment waypoints. */
 function simplifyWaypoints(waypoints) {
@@ -288,35 +181,40 @@ function simplifyWaypoints(waypoints) {
         jogFound = false;
         for (let i = 0; i < pts.length - 3; i++) {
             const a = pts[i], b = pts[i + 1], c = pts[i + 2], d = pts[i + 3];
-            // Small vertical jog
+            // Small vertical jog: A→B horizontal, B→C vertical (short), C→D horizontal
             const jogH = Math.abs(b[1] - c[1]);
             if (Math.abs(a[1] - b[1]) < 0.5 &&
                 Math.abs(b[0] - c[0]) < 0.5 &&
                 Math.abs(c[1] - d[1]) < 0.5 &&
-                jogH > 0.5 && jogH < JOG_THRESHOLD) {
-                const jogMid = (b[1] + c[1]) / 2;
-                const snapY = Math.abs(a[1] - jogMid) <= Math.abs(d[1] - jogMid) ? a[1] : d[1];
-                const newPts = pts.slice();
-                newPts[i + 1] = [b[0], snapY];
-                newPts[i + 2] = [c[0], snapY];
-                pts = newPts;
-                jogFound = true;
-                break;
+                jogH > 0.5 &&
+                jogH < JOG_THRESHOLD) {
+                // Only collapse if A and D share the same Y (internal jog).
+                if (Math.abs(a[1] - d[1]) < 0.5) {
+                    const snapY = a[1];
+                    const newPts = pts.slice();
+                    newPts[i + 1] = [b[0], snapY];
+                    newPts[i + 2] = [c[0], snapY];
+                    pts = newPts;
+                    jogFound = true;
+                    break;
+                }
             }
-            // Small horizontal jog
+            // Small horizontal jog: A→B vertical, B→C horizontal (short), C→D vertical
             const jogW = Math.abs(b[0] - c[0]);
             if (Math.abs(a[0] - b[0]) < 0.5 &&
                 Math.abs(b[1] - c[1]) < 0.5 &&
                 Math.abs(c[0] - d[0]) < 0.5 &&
-                jogW > 0.5 && jogW < JOG_THRESHOLD) {
-                const jogMid = (b[0] + c[0]) / 2;
-                const snapX = Math.abs(a[0] - jogMid) <= Math.abs(d[0] - jogMid) ? a[0] : d[0];
-                const newPts = pts.slice();
-                newPts[i + 1] = [snapX, b[1]];
-                newPts[i + 2] = [snapX, c[1]];
-                pts = newPts;
-                jogFound = true;
-                break;
+                jogW > 0.5 &&
+                jogW < JOG_THRESHOLD) {
+                if (Math.abs(a[0] - d[0]) < 0.5) {
+                    const snapX = a[0];
+                    const newPts = pts.slice();
+                    newPts[i + 1] = [snapX, b[1]];
+                    newPts[i + 2] = [snapX, c[1]];
+                    pts = newPts;
+                    jogFound = true;
+                    break;
+                }
             }
         }
     }
@@ -326,9 +224,14 @@ function simplifyWaypoints(waypoints) {
         const prev = result[result.length - 1];
         const curr = pts[i];
         const next = pts[i + 1];
+        // Skip near-duplicate points; but only if removing won't create a diagonal
         const distToPrev = Math.abs(prev[0] - curr[0]) + Math.abs(prev[1] - curr[1]);
-        if (distToPrev < MIN_SEGMENT_LENGTH)
-            continue;
+        if (distToPrev < MIN_SEGMENT_LENGTH) {
+            const wouldDiag = Math.abs(prev[0] - next[0]) > 0.5 && Math.abs(prev[1] - next[1]) > 0.5;
+            if (!wouldDiag)
+                continue;
+        }
+        // Skip collinear points (three points on the same axis)
         const sameX = Math.abs(prev[0] - curr[0]) < 0.01 && Math.abs(curr[0] - next[0]) < 0.01;
         const sameY = Math.abs(prev[1] - curr[1]) < 0.01 && Math.abs(curr[1] - next[1]) < 0.01;
         if (!sameX && !sameY) {
@@ -345,7 +248,8 @@ function waypointsToSvgPath(waypoints, cornerRadius) {
     if (waypoints.length === 2) {
         return `M ${waypoints[0][0]},${waypoints[0][1]} L ${waypoints[1][0]},${waypoints[1][1]}`;
     }
-    // Pre-compute arc radii so adjacent corners sharing a segment never overlap
+    // Pre-compute arc radii so that two adjacent corners sharing a segment
+    // never consume more than the segment length combined.
     const radii = new Array(waypoints.length).fill(0);
     for (let i = 1; i < waypoints.length - 1; i++) {
         const prev = waypoints[i - 1];
@@ -356,7 +260,6 @@ function waypointsToSvgPath(waypoints, cornerRadius) {
         radii[i] =
             lenPrev < 0.01 || lenNext < 0.01 ? 0 : Math.min(cornerRadius, lenPrev / 2, lenNext / 2);
     }
-    // Shrink radii so two corners sharing a segment together consume at most the full segment length
     for (let i = 1; i < waypoints.length - 2; i++) {
         const curr = waypoints[i];
         const next = waypoints[i + 1];
@@ -374,7 +277,7 @@ function waypointsToSvgPath(waypoints, cornerRadius) {
         const curr = waypoints[i];
         const next = waypoints[i + 1];
         const r = radii[i];
-        if (r < 2) {
+        if (r < 0.01) {
             path += ` L ${curr[0]},${curr[1]}`;
             continue;
         }
@@ -384,30 +287,38 @@ function waypointsToSvgPath(waypoints, cornerRadius) {
         const lenNext = Math.sqrt(dNext[0] * dNext[0] + dNext[1] * dNext[1]);
         const uPrev = [dPrev[0] / lenPrev, dPrev[1] / lenPrev];
         const uNext = [dNext[0] / lenNext, dNext[1] / lenNext];
-        const arcStart = [curr[0] + uPrev[0] * r, curr[1] + uPrev[1] * r];
-        const arcEnd = [curr[0] + uNext[0] * r, curr[1] + uNext[1] * r];
-        const cross = dPrev[0] * dNext[1] - dPrev[1] * dNext[0];
+        const cross = uPrev[0] * uNext[1] - uPrev[1] * uNext[0];
+        const deflection = Math.abs(cross);
+        const scaledR = r * deflection;
+        if (scaledR < 0.5) {
+            path += ` L ${curr[0]},${curr[1]}`;
+            continue;
+        }
+        const arcStart = [curr[0] + uPrev[0] * scaledR, curr[1] + uPrev[1] * scaledR];
+        const arcEnd = [curr[0] + uNext[0] * scaledR, curr[1] + uNext[1] * scaledR];
         const sweep = cross > 0 ? 0 : 1;
         path += ` L ${arcStart[0]},${arcStart[1]}`;
-        path += ` A ${r} ${r} 0 0 ${sweep} ${arcEnd[0]},${arcEnd[1]}`;
+        path += ` A ${scaledR} ${scaledR} 0 0 ${sweep} ${arcEnd[0]},${arcEnd[1]}`;
     }
     const last = waypoints[waypoints.length - 1];
     path += ` L ${last[0]},${last[1]}`;
     return path;
 }
 // ─── Waypoint computation ───
-function computeWaypoints(from, to, nodeBoxes, sourceNodeId, targetNodeId, padding, exitStub, entryStub, allocator) {
-    const isSelfConnection = sourceNodeId === targetNodeId;
-    const inflatedBoxes = nodeBoxes
-        .filter((box) => (isSelfConnection ? true : box.id !== sourceNodeId && box.id !== targetNodeId))
-        .map((box) => inflateBox(box, padding));
+function computeWaypoints(from, to, nodeBoxes, sourceNodeId, targetNodeId, padding, exitStub, entryStub, scopedInternal, allocator) {
+    const isSelfConnection = sourceNodeId === targetNodeId && !scopedInternal;
+    const inflatedBoxes = nodeBoxes.map((box) => inflateBox(box, padding));
     const stubExit = [from[0] + exitStub, from[1]];
     const stubEntry = [to[0] - entryStub, to[1]];
     const xMin = Math.min(stubExit[0], stubEntry[0]);
     const xMax = Math.max(stubExit[0], stubEntry[0]);
-    if (!isSelfConnection && to[0] > from[0]) {
-        // Forward connection
-        let candidateY = (from[1] + to[1]) / 2;
+    if (!isSelfConnection && to[0] >= from[0] - exitStub) {
+        // Straight connection: if ports share the same Y and the direct path is clear
+        // of non-source/target obstacles, return a direct 2-point line.
+        // Static SVG: skip the straight-line early return. Opaque port labels cover
+        // flat connections. All paths go through BELOW_BIAS routing so they stay visible.
+        // (Platform uses [from, to] here because labels are interactive/hideable.)
+        let candidateY = (from[1] + to[1]) / 2 + BELOW_BIAS;
         const intermediateBoxes = inflatedBoxes.filter((box) => box.left < xMax && box.right > xMin);
         if (intermediateBoxes.length >= 2) {
             const clusterTop = Math.min(...intermediateBoxes.map((b) => b.top));
@@ -415,79 +326,67 @@ function computeWaypoints(from, to, nodeBoxes, sourceNodeId, targetNodeId, paddi
             if (candidateY > clusterTop && candidateY < clusterBottom) {
                 const distToTop = candidateY - clusterTop;
                 const distToBottom = clusterBottom - candidateY;
-                candidateY = distToTop <= distToBottom
-                    ? clusterTop - padding
-                    : clusterBottom + padding;
+                candidateY = distToTop < distToBottom ? clusterTop - padding : clusterBottom + padding;
             }
         }
-        let clearY = findClearY(xMin, xMax, candidateY, inflatedBoxes);
-        if (Math.abs(from[1] - to[1]) < JOG_THRESHOLD && Math.abs(clearY - from[1]) < JOG_THRESHOLD) {
-            return null; // Fall back to bezier
-        }
-        // Try center-corner: single vertical turn at the midpoint
-        const midX = (stubExit[0] + stubEntry[0]) / 2;
+        const clearY = allocator
+            ? allocator.claim(xMin, xMax, findClearY(xMin, xMax, candidateY, inflatedBoxes))
+            : findClearY(xMin, xMax, candidateY, inflatedBoxes);
         const yMin = Math.min(from[1], to[1]);
         const yMax = Math.max(from[1], to[1]);
-        const clearMidX = findClearX(yMin, yMax, midX, inflatedBoxes);
-        const freeMidX = allocator.findFreeX(yMin, yMax, clearMidX, inflatedBoxes);
-        if (yMax - yMin >= JOG_THRESHOLD &&
-            freeMidX > stubExit[0] &&
-            freeMidX < stubEntry[0] &&
+        const stubsCross = stubExit[0] >= stubEntry[0];
+        const midX = stubsCross
+            ? (from[0] + to[0]) / 2
+            : stubExit[0] + (stubEntry[0] - stubExit[0]) * 0.75;
+        const freeMidX = findClearX(yMin, yMax || yMin + 1, midX, inflatedBoxes);
+        const lShapeXValid = stubsCross
+            ? freeMidX >= Math.min(from[0], to[0]) && freeMidX <= Math.max(from[0], to[0])
+            : freeMidX > stubExit[0] && freeMidX < stubEntry[0];
+        if (lShapeXValid &&
             verticalSegmentClear(freeMidX, yMin, yMax, inflatedBoxes) &&
-            allocator.findFreeY(from[0], freeMidX, from[1], inflatedBoxes) === from[1] &&
-            allocator.findFreeY(freeMidX, to[0], to[1], inflatedBoxes) === to[1]) {
-            allocator.claim(from[0], freeMidX, from[1]);
-            allocator.claim(freeMidX, to[0], to[1]);
-            allocator.claimVertical(yMin, yMax, freeMidX);
+            !inflatedBoxes.some((box) => segmentOverlapsBox(stubExit[0], freeMidX, from[1], box)) &&
+            !inflatedBoxes.some((box) => segmentOverlapsBox(freeMidX, stubEntry[0], to[1], box))) {
             return simplifyWaypoints([from, [freeMidX, from[1]], [freeMidX, to[1]], to]);
         }
-        // S-shape with horizontal channel
-        clearY = allocator.findFreeY(xMin, xMax, clearY, inflatedBoxes);
         if (Math.abs(clearY - from[1]) < JOG_THRESHOLD &&
             !inflatedBoxes.some((box) => segmentOverlapsBox(xMin, xMax, from[1], box))) {
-            clearY = from[1];
+            candidateY = from[1];
         }
         else if (Math.abs(clearY - to[1]) < JOG_THRESHOLD &&
             !inflatedBoxes.some((box) => segmentOverlapsBox(xMin, xMax, to[1], box))) {
-            clearY = to[1];
+            candidateY = to[1];
+        }
+        else {
+            candidateY = clearY;
         }
-        allocator.claim(xMin, xMax, clearY);
-        // Validate vertical segments
-        const exitYMin = Math.min(from[1], clearY);
-        const exitYMax = Math.max(from[1], clearY);
+        const exitYMin = Math.min(from[1], candidateY);
+        const exitYMax = Math.max(from[1], candidateY);
         let exitX = findClearX(exitYMin, exitYMax, stubExit[0], inflatedBoxes);
-        exitX = allocator.findFreeX(exitYMin, exitYMax, exitX, inflatedBoxes);
         if (exitX < from[0]) {
             exitX = stubExit[0];
             if (!verticalSegmentClear(exitX, exitYMin, exitYMax, inflatedBoxes)) {
                 exitX = findClearX(exitYMin, exitYMax, stubExit[0] + TRACK_SPACING, inflatedBoxes);
-                exitX = allocator.findFreeX(exitYMin, exitYMax, exitX, inflatedBoxes);
             }
         }
-        allocator.claimVertical(exitYMin, exitYMax, exitX);
-        const entryYMin = Math.min(to[1], clearY);
-        const entryYMax = Math.max(to[1], clearY);
+        const entryYMin = Math.min(to[1], candidateY);
+        const entryYMax = Math.max(to[1], candidateY);
         let entryX = findClearX(entryYMin, entryYMax, stubEntry[0], inflatedBoxes);
-        entryX = allocator.findFreeX(entryYMin, entryYMax, entryX, inflatedBoxes);
         if (entryX > to[0]) {
             entryX = stubEntry[0];
             if (!verticalSegmentClear(entryX, entryYMin, entryYMax, inflatedBoxes)) {
                 entryX = findClearX(entryYMin, entryYMax, stubEntry[0] - TRACK_SPACING, inflatedBoxes);
-                entryX = allocator.findFreeX(entryYMin, entryYMax, entryX, inflatedBoxes);
             }
         }
-        allocator.claimVertical(entryYMin, entryYMax, entryX);
         return simplifyWaypoints([
             from,
             [exitX, from[1]],
-            [exitX, clearY],
-            [entryX, clearY],
+            [exitX, candidateY],
+            [entryX, candidateY],
             [entryX, to[1]],
             to,
         ]);
     }
     else {
-        // Backward connection or self-connection — escape vertically, loop around
         const sourceBox = nodeBoxes.find((b) => b.id === sourceNodeId);
         const targetBox = nodeBoxes.find((b) => b.id === targetNodeId);
         const corridorBoxes = inflatedBoxes.filter((box) => box.left < xMax && box.right > xMin);
@@ -503,23 +402,19 @@ function computeWaypoints(from, to, nodeBoxes, sourceNodeId, targetNodeId, paddi
         }
         const maxBottom = Math.max(...bottoms, from[1] + 50, to[1] + 50);
         const minTop = Math.min(...tops, from[1] - 50, to[1] - 50);
-        const avgY = (from[1] + to[1]) / 2;
+        const avgY = (from[1] + to[1]) / 2 + BELOW_BIAS;
         const escapeBelow = maxBottom + padding;
         const escapeAbove = minTop - padding;
-        let escapeY = Math.abs(escapeAbove - avgY) <= Math.abs(escapeBelow - avgY) ? escapeAbove : escapeBelow;
-        escapeY = findClearY(xMin, xMax, escapeY, inflatedBoxes);
-        escapeY = allocator.findFreeY(xMin, xMax, escapeY, inflatedBoxes);
-        allocator.claim(xMin, xMax, escapeY);
+        let escapeY = Math.abs(escapeAbove - avgY) < Math.abs(escapeBelow - avgY) ? escapeAbove : escapeBelow;
+        escapeY = allocator
+            ? allocator.claim(xMin, xMax, findClearY(xMin, xMax, escapeY, inflatedBoxes))
+            : findClearY(xMin, xMax, escapeY, inflatedBoxes);
         const bwExitYMin = Math.min(from[1], escapeY);
         const bwExitYMax = Math.max(from[1], escapeY);
-        let bwExitX = findClearX(bwExitYMin, bwExitYMax, stubExit[0], inflatedBoxes);
-        bwExitX = allocator.findFreeX(bwExitYMin, bwExitYMax, bwExitX, inflatedBoxes);
-        allocator.claimVertical(bwExitYMin, bwExitYMax, bwExitX);
+        const bwExitX = findClearX(bwExitYMin, bwExitYMax, stubExit[0], inflatedBoxes);
         const bwEntryYMin = Math.min(to[1], escapeY);
         const bwEntryYMax = Math.max(to[1], escapeY);
-        let bwEntryX = findClearX(bwEntryYMin, bwEntryYMax, stubEntry[0], inflatedBoxes);
-        bwEntryX = allocator.findFreeX(bwEntryYMin, bwEntryYMax, bwEntryX, inflatedBoxes);
-        allocator.claimVertical(bwEntryYMin, bwEntryYMax, bwEntryX);
+        const bwEntryX = findClearX(bwEntryYMin, bwEntryYMax, stubEntry[0], inflatedBoxes);
         return simplifyWaypoints([
             from,
             [bwExitX, from[1]],
@@ -531,11 +426,7 @@ function computeWaypoints(from, to, nodeBoxes, sourceNodeId, targetNodeId, paddi
     }
 }
 // ─── Public API ───
-/**
- * Calculate an orthogonal SVG path between two ports.
- * Returns null if the path should fall back to bezier (e.g. nearly aligned ports).
- */
-export function calculateOrthogonalPath(from, to, nodeBoxes, sourceNodeId, targetNodeId, options, allocator) {
+export function calculateOrthogonalPath(from, to, nodeBoxes, sourceNodeId, targetNodeId, options) {
     const cornerRadius = options?.cornerRadius ?? 10;
     const padding = options?.padding ?? 15;
     const stubLength = options?.stubLength ?? 20;
@@ -545,18 +436,17 @@ export function calculateOrthogonalPath(from, to, nodeBoxes, sourceNodeId, targe
     const toPortIndex = options?.toPortIndex ?? 0;
     const exitStub = Math.min(stubLength + fromPortIndex * stubSpacing, maxStubLength);
     const entryStub = Math.min(stubLength + toPortIndex * stubSpacing, maxStubLength);
-    const alloc = allocator ?? new TrackAllocator();
-    const waypoints = computeWaypoints(from, to, nodeBoxes, sourceNodeId, targetNodeId, padding, exitStub, entryStub, alloc);
+    const waypoints = computeWaypoints(from, to, nodeBoxes, sourceNodeId, targetNodeId, padding, exitStub, entryStub, options?.scopedInternal, options?.allocator);
     if (!waypoints)
         return null;
     return waypointsToSvgPath(waypoints, cornerRadius);
 }
 /**
- * Safe wrapper — returns null if routing fails, caller falls back to bezier.
+ * Safe wrapper: returns null if routing fails, caller falls back to straight line.
  */
-export function calculateOrthogonalPathSafe(from, to, nodeBoxes, sourceNodeId, targetNodeId, options, allocator) {
+export function calculateOrthogonalPathSafe(from, to, nodeBoxes, sourceNodeId, targetNodeId, options) {
     try {
-        const path = calculateOrthogonalPath(from, to, nodeBoxes, sourceNodeId, targetNodeId, options, allocator);
+        const path = calculateOrthogonalPath(from, to, nodeBoxes, sourceNodeId, targetNodeId, options);
         if (!path || path.length < 5)
             return null;
         return path;