@statelyai/layout 0.4.2 → 0.5.0

package/src/layered/index.ts

@@ -82,6 +82,8 @@ import {
   placeNodesInLayers,
   placeNodesInteractively,
   placePorts,
+  recordSweptPortOrder,
+  trackLabelPortSideFeedback,
   routeEdgesOrthogonally,
   routeEdgesWithPolylines,
   routeEdgesWithSplines,
@@ -1199,53 +1201,101 @@ function runSeparatedComponents<N, E, G, P>(
           bottom: options.padding?.bottom ?? 12,
           left: options.padding?.left ?? 12,
         };
+  // Components are packed in reading order, row by row. For UP and LEFT layouts
+  // the packing is mirrored along the flow so later components follow the first
+  // one's flow instead of preceding it (e.g. an isolated state below an UP
+  // statechart's start): LEFT mirrors each row, UP mirrors the stack of rows.
+  // Compaction measures every shape in that mirrored frame.
+  const direction = options.direction ?? graph.direction ?? "right";
+  type Rect = { x: number; y: number; width: number; height: number };
+  // Everything a component draws, so compaction keeps other components off its
+  // routes and labels as well as its nodes.
+  const drawnRects = (result: VisualGraph<N, E, G, P>): Rect[] => {
+    const rects: Rect[] = [];
+    for (const node of result.nodes) {
+      const x = node.x ?? 0,
+        y = node.y ?? 0;
+      rects.push({ x, y, width: node.width ?? 0, height: node.height ?? 0 });
+      for (const port of node.ports ?? [])
+        rects.push({
+          x: x + (port.x ?? 0),
+          y: y + (port.y ?? 0),
+          width: port.width ?? 0,
+          height: port.height ?? 0,
+        });
+    }
+    for (const edge of result.edges) {
+      const points = edge.points ?? [];
+      for (let index = 1; index < points.length; index++) {
+        const from = points[index - 1]!,
+          to = points[index]!;
+        const x = Math.min(from.x, to.x),
+          y = Math.min(from.y, to.y);
+        rects.push({ x, y, width: Math.max(from.x, to.x) - x, height: Math.max(from.y, to.y) - y });
+      }
+      if ((edge.width ?? 0) > 0 || (edge.height ?? 0) > 0)
+        rects.push({
+          x: edge.x ?? 0,
+          y: edge.y ?? 0,
+          width: edge.width ?? 0,
+          height: edge.height ?? 0,
+        });
+    }
+    return rects;
+  };
+  const rows: Array<Array<{ component: (typeof components)[number]; x: number }>> = [];
   let x = 0;
+  for (const component of components) {
+    if (x > 0 && x + component.bounds.width > maxRowWidth) x = 0;
+    if (x === 0) rows.push([]);
+    rows.at(-1)!.push({ component, x });
+    x += component.bounds.width + componentSpacing;
+  }
   let y = 0;
-  let rowHeight = 0;
   const compactConnectedComponents = options.settings?.["compaction.connectedComponents"] === true;
   const placedShapes: Array<{ left: number; right: number; top: number; bottom: number }> = [];
   const nodeResults = new Map<string, VisualNode<N, P>>();
   const edgeResults = new Map<string, (typeof components)[number]["result"]["edges"][number]>();
   const placements: Array<{ component: (typeof components)[number]; x: number; y: number }> = [];
-  for (const component of components) {
-    if (x > 0 && x + component.bounds.width > maxRowWidth) {
-      x = 0;
-      y += rowHeight + componentSpacing;
-      rowHeight = 0;
-    }
-    let compactedY = y;
-    if (compactConnectedComponents && y > 0) {
-      let requiredY = 0;
-      for (const node of component.result.nodes) {
-        const localLeft = x + (node.x ?? 0) - component.bounds.left;
-        const localRight = localLeft + (node.width ?? 0);
-        const localTop = (node.y ?? 0) - component.bounds.top;
-        for (const placed of placedShapes) {
-          if (localRight <= placed.left || localLeft >= placed.right) continue;
-          requiredY = Math.max(requiredY, placed.bottom + componentSpacing - localTop);
-        }
+  for (const row of rows) {
+    const rowWidth = Math.max(...row.map((entry) => entry.x + entry.component.bounds.width));
+    let rowHeight = 0;
+    for (const { component, x: packedX } of row) {
+      const { bounds } = component;
+      const left = direction === "left" ? rowWidth - packedX - bounds.width : packedX;
+      const shapes = drawnRects(component.result).map((rect) => ({
+        left: left + rect.x - bounds.left,
+        top:
+          direction === "up"
+            ? bounds.top + bounds.height - rect.y - rect.height
+            : rect.y - bounds.top,
+        width: rect.width,
+        height: rect.height,
+      }));
+      let compactedY = y;
+      if (compactConnectedComponents && y > 0) {
+        let requiredY = 0;
+        for (const shape of shapes)
+          for (const placed of placedShapes) {
+            if (shape.left + shape.width <= placed.left || shape.left >= placed.right) continue;
+            requiredY = Math.max(requiredY, placed.bottom + componentSpacing - shape.top);
+          }
+        compactedY = Math.min(y, requiredY);
       }
-      compactedY = Math.min(y, requiredY);
+      for (const shape of shapes)
+        placedShapes.push({
+          left: shape.left,
+          right: shape.left + shape.width,
+          top: compactedY + shape.top,
+          bottom: compactedY + shape.top + shape.height,
+        });
+      placements.push({ component, x: left, y: compactedY });
+      rowHeight = Math.max(rowHeight, bounds.height);
     }
-    for (const node of component.result.nodes)
-      placedShapes.push({
-        left: x + (node.x ?? 0) - component.bounds.left,
-        right: x + (node.x ?? 0) - component.bounds.left + (node.width ?? 0),
-        top: compactedY + (node.y ?? 0) - component.bounds.top,
-        bottom: compactedY + (node.y ?? 0) - component.bounds.top + (node.height ?? 0),
-      });
-    placements.push({ component, x, y: compactedY });
-    x += component.bounds.width + componentSpacing;
-    rowHeight = Math.max(rowHeight, component.bounds.height);
+    y += rowHeight + componentSpacing;
   }
-  // Components are packed in reading order. For UP and LEFT layouts, mirror the
-  // packing along the flow so later components follow the first one's flow
-  // instead of preceding it (e.g. an isolated state below an UP statechart's start).
-  const direction = options.direction ?? graph.direction ?? "right";
-  const packedWidth = Math.max(0, ...placements.map((p) => p.x + p.component.bounds.width));
   const packedHeight = Math.max(0, ...placements.map((p) => p.y + p.component.bounds.height));
-  for (const { component, x: packedX, y: packedY } of placements) {
-    const left = direction === "left" ? packedWidth - packedX - component.bounds.width : packedX;
+  for (const { component, x: left, y: packedY } of placements) {
     const top = direction === "up" ? packedHeight - packedY - component.bounds.height : packedY;
     const dx = padding.left + left - component.bounds.left;
     const dy = padding.top + top - component.bounds.top;
@@ -1324,7 +1374,10 @@ export function* createLayeredScopePipeline<N, E, G, P>(
   graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>,
   options: LayeredLayoutOptions,
   context?: LayoutExecutionContext,
+  /** Pairs and segments that keep their former routing because the new one bent them diagonally. */
+  fallbacks: OrthogonalFallbacks = { antiparallelPairs: new Set(), feedbackSegments: new Set() },
 ): Generator<LayeredCrossingPhase, VisualGraph<N, E, G, P>, LayerOrder> {
+  const scopeOptions = options;
   if ((options.settings?.["spacing.edgeEdge"] ?? 10) < 2) {
     options = { ...options, settings: { ...options.settings, "spacing.edgeEdge": 2 } };
   }
@@ -1683,7 +1736,7 @@ export function* createLayeredScopePipeline<N, E, G, P>(
       },
     };
   }
-  const northSouth = insertNorthSouthPortDummies(expanded);
+  const northSouth = insertNorthSouthPortDummies(expanded, preparedPorts);
   expanded = northSouth.expansion;
   if (prepareModelOrder) markInitialModelOrderPrepared(expanded.input, preparedPorts!);
   const associates = new Map<string, string[]>(),
@@ -1789,6 +1842,8 @@ export function* createLayeredScopePipeline<N, E, G, P>(
     minimize: minimizeScope,
     finishOrder: finishCrossingOrder,
   };
+  const crossingOrder = order;
+  recordSweptPortOrder(graph, direction, order);
   traceLayeredPhase(() => ({
     kind: "crossing-order",
     scope: graph.id,
@@ -2154,6 +2209,10 @@ export function* createLayeredScopePipeline<N, E, G, P>(
   // rather than moving or orthogonalizing its routes afterwards.
   if (options.strategies?.routeEdges)
     measure("post-compaction", () => applyPostCompaction(expanded.input, placement));
+  const labelPortSideSegments = trackLabelPortSideFeedback(
+    expanded.input,
+    fallbacks.feedbackSegments,
+  );
   let expandedRoutes = measure("edge-routing", () =>
     edgeRouter(expanded.input, expanded.orientation, placement),
   );
@@ -2218,6 +2277,7 @@ export function* createLayeredScopePipeline<N, E, G, P>(
   const outerAntiparallelLabelIds = new Set<string>();
   const parallelLabelPositions = new Map<string, Point>();
   const postCompactionNodeCrossDeltas = new Map<string, number>();
+  const flowOrderedPairs = new Map<string, readonly [string, string]>();
   const horizontalAntiparallelFlow = direction === "left" || direction === "right";
   const usesVizInteractivePlacementProfile =
     options.strategies?.routeEdges === undefined &&
@@ -2313,6 +2373,7 @@ export function* createLayeredScopePipeline<N, E, G, P>(
     const horizontal = horizontalAntiparallelFlow;
     const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
     const pairEdges = new Map<string, GraphEdge[]>();
+    const flowOrder = direction === "left" || direction === "up";
     for (const edge of graph.edges) {
       if (edge.sourceId === edge.targetId || (edge.width ?? 0) <= 0 || (edge.height ?? 0) <= 0) {
         continue;
@@ -2322,7 +2383,7 @@ export function* createLayeredScopePipeline<N, E, G, P>(
       pair.push(edge);
       pairEdges.set(key, pair);
     }
-    for (const pair of pairEdges.values()) {
+    for (const [pairKey, pair] of pairEdges) {
       if (
         pair.length !== 2 ||
         pair[0]!.sourceId !== pair[1]!.targetId ||
@@ -2363,9 +2424,13 @@ export function* createLayeredScopePipeline<N, E, G, P>(
       const hasFlexiblePairPorts = hasFlexiblePorts(firstNode) && hasFlexiblePorts(secondNode);
       if (isolatedAntiparallelPair && !hasFlexiblePairPorts) continue;
 
-      const firstBeforeSecond = horizontal
-        ? firstRect.x + firstRect.width / 2 < secondRect.x + secondRect.width / 2
-        : firstRect.y + firstRect.height / 2 < secondRect.y + secondRect.height / 2;
+      // "Before" is in flow order: UP and LEFT layouts flow toward smaller coordinates.
+      const pairFlowOrder = flowOrder && !fallbacks.antiparallelPairs.has(pairKey);
+      const firstBeforeSecond =
+        (horizontal
+          ? firstRect.x + firstRect.width / 2 < secondRect.x + secondRect.width / 2
+          : firstRect.y + firstRect.height / 2 < secondRect.y + secondRect.height / 2) !==
+        pairFlowOrder;
       const beforeRect = firstBeforeSecond ? firstRect : secondRect;
       const afterRect = firstBeforeSecond ? secondRect : firstRect;
       const forward = pair.find((edge) =>
@@ -2374,6 +2439,7 @@ export function* createLayeredScopePipeline<N, E, G, P>(
           : edge.sourceId === pair[0]!.targetId,
       );
       if (!forward?.sourcePort || !forward.targetPort) continue;
+      if (pairFlowOrder) flowOrderedPairs.set(pairKey, [firstNode.id, secondNode.id]);
 
       let cross = Math.min(
         horizontal ? firstRect.y : firstRect.x,
@@ -2554,6 +2620,7 @@ export function* createLayeredScopePipeline<N, E, G, P>(
       routes.pointsByEdgeId as Map<string, readonly Point[]>,
       placement.rectByNodeId as Map<string, EntityRect>,
       horizontal,
+      Number(options.settings?.["spacing.edgeEdge"] ?? 10),
     );
   }
   if (options.settings?.["layering.nodePromotion.strategy"] === "MODEL_ORDER_LEFT_TO_RIGHT") {
@@ -2667,8 +2734,21 @@ export function* createLayeredScopePipeline<N, E, G, P>(
     };
   }
 
+  // Stacking the pair's labels from the padding and aligning both endpoints
+  // moves the nodes without regard for their layer neighbors, so it only
+  // applies when the two nodes connect to nothing else.
+  const connectsOnlyTo = (nodeId: string, otherId: string) =>
+    graph.edges.every(
+      (edge) =>
+        edge.sourceId === edge.targetId ||
+        (edge.sourceId !== nodeId && edge.targetId !== nodeId) ||
+        edge.sourceId === otherId ||
+        edge.targetId === otherId,
+    );
   for (const pair of labeledEdgesByPair.values()) {
     if (pair.length < 2) continue;
+    const { sourceId, targetId } = pair[0]!;
+    if (!connectsOnlyTo(sourceId, targetId) || !connectsOnlyTo(targetId, sourceId)) continue;
     const sourceRect = mutableRects.get(pair[0]!.sourceId);
     const targetRect = mutableRects.get(pair[0]!.targetId);
     if (!sourceRect || !targetRect) continue;
@@ -3249,6 +3329,41 @@ export function* createLayeredScopePipeline<N, E, G, P>(
     });
   }
 
+  // Diagonals are never valid orthogonal routes. A flow-ordered antiparallel
+  // pair or a label-port-side feedback chain that came out diagonal falls back
+  // to its former routing when that has fewer diagonals.
+  if (edgeRouting === "ORTHOGONAL") {
+    const diagonalEdges = edges.filter((edge) => countDiagonals(edge.points) > 0);
+    const antiparallelPairs = [...flowOrderedPairs].flatMap(([key, nodeIds]) =>
+      diagonalEdges.some(
+        (edge) => nodeIds.includes(edge.sourceId) || nodeIds.includes(edge.targetId),
+      )
+        ? [key]
+        : [],
+    );
+    const feedbackSegments = diagonalEdges.flatMap((edge) => {
+      const segments = expanded.segmentIdsByEdgeId.get(edge.id) ?? [edge.id];
+      return segments.some((id) => labelPortSideSegments.has(id)) ? segments : [];
+    });
+    if (antiparallelPairs.length > 0 || feedbackSegments.length > 0) {
+      const retry = createLayeredScopePipeline(
+        graph,
+        scopeOptions,
+        context && { ...context, diagnostics: [] },
+        {
+          antiparallelPairs: new Set([...fallbacks.antiparallelPairs, ...antiparallelPairs]),
+          feedbackSegments: new Set([...fallbacks.feedbackSegments, ...feedbackSegments]),
+        },
+      );
+      const prepared = retry.next();
+      const resumed = prepared.done ? prepared : retry.next(crossingOrder);
+      if (!resumed.done) throw new Error("Layered scope yielded more than one crossing phase");
+      const diagonals = (routed: readonly { points?: readonly Point[] }[]) =>
+        routed.reduce((sum, edge) => sum + countDiagonals(edge.points), 0);
+      if (diagonals(resumed.value.edges) < diagonals(edges)) return resumed.value;
+    }
+  }
+
   return setElkjs0111ResultPolicy(
     { ...graph, direction, nodes, edges },
     {
@@ -3261,6 +3376,23 @@ export function* createLayeredScopePipeline<N, E, G, P>(
   );
 }
 
+interface OrthogonalFallbacks {
+  /** Antiparallel pair keys that keep coordinate order instead of flow order. */
+  antiparallelPairs: ReadonlySet<string>;
+  /** Feedback segments that keep the plain detour instead of label-dummy port sides. */
+  feedbackSegments: ReadonlySet<string>;
+}
+
+function countDiagonals(points: readonly Point[] | undefined): number {
+  let count = 0;
+  for (let index = 1; index < (points?.length ?? 0); index++) {
+    const a = points![index - 1]!;
+    const b = points![index]!;
+    if (Math.abs(a.x - b.x) > 1e-6 && Math.abs(a.y - b.y) > 1e-6) count++;
+  }
+  return count;
+}
+
 /**
  * Deterministic native layered layout for an `@statelyai/graph` graph.
  *

package/src/layered/north-south-ports.ts

@@ -27,7 +27,11 @@ export interface NorthSouthPortExpansion {
 }
 
 /** Detach fixed cross-axis ports into same-layer units before crossing minimization. */
-export function insertNorthSouthPortDummies(expansion: LongEdgeExpansion): NorthSouthPortExpansion {
+export function insertNorthSouthPortDummies(
+  expansion: LongEdgeExpansion,
+  /** Physical port order after ELK's model-order sort, by node id. */
+  sortedPorts?: ReadonlyMap<string, readonly string[]>,
+): NorthSouthPortExpansion {
   const { input, orientation } = expansion;
   const vertical = input.direction === "down" || input.direction === "up";
   const forward =
@@ -152,14 +156,23 @@ export function insertNorthSouthPortDummies(expansion: LongEdgeExpansion): North
   const roleOrder = (origin: CrossPortOrigin) =>
     origin.input && origin.output ? 2 : origin.input ? 0 : 1;
   const negativeFlow = input.direction === "left" || input.direction === "up";
+  // With model order, ELK reverses each side's output-only ports before
+  // creating dummies (modelOrderNorthSouthInputReversing).
+  const modelOrder = (input.settings["considerModelOrder.strategy"] ?? "NONE") !== "NONE";
   const orderedOrigins = input.graph.nodes.flatMap((node) => {
     const entries = [...origins].filter(([, origin]) => origin.node.id === node.id);
     const constraints = input.nodeSettings?.(node)?.portConstraints;
+    const sorted = sortedPorts?.get(node.id);
     const coordinate = (origin: CrossPortOrigin) => {
+      const flip = modelOrder && origin.output && !origin.input ? -1 : 1;
       if (constraints === "FIXED_POS" || constraints === "FIXED_RATIO")
-        return (vertical ? (origin.port.y ?? 0) : (origin.port.x ?? 0)) * (negativeFlow ? -1 : 1);
-      const index = node.ports?.indexOf(origin.port) ?? 0;
-      return origin.beforeOwner ? index : -index;
+        return (
+          (vertical ? (origin.port.y ?? 0) : (origin.port.x ?? 0)) * (negativeFlow ? -1 : 1) * flip
+        );
+      const index = sorted
+        ? sorted.indexOf(JSON.stringify([node.id, origin.port.name]))
+        : (node.ports?.indexOf(origin.port) ?? 0);
+      return (origin.beforeOwner ? index : -index) * flip;
     };
     return entries.sort(
       ([, a], [, b]) =>

package/src/layered/strategies.ts

@@ -72,6 +72,24 @@ const modelSweepInputs = new WeakSet<LayeredPhaseInput>();
 
 const nodeRelativePortRanksByInput = new WeakMap<LayeredPhaseInput, boolean>();
 
+const labelPortSideFeedbackByInput = new WeakMap<
+  LayeredPhaseInput,
+  { exempt: ReadonlySet<string>; routed: Set<string> }
+>();
+
+/**
+ * @internal Collect the feedback segments routed to a center-label dummy's port
+ * sides. Exempt segments keep the plain feedback detour instead.
+ */
+export function trackLabelPortSideFeedback(
+  input: LayeredPhaseInput,
+  exempt: ReadonlySet<string>,
+): ReadonlySet<string> {
+  const routed = new Set<string>();
+  labelPortSideFeedbackByInput.set(input, { exempt, routed });
+  return routed;
+}
+
 function getOrientedEndpoints(
   edge: GraphEdge,
   orientation: AcyclicOrientation,
@@ -1794,6 +1812,8 @@ function sortLayerByAdjacentPosition(
   sameLayerNeighbors: ReadonlyMap<string, readonly string[]> = new Map(),
   orderedVisits?: ReadonlyMap<string, readonly (number | string)[]>,
   forcedCompare?: (left: string, right: string) => number,
+  /** Nodes ELK's forced model-order comparator ties with everything. */
+  forcedTies?: ReadonlySet<string>,
 ): void {
   const originalIndex = new Map(layer.map((nodeId, index) => [nodeId, index] as const));
   const adjacentPosition = new Map<string, number | undefined>();
@@ -1870,6 +1890,7 @@ function sortLayerByAdjacentPosition(
   }
 
   const compare = (a: string, b: string) => {
+    if (forcedTies?.has(a) || forcedTies?.has(b)) return 0;
     return (
       forcedCompare?.(a, b) ||
       (adjacentPosition.get(a) ?? 0) - (adjacentPosition.get(b) ?? 0) ||
@@ -2185,6 +2206,18 @@ export function createLayerSweepSession(
     usesInitialModelOrder && input.settings["crossingMinimization.forceNodeModelOrder"] === true
       ? normalModelComparator(input)
       : undefined;
+  // ELK's forced comparator returns 0 for separate-layer nodes before
+  // consulting barycenters, so insertion sort never moves past them.
+  const forcedTies = forcedCompare
+    ? new Set(
+        input.graph.nodes
+          .filter((node) => {
+            const constraint = input.nodeSettings?.(node)?.["layering.layerConstraint"];
+            return constraint === "FIRST_SEPARATE" || constraint === "LAST_SEPARATE";
+          })
+          .map((node) => node.id),
+      )
+    : undefined;
   const usePortRanks = true;
   const medianWeights = new Map<string, number>();
   const listedEdgeIds = new Map<string, string>();
@@ -2440,8 +2473,10 @@ export function createLayerSweepSession(
       (working[firstLayerIndex] ?? []).map((id) => [id, random.nextDouble()]),
     );
     const compare = (left: string, right: string) =>
-      forcedCompare?.(left, right) ||
-      (firstLayerWeights.get(left) ?? 0) - (firstLayerWeights.get(right) ?? 0);
+      forcedTies?.has(left) || forcedTies?.has(right)
+        ? 0
+        : forcedCompare?.(left, right) ||
+          (firstLayerWeights.get(left) ?? 0) - (firstLayerWeights.get(right) ?? 0);
     const first = working[firstLayerIndex];
     if (first) {
       if (forcedCompare)
@@ -2596,6 +2631,7 @@ export function createLayerSweepSession(
               sameLayerNeighbors(isForward),
               adjacent.visits,
               forcedCompare,
+              forcedTies,
             );
           }
           groupMixedPortDirections(current, previous, working[layer + 1]);
@@ -2625,6 +2661,7 @@ export function createLayerSweepSession(
               sameLayerNeighbors(isForward),
               adjacent.visits,
               forcedCompare,
+              forcedTies,
             );
           }
           groupMixedPortDirections(current, next, working[layer - 1]);
@@ -5845,6 +5882,25 @@ function routeEdges(style: "ORTHOGONAL" | "POLYLINE" | "SPLINES"): EdgeRouter {
               input,
             )
           : targetFallback;
+        // A reversed chain enters a center-label dummy through its forward-side
+        // port and leaves through its backward-side port: route to those sides.
+        const [forwardSide, backwardSide] = (
+          {
+            right: ["EAST", "WEST"],
+            left: ["WEST", "EAST"],
+            down: ["SOUTH", "NORTH"],
+            up: ["NORTH", "SOUTH"],
+          } as const
+        )[input.direction];
+        const labelPortSides = labelPortSideFeedbackByInput.get(input);
+        const faces = (node: GraphNode, side: unknown, away: string) =>
+          !fixedSideFeedback &&
+          !labelPortSides?.exempt.has(edge.id) &&
+          node.id.startsWith("__layout_dummy:label:") &&
+          side === away;
+        const sourceFace = faces(source, feedbackSourcePortSide, backwardSide) ? -1 : 1;
+        const targetFace = faces(target, feedbackTargetPortSide, forwardSide) ? -1 : 1;
+        if (sourceFace < 0 || targetFace < 0) labelPortSides?.routed.add(edge.id);
         if (horizontal) {
           const sign = fixedSideFeedback
             ? Math.sign(sourceRect.x - targetRect.x) || 1
@@ -5859,16 +5915,16 @@ function routeEdges(style: "ORTHOGONAL" | "POLYLINE" | "SPLINES"): EdgeRouter {
             fixedSideFeedback && input.settings.unnecessaryBendpoints === true;
           pointsByEdgeId.set(edge.id, [
             start,
-            { x: start.x + sign * flowSpacing, y: start.y },
-            { x: start.x + sign * flowSpacing, y: outerCross },
+            { x: start.x + sourceFace * sign * flowSpacing, y: start.y },
+            { x: start.x + sourceFace * sign * flowSpacing, y: outerCross },
             ...(preserveCenters
               ? [
                   { x: sourceRect.x + sourceRect.width / 2, y: outerCross },
                   { x: targetRect.x + targetRect.width / 2, y: outerCross },
                 ]
               : []),
-            { x: end.x - sign * flowSpacing, y: outerCross },
-            { x: end.x - sign * flowSpacing, y: end.y },
+            { x: end.x - targetFace * sign * flowSpacing, y: outerCross },
+            { x: end.x - targetFace * sign * flowSpacing, y: end.y },
             end,
           ]);
         } else {
@@ -5885,16 +5941,16 @@ function routeEdges(style: "ORTHOGONAL" | "POLYLINE" | "SPLINES"): EdgeRouter {
             fixedSideFeedback && input.settings.unnecessaryBendpoints === true;
           pointsByEdgeId.set(edge.id, [
             start,
-            { x: start.x, y: start.y + sign * flowSpacing },
-            { x: outerCross, y: start.y + sign * flowSpacing },
+            { x: start.x, y: start.y + sourceFace * sign * flowSpacing },
+            { x: outerCross, y: start.y + sourceFace * sign * flowSpacing },
             ...(preserveCenters
               ? [
                   { x: outerCross, y: sourceRect.y + sourceRect.height / 2 },
                   { x: outerCross, y: targetRect.y + targetRect.height / 2 },
                 ]
               : []),
-            { x: outerCross, y: end.y - sign * flowSpacing },
-            { x: end.x, y: end.y - sign * flowSpacing },
+            { x: outerCross, y: end.y - targetFace * sign * flowSpacing },
+            { x: end.x, y: end.y - targetFace * sign * flowSpacing },
             end,
           ]);
         }
@@ -6528,6 +6584,67 @@ export const routeEdgesOrthogonally = routeEdges("ORTHOGONAL");
 export const routeEdgesWithPolylines = routeEdges("POLYLINE");
 export const routeEdgesWithSplines = routeEdges("SPLINES");
 
+type PortSide = "NORTH" | "SOUTH" | "WEST" | "EAST";
+const sweptPortRanks = new WeakMap<
+  readonly GraphPort<unknown>[],
+  (port: GraphPort<unknown>, side: PortSide) => number | undefined
+>();
+
+/**
+ * Order movable ports along each physical side as crossing minimization left
+ * them, as ELK places ports from its swept port lists. The lists are
+ * clockwise per canonical side.
+ */
+export function recordSweptPortOrder(
+  graph: Pick<LayeredPhaseInput["graph"], "nodes" | "edges">,
+  direction: LayeredPhaseInput["direction"],
+  order: LayerOrder,
+): void {
+  // Unconnected ports carry no swept decision.
+  const connected = new Set(
+    graph.edges.flatMap((edge) => [
+      JSON.stringify([edge.sourceId, edge.sourcePort]),
+      JSON.stringify([edge.targetId, edge.targetPort]),
+    ]),
+  );
+  const vertical = direction === "down" || direction === "up";
+  const reverse = direction === "up" || direction === "left";
+  const canonical: Record<PortSide, PortSide> =
+    direction === "right"
+      ? { NORTH: "NORTH", EAST: "EAST", SOUTH: "SOUTH", WEST: "WEST" }
+      : direction === "left"
+        ? { NORTH: "NORTH", EAST: "WEST", SOUTH: "SOUTH", WEST: "EAST" }
+        : direction === "down"
+          ? { NORTH: "WEST", EAST: "SOUTH", SOUTH: "EAST", WEST: "NORTH" }
+          : { NORTH: "EAST", EAST: "SOUTH", SOUTH: "WEST", WEST: "NORTH" };
+  for (const node of graph.nodes) {
+    if (!node.ports) continue;
+    const swept = order.physicalPortOrderByNodeId?.get(node.id);
+    if (!swept) {
+      sweptPortRanks.delete(node.ports);
+      continue;
+    }
+    const index = new Map(swept.flatMap((id, i) => (connected.has(id) ? [[id, i] as const] : [])));
+    const rankByPort = new Map(
+      node.ports.map((port) => [port, index.get(JSON.stringify([node.id, port.name]))]),
+    );
+    sweptPortRanks.set(node.ports, (port, side) => {
+      const rank = rankByPort.get(port);
+      if (rank === undefined) return undefined;
+      // Canonical clockwise ranks rise with the flow coordinate on NORTH,
+      // with the cross coordinate on EAST, and fall on SOUTH and WEST.
+      const alongFlow = (side === "NORTH" || side === "SOUTH") !== vertical;
+      const c = canonical[side];
+      const sign = alongFlow
+        ? (c === "NORTH" ? 1 : -1) * (reverse ? -1 : 1)
+        : c === "EAST"
+          ? 1
+          : -1;
+      return sign * rank;
+    });
+  }
+}
+
 export function placePorts<P>(
   ports: readonly GraphPort<P>[] | undefined,
   rect: EntityRect,
@@ -6573,13 +6690,24 @@ export function placePorts<P>(
     group.push(port);
     grouped.set(side, group);
   }
+  const swept =
+    constraints === "FIXED_ORDER" || constraints === "FIXED_POS" || constraints === "FIXED_RATIO"
+      ? undefined
+      : sweptPortRanks.get(ports as readonly GraphPort<unknown>[]);
   for (const group of grouped.values()) {
-    group.sort(
-      (left, right) =>
-        Number(portSettings?.(left)?.["port.index"] ?? ports.indexOf(left)) -
-        Number(portSettings?.(right)?.["port.index"] ?? ports.indexOf(right)),
-    );
     const side = sideByPort.get(group[0]!);
+    const ranks = swept && group.map((port) => swept(port as GraphPort<unknown>, side!));
+    const ranked =
+      ranks?.every((rank) => rank !== undefined) &&
+      group.every((port) => portSettings?.(port)?.["port.index"] === undefined)
+        ? new Map(group.map((port, i) => [port, ranks[i]!]))
+        : undefined;
+    group.sort((left, right) =>
+      ranked
+        ? ranked.get(left)! - ranked.get(right)!
+        : Number(portSettings?.(left)?.["port.index"] ?? ports.indexOf(left)) -
+          Number(portSettings?.(right)?.["port.index"] ?? ports.indexOf(right)),
+    );
     if (constraints === "FIXED_ORDER" && (side === "SOUTH" || side === "WEST")) {
       group.reverse();
     }