// 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,
  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
 */
export function createRouter(components, connections = [], {
  frames = [],
  interiorSegmentPx = 16,
  microSegmentPx = 8,
  labelRectFor = null,
  distinctAutomaticPorts = false,
  preferReadableRoutes = false,
} = {}) {
  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 (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,
    reciprocalCandidateCount: 0,
    reciprocalImprovedCount: 0,
    gridAttempts: [],
  };

  // ---- Connection routing ------------------------------------------------------
  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))
      .map((points) => points.slice(1, -1));
  }

  const AUTOMATIC_PORT_CORNER_GUTTER = 16;
  const AUTOMATIC_PORT_ALIGNMENT_DELTA = 16;

  function portHasCornerClearance(rect, side, point) {
    if (side === 'left' || side === 'right') {
      const inset = Math.min(AUTOMATIC_PORT_CORNER_GUTTER, rect.height / 2);
      return point[1] >= rect.y + inset && point[1] <= rect.y + rect.height - inset;
    }
    if (side === 'top' || side === 'bottom') {
      const inset = Math.min(AUTOMATIC_PORT_CORNER_GUTTER, rect.width / 2);
      return point[0] >= rect.x + inset && point[0] <= rect.x + rect.width - inset;
    }
    return false;
  }

  function alignFacingPorts(conn, from, to, start, end, fromSide, toSide, ports) {
    const hasExplicitGeometry = (
      conn.via
      || (conn.route && conn.route !== 'auto')
      || conn.channelX !== undefined
      || conn.channelY !== undefined
      || conn.labelAt
    );
    const horizontallyFacing = (
      (fromSide === 'right' && toSide === 'left')
      || (fromSide === 'left' && toSide === 'right')
    );
    const verticallyFacing = (
      (fromSide === 'bottom' && toSide === 'top')
      || (fromSide === 'top' && toSide === 'bottom')
    );
    if (hasExplicitGeometry || (!horizontallyFacing && !verticallyFacing)) return { start, end };

    const fromSpread = Boolean(ports?.from);
    const toSpread = Boolean(ports?.to);
    if (fromSpread && toSpread) return { start, end };
    const hasExplicitSides = (
      (conn.fromSide && conn.fromSide !== 'auto')
      || (conn.toSide && conn.toSide !== 'auto')
    );
    if (!fromSpread && !toSpread && hasExplicitSides) return { start, end };

    const alignmentDelta = horizontallyFacing
      ? Math.abs(start[1] - end[1])
      : Math.abs(start[0] - end[0]);
    if (alignmentDelta >= AUTOMATIC_PORT_ALIGNMENT_DELTA) return { start, end };

    // Keep the shared endpoint's distinct spread slot and move only the
    // relationship's unshared endpoint onto that axis. With no spread endpoint,
    // retain the existing least-movement choice between the two facing sides.
    // If both endpoints are shared, preserve the outside bridge so no competing
    // port is silently collapsed.
    const alignEndToStart = horizontallyFacing
      ? { start, end: [end[0], start[1]] }
      : { start, end: [start[0], end[1]] };
    const alignStartToEnd = horizontallyFacing
      ? { start: [start[0], end[1]], end }
      : { start: [end[0], start[1]], end };
    const candidates = fromSpread
      ? [alignEndToStart]
      : toSpread
        ? [alignStartToEnd]
        : [alignEndToStart, alignStartToEnd];
    for (const candidate of candidates) {
      const points = [candidate.start, candidate.end];
      if (portHasCornerClearance(from, fromSide, candidate.start)
          && portHasCornerClearance(to, toSide, candidate.end)
          && routeHonorsEndpointSides(points, fromSide, toSide)
          && routeClearsEndpointComponents(points, from, to)
          && routeClearsComponents(conn, points)) {
        return candidate;
      }
    }
    return { start, end };
  }

  // 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: {
        // 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),
        ];
        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)))) return candidate;
        }
        // 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.
        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,
          })));
        const gridMetrics = {};
        planningMetrics.gridSearchCount += 1;
        planningMetrics.avoidedSegmentCount += avoidedSegments.length;
        const searched = shortestOrthogonalGridRoute({
          start,
          end,
          points: [start, end],
          obstacles: [...components.values(), ...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) : 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);
  const automaticPorts = automaticPortSpread(connections, components, {
    sideFor: (relation, endpoint) => rowFanOutSides(components.get(relation.from), components.get(relation.to))
      ?.[endpoint === 'source' ? 'fromSide' : 'toSide'],
    // 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);
    const fanOut = rowFanOutSides(from, to);
    return {
      fromSide: chosenSide(conn.fromSide, fanOut?.fromSide || defaultFromSide(from, to)),
      toSide: chosenSide(conn.toSide, fanOut?.toSide || defaultToSide(from, to)),
    };
  }

  function connectionSides(conn) {
    if (!routesPlanned && !routesPlanning) planRoutes();
    return selectedSides.get(conn) || 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) };
    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]) || 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) {
    return resolvedRoutes.reduce((total, entry) => total + Number(
      !(relationshipsShareEndpoint(conn, entry.conn)
        && (!distinctAutomaticPorts || hasAuthoredRouteGeometry(entry.conn) || entry.conn.labelAt || conn.labelAt))
      && points.slice(1).some((end, index) => entry.points.slice(1).some((otherEnd, otherIndex) =>
        properSegmentIntersection(points[index], end, entry.points[otherIndex], otherEnd))),
    ), 0);
  }

  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();
      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) || 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
            && !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 endpointSlotsClear = (candidateRoutes) => {
              const entries = [...others, ...candidateRoutes];
              for (const candidate of candidateRoutes) {
                const sides = candidate.conn === conn ? firstSides : secondSides;
                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 = other.conn === conn ? firstSides
                      : other.conn === second.conn ? secondSides : selectedSides.get(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)));
            };
            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)) 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;
          }
        }
      }
      allowGridSearch = false;
      try {
        improveReciprocalPairs();
        for (const entry of resolvedRoutes) {
          const { conn } = entry;
          if (jointlyImproved.has(conn) || hasAuthoredRouteGeometry(conn) || conn.labelAt) 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 or more than two bends.
          if (entry.points.length <= 4 && crossingCount(conn, entry.points, others) === 0) continue;
          let best = null;
          let bestCost = 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;
            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),
              });
              // A shorter route must not expand the canvas and shrink every
              // label at the default viewport. Include its reserved label too.
              if (rect && (!withinScene([rect.x, rect.y]) || !withinScene([rect.x + rect.width, rect.y + rect.height]))) 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 });
        }
      } 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 { pathFor, connectionSides, connectionEndpointSide, routingMetrics };
}