@stacksjs/defaults 0.75.361 → 0.75.362

package/ai/skills/stacks-technical-diagrams/renderers/architecture/routing.mjs

@@ -0,0 +1,1469 @@
+// Internal architecture router shared by rendering and geometry inspection.
+// Create a new router when measured boxes or connections change: port spreading
+// is computed once and route results are cached for this scene.
+
+import {
+  segmentIntersectsRect,
+  anchor,
+  automaticPortSpread,
+  alignAutomaticFacingPorts,
+  portHasCornerClearance,
+  automaticPortRhythmBridge,
+  defaultFromSide,
+  defaultToSide,
+  chosenSide,
+  properSegmentIntersection,
+  routeHonorsEndpointSides,
+  normalizeRoutePoints,
+  rectsOverlap,
+  roundedPath,
+  collectBorderRuns,
+  collectRouteRhythmIssues,
+  frameBorderSegments,
+} from '../shared/geometry.mjs';
+import { shortestOrthogonalGridRoute } from '../shared/route-quality.mjs';
+
+/**
+ * Router bound to one set of measured component boxes.
+ *
+ * @param {Map<string, {x,y,width,height,cx,cy}>} components measured boxes by id
+ * @param {Array<object>} connections the connection list to spread ports across
+ * @param {object} [options]
+ * @param {Array<{x,y,width,height,radius?}>} [options.frames] structural frames
+ *   (boundaries) whose borders an automatic route may cross but never follow
+ * @param {number} [options.interiorSegmentPx] showcase floor for interior segments
+ * @param {number} [options.microSegmentPx] floor for any segment
+ * @param {(conn: object, points: number[][], context: {routes: number[][][], labels: object[]}) => object|null} [options.labelRectFor]
+ *   default label rect of a routed relationship given the routes and label
+ *   rects resolved so far; later automatic routes keep clear of it so a dense
+ *   fan-out does not leave the label nowhere to go
+ * @param {(conn: object, endpoint: 'source'|'target') => string|undefined} [options.sideFor]
+ *   endpoint side of a relationship whose author did not pin one, for a type
+ *   that reads its layout on a different axis than architecture's row fan-out;
+ *   an endpoint this hook leaves undefined keeps the shared inference
+ * @param {number} [options.maxPortSpacing] widest spacing the automatic port
+ *   spread may use on a shared side; a type whose endpoint glyphs are taller
+ *   than the default raises this so two symbols never draw over each other
+ * @param {(context: {conn: object, from: object, to: object, start: number[], end: number[], fromSide: string, toSide: string}) => number[][][]} [options.preferredCandidates]
+ *   candidate families tried before the shared ones, so a type-owned corridor
+ *   (a bundled trunk, a dedicated lane) wins over the generic midpoint
+ * @param {boolean} [options.crossingFreeGridFirst = false] before the obstacle
+ *   grid search that may cross earlier routes, try one that treats every
+ *   unrelated resolved route as a wall. A type whose showcase gate rejects any
+ *   proper crossing (erd) opts in so a later relationship takes a clear detour
+ *   instead of the shorter crossing the gate would refuse.
+ * @param {number} [options.componentGapPx = 0] when positive, the obstacle
+ *   grid first keeps a route this far from every component it merely passes
+ *   (its own endpoints stay at the 2-unit clearance) and falls back to the
+ *   tight search only when no spaced route is accepted, so a detour does not
+ *   run along a neighbouring box edge 3 units away from its border.
+ * @param {number} [options.minimumTerminalSegmentPx = 0] shortest first and
+ *   last segment any automatic route may have, applied even with
+ *   compositionFloors off: a type that rounds its corners when drawing needs
+ *   the end segment to outlast the corner radius plus the micro-segment floor.
+ * @param {boolean} [options.compositionFloors = true] hold every automatic
+ *   route to the rhythm floors the showcase gate enforces, so the planner never
+ *   accepts a route the gate will reject. A type that draws a route differently
+ *   from its logical points (the erd renderer removes the bundled trunk stretch
+ *   from each branch and draws the bus as one path) turns this off: the floors
+ *   describe a route drawn exactly as planned, and that type answers for the
+ *   drawn result at its own gate instead.
+ * @param {number} [options.readabilityBottomMargin = 0] extra vertical room for
+ *   the bounded readability sweep on an intrinsic-height canvas. Width and
+ *   authored geometry stay fixed; fixed canvases leave this at zero.
+ */
+export function createRouter(components, connections = [], {
+  frames = [],
+  interiorSegmentPx = 16,
+  microSegmentPx = 8,
+  labelRectFor = null,
+  distinctAutomaticPorts = false,
+  preferReadableRoutes = false,
+  sideFor = null,
+  maxPortSpacing = null,
+  preferredCandidates = null,
+  compositionFloors = true,
+  crossingFreeGridFirst = false,
+  componentGapPx = 0,
+  minimumTerminalSegmentPx = 0,
+  readabilityBottomMargin = 0,
+} = {}) {
+  const frameBorders = frames.flatMap((frame) => frameBorderSegments(frame));
+  const LABEL_CLEARANCE = 4;
+  // Labels of already-routed relationships, reserved while planning the rest.
+  let reservedLabels = [];
+  let honourReservedLabels = true;
+  let allowGridSearch = true;
+
+  function routeClearsReservedLabels(conn, points) {
+    if (!honourReservedLabels) return true;
+    for (const entry of reservedLabels) {
+      if (entry.conn === conn) continue;
+      for (let index = 0; index < points.length - 1; index += 1) {
+        if (segmentIntersectsRect({ start: points[index], end: points[index + 1] }, entry.rect, LABEL_CLEARANCE)) {
+          return false;
+        }
+      }
+    }
+    return true;
+  }
+
+  // The grid search adds its own 2px component clearance; pre-expand so a
+  // reserved label keeps the same 4px clearance the placement pass demands.
+  function reservedLabelObstacles(gridClearance) {
+    if (!honourReservedLabels) return [];
+    const grow = LABEL_CLEARANCE - gridClearance;
+    return reservedLabels.map(({ rect }) => ({
+      x: rect.x - grow,
+      y: rect.y - grow,
+      width: rect.width + grow * 2,
+      height: rect.height + grow * 2,
+    }));
+  }
+
+  // Automatic routes are held to the same composition floors the showcase
+  // gate enforces afterwards. Accepting a route here that the gate rejects
+  // only hands the author a hand-routing repair the planner could have made.
+  function routeMeetsCompositionFloors(points) {
+    if (minimumTerminalSegmentPx > 0 && points.length > 2) {
+      const span = (a, b) => Math.abs(b[0] - a[0]) + Math.abs(b[1] - a[1]);
+      if (span(points[0], points[1]) < minimumTerminalSegmentPx
+        || span(points.at(-2), points.at(-1)) < minimumTerminalSegmentPx) return false;
+    }
+    if (compositionFloors
+        && collectRouteRhythmIssues({ routedRelations: [{ points }], interiorSegmentPx, microSegmentPx }).length) {
+      return false;
+    }
+    return !frames.length || collectBorderRuns({ routedRelations: [{ points }], frames }).length === 0;
+  }
+  const planningMetrics = {
+    routeCount: 0,
+    explicitRouteCount: 0,
+    automaticRouteCount: 0,
+    gridSearchCount: 0,
+    gridRoutedCount: 0,
+    gridCandidateNodeCount: 0,
+    gridUsableNodeCount: 0,
+    gridEdgeCount: 0,
+    gridVisitedNodeCount: 0,
+    avoidedSegmentCount: 0,
+    conflictFallbackCount: 0,
+    maximumGridSearchCount: 64,
+    gridBudgetExhaustedCount: 0,
+    crossoverRoutedCount: 0,
+    readabilityCandidateCount: 0,
+    readabilityImprovedCount: 0,
+    labelRelocationCandidateCount: 0,
+    labelRelocationImprovedCount: 0,
+    reciprocalCandidateCount: 0,
+    reciprocalImprovedCount: 0,
+    gridAttempts: [],
+  };
+
+  // ---- Connection routing ------------------------------------------------------
+  const gridComponentGaps = componentGapPx > 0 ? [componentGapPx, 0] : [0];
+  // The spaced search is a readability preference, so its route must also be
+  // clean as drawn: full rhythm floors (even for a type that turns them off)
+  // and terminal segments long enough for a rounded corner and an end marker.
+  function spacedRouteIsClean(points, gap) {
+    if (gap === 0) return true;
+    const terminal = (a, b) => Math.abs(b[0] - a[0]) + Math.abs(b[1] - a[1]);
+    return terminal(points[0], points[1]) >= 16 && terminal(points.at(-2), points.at(-1)) >= 16
+      && collectRouteRhythmIssues({ routedRelations: [{ points }], interiorSegmentPx, microSegmentPx }).length === 0;
+  }
+  function gridComponentObstacles(conn, gap) {
+    return [...components.values()].map((component) => (gap === 0 || component.id === conn.from || component.id === conn.to
+      ? component
+      : { ...component, x: component.x - gap, y: component.y - gap, width: component.width + gap * 2, height: component.height + gap * 2 }));
+  }
+
+  function routeClearsComponents(conn, points, clearance = 2) {
+    const endpointIds = new Set([conn.from, conn.to]);
+    for (const component of components.values()) {
+      if (endpointIds.has(component.id)) continue;
+      for (let index = 0; index < points.length - 1; index += 1) {
+        if (segmentIntersectsRect({ start: points[index], end: points[index + 1] }, component, clearance)) {
+          return false;
+        }
+      }
+    }
+    return routeClearsReservedLabels(conn, points);
+  }
+
+  function routeClearsEndpointComponents(points, from, to) {
+    const lastSegment = points.length - 2;
+    for (let index = 0; index <= lastSegment; index += 1) {
+      const segment = { start: points[index], end: points[index + 1] };
+      if (index > 0 && segmentIntersectsRect(segment, from)) return false;
+      if (index < lastSegment && segmentIntersectsRect(segment, to)) return false;
+    }
+    return true;
+  }
+
+  function relationshipsShareEndpoint(left, right) {
+    return left.from === right.from
+      || left.from === right.to
+      || left.to === right.from
+      || left.to === right.to;
+  }
+
+  function collinearOverlapLength(leftStart, leftEnd, rightStart, rightEnd) {
+    const epsilon = 0.0001;
+    if (Math.abs(leftStart[0] - leftEnd[0]) <= epsilon
+        && Math.abs(rightStart[0] - rightEnd[0]) <= epsilon
+        && Math.abs(leftStart[0] - rightStart[0]) <= epsilon) {
+      return Math.max(0,
+        Math.min(Math.max(leftStart[1], leftEnd[1]), Math.max(rightStart[1], rightEnd[1]))
+          - Math.max(Math.min(leftStart[1], leftEnd[1]), Math.min(rightStart[1], rightEnd[1])));
+    }
+    if (Math.abs(leftStart[1] - leftEnd[1]) <= epsilon
+        && Math.abs(rightStart[1] - rightEnd[1]) <= epsilon
+        && Math.abs(leftStart[1] - rightStart[1]) <= epsilon) {
+      return Math.max(0,
+        Math.min(Math.max(leftStart[0], leftEnd[0]), Math.max(rightStart[0], rightEnd[0]))
+          - Math.max(Math.min(leftStart[0], leftEnd[0]), Math.min(rightStart[0], rightEnd[0])));
+    }
+    return 0;
+  }
+
+  function orthogonalTouchOnResolvedInterior(start, end, resolvedStart, resolvedEnd) {
+    const epsilon = 0.0001;
+    const candidateHorizontal = Math.abs(start[1] - end[1]) <= epsilon;
+    const candidateVertical = Math.abs(start[0] - end[0]) <= epsilon;
+    const resolvedHorizontal = Math.abs(resolvedStart[1] - resolvedEnd[1]) <= epsilon;
+    const resolvedVertical = Math.abs(resolvedStart[0] - resolvedEnd[0]) <= epsilon;
+    if (candidateHorizontal && resolvedVertical) {
+      const x = resolvedStart[0];
+      const y = start[1];
+      return x >= Math.min(start[0], end[0]) - epsilon
+        && x <= Math.max(start[0], end[0]) + epsilon
+        && y > Math.min(resolvedStart[1], resolvedEnd[1]) + epsilon
+        && y < Math.max(resolvedStart[1], resolvedEnd[1]) - epsilon;
+    }
+    if (candidateVertical && resolvedHorizontal) {
+      const x = start[0];
+      const y = resolvedStart[1];
+      return y >= Math.min(start[1], end[1]) - epsilon
+        && y <= Math.max(start[1], end[1]) + epsilon
+        && x > Math.min(resolvedStart[0], resolvedEnd[0]) + epsilon
+        && x < Math.max(resolvedStart[0], resolvedEnd[0]) - epsilon;
+    }
+    return false;
+  }
+
+  function unrelatedResolvedRoutes(conn, resolvedRoutes) {
+    return resolvedRoutes.filter((entry) => !relationshipsShareEndpoint(conn, entry.conn));
+  }
+
+  function routeConflictsWithResolved(conn, points, resolvedRoutes) {
+    const unrelated = unrelatedResolvedRoutes(conn, resolvedRoutes);
+    for (const entry of unrelated) {
+      for (let left = 0; left < points.length - 1; left += 1) {
+        for (let right = 0; right < entry.points.length - 1; right += 1) {
+          if (properSegmentIntersection(
+            points[left],
+            points[left + 1],
+            entry.points[right],
+            entry.points[right + 1],
+          )) return true;
+          if (orthogonalTouchOnResolvedInterior(
+            points[left],
+            points[left + 1],
+            entry.points[right],
+            entry.points[right + 1],
+          )) return true;
+          if (collinearOverlapLength(
+            points[left],
+            points[left + 1],
+            entry.points[right],
+            entry.points[right + 1],
+          ) >= 8) return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  function routeOverlapsResolved(conn, points, resolvedRoutes) {
+    // A common destination does not make two independently labelled routes a
+    // bus. Keep their corridors distinct too; explicit routes bypass planning.
+    for (const entry of resolvedRoutes) {
+      if (relationshipsShareEndpoint(conn, entry.conn)
+          && (!distinctAutomaticPorts || hasAuthoredRouteGeometry(entry.conn) || entry.conn.labelAt || conn.labelAt)) continue;
+      for (let left = 0; left < points.length - 1; left += 1) {
+        for (let right = 0; right < entry.points.length - 1; right += 1) {
+          if (collinearOverlapLength(
+            points[left],
+            points[left + 1],
+            entry.points[right],
+            entry.points[right + 1],
+          ) >= 8) return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  const OUTWARD_SIDE_VECTOR = {
+    left: [-1, 0],
+    right: [1, 0],
+    top: [0, -1],
+    bottom: [0, 1],
+  };
+
+  function outwardStub(point, side, distance = 24) {
+    const [dx, dy] = OUTWARD_SIDE_VECTOR[side] || [0, 0];
+    return [point[0] + dx * distance, point[1] + dy * distance];
+  }
+
+  function collinearBacktrack(a, b, c) {
+    const first = [b[0] - a[0], b[1] - a[1]];
+    const second = [c[0] - b[0], c[1] - b[1]];
+    const cross = first[0] * second[1] - first[1] * second[0];
+    const dot = first[0] * second[0] + first[1] * second[1];
+    return Math.abs(cross) <= 0.0001 && dot < -0.0001;
+  }
+
+  function sideAwareBridgeCandidates(start, end, fromSide, toSide) {
+    const startStub = outwardStub(start, fromSide);
+    const endStub = outwardStub(end, toSide);
+    const rawCandidates = [];
+    const minimumBridge = 16;
+    const verticalSides = new Set(['top', 'bottom']);
+    const horizontalSides = new Set(['left', 'right']);
+
+    // Port spreading can leave parallel-side anchors only a few pixels apart.
+    // Route through a bounded outside channel so we keep both endpoint normals
+    // without introducing a tiny, noisy connector between the two stubs.
+    if (verticalSides.has(fromSide) && verticalSides.has(toSide)
+        && Math.abs(start[0] - end[0]) < minimumBridge) {
+      for (const channelX of [
+        Math.max(start[0], end[0]) + minimumBridge,
+        Math.min(start[0], end[0]) - minimumBridge,
+      ]) {
+        rawCandidates.push([
+          startStub,
+          [channelX, startStub[1]],
+          [channelX, endStub[1]],
+          endStub,
+        ]);
+      }
+    }
+    if (horizontalSides.has(fromSide) && horizontalSides.has(toSide)
+        && Math.abs(start[1] - end[1]) < minimumBridge) {
+      for (const channelY of [
+        Math.max(start[1], end[1]) + minimumBridge,
+        Math.min(start[1], end[1]) - minimumBridge,
+      ]) {
+        rawCandidates.push([
+          startStub,
+          [startStub[0], channelY],
+          [endStub[0], channelY],
+          endStub,
+        ]);
+      }
+    }
+
+    rawCandidates.push(
+      [startStub, [endStub[0], startStub[1]], endStub],
+      [startStub, [startStub[0], endStub[1]], endStub],
+    );
+    return rawCandidates.map((candidate) => normalizeRoutePoints([start, ...candidate, end]))
+      .filter((points) => points.length >= 2)
+      .filter((points) => !collinearBacktrack(points[0], points[1], points[2] || points[1]))
+      .filter((points) => !collinearBacktrack(points.at(-3) || points.at(-2), points.at(-2), points.at(-1)))
+      .filter((points) => routeHonorsEndpointSides(points, fromSide, toSide))
+      .sort((a, b) => a.length - b.length)
+      .map((points) => points.slice(1, -1));
+  }
+
+  const AUTOMATIC_PORT_CORNER_GUTTER = 16;
+
+  function alignFacingPorts(conn, from, to, start, end, fromSide, toSide, ports) {
+    return alignAutomaticFacingPorts(conn, from, to, start, end, fromSide, toSide, ports, {
+      accept: points => routeClearsEndpointComponents(points, from, to) && routeClearsComponents(conn, points),
+    });
+  }
+
+  // A reciprocal pair is repaired jointly after planning, so crossings that
+  // involve it are not final yet; keep the established first choice there.
+  const reciprocal = (conn) => connections.some((other) => other.from === conn.to && other.to === conn.from);
+  function siblingCrossings(conn, points, resolvedRoutes) {
+    if (reciprocal(conn)) return 0;
+    return crossingCount(conn, points, resolvedRoutes.filter((entry) => !reciprocal(entry.conn)));
+  }
+
+  function routeVia(conn, from, to, start, end, fromSide, toSide, resolvedRoutes = []) {
+    if (conn.via) return conn.via;
+    switch (conn.route || 'auto') {
+      case 'straight':
+        return [];
+      case 'orthogonal-h': {
+        const midX = (start[0] + end[0]) / 2;
+        return [[midX, start[1]], [midX, end[1]]];
+      }
+      case 'orthogonal-v': {
+        const midY = (start[1] + end[1]) / 2;
+        return [[start[0], midY], [end[0], midY]];
+      }
+      case 'auto':
+      default: {
+        // A caller may own the corridor for relationships that would otherwise
+        // share one channel. Preferred candidates are tried before the shared
+        // families, so a declared trunk or lane wins over the generic midpoint;
+        // a candidate that violates the endpoint contract or an obstacle is
+        // skipped and the historical order below still applies.
+        if (preferredCandidates) {
+          for (const candidate of preferredCandidates({ conn, from, to, start, end, fromSide, toSide }) || []) {
+            const points = [start, ...candidate, end];
+            if (routeHonorsEndpointSides(points, fromSide, toSide)
+                && routeClearsEndpointComponents(points, from, to)
+                && routeClearsComponents(conn, points)
+                && routeMeetsCompositionFloors(points)
+                && !routeConflictsWithResolved(conn, points, resolvedRoutes)) return candidate;
+          }
+        }
+
+        // Direct line unless the anchors are clearly orthogonal-friendly.
+        const deltaX = Math.abs(start[0] - end[0]);
+        const deltaY = Math.abs(start[1] - end[1]);
+        if (deltaX < 4 || deltaY < 4) {
+          const direct = [start, end];
+          if (routeHonorsEndpointSides(direct, fromSide, toSide)
+              && routeClearsEndpointComponents(direct, from, to)
+              && routeClearsComponents(conn, direct)
+              && routeMeetsCompositionFloors(direct)
+              && !routeConflictsWithResolved(conn, direct, resolvedRoutes)) return [];
+        }
+
+        const rhythmBridge = automaticPortRhythmBridge(start, end, fromSide, toSide, {
+          accept: (points) => (
+            routeClearsEndpointComponents(points, from, to)
+            && routeClearsComponents(conn, points)
+            && routeMeetsCompositionFloors(points)
+            && !routeConflictsWithResolved(conn, points, resolvedRoutes)
+          ),
+        });
+        if (rhythmBridge) return rhythmBridge.slice(1, -1);
+
+        // Automatic port spreading can leave otherwise aligned endpoints only a
+        // few pixels apart. A midpoint route would split that tiny difference
+        // into two unreadable endpoint stubs, so take a bounded outside channel
+        // when both anchors sit on parallel component sides.
+        const minimumStub = 8;
+        const fromVerticalSide = start[1] === from.y || start[1] === from.y + from.height;
+        const toVerticalSide = end[1] === to.y || end[1] === to.y + to.height;
+        if (fromVerticalSide && toVerticalSide && deltaX < minimumStub * 2) {
+          const outsideChannels = [
+            Math.max(start[0], end[0]) + minimumStub * 2,
+            Math.min(start[0], end[0]) - minimumStub * 2,
+          ];
+          for (const channelX of outsideChannels) {
+            const candidate = [[channelX, start[1]], [channelX, end[1]]];
+            const points = [start, ...candidate, end];
+            if (routeHonorsEndpointSides(points, fromSide, toSide)
+                && routeClearsComponents(conn, points)
+                && routeMeetsCompositionFloors(points)
+                && !routeConflictsWithResolved(conn, points, resolvedRoutes)) return candidate;
+          }
+        }
+
+        const fromHorizontalSide = start[0] === from.x || start[0] === from.x + from.width;
+        const toHorizontalSide = end[0] === to.x || end[0] === to.x + to.width;
+        if (fromHorizontalSide && toHorizontalSide && deltaY < minimumStub * 2) {
+          const outsideChannels = [
+            Math.max(start[1], end[1]) + minimumStub * 2,
+            Math.min(start[1], end[1]) - minimumStub * 2,
+          ];
+          for (const channelY of outsideChannels) {
+            const candidate = [[start[0], channelY], [end[0], channelY]];
+            const points = [start, ...candidate, end];
+            if (routeHonorsEndpointSides(points, fromSide, toSide)
+                && routeClearsComponents(conn, points)
+                && routeMeetsCompositionFloors(points)
+                && !routeConflictsWithResolved(conn, points, resolvedRoutes)) return candidate;
+          }
+        }
+
+        const midX = (start[0] + end[0]) / 2;
+        const horizontalFirst = [[midX, start[1]], [midX, end[1]]];
+        const midY = (start[1] + end[1]) / 2;
+        const verticalFirst = [[start[0], midY], [end[0], midY]];
+        const candidates = [horizontalFirst, verticalFirst];
+        const sideSafe = candidates.filter((candidate) => (
+          routeHonorsEndpointSides([start, ...candidate, end], fromSide, toSide)
+        ));
+        const sideAware = sideAwareBridgeCandidates(start, end, fromSide, toSide);
+        const nearParallelPorts = (
+          ((fromSide === 'top' || fromSide === 'bottom')
+            && (toSide === 'top' || toSide === 'bottom')
+            && deltaX < minimumStub * 2)
+          || ((fromSide === 'left' || fromSide === 'right')
+            && (toSide === 'left' || toSide === 'right')
+            && deltaY < minimumStub * 2)
+        );
+        const ordered = [
+          ...(nearParallelPorts ? sideAware : sideSafe),
+          ...(nearParallelPorts ? sideSafe : sideAware),
+        ];
+        let firstFeasible = null;
+        for (const candidate of ordered) {
+          const points = [start, ...candidate, end];
+          if (!(routeClearsEndpointComponents(points, from, to)
+              && routeClearsComponents(conn, points)
+              && routeMeetsCompositionFloors(points)
+              && !routeConflictsWithResolved(conn, points, resolvedRoutes)
+              && (!distinctAutomaticPorts || (!routeOverlapsResolved(conn, points, resolvedRoutes)
+                && !siblingCrossings(conn, points, resolvedRoutes))))) continue;
+          if (!conn.label || !labelRectFor || labelRectFor(conn, points, {
+            routes: resolvedRoutes.map((entry) => entry.points),
+            labels: reservedLabels.map((entry) => entry.rect),
+          })) return candidate;
+          firstFeasible ||= candidate;
+        }
+        if (firstFeasible) return firstFeasible;
+        // Siblings fanning out from one side all want the same midpoint
+        // channel. Step outward through the corridor to a free parallel
+        // channel before searching.
+        if (distinctAutomaticPorts) {
+          const channels = (from, to, mid) => {
+            const [low, high] = [Math.min(from, to) + 24, Math.max(from, to) - 24];
+            const values = [];
+            for (let offset = 16; mid - offset >= low || mid + offset <= high; offset += 16) {
+              values.push(...[mid + offset, mid - offset].filter((value) => value >= low && value <= high));
+            }
+            return values;
+          };
+          for (const candidate of [
+            ...channels(start[0], end[0], midX).map((x) => [[x, start[1]], [x, end[1]]]),
+            ...channels(start[1], end[1], midY).map((y) => [[start[0], y], [end[0], y]]),
+          ]) {
+            const points = [start, ...candidate, end];
+            if (routeHonorsEndpointSides(points, fromSide, toSide)
+                && routeClearsEndpointComponents(points, from, to)
+                && routeClearsComponents(conn, points)
+                && routeMeetsCompositionFloors(points)
+                && !routeConflictsWithResolved(conn, points, resolvedRoutes)
+                && !routeOverlapsResolved(conn, points, resolvedRoutes)
+                && !siblingCrossings(conn, points, resolvedRoutes)) return candidate;
+          }
+        }
+
+        // Two-bend doglegs are deliberately cheap, but a real architecture can
+        // place adjacent components on both of those corridors. Search a
+        // bounded obstacle grid before falling back to a route that the Clean
+        // Flow gate already knows violates the inferred endpoint directions.
+        // This keeps ordinary multi-bend avoidance renderer-owned instead of
+        // forcing the author to hand-place via points.
+        // Alternative endpoint pairs are cheap probes, not another grid-search
+        // budget. A legal short bridge often beats the first grid detour.
+        if (!allowGridSearch) return sideSafe[0] || sideAware[0] || horizontalFirst;
+        if (planningMetrics.gridSearchCount >= planningMetrics.maximumGridSearchCount) {
+          planningMetrics.gridBudgetExhaustedCount += 1;
+          planningMetrics.conflictFallbackCount += 1;
+          return sideSafe[0] || sideAware[0] || horizontalFirst;
+        }
+        // First-draft architecture graphs are not always planar at their
+        // authored node positions. The renderer gives automatic crossings a
+        // visible halo, so the grid owns opaque-node avoidance and rejects
+        // ambiguous shared corridors without forcing the model to hand-route
+        // a sprawling perimeter detour. Cheap candidates above still prefer a
+        // genuinely crossing-free path whenever one is available.
+        if (crossingFreeGridFirst) {
+          const unrelatedSegments = unrelatedResolvedRoutes(conn, resolvedRoutes)
+            .flatMap((entry) => entry.points.slice(1).map((end, index) => ({ start: entry.points[index], end })));
+          for (const gap of unrelatedSegments.length ? gridComponentGaps : []) {
+            planningMetrics.gridSearchCount += 1;
+            const strict = shortestOrthogonalGridRoute({
+              start,
+              end,
+              points: [start, end],
+              obstacles: [...gridComponentObstacles(conn, gap), ...reservedLabelObstacles(2)],
+              fromSide,
+              toSide,
+              clearance: 2,
+              maximumObstacleCount: 80,
+              endpointStubPx: 24,
+              maximumGridNodes: 4096,
+              avoidedSegments: unrelatedSegments,
+              allowAvoidedCrossings: false,
+              minimumAvoidedOverlapPx: 8,
+              routeSeparationPx: 8,
+              minimumSegmentPx: interiorSegmentPx,
+              borderSegments: frameBorders,
+              bendPenaltyPx: 48,
+            });
+            if (strict
+                && routeClearsEndpointComponents(strict.points, from, to)
+                && routeClearsComponents(conn, strict.points)
+                && !routeConflictsWithResolved(conn, strict.points, resolvedRoutes)
+                && !routeOverlapsResolved(conn, strict.points, resolvedRoutes)
+                && routeMeetsCompositionFloors(strict.points)
+                && spacedRouteIsClean(strict.points, gap)) {
+              planningMetrics.gridRoutedCount += 1;
+              return strict.points.slice(1, -1);
+            }
+          }
+        }
+        const avoidedSegments = resolvedRoutes
+          .filter((entry) => distinctAutomaticPorts && relationshipsShareEndpoint(conn, entry.conn)
+            && !hasAuthoredRouteGeometry(entry.conn) && !entry.conn.labelAt && !conn.labelAt)
+          .flatMap((entry) => entry.points.slice(1).map((end, index) => ({
+            start: entry.points[index], end,
+          })));
+        for (const gap of gridComponentGaps) {
+          const gridMetrics = {};
+          planningMetrics.gridSearchCount += 1;
+          planningMetrics.avoidedSegmentCount += avoidedSegments.length;
+          const searched = shortestOrthogonalGridRoute({
+            start,
+            end,
+            points: [start, end],
+            obstacles: [...gridComponentObstacles(conn, gap), ...reservedLabelObstacles(2)],
+            fromSide,
+            toSide,
+            clearance: 2,
+            maximumObstacleCount: 80,
+            endpointStubPx: 24,
+            maximumGridNodes: 4096,
+            avoidedSegments,
+            allowAvoidedCrossings: true,
+            minimumAvoidedOverlapPx: 8,
+            routeSeparationPx: 8,
+            minimumSegmentPx: interiorSegmentPx,
+            borderSegments: frameBorders,
+            bendPenaltyPx: 48,
+            metrics: gridMetrics,
+          });
+          planningMetrics.gridCandidateNodeCount += gridMetrics.candidateNodeCount || 0;
+          planningMetrics.gridUsableNodeCount += gridMetrics.usableNodeCount || 0;
+          planningMetrics.gridEdgeCount += gridMetrics.graphEdgeCount || 0;
+          planningMetrics.gridVisitedNodeCount += gridMetrics.visitedNodeCount || 0;
+          const clearsEndpoints = searched
+            ? routeClearsEndpointComponents(searched.points, from, to) : false;
+          const clearsComponents = searched
+            ? routeClearsComponents(conn, searched.points) : false;
+          const clearsRelationships = searched
+            ? !routeConflictsWithResolved(conn, searched.points, resolvedRoutes) : false;
+          const clearsSharedCorridors = searched
+            ? !routeOverlapsResolved(conn, searched.points, resolvedRoutes) : false;
+          const meetsFloors = searched
+            ? routeMeetsCompositionFloors(searched.points) && spacedRouteIsClean(searched.points, gap) : false;
+          const accepted = Boolean(
+            searched && clearsEndpoints && clearsComponents && clearsSharedCorridors && meetsFloors,
+          );
+          planningMetrics.gridAttempts.push({
+            relationship: conn.id || `${conn.from}->${conn.to}`,
+            fromSide,
+            toSide,
+            inputAvoidedSegmentCount: avoidedSegments.length,
+            ...gridMetrics,
+            accepted,
+            ...(!accepted && searched ? {
+              rejectedBy: [
+                ...(!clearsEndpoints ? ['endpoint-components'] : []),
+                ...(!clearsComponents ? ['components'] : []),
+                ...(!clearsSharedCorridors ? ['shared-corridor'] : []),
+                ...(!meetsFloors ? ['composition-floors'] : []),
+              ],
+              candidatePoints: searched.points,
+            } : {}),
+          });
+          if (accepted) {
+            planningMetrics.gridRoutedCount += 1;
+            if (!clearsRelationships) planningMetrics.crossoverRoutedCount += 1;
+            return searched.points.slice(1, -1);
+          }
+        }
+
+        // Both bounded doglegs are blocked. Keep the best endpoint-safe route
+        // when one exists so the universal Clean Flow gate reports the actual
+        // obstacle; otherwise preserve the historical deterministic fallback
+        // and let the endpoint-direction gate explain the side mismatch.
+        planningMetrics.conflictFallbackCount += 1;
+        return sideSafe[0] || sideAware[0] || horizontalFirst;
+      }
+    }
+  }
+
+  // A node's neighbours laid out as one row below (or above) it read as a
+  // fan-out: reach them all through the same vertical side. Center-based
+  // inference alone sends the outer ones sideways around their siblings.
+  const neighbourRects = new Map();
+  for (const conn of connections) {
+    const from = components.get(conn.from);
+    const to = components.get(conn.to);
+    if (!from || !to || from === to) continue;
+    for (const [node, other] of [[from, to], [to, from]]) {
+      neighbourRects.set(node.id, [...(neighbourRects.get(node.id) || []), other]);
+    }
+  }
+  function rowFanOutSides(from, to) {
+    if (!preferReadableRoutes) return null;
+    const verticalSides = (node, other) => {
+      const below = other.y >= node.y + node.height;
+      if (!below && other.y + other.height > node.y) return null;
+      if (['top', 'bottom'].includes(defaultFromSide(node, other))) return null;
+      const rowSibling = (neighbourRects.get(node.id) || []).some((sibling) => sibling !== other
+        && Math.abs(sibling.cy - other.cy) < 1
+        && defaultFromSide(node, sibling) === (below ? 'bottom' : 'top'));
+      // Only when a node of that row blocks a sideways route to one of the
+      // neighbours on this side; otherwise side exits stay clear and keep the
+      // vertical side free. Decide per side so a row never mixes both styles.
+      const blocked = (target) => {
+        const [gapStart, gapEnd] = target.cx < node.cx
+          ? [target.x + target.width, node.x] : [node.x + node.width, target.x];
+        return [...components.values()].some((rect) => rect !== node && rect !== target
+          && rect.y < target.y + target.height && rect.y + rect.height > target.y
+          && rect.x < gapEnd && rect.x + rect.width > gapStart);
+      };
+      const sameSide = (neighbourRects.get(node.id) || []).filter((sibling) => Math.abs(sibling.cy - other.cy) < 1
+        && defaultFromSide(node, sibling) === defaultFromSide(node, other));
+      return rowSibling && sameSide.some(blocked) ? (below ? 'bottom' : 'top') : null;
+    };
+    const opposite = { top: 'bottom', bottom: 'top' };
+    const fromSide = verticalSides(from, to);
+    if (fromSide) return { fromSide, toSide: opposite[fromSide] };
+    const toSide = verticalSides(to, from);
+    return toSide ? { fromSide: opposite[toSide], toSide } : null;
+  }
+
+  const pathCache = new Map();
+  const selectedSides = new Map();
+  const stroke = (relation) => relation.width || (relation.variant === 'emphasis' ? 1.8 : 1.5);
+  const markerSpacing = (left, right) => 3.5 * (stroke(left) + stroke(right));
+  const portSpacing = (left, right) => Math.max(14, markerSpacing(left, right) + 3.5);
+  function fanOutSide(conn, endpoint) {
+    const fanOut = rowFanOutSides(components.get(conn.from), components.get(conn.to));
+    return endpoint === 'source' ? fanOut?.fromSide : fanOut?.toSide;
+  }
+  // A caller may own the endpoint side of a relationship; whatever it leaves
+  // unresolved keeps architecture's row fan-out inference.
+  function inferredSide(conn, endpoint) {
+    return sideFor?.(conn, endpoint) || fanOutSide(conn, endpoint);
+  }
+  const automaticPorts = automaticPortSpread(connections, components, {
+    sideFor: inferredSide,
+    ...(maxPortSpacing === null ? {} : { maxSpacing: maxPortSpacing }),
+    // Preserve the established initial placement for ordinary markers; only
+    // widen groups whose arrowheads cannot fit the legacy 14px slots.
+    ...(distinctAutomaticPorts ? { spacingFor: (left, right) =>
+      markerSpacing(left, right) > 14 ? portSpacing(left, right) : 14 } : {}),
+  });
+  const incidentEndpoints = new Map();
+  for (const conn of connections) {
+    if (!components.has(conn.from) || !components.has(conn.to)) continue;
+    for (const [field, sideField] of [['from', 'fromSide'], ['to', 'toSide']]) {
+      const entries = incidentEndpoints.get(conn[field]) || [];
+      entries.push({ conn, field, sideField });
+      incidentEndpoints.set(conn[field], entries);
+    }
+  }
+  function inferredConnectionSides(conn) {
+    const from = components.get(conn.from);
+    const to = components.get(conn.to);
+    return {
+      fromSide: chosenSide(conn.fromSide, inferredSide(conn, 'source') || defaultFromSide(from, to)),
+      toSide: chosenSide(conn.toSide, inferredSide(conn, 'target') || defaultToSide(from, to)),
+    };
+  }
+
+  function connectionSides(conn) {
+    if (!routesPlanned && !routesPlanning) planRoutes();
+    return selectedSides.get(conn) || inferredConnectionSides(conn);
+  }
+
+  // The same side inference without the planning pass. A caller that must group
+  // relationships before any route exists (the erd renderer assigns a shared
+  // trunk per fan-in) reads its sides here: connectionSides() plans routes, and
+  // planning asks the grouping what the trunks are.
+  function inferredSides(conn) {
+    return inferredConnectionSides(conn);
+  }
+
+  function connectionEndpointSide(conn, endpoint) {
+    const field = endpoint === 'source' ? 'fromSide' : 'toSide';
+    if (conn[field] && conn[field] !== 'auto') return conn[field];
+    return connectionSides(conn)[field];
+  }
+
+  function hasAuthoredRouteGeometry(conn) {
+    return Boolean(
+      conn?.via
+      || (conn?.route && conn.route !== 'auto')
+      || conn?.channelX !== undefined
+      || conn?.channelY !== undefined
+    );
+  }
+
+  function hasAuthoredLabelPlacement(conn) {
+    return ['labelAt', 'labelDx', 'labelDy', 'labelSegment']
+      .some((field) => conn?.[field] !== undefined);
+  }
+
+  // A route can change sides after the initial port spread. Reserve slots on
+  // the final side as well: falling back to its midpoint can put an arrow
+  // between two existing slots, or directly on another incoming arrow.
+  function automaticEndpoint(conn, endpoint, rect, side, inferredSide) {
+    const initial = side === inferredSide ? automaticPorts.get(conn)?.[endpoint] : null;
+    const preferred = initial || anchor(rect, side);
+    if (hasAuthoredRouteGeometry(conn) || conn.labelAt) return { point: preferred, spread: Boolean(initial) };
+    const axis = side === 'left' || side === 'right' ? 1 : 0;
+    const occupied = [];
+    for (const { conn: other, field, sideField } of incidentEndpoints.get(rect.id) || []) {
+      if (other === conn || hasAuthoredRouteGeometry(other) || other.labelAt) continue;
+      const routed = pathCache.get(other);
+      const sides = selectedSides.get(other) || inferredConnectionSides(other);
+      if (sides[sideField] !== side) continue;
+      const point = routed
+        ? (field === 'from' ? routed.points[0] : routed.points.at(-1))
+        : automaticPorts.get(other)?.[field] || anchor(rect, side);
+      occupied.push({ value: point[axis], spacing: portSpacing(conn, other) });
+    }
+    if (!occupied.length) return { point: preferred, spread: Boolean(initial) };
+    // On an alternate side, equally close slots should approach the other
+    // node rather than pass its neighbours just because a coordinate is lower.
+    // Keep the established spread order on the inferred side unchanged.
+    const counterpart = components.get(endpoint === 'from' ? conn.to : conn.from);
+    const toward = side === inferredSide ? preferred[axis] : (axis === 1 ? counterpart.cy : counterpart.cx);
+    const candidates = [preferred[axis], ...occupied.flatMap(({ value, spacing }) => [value - spacing, value + spacing])]
+      .sort((a, b) => Math.abs(a - preferred[axis]) - Math.abs(b - preferred[axis])
+        || Math.abs(a - toward) - Math.abs(b - toward) || a - b);
+    for (const value of candidates) {
+      const point = [...preferred];
+      point[axis] = value;
+      if (portHasCornerClearance(rect, side, point)
+          && occupied.every((other) => Math.abs(value - other.value) >= other.spacing - 0.0001)) {
+        return { point, spread: true };
+      }
+    }
+    return { point: preferred, spread: true, crowded: true };
+  }
+
+  function connectionGeometry(conn, sides = inferredConnectionSides(conn)) {
+    const from = components.get(conn.from);
+    const to = components.get(conn.to);
+    const inferred = inferredConnectionSides(conn);
+    const { fromSide, toSide } = sides;
+    const legacyPorts = fromSide === inferred.fromSide && toSide === inferred.toSide ? automaticPorts.get(conn) : null;
+    const source = distinctAutomaticPorts
+      ? automaticEndpoint(conn, 'from', from, fromSide, inferred.fromSide)
+      : { point: legacyPorts?.from || anchor(from, fromSide), spread: Boolean(legacyPorts?.from) };
+    const target = distinctAutomaticPorts
+      ? automaticEndpoint(conn, 'to', to, toSide, inferred.toSide)
+      : { point: legacyPorts?.to || anchor(to, toSide), spread: Boolean(legacyPorts?.to) };
+    const ports = { from: source.spread, to: target.spread };
+    const { start, end } = alignFacingPorts(
+      conn,
+      from,
+      to,
+      source.point,
+      target.point,
+      fromSide,
+      toSide,
+      ports,
+    );
+    return { from, to, start, end, fromSide, toSide, crowded: source.crowded || target.crowded };
+  }
+
+  function routedForGeometry(conn, resolvedRoutes, geometry) {
+    const { from, to, start, end, fromSide, toSide } = geometry;
+    const authoredPoints = [
+      start,
+      ...routeVia(conn, from, to, start, end, fromSide, toSide, resolvedRoutes),
+      end,
+    ];
+    // Explicit waypoints are author-owned geometry. Keep even a collinear
+    // waypoint: it can intentionally split a route at a semantic touch point,
+    // and preserving it is part of the backwards-compatible authoring contract.
+    // Automatic routes remain normalized so the renderer does not emit noisy
+    // duplicate turns or zero-length segments.
+    const points = hasAuthoredRouteGeometry(conn)
+      ? authoredPoints
+      : normalizeRoutePoints(authoredPoints);
+    return { d: roundedPath(points, 8), points };
+  }
+
+  function cachePath(conn, routed, sides) {
+    pathCache.set(conn, routed);
+    selectedSides.set(conn, { fromSide: sides.fromSide, toSide: sides.toSide });
+    return routed;
+  }
+
+  const SIDE_ORDER = ['right', 'bottom', 'left', 'top'];
+  function candidateSidePairs(conn) {
+    const inferred = inferredConnectionSides(conn);
+    const authoredFrom = conn.fromSide && conn.fromSide !== 'auto' ? conn.fromSide : null;
+    const authoredTo = conn.toSide && conn.toSide !== 'auto' ? conn.toSide : null;
+    const fromOptions = authoredFrom
+      ? [authoredFrom]
+      : [inferred.fromSide, ...SIDE_ORDER.filter((side) => side !== inferred.fromSide)];
+    const toOptions = authoredTo
+      ? [authoredTo]
+      : [inferred.toSide, ...SIDE_ORDER.filter((side) => side !== inferred.toSide)];
+    return fromOptions.flatMap((fromSide) => toOptions.map((toSide) => ({
+      fromSide,
+      toSide,
+      deviationCount: Number(fromSide !== inferred.fromSide) + Number(toSide !== inferred.toSide),
+    }))).sort((left, right) => {
+      if (left.deviationCount !== right.deviationCount) {
+        return left.deviationCount - right.deviationCount;
+      }
+      const leftGeometry = connectionGeometry(conn, left);
+      const rightGeometry = connectionGeometry(conn, right);
+      const leftDistance = Math.abs(leftGeometry.end[0] - leftGeometry.start[0])
+        + Math.abs(leftGeometry.end[1] - leftGeometry.start[1]);
+      const rightDistance = Math.abs(rightGeometry.end[0] - rightGeometry.start[0])
+        + Math.abs(rightGeometry.end[1] - rightGeometry.start[1]);
+      return leftDistance - rightDistance;
+    });
+  }
+
+  function routeIsClear(conn, routed, geometry, resolvedRoutes) {
+    return !geometry.crowded && routed.points.length >= 2
+      && routeHonorsEndpointSides(routed.points, geometry.fromSide, geometry.toSide)
+      && routeClearsEndpointComponents(routed.points, geometry.from, geometry.to)
+      && routeClearsComponents(conn, routed.points)
+      && routeMeetsCompositionFloors(routed.points)
+      && !routeOverlapsResolved(conn, routed.points, resolvedRoutes);
+  }
+
+  function crossingCount(conn, points, resolvedRoutes) {
+    let count = 0;
+    for (const entry of resolvedRoutes) {
+      if (relationshipsShareEndpoint(conn, entry.conn)
+          && (!distinctAutomaticPorts || hasAuthoredRouteGeometry(entry.conn) || entry.conn.labelAt || conn.labelAt)) continue;
+      let crosses = false;
+      for (let index = 1; index < points.length && !crosses; index += 1) {
+        for (let otherIndex = 1; otherIndex < entry.points.length; otherIndex += 1) {
+          if (properSegmentIntersection(points[index - 1], points[index], entry.points[otherIndex - 1], entry.points[otherIndex])) {
+            crosses = true;
+            break;
+          }
+        }
+      }
+      if (crosses) count += 1;
+    }
+    return count;
+  }
+
+  function readabilityCost(conn, routed, resolvedRoutes) {
+    const points = routed.points;
+    const length = points.slice(1).reduce((total, point, index) => total
+      + Math.abs(point[0] - points[index][0]) + Math.abs(point[1] - points[index][1]), 0);
+    // A crossover is a reading cost even with a halo. Keep it finite: avoiding
+    // one crossing must not justify an arbitrarily long perimeter excursion.
+    return length + Math.max(0, points.length - 2) * 48 + crossingCount(conn, points, resolvedRoutes) * 160;
+  }
+
+  function computePath(conn, resolvedRoutes) {
+    if (hasAuthoredRouteGeometry(conn)) {
+      const sides = inferredConnectionSides(conn);
+      return cachePath(conn, routedForGeometry(
+        conn,
+        resolvedRoutes,
+        connectionGeometry(conn, sides),
+      ), sides);
+    }
+
+    let firstFallback = null;
+    const clearRoute = () => {
+      let firstClear = null;
+      for (const sides of candidateSidePairs(conn)) {
+        const geometry = connectionGeometry(conn, sides);
+        const routed = routedForGeometry(conn, resolvedRoutes, geometry);
+        if (!firstFallback) firstFallback = { routed, sides };
+        if (routeIsClear(conn, routed, geometry, resolvedRoutes)) {
+          firstClear = { routed, sides };
+          break;
+        }
+      }
+      return firstClear;
+    };
+    const routeLength = ({ routed }) => routed.points.slice(1)
+      .reduce((total, point, index) => total + Math.abs(point[0] - routed.points[index][0]) + Math.abs(point[1] - routed.points[index][1]), 0);
+
+    // Reserved labels are a preference, not an obstacle. A route that has no
+    // corridor around them, or that would have to detour far around them,
+    // takes the plain route instead and the label placement pass moves the
+    // label; only a modest extra length is worth keeping a label in place.
+    honourReservedLabels = true;
+    let chosen = clearRoute();
+    if (reservedLabels.length) {
+      honourReservedLabels = false;
+      if (!chosen) chosen = clearRoute();
+      else {
+        const direct = Math.abs(chosen.routed.points.at(-1)[0] - chosen.routed.points[0][0])
+          + Math.abs(chosen.routed.points.at(-1)[1] - chosen.routed.points[0][1]);
+        if (routeLength(chosen) > direct * 1.25 + 64) {
+          const plain = clearRoute();
+          if (plain && routeLength(plain) * 1.25 + 64 < routeLength(chosen)) chosen = plain;
+        }
+      }
+      honourReservedLabels = true;
+    }
+    if (chosen) return cachePath(conn, chosen.routed, chosen.sides);
+    return cachePath(conn, firstFallback.routed, firstFallback.sides);
+  }
+
+  let routesPlanned = false;
+  let routesPlanning = false;
+  function planRoutes() {
+    if (routesPlanned || routesPlanning) return;
+    routesPlanning = true;
+    const indexed = connections
+      .map((conn, index) => ({ conn, index }))
+      .filter(({ conn }) => components.has(conn.from) && components.has(conn.to));
+    const explicit = indexed.filter(({ conn }) => hasAuthoredRouteGeometry(conn));
+    const automatic = indexed.filter(({ conn }) => !hasAuthoredRouteGeometry(conn))
+      .sort((left, right) => {
+        const leftFrom = components.get(left.conn.from);
+        const leftTo = components.get(left.conn.to);
+        const rightFrom = components.get(right.conn.from);
+        const rightTo = components.get(right.conn.to);
+        const leftDistance = Math.abs(leftTo.cx - leftFrom.cx) + Math.abs(leftTo.cy - leftFrom.cy);
+        const rightDistance = Math.abs(rightTo.cx - rightFrom.cx) + Math.abs(rightTo.cy - rightFrom.cy);
+        return leftDistance - rightDistance || left.index - right.index;
+      });
+    const resolvedRoutes = [];
+    reservedLabels = [];
+    for (const { conn } of [...explicit, ...automatic]) {
+      const routed = computePath(conn, resolvedRoutes);
+      resolvedRoutes.push({ conn, points: routed.points });
+      const rect = labelRectFor?.(conn, routed.points, {
+        routes: resolvedRoutes.map((entry) => entry.points),
+        labels: reservedLabels.map((entry) => entry.rect),
+      });
+      if (rect) reservedLabels.push({ conn, rect });
+    }
+    // Improve against the complete set of routes, not only earlier edges.
+    // A greedy side change during the initial pass can steal a later edge's
+    // corridor. This bounded sweep only changes one route at a time, keeping
+    // every other route and label as an obstacle/reference.
+    if (preferReadableRoutes) {
+      const scenePoints = resolvedRoutes.flatMap((entry) => entry.points);
+      for (const rect of [...components.values(), ...frames, ...reservedLabels.map((entry) => entry.rect)]) {
+        scenePoints.push([rect.x, rect.y], [rect.x + rect.width, rect.y + rect.height]);
+      }
+      const bounds = {
+        left: Math.min(...scenePoints.map(([x]) => x)), right: Math.max(...scenePoints.map(([x]) => x)),
+        top: Math.min(...scenePoints.map(([, y]) => y)),
+        bottom: Math.max(...scenePoints.map(([, y]) => y)),
+      };
+      const withinScene = ([x, y]) => x >= bounds.left && x <= bounds.right && y >= bounds.top && y <= bounds.bottom;
+      const jointlyImproved = new Set();
+      const endpointSlotsClear = (candidateRoutes, others, sidesOf) => {
+        const entries = [...others, ...candidateRoutes];
+        for (const candidate of candidateRoutes) {
+          const sides = sidesOf(candidate.conn);
+          for (const [componentId, side, point] of [
+            [candidate.conn.from, sides.fromSide, candidate.points[0]],
+            [candidate.conn.to, sides.toSide, candidate.points.at(-1)],
+          ]) {
+            const coordinate = side === 'left' || side === 'right' ? 1 : 0;
+            for (const other of entries) {
+              if (other.conn === candidate.conn) continue;
+              const otherSides = sidesOf(other.conn);
+              for (const [otherId, otherSide, otherPoint] of [
+                [other.conn.from, otherSides.fromSide, other.points[0]],
+                [other.conn.to, otherSides.toSide, other.points.at(-1)],
+              ]) {
+                if (componentId === otherId && side === otherSide
+                    && Math.abs(point[coordinate] - otherPoint[coordinate])
+                      < portSpacing(candidate.conn, other.conn) - 0.0001) return false;
+              }
+            }
+          }
+        }
+        return true;
+      };
+      const labelClears = (rect, owner, entries, labels) => {
+        if (!rect) return !owner.label;
+        if (!withinScene([rect.x, rect.y])
+            || !withinScene([rect.x + rect.width, rect.y + rect.height])
+            || labels.some((other) => rectsOverlap(rect, other.rect, 2))) return false;
+        return entries.every((entry) => entry.conn === owner || entry.points.slice(1).every((end, index) =>
+          !segmentIntersectsRect({ start: entry.points[index], end }, rect, LABEL_CLEARANCE)));
+      };
+      function improveReciprocalPairs() {
+        // A one-route sweep cannot repair reciprocal facing edges whose initial
+        // spread groups differ. Try both direct lanes together after final side
+        // geometry is known, leaving every other route and authored port in place.
+        const paired = new Set();
+        for (const first of resolvedRoutes) {
+          const conn = first.conn;
+          if (paired.has(conn) || typeOwned.has(conn) || hasAuthoredRouteGeometry(conn) || hasAuthoredLabelPlacement(conn)
+              || (conn.fromSide && conn.fromSide !== 'auto')
+              || (conn.toSide && conn.toSide !== 'auto')) continue;
+          const second = resolvedRoutes.find((entry) => entry !== first
+            && entry.conn.from === conn.to && entry.conn.to === conn.from && !typeOwned.has(entry.conn)
+            && !hasAuthoredRouteGeometry(entry.conn) && !hasAuthoredLabelPlacement(entry.conn)
+            && (!entry.conn.fromSide || entry.conn.fromSide === 'auto')
+            && (!entry.conn.toSide || entry.conn.toSide === 'auto'));
+          if (!second) continue;
+          paired.add(conn);
+          paired.add(second.conn);
+          const firstSides = inferredConnectionSides(conn);
+          const secondSides = inferredConnectionSides(second.conn);
+          const horizontal = firstSides.fromSide === 'right' && firstSides.toSide === 'left'
+            && secondSides.fromSide === 'left' && secondSides.toSide === 'right';
+          const horizontalReverse = firstSides.fromSide === 'left' && firstSides.toSide === 'right'
+            && secondSides.fromSide === 'right' && secondSides.toSide === 'left';
+          const vertical = firstSides.fromSide === 'bottom' && firstSides.toSide === 'top'
+            && secondSides.fromSide === 'top' && secondSides.toSide === 'bottom';
+          const verticalReverse = firstSides.fromSide === 'top' && firstSides.toSide === 'bottom'
+            && secondSides.fromSide === 'bottom' && secondSides.toSide === 'top';
+          if (!horizontal && !horizontalReverse && !vertical && !verticalReverse) continue;
+          if (first.points.length <= 2 && second.points.length <= 2) continue;
+          const axis = horizontal || horizontalReverse ? 1 : 0;
+          const others = resolvedRoutes.filter((entry) => entry !== first && entry !== second);
+          const firstGeometry = connectionGeometry(conn, firstSides);
+          const secondGeometry = connectionGeometry(second.conn, secondSides);
+          if (firstGeometry.crowded || secondGeometry.crowded) continue;
+          const previousLabels = reservedLabels;
+          let improved = false;
+          reservedLabels = reservedLabels.filter((entry) => entry.conn !== conn && entry.conn !== second.conn);
+          try {
+            const lanes = (geometry) => [...new Set([geometry.start[axis], geometry.end[axis]])];
+            const direct = (geometry, lane) => {
+              const start = [...geometry.start];
+              const end = [...geometry.end];
+              start[axis] = lane;
+              end[axis] = lane;
+              return { points: [start, end], d: roundedPath([start, end], 8) };
+            };
+            const pairSides = (candidate) => (candidate === conn ? firstSides
+              : candidate === second.conn ? secondSides : selectedSides.get(candidate));
+            let best = null;
+            let bestCost = readabilityCost(conn, first, [...others, second])
+              + readabilityCost(second.conn, second, [...others, first]);
+            for (const firstLane of lanes(firstGeometry)) {
+              for (const secondLane of lanes(secondGeometry)) {
+                planningMetrics.reciprocalCandidateCount += 1;
+                const firstRoute = { conn, ...direct(firstGeometry, firstLane) };
+                const secondRoute = { conn: second.conn, ...direct(secondGeometry, secondLane) };
+                const candidates = [firstRoute, secondRoute];
+                if (!candidates.every((entry) => entry.points.every(withinScene))) continue;
+                if (!endpointSlotsClear(candidates, others, pairSides)) continue;
+                if (!candidates.every((entry, index) => {
+                  const geometry = entry.conn === conn ? firstGeometry : secondGeometry;
+                  if (!portHasCornerClearance(geometry.from, geometry.fromSide, entry.points[0])
+                      || !portHasCornerClearance(geometry.to, geometry.toSide, entry.points.at(-1))) return false;
+                  return routeIsClear(entry.conn, entry, geometry, [...others, candidates[1 - index]]);
+                })) continue;
+                const firstRect = labelRectFor?.(conn, firstRoute.points, {
+                  routes: [...others.map((entry) => entry.points), ...candidates.map((entry) => entry.points)],
+                  labels: reservedLabels.map((entry) => entry.rect),
+                });
+                if (!labelClears(firstRect, conn, [...others, secondRoute], reservedLabels)) continue;
+                const secondRect = labelRectFor?.(second.conn, secondRoute.points, {
+                  routes: [...others.map((entry) => entry.points), ...candidates.map((entry) => entry.points)],
+                  labels: [...reservedLabels.map((entry) => entry.rect), ...(firstRect ? [firstRect] : [])],
+                });
+                if (!labelClears(secondRect, second.conn, [...others, firstRoute], [
+                  ...reservedLabels, ...(firstRect ? [{ conn, rect: firstRect }] : []),
+                ])) continue;
+                const cost = readabilityCost(conn, firstRoute, [...others, secondRoute])
+                  + readabilityCost(second.conn, secondRoute, [...others, firstRoute]);
+                if (cost < bestCost) {
+                  best = { firstRoute, secondRoute, firstRect, secondRect };
+                  bestCost = cost;
+                }
+              }
+            }
+            if (!best) continue;
+            cachePath(conn, best.firstRoute, firstSides);
+            cachePath(second.conn, best.secondRoute, secondSides);
+            first.points = best.firstRoute.points;
+            second.points = best.secondRoute.points;
+            planningMetrics.reciprocalImprovedCount += 1;
+            jointlyImproved.add(conn);
+            jointlyImproved.add(second.conn);
+            improved = true;
+            reservedLabels = [
+              ...reservedLabels,
+              ...(best.firstRect ? [{ conn, rect: best.firstRect }] : []),
+              ...(best.secondRect ? [{ conn: second.conn, rect: best.secondRect }] : []),
+            ];
+          } finally {
+            if (!improved) reservedLabels = previousLabels;
+          }
+        }
+      }
+      // A type-owned corridor (an erd bundled trunk or dedicated lane) is the
+      // route its renderer draws around; the generic sweep must not trade it
+      // for a shorter lane and leave the bus without its branch.
+      const followsPreferredCorridor = (entry) => {
+        if (!preferredCandidates) return false;
+        const sides = selectedSides.get(entry.conn);
+        if (!sides) return false;
+        const interior = JSON.stringify(entry.points.slice(1, -1));
+        return (preferredCandidates({
+          conn: entry.conn,
+          from: components.get(entry.conn.from),
+          to: components.get(entry.conn.to),
+          start: entry.points[0],
+          end: entry.points.at(-1),
+          fromSide: sides.fromSide,
+          toSide: sides.toSide,
+        }) || []).some((candidate) => JSON.stringify(candidate) === interior);
+      };
+      const typeOwned = new Set(resolvedRoutes.filter(followsPreferredCorridor).map((entry) => entry.conn));
+      function relocatedLabelsFor(conn, routed, others) {
+        // A provisional label may occupy an otherwise clear corridor. Move at
+        // most one automatic label, on its existing route, and accept the pair
+        // only when both labels fit without borrowing other labels' space.
+        const displaced = reservedLabels.filter((label) => label.conn !== conn && routed.points.slice(1).some((end, index) =>
+          segmentIntersectsRect({ start: routed.points[index], end }, label.rect, LABEL_CLEARANCE)));
+        if (displaced.length !== 1) return null;
+        const owner = displaced[0].conn;
+        if (typeOwned.has(owner) || hasAuthoredRouteGeometry(owner) || hasAuthoredLabelPlacement(owner)) return null;
+        const labels = reservedLabels.filter((label) => label.conn !== conn && label.conn !== owner);
+        const routes = [...others, { conn, points: routed.points }];
+        const moved = routes.find((entry) => entry.conn === owner);
+        for (const entry of [moved, { conn, points: routed.points }]) {
+          const rect = labelRectFor?.(entry.conn, entry.points, {
+            routes: routes.map((route) => route.points),
+            labels: labels.map((label) => label.rect),
+          });
+          if (!labelClears(rect, entry.conn, routes, labels)
+              || (rect && [...components.values()].some((component) => rectsOverlap(rect, component, -2)))) return null;
+          if (rect) labels.push({ conn: entry.conn, rect });
+        }
+        return labels;
+      }
+      function improveComplexRoutes(onlyCrossings = false) {
+        for (const entry of resolvedRoutes) {
+          const { conn } = entry;
+          if (jointlyImproved.has(conn) || typeOwned.has(conn) || hasAuthoredRouteGeometry(conn) || hasAuthoredLabelPlacement(conn)) continue;
+          const others = resolvedRoutes.filter((other) => other !== entry);
+          // Preserve uncomplicated routes and their established inferred sides.
+          // Spend the comparison budget where the complete scene has a reading
+          // cost: a crossover, more than two bends, or no room for its label.
+          const crossingsBefore = crossingCount(conn, entry.points, others);
+          const currentLabel = labelRectFor?.(conn, entry.points, {
+            routes: others.map(other => other.points),
+            labels: reservedLabels.filter(label => label.conn !== conn).map(label => label.rect),
+          });
+          const labelBlocked = Boolean(conn.label && labelRectFor && !currentLabel);
+          if (!labelBlocked && crossingsBefore === 0 && (onlyCrossings || entry.points.length <= 4)) continue;
+          let best = null;
+          let bestCost = labelBlocked ? Infinity : readabilityCost(conn, { points: entry.points }, others);
+          for (const sides of candidateSidePairs(conn)) {
+            const geometry = connectionGeometry(conn, sides);
+            const routed = routedForGeometry(conn, others, geometry);
+            planningMetrics.readabilityCandidateCount += 1;
+            if (!routed.points.every(withinScene) || !routeIsClear(conn, routed, geometry, others)) continue;
+            if (onlyCrossings && crossingCount(conn, routed.points, others) >= crossingsBefore) continue;
+            const cost = readabilityCost(conn, routed, others);
+            if (cost < bestCost) {
+              const rect = labelRectFor?.(conn, routed.points, {
+                routes: [...others.map((other) => other.points), routed.points],
+                labels: reservedLabels.filter((label) => label.conn !== conn).map((label) => label.rect),
+              });
+              // Include the reserved label in this pass's bounds. In
+              // particular, a shorter route must not widen and shrink the graph.
+              if (labelRectFor && !labelClears(rect, conn, others, reservedLabels.filter(label => label.conn !== conn))) continue;
+              if (onlyCrossings && (!endpointSlotsClear([{ conn, points: routed.points }], others,
+                candidate => candidate === conn ? sides : selectedSides.get(candidate))
+                  || (rect && [...components.values()].some(component => rectsOverlap(rect, component, -2))))) continue;
+              best = { routed, sides, rect };
+              bestCost = cost;
+            }
+          }
+          if (!best) continue;
+          cachePath(conn, best.routed, best.sides);
+          entry.points = best.routed.points;
+          planningMetrics.readabilityImprovedCount += 1;
+          reservedLabels = reservedLabels.filter((label) => label.conn !== conn);
+          if (best.rect) reservedLabels.push({ conn, rect: best.rect });
+        }
+      }
+      allowGridSearch = false;
+      try {
+        improveReciprocalPairs();
+        improveComplexRoutes();
+        // A bent route between nodes that overlap across the gap separating
+        // them can run straight through facing sides inside that overlap.
+        // Authored sides must already face; every other route, slot and label
+        // stays fixed, and the straight lane must pass the same checks.
+        for (const entry of resolvedRoutes) {
+          const { conn } = entry;
+          if (entry.points.length < 4 || jointlyImproved.has(conn) || typeOwned.has(conn)
+              || hasAuthoredRouteGeometry(conn) || hasAuthoredLabelPlacement(conn)) continue;
+          const from = components.get(conn.from);
+          const to = components.get(conn.to);
+          const facing = from.x + from.width <= to.x ? { fromSide: 'right', toSide: 'left' }
+            : to.x + to.width <= from.x ? { fromSide: 'left', toSide: 'right' }
+              : from.y + from.height <= to.y ? { fromSide: 'bottom', toSide: 'top' }
+                : to.y + to.height <= from.y ? { fromSide: 'top', toSide: 'bottom' } : null;
+          if (!facing) continue;
+          const axis = facing.fromSide === 'right' || facing.fromSide === 'left' ? 1 : 0;
+          const [origin, size] = axis === 1 ? ['y', 'height'] : ['x', 'width'];
+          const low = Math.max(from[origin], to[origin]) + AUTOMATIC_PORT_CORNER_GUTTER;
+          const high = Math.min(from[origin] + from[size], to[origin] + to[size]) - AUTOMATIC_PORT_CORNER_GUTTER;
+          if (high < low
+              || (conn.fromSide && conn.fromSide !== 'auto' && conn.fromSide !== facing.fromSide)
+              || (conn.toSide && conn.toSide !== 'auto' && conn.toSide !== facing.toSide)) continue;
+          const sides = facing;
+          const geometry = connectionGeometry(conn, sides);
+          const start = geometry.start;
+          const end = geometry.end;
+          const clamp = (value) => Math.min(high, Math.max(low, value));
+          const others = resolvedRoutes.filter((other) => other !== entry);
+          const otherLabels = reservedLabels.filter((label) => label.conn !== conn);
+          const crossingsBefore = crossingCount(conn, entry.points, others);
+          const sidesOf = (candidate) => (candidate === conn ? sides : selectedSides.get(candidate));
+          for (const lane of new Set([start[axis], end[axis], (start[axis] + end[axis]) / 2, (low + high) / 2].map(clamp))) {
+            const points = [[...start], [...end]];
+            points[0][axis] = lane;
+            points[1][axis] = lane;
+            const routed = { conn, points, d: roundedPath(points, 8) };
+            if (!points.every(withinScene)
+                || !endpointSlotsClear([routed], others, sidesOf)
+                || !routeIsClear(conn, routed, geometry, others)
+                || crossingCount(conn, points, others) > crossingsBefore) continue;
+            const rect = labelRectFor?.(conn, points, {
+              routes: [...others.map((other) => other.points), points],
+              labels: otherLabels.map((label) => label.rect),
+            });
+            if (!labelClears(rect, conn, others, otherLabels)) continue;
+            cachePath(conn, { points, d: routed.d }, sides);
+            entry.points = points;
+            planningMetrics.readabilityImprovedCount += 1;
+            reservedLabels = [...otherLabels, ...(rect ? [{ conn, rect }] : [])];
+            break;
+          }
+        }
+        // Finish the established route/straightening plan first. Moving a
+        // label earlier could prevent a later edge from taking its straight
+        // corridor, even though the local candidate was cheaper.
+        for (const entry of resolvedRoutes) {
+          const { conn } = entry;
+          if (jointlyImproved.has(conn) || typeOwned.has(conn) || hasAuthoredRouteGeometry(conn) || hasAuthoredLabelPlacement(conn)) continue;
+          const others = resolvedRoutes.filter((other) => other !== entry);
+          if (entry.points.length <= 4 && crossingCount(conn, entry.points, others) === 0) continue;
+          let best = null;
+          let bestCost = readabilityCost(conn, entry, others);
+          if (labelRectFor && reservedLabels.some((label) => label.conn !== conn)) {
+            // One additional side sweep, with no grid search or cascading
+            // relayout. Temporary reservations can be ignored only after a
+            // replacement placement is verified against the complete scene.
+            for (const sides of candidateSidePairs(conn)) {
+              const geometry = connectionGeometry(conn, sides);
+              let routed;
+              let clear;
+              honourReservedLabels = false;
+              try {
+                routed = routedForGeometry(conn, others, geometry);
+                clear = routeIsClear(conn, routed, geometry, others);
+              } finally {
+                honourReservedLabels = true;
+              }
+              planningMetrics.labelRelocationCandidateCount += 1;
+              const cost = readabilityCost(conn, routed, others);
+              if (cost >= bestCost || !clear || !routed.points.every(withinScene)
+                  || crossingCount(conn, routed.points, others) > crossingCount(conn, entry.points, others)
+                  || !endpointSlotsClear([{ conn, points: routed.points }], others,
+                    (candidate) => candidate === conn ? sides : selectedSides.get(candidate))) continue;
+              const labels = relocatedLabelsFor(conn, routed, others);
+              if (!labels) continue;
+              best = { routed, sides, labels };
+              bestCost = cost;
+            }
+          }
+          if (!best) continue;
+          cachePath(conn, best.routed, best.sides);
+          entry.points = best.routed.points;
+          reservedLabels = best.labels;
+          planningMetrics.labelRelocationImprovedCount += 1;
+        }
+        // A side's midpoint may be blocked even when a corner port has a
+        // clear one-bend route. Probe bent automatic routes, keeping
+        // all other paths/labels fixed and the existing corner inset intact.
+        // Eight perpendicular side pairs, at most three slots per endpoint:
+        // 72 cheap candidates per route, without another grid search.
+        for (const entry of resolvedRoutes) {
+          const { conn } = entry;
+          if (entry.points.length < 4 || jointlyImproved.has(conn) || typeOwned.has(conn)
+              || hasAuthoredRouteGeometry(conn) || hasAuthoredLabelPlacement(conn)) continue;
+          const others = resolvedRoutes.filter((other) => other !== entry);
+          const labels = reservedLabels.filter((label) => label.conn !== conn);
+          const crossingsBefore = crossingCount(conn, entry.points, others);
+          let best = null;
+          let bestCost = readabilityCost(conn, entry, others);
+          const slots = (rect, side, preferred) => {
+            const horizontal = side === 'left' || side === 'right';
+            const axis = horizontal ? 1 : 0;
+            const origin = horizontal ? rect.y : rect.x;
+            const size = horizontal ? rect.height : rect.width;
+            const inset = Math.min(AUTOMATIC_PORT_CORNER_GUTTER, size / 2);
+            return [...new Set([preferred[axis], origin + inset, origin + size - inset])].map((value) => {
+              const point = [...preferred];
+              point[axis] = value;
+              return point;
+            }).filter((point) => portHasCornerClearance(rect, side, point));
+          };
+          for (const sides of candidateSidePairs(conn)) {
+            const horizontal = (side) => side === 'left' || side === 'right';
+            if (horizontal(sides.fromSide) === horizontal(sides.toSide)) continue;
+            const geometry = connectionGeometry(conn, sides);
+            for (const start of slots(geometry.from, sides.fromSide, geometry.start)) {
+              for (const end of slots(geometry.to, sides.toSide, geometry.end)) {
+                const corner = horizontal(sides.fromSide) ? [end[0], start[1]] : [start[0], end[1]];
+                const points = normalizeRoutePoints([start, corner, end]);
+                const routed = { points, d: roundedPath(points, 8) };
+                const cost = readabilityCost(conn, routed, others);
+                if (cost >= bestCost || points.length !== 3 || !points.every(withinScene)
+                    || !endpointSlotsClear([{ conn, points }], others,
+                      (candidate) => candidate === conn ? sides : selectedSides.get(candidate))
+                    || !routeIsClear(conn, routed, { ...geometry, start, end, crowded: false }, others)
+                    || crossingCount(conn, points, others) > crossingsBefore) continue;
+                const rect = labelRectFor?.(conn, points, {
+                  routes: [...others.map((other) => other.points), points],
+                  labels: labels.map((label) => label.rect),
+                });
+                if (!labelClears(rect, conn, others, labels)
+                    || (rect && [...components.values()].some((component) => rectsOverlap(rect, component, -2)))) continue;
+                best = { routed, sides, rect };
+                bestCost = cost;
+              }
+            }
+          }
+          if (!best) continue;
+          cachePath(conn, best.routed, best.sides);
+          entry.points = best.routed.points;
+          reservedLabels = [...labels, ...(best.rect ? [{ conn, rect: best.rect }] : [])];
+          planningMetrics.readabilityImprovedCount += 1;
+        }
+        // Complete the original bounded plan first. Only a remaining crossing
+        // can justify using an extra lower corridor; an already clear scene
+        // must not grow merely because its labels could move into that space.
+        if (readabilityBottomMargin > 0) {
+          bounds.bottom += readabilityBottomMargin;
+          improveComplexRoutes(true);
+        }
+      } finally {
+        allowGridSearch = true;
+      }
+    }
+    planningMetrics.routeCount = resolvedRoutes.length;
+    planningMetrics.explicitRouteCount = explicit.length;
+    planningMetrics.automaticRouteCount = automatic.length;
+    routesPlanning = false;
+    routesPlanned = true;
+  }
+
+  function pathFor(conn) {
+    planRoutes();
+    if (pathCache.has(conn)) return pathCache.get(conn);
+    return computePath(conn, []);
+  }
+
+  function routingMetrics() {
+    planRoutes();
+    return { ...planningMetrics };
+  }
+
+  return { ports: automaticPorts, pathFor, connectionSides, inferredSides, connectionEndpointSide, routingMetrics };
+}