@statelyai/layout 0.3.0 → 0.4.1

package/src/layered/native-routing.ts

@@ -0,0 +1,275 @@
+import type { GraphNode, VisualGraph } from "@statelyai/graph";
+import type { LayeredLayoutOptions } from "./types";
+import { routeCrosses } from "../authoring/routing";
+import {
+  orthogonalRouting,
+  routeToPoints,
+  type EdgeRoutingSettings,
+  type RouteSide,
+  type RouteEndpoint,
+} from "../routing";
+import { recordRouteGeometry } from "../routing/layout-cache";
+
+/** Keep valid layered tracks; repair infeasible port leads and obstacle crossings. */
+export function repairFlatRouting<N, E, G, P>(
+  graph: VisualGraph<N, E, G, P>,
+  options: LayeredLayoutOptions,
+): VisualGraph<N, E, G, P> {
+  if (
+    graph.nodes.some((n) => n.parentId != null) ||
+    options.settings?.noLayout ||
+    (options.settings?.edgeRouting ?? "ORTHOGONAL") !== "ORTHOGONAL" ||
+    options.strategies?.routeEdges
+  )
+    return graph;
+  const overlaps = (
+    a: { x: number; y: number; width: number; height: number },
+    b: { x: number; y: number; width: number; height: number },
+  ) => a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+  // Leave room for port centers outside the node and their 9px exit leads.
+  const portClearance = (n: (typeof graph.nodes)[number]) => {
+    const reach = Math.max(
+      0,
+      ...(n.ports ?? []).flatMap((p) => [
+        -(p.x ?? 0) - (p.width ?? 0) / 2,
+        -(p.y ?? 0) - (p.height ?? 0) / 2,
+        (p.x ?? 0) + (p.width ?? 0) / 2 - n.width,
+        (p.y ?? 0) + (p.height ?? 0) / 2 - n.height,
+      ]),
+    );
+    const margin = 9 + reach;
+    return {
+      x: n.x - margin,
+      y: n.y - margin,
+      width: n.width + 2 * margin,
+      height: n.height + 2 * margin,
+    };
+  };
+  const labels = graph.edges.filter((e) => e.width > 0 && e.height > 0);
+  const labelCollision = labels.some(
+    (e, i) =>
+      graph.nodes.some((n) => overlaps(e, portClearance(n))) ||
+      labels.slice(i + 1).some((other) => overlaps(e, other)),
+  );
+  const routingDefect = graph.edges.some((edge) => {
+    if (
+      graph.nodes.some((node) => routeCrosses(edge.points, node)) ||
+      labels.some((label) => label.id !== edge.id && routeCrosses(edge.points, label))
+    )
+      return true;
+    const points = edge.points ?? [];
+    const loopNode =
+      edge.sourceId === edge.targetId ? graph.nodes.find((n) => n.id === edge.sourceId) : undefined;
+    const terminals = [
+      ...(loopNode
+        ? [
+            {
+              x: loopNode.x - 12,
+              y: loopNode.y - 12,
+              width: loopNode.width + 24,
+              height: loopNode.height + 24,
+            },
+          ]
+        : []),
+      ...(edge.width > 0 && edge.height > 0 ? [edge] : []),
+    ];
+    for (let i = 1; i < points.length; i++) {
+      const a = points[i - 1]!,
+        b = points[i]!;
+      if (Math.abs(a.x - b.x) > 1e-8 && Math.abs(a.y - b.y) > 1e-8) return true;
+      for (let j = i + 1; j < points.length; j++) {
+        const c = points[j - 1]!,
+          d = points[j]!;
+        const horizontal =
+          Math.abs(a.y - b.y) < 1e-8 && Math.abs(c.y - d.y) < 1e-8 && Math.abs(a.y - c.y) < 1e-8;
+        const vertical =
+          Math.abs(a.x - b.x) < 1e-8 && Math.abs(c.x - d.x) < 1e-8 && Math.abs(a.x - c.x) < 1e-8;
+        if (!horizontal && !vertical) continue;
+        const axis = horizontal ? "x" : "y",
+          fixed = horizontal ? "y" : "x";
+        const lo = Math.max(Math.min(a[axis], b[axis]), Math.min(c[axis], d[axis]));
+        const hi = Math.min(Math.max(a[axis], b[axis]), Math.max(c[axis], d[axis]));
+        if (hi - lo < 1e-8) continue;
+        let intervals = [[lo, hi]];
+        for (const rect of terminals) {
+          const span = horizontal ? rect.height : rect.width;
+          if (a[fixed] < rect[fixed] || a[fixed] > rect[fixed] + span) continue;
+          const lower = rect[axis],
+            upper = lower + (horizontal ? rect.width : rect.height);
+          intervals = intervals
+            .flatMap(([start, end]) => [
+              [start!, Math.min(end!, lower)],
+              [Math.max(start!, upper), end!],
+            ])
+            .filter(([start, end]) => end! - start! > 1e-8);
+        }
+        if (intervals.length) return true;
+      }
+    }
+    return false;
+  });
+  if (!labelCollision && !routingDefect) return graph;
+  const edges = graph.edges.map((edge) => ({ ...edge }));
+  // The original track may put an exterior label partly inside a node. Move
+  // only colliding labels before routing their actual boundary connections.
+  for (const edge of edges.filter((e) => e.width > 0 && e.height > 0)) {
+    const obstacles = [
+      ...graph.nodes.map(portClearance),
+      ...edges.filter((e) => e.id !== edge.id && e.width > 0 && e.height > 0),
+    ];
+    if (!obstacles.some((rect) => overlaps(edge, rect))) continue;
+    const xs = [edge.x, ...obstacles.flatMap((r) => [r.x - edge.width - 8, r.x + r.width + 8])];
+    const ys = [edge.y, ...obstacles.flatMap((r) => [r.y - edge.height - 8, r.y + r.height + 8])];
+    let best: { x: number; y: number; distance: number } | undefined;
+    for (const x of xs)
+      for (const y of ys) {
+        const distance = Math.abs(x - edge.x) + Math.abs(y - edge.y);
+        if (best && distance >= best.distance) continue;
+        if (!obstacles.some((rect) => overlaps({ ...edge, x, y }, rect))) best = { x, y, distance };
+      }
+    if (best) {
+      edge.x = best.x;
+      edge.y = best.y;
+    }
+  }
+  const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
+  const fixedImplicitSide = (
+    nodeId: string,
+    portName: string | undefined,
+    point: { x: number; y: number } | undefined,
+    away: { x: number; y: number } | undefined,
+  ): RouteSide | undefined => {
+    const node = nodes.get(nodeId);
+    if (
+      !node ||
+      portName !== undefined ||
+      !point ||
+      !["FIXED_SIDE", "FIXED_ORDER", "FIXED_RATIO", "FIXED_POS"].includes(
+        String(options.nodeSettings?.(node)?.portConstraints),
+      )
+    )
+      return undefined;
+    // Fixed implicit attachments are assigned before reversal. Repair must
+    // preserve the initial face, including special self-loop attachments.
+    const faces: [RouteSide, number][] = [
+      ["left", Math.abs(point.x - node.x)],
+      ["right", Math.abs(point.x - node.x - node.width)],
+      ["top", Math.abs(point.y - node.y)],
+      ["bottom", Math.abs(point.y - node.y - node.height)],
+    ];
+    const leadSide: RouteSide | undefined =
+      away && (Math.abs(away.x - point.x) > 1e-8 || Math.abs(away.y - point.y) > 1e-8)
+        ? Math.abs(away.x - point.x) >= Math.abs(away.y - point.y)
+          ? away.x > point.x
+            ? "right"
+            : "left"
+          : away.y > point.y
+            ? "bottom"
+            : "top"
+        : undefined;
+    faces.sort((a, b) => a[1] - b[1] || Number(b[0] === leadSide) - Number(a[0] === leadSide));
+    return faces[0]![1] < 1e-6 ? faces[0]![0] : undefined;
+  };
+  const attachments: Record<string, EdgeRoutingSettings> = Object.fromEntries(
+    graph.edges.map((edge) => [
+      edge.id,
+      {
+        sourceSide: fixedImplicitSide(
+          edge.sourceId,
+          edge.sourcePort,
+          edge.points?.[0],
+          edge.points?.[1],
+        ),
+        targetSide: fixedImplicitSide(
+          edge.targetId,
+          edge.targetPort,
+          edge.points?.at(-1),
+          edge.points?.at(-2),
+        ),
+      },
+    ]),
+  );
+  const routingNodes = new Map<string, GraphNode>(graph.nodes.map((node) => [node.id, node]));
+  const syntheticPorts = new Map<string, Set<string>>();
+  const attach = (
+    edgeId: string,
+    nodeId: string,
+    portName: string | undefined,
+    point: { x: number; y: number } | undefined,
+    source: boolean,
+  ) => {
+    const side = source ? attachments[edgeId]?.sourceSide : attachments[edgeId]?.targetSide;
+    if (
+      !side ||
+      !point ||
+      !["FIXED_POS", "FIXED_RATIO"].includes(
+        String(options.nodeSettings?.(nodes.get(nodeId)!)?.portConstraints),
+      )
+    )
+      return portName;
+    const node = routingNodes.get(nodeId)!;
+    let name = `__layout_implicit:${edgeId}:${source ? "source" : "target"}`;
+    while (node.ports?.some((p) => p.name === name)) name += ":";
+    const names = syntheticPorts.get(nodeId) ?? new Set<string>();
+    names.add(name);
+    syntheticPorts.set(nodeId, names);
+    routingNodes.set(nodeId, {
+      ...node,
+      ports: [
+        ...(node.ports ?? []),
+        {
+          name,
+          data: undefined,
+          direction: "inout",
+          x: point.x - node.x!,
+          y: point.y - node.y!,
+          width: 0,
+          height: 0,
+        },
+      ],
+    });
+    return name;
+  };
+  const routingEdges = edges.map((edge) => ({
+    ...edge,
+    sourcePort: attach(edge.id, edge.sourceId, edge.sourcePort, edge.points?.[0], true),
+    targetPort: attach(edge.id, edge.targetId, edge.targetPort, edge.points?.at(-1), false),
+  }));
+  const snapshot = orthogonalRouting.route(
+    { ...graph, nodes: [...routingNodes.values()], edges: routingEdges },
+    { coordinateSpace: "world", maxSearchNodes: 40000, edges: attachments },
+  );
+  const authoredEndpoint = (endpoint: RouteEndpoint): RouteEndpoint => {
+    if (
+      endpoint.kind !== "node" ||
+      endpoint.port === undefined ||
+      !syntheticPorts.get(endpoint.nodeId)?.has(endpoint.port)
+    )
+      return endpoint;
+    const { port: _privatePort, ...authored } = endpoint;
+    return authored;
+  };
+  const routes = new Map(
+    [...snapshot.routes].map(([id, route]) => [
+      id,
+      {
+        ...route,
+        sections: route.sections.map((section) => ({
+          ...section,
+          from: authoredEndpoint(section.from),
+          to: authoredEndpoint(section.to),
+        })),
+      },
+    ]),
+  );
+  const result = {
+    ...graph,
+    edges: edges.map((edge) => ({
+      ...edge,
+      points: routeToPoints(routes.get(edge.id)!),
+    })),
+    compoundRoutes: routes,
+  };
+  recordRouteGeometry(result, routes);
+  return result;
+}

package/src/layered/network-simplex.ts

@@ -5,6 +5,7 @@
  * Source commit: 54123e884b1ae743b453260f713b20c9bf5787f2
  * SPDX-License-Identifier: EPL-2.0
  *******************************************************************************/
+import { connectedEdgesInPortOrder } from "./port-edge-order";
 import type { GraphEdge } from "@statelyai/graph";
 import type { AcyclicOrientation, LayerAssigner, LayeredPhaseInput } from "./types";
 
@@ -44,13 +45,13 @@ function getOrientedEndpoints(
     : [edge.sourceId, edge.targetId];
 }
 
-function getComponents(input: LayeredPhaseInput, orientation: AcyclicOrientation): string[][] {
+export function networkSimplexComponents(input: LayeredPhaseInput): string[][] {
   const adjacent = new Map(input.graph.nodes.map((node) => [node.id, [] as string[]]));
-  for (const edge of input.graph.edges) {
-    const [sourceId, targetId] = getOrientedEndpoints(edge, orientation);
-    if (sourceId === targetId) continue;
-    adjacent.get(sourceId)?.push(targetId);
-    adjacent.get(targetId)?.push(sourceId);
+  for (const node of input.graph.nodes) {
+    for (const edge of connectedEdgesInPortOrder(input, node.id)) {
+      if (edge.sourceId === edge.targetId) continue;
+      adjacent.get(node.id)?.push(edge.sourceId === node.id ? edge.targetId : edge.sourceId);
+    }
   }
   const visited = new Set<string>();
   const components: string[][] = [];
@@ -96,17 +97,12 @@ function createSimplexGraph(
     treeNode: false,
   }));
   const nodeById = new Map(nodes.map((node) => [node.id, node]));
-  const edgeBySource = new Map(component.map((id) => [id, [] as GraphEdge[]]));
-  for (const edge of input.graph.edges) {
-    const [sourceId, targetId] = getOrientedEndpoints(edge, orientation);
-    if (sourceId !== targetId && memberIds.has(sourceId) && memberIds.has(targetId)) {
-      edgeBySource.get(sourceId)?.push(edge);
-    }
-  }
   const edges: SimplexEdge[] = [];
   for (const sourceId of component) {
-    for (const graphEdge of edgeBySource.get(sourceId) ?? []) {
+    for (const graphEdge of connectedEdgesInPortOrder(input, sourceId)) {
       const [orientedSourceId, targetId] = getOrientedEndpoints(graphEdge, orientation);
+      if (orientedSourceId !== sourceId || sourceId === targetId || !memberIds.has(targetId))
+        continue;
       const source = nodeById.get(orientedSourceId);
       const target = nodeById.get(targetId);
       if (!source || !target) continue;
@@ -328,7 +324,7 @@ export function runNetworkSimplex(
 }
 
 export const assignLayersWithNetworkSimplex: LayerAssigner = (input, orientation) => {
-  const components = getComponents(input, orientation);
+  const components = networkSimplexComponents(input);
   const layerByNodeId = new Map<string, number>();
   let previousLayerCounts: number[] | undefined;
   const thoroughness = input.settings.thoroughness ?? 7;

package/src/layered/node-margins.ts

@@ -0,0 +1,59 @@
+import { getOrientedPortDirection, placePorts } from "./strategies";
+import type { AcyclicOrientation, LayeredPhaseInput } from "./types";
+
+interface CrossMargins {
+  before: number;
+  after: number;
+  flowBefore: number;
+  flowAfter: number;
+}
+const preparedMargins = new WeakMap<LayeredPhaseInput, ReadonlyMap<string, CrossMargins>>();
+
+/** Physical port boxes contribute to node margins before BK alignment and compaction. */
+export function preparePortMargins(
+  input: LayeredPhaseInput,
+  sizes = input.sizes,
+  orientation?: AcyclicOrientation,
+): void {
+  const horizontal = input.direction === "right" || input.direction === "left";
+  const margins = new Map<string, CrossMargins>();
+  for (const node of input.graph.nodes) {
+    const size = sizes.get(node.id) ?? { width: 0, height: 0 };
+    const ports = placePorts(
+      node.ports,
+      { x: 0, y: 0, width: size.width, height: size.height },
+      input.direction,
+      (port) => input.portSettings?.(port, node),
+      { ...input.settings, ...input.nodeSettings?.(node) },
+      // Free ports take their side from the acyclic edge direction, as in final placement.
+      orientation ? (port) => getOrientedPortDirection(input, orientation, node, port) : undefined,
+    );
+    let before = 0,
+      after = 0,
+      flowBefore = 0,
+      flowAfter = 0;
+    for (const port of ports ?? []) {
+      const start = horizontal ? (port.y ?? 0) : (port.x ?? 0);
+      const end = start + (horizontal ? (port.height ?? 0) : (port.width ?? 0));
+      before = Math.max(before, -start);
+      after = Math.max(after, end - (horizontal ? size.height : size.width));
+      const flowStart = horizontal ? (port.x ?? 0) : (port.y ?? 0);
+      const flowEnd = flowStart + (horizontal ? (port.width ?? 0) : (port.height ?? 0));
+      flowBefore = Math.max(flowBefore, -flowStart);
+      flowAfter = Math.max(flowAfter, flowEnd - (horizontal ? size.width : size.height));
+    }
+    if (before || after || flowBefore || flowAfter) {
+      const reverse = input.direction === "left" || input.direction === "up";
+      margins.set(node.id, {
+        before,
+        after,
+        flowBefore: reverse ? flowAfter : flowBefore,
+        flowAfter: reverse ? flowBefore : flowAfter,
+      });
+    }
+  }
+  preparedMargins.set(input, margins);
+}
+
+export const portCrossMargins = (input: LayeredPhaseInput, id: string): CrossMargins | undefined =>
+  preparedMargins.get(input)?.get(id);

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

@@ -0,0 +1,271 @@
+/*******************************************************************************
+ * Copyright (c) 2011, 2020 Kiel University and others.
+ * Adapted from ELK v0.11.0 NorthSouthPortPreprocessor.java (new approach).
+ * Source commit: 54123e884b1ae743b453260f713b20c9bf5787f2
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+import type { GraphNode, GraphPort, Point } from "@statelyai/graph";
+import type { LongEdgeExpansion } from "./long-edges";
+import { inheritCycleRandom } from "./cycle-random";
+
+export interface CrossPortOrigin {
+  node: GraphNode;
+  port: GraphPort;
+  /** Physical port face. */
+  side: "NORTH" | "SOUTH" | "WEST" | "EAST";
+  /** Position relative to the owner's canonical cross coordinate. */
+  beforeOwner: boolean;
+  input: boolean;
+  output: boolean;
+}
+export interface NorthSouthPortExpansion {
+  expansion: LongEdgeExpansion;
+  originsByDummyId: ReadonlyMap<string, CrossPortOrigin>;
+  incomingEdgeOrderByDummyId?: ReadonlyMap<string, readonly string[]>;
+  successorsByNodeId: ReadonlyMap<string, readonly string[]>;
+  layoutUnitByNodeId: ReadonlyMap<string, string>;
+}
+
+/** Detach fixed cross-axis ports into same-layer units before crossing minimization. */
+export function insertNorthSouthPortDummies(expansion: LongEdgeExpansion): NorthSouthPortExpansion {
+  const { input, orientation } = expansion;
+  const vertical = input.direction === "down" || input.direction === "up";
+  const forward =
+    input.direction === "right"
+      ? "EAST"
+      : input.direction === "left"
+        ? "WEST"
+        : input.direction === "down"
+          ? "SOUTH"
+          : "NORTH";
+  const backward = ({ EAST: "WEST", WEST: "EAST", NORTH: "SOUTH", SOUTH: "NORTH" } as const)[
+    forward
+  ];
+  const nodes = [...input.graph.nodes];
+  const used = new Set(nodes.map((n) => n.id));
+  const sizes = new Map(input.sizes);
+  const layers = new Map(expansion.assignment.layerByNodeId);
+  const origins = new Map<string, CrossPortOrigin>();
+  const byPort = new Map<GraphPort, string>();
+  const successors = new Map<string, string[]>();
+  const units = new Map<string, string>();
+  // Upstream gives every fixed-side normal node its own layout unit, even
+  // when it has no connected cross-axis ports.
+  for (const node of input.graph.nodes) {
+    const constraints = input.nodeSettings?.(node)?.portConstraints;
+    if (
+      !node.id.startsWith("__layout_dummy:") &&
+      constraints &&
+      constraints !== "UNDEFINED" &&
+      constraints !== "FREE"
+    )
+      units.set(node.id, node.id);
+  }
+  const attach = (
+    owner: GraphNode,
+    port: GraphPort,
+    side: CrossPortOrigin["side"],
+    incoming: boolean,
+  ) => {
+    let id = byPort.get(port);
+    if (!id) {
+      id = `__layout_dummy:north-south:${owner.id}:${port.name}`;
+      while (used.has(id)) id += ":";
+      used.add(id);
+      byPort.set(port, id);
+      // Canonical cross coordinates remain physical x in vertical layouts, y otherwise.
+      const beforeOwner = vertical ? side === "WEST" : side === "NORTH";
+      origins.set(id, { node: owner, port, side, beforeOwner, input: false, output: false });
+      nodes.push({ type: "node", id, data: undefined, width: 0, height: 0, ports: [] });
+      sizes.set(id, { width: 0, height: 0 });
+      layers.set(id, layers.get(owner.id) ?? 0);
+      units.set(owner.id, owner.id);
+      units.set(id, owner.id);
+      const from = beforeOwner ? id : owner.id;
+      const to = beforeOwner ? owner.id : id;
+      if (input.portSettings?.(port, owner)?.allowNonFlowPortsToSwitchSides !== true)
+        successors.set(from, [...(successors.get(from) ?? []), to]);
+    }
+    const origin = origins.get(id)!;
+    const role = incoming ? "input" : "output";
+    if (!origin[role]) {
+      origin[role] = true;
+      nodes
+        .find((n) => n.id === id)!
+        .ports!.push({
+          name: role,
+          direction: incoming ? "in" : "out",
+          x: 0,
+          y: 0,
+          width: 0,
+          height: 0,
+          data: undefined,
+        });
+    }
+    return { id, role };
+  };
+  const nodeById = new Map(input.graph.nodes.map((n) => [n.id, n]));
+  const edges = input.graph.edges.map((edge) => {
+    const reverse = orientation.reversedEdgeIds.has(edge.id);
+    const endpoint = (nodeId: string, portName: string | undefined, incoming: boolean) => {
+      const owner = nodeById.get(nodeId);
+      if (!owner || owner.id.startsWith("__layout_dummy:")) return undefined;
+      const constraints = input.nodeSettings?.(owner)?.portConstraints;
+      if (!constraints || constraints === "UNDEFINED" || constraints === "FREE") return undefined;
+      const port = owner.ports?.find((p) => p.name === portName);
+      if (!port) return undefined;
+      const side = input.portSettings?.(port, owner)?.["port.side"];
+      if (side !== "NORTH" && side !== "SOUTH" && side !== "WEST" && side !== "EAST")
+        return undefined;
+      if (vertical ? side !== "WEST" && side !== "EAST" : side !== "NORTH" && side !== "SOUTH")
+        return undefined;
+      return attach(owner, port, side, incoming);
+    };
+    // Dedicated same-side and north/south loop dummies are a separate upstream phase.
+    if (edge.sourceId === edge.targetId) return edge;
+    const source = endpoint(edge.sourceId, edge.sourcePort, reverse);
+    const target = endpoint(edge.targetId, edge.targetPort, !reverse);
+    return source || target
+      ? {
+          ...edge,
+          sourceId: source?.id ?? edge.sourceId,
+          sourcePort: source?.role ?? edge.sourcePort,
+          targetId: target?.id ?? edge.targetId,
+          targetPort: target?.role ?? edge.targetPort,
+        }
+      : edge;
+  });
+  if (!origins.size)
+    return {
+      expansion,
+      originsByDummyId: origins,
+      successorsByNodeId: successors,
+      layoutUnitByNodeId: units,
+    };
+  // The upstream mixed-role dummy creates its WEST input before its EAST output.
+  for (const node of nodes)
+    if (origins.has(node.id))
+      node.ports?.sort((a, b) => Number(a.name === "output") - Number(b.name === "output"));
+  // ELK creates each side's input, output, then mixed-role dummies in
+  // canonical flow order. Barycenter associates retain that creation order;
+  // insertion at one northern index reverses it in the layer itself.
+  const roleOrder = (origin: CrossPortOrigin) =>
+    origin.input && origin.output ? 2 : origin.input ? 0 : 1;
+  const negativeFlow = input.direction === "left" || input.direction === "up";
+  const orderedOrigins = input.graph.nodes.flatMap((node) => {
+    const entries = [...origins].filter(([, origin]) => origin.node.id === node.id);
+    const constraints = input.nodeSettings?.(node)?.portConstraints;
+    const coordinate = (origin: CrossPortOrigin) => {
+      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 entries.sort(
+      ([, a], [, b]) =>
+        Number(!a.beforeOwner) - Number(!b.beforeOwner) ||
+        roleOrder(a) - roleOrder(b) ||
+        coordinate(a) - coordinate(b),
+    );
+  });
+  const incomingEdgeOrderByDummyId = new Map<string, readonly string[]>();
+  for (const [dummy, origin] of origins) {
+    if (!origin.input) continue;
+    const ordered = expansion.incomingEdgeOrderByNodeId?.get(origin.node.id) ?? [];
+    if (!ordered.length) continue;
+    const ids = ordered.flatMap((id) => expansion.segmentIdsByEdgeId.get(id) ?? [id]);
+    incomingEdgeOrderByDummyId.set(
+      dummy,
+      ids.filter((id) =>
+        edges.some(
+          (edge) =>
+            edge.id === id &&
+            (orientation.reversedEdgeIds.has(id) ? edge.sourceId : edge.targetId) === dummy,
+        ),
+      ),
+    );
+  }
+  origins.clear();
+  for (const [id, origin] of orderedOrigins) origins.set(id, origin);
+  const seed = expansion.assignment.seedOrder ?? input.graph.nodes.map((n) => n.id);
+  const seedOrder = seed.flatMap((id) => [
+    ...[...origins]
+      .filter(([, o]) => o.node.id === id && o.beforeOwner)
+      .map(([dummy]) => dummy)
+      .reverse(),
+    id,
+    ...[...origins].filter(([, o]) => o.node.id === id && !o.beforeOwner).map(([dummy]) => dummy),
+  ]);
+  return {
+    expansion: {
+      ...expansion,
+      input: inheritCycleRandom(input, {
+        ...input,
+        graph: { ...input.graph, nodes, edges },
+        sizes,
+        nodeSettings: (n) =>
+          origins.has(n.id) ? { portConstraints: "FIXED_POS" } : input.nodeSettings?.(n),
+        portSettings: (p, n) =>
+          origins.has(n.id)
+            ? { "port.side": p.name === "input" ? backward : forward }
+            : input.portSettings?.(p, n),
+      }),
+      assignment: { ...expansion.assignment, layerByNodeId: layers, seedOrder },
+    },
+    originsByDummyId: origins,
+    incomingEdgeOrderByDummyId,
+    successorsByNodeId: successors,
+    layoutUnitByNodeId: units,
+  };
+}
+
+/** Reconnect orthogonal/polyline endpoints after routing, preserving the dummy-row bend. */
+export function restoreNorthSouthPortRoutes(
+  phase: NorthSouthPortExpansion,
+  placement: import("./types").NodePlacement,
+  routes: import("./types").EdgeRoutes,
+  anchor: (origin: CrossPortOrigin) => import("@statelyai/graph").Point,
+  restoredJunctionCounts?: Map<string, number>,
+): import("./types").EdgeRoutes {
+  if (phase.originsByDummyId.size === 0) return routes;
+  const vertical =
+    phase.expansion.input.direction === "down" || phase.expansion.input.direction === "up";
+  const pointsByEdgeId = new Map(routes.pointsByEdgeId);
+  const junctionPointsByEdgeId = new Map(routes.junctionPointsByEdgeId);
+  const addJunction = (edge: string, origin: CrossPortOrigin, bend: Point) => {
+    // ELK marks every restored branch when both dummy faces refer to one port.
+    // Spline restoration records its cross coordinate instead of junctions.
+    if (origin.input && origin.output && phase.expansion.input.settings.edgeRouting !== "SPLINES") {
+      junctionPointsByEdgeId.set(edge, [...(junctionPointsByEdgeId.get(edge) ?? []), bend]);
+      restoredJunctionCounts?.set(edge, (restoredJunctionCounts.get(edge) ?? 0) + 1);
+    }
+  };
+  for (const edge of phase.expansion.input.graph.edges) {
+    const original = pointsByEdgeId.get(edge.id);
+    if (!original?.length) continue;
+    const source = phase.originsByDummyId.get(edge.sourceId);
+    const target = phase.originsByDummyId.get(edge.targetId);
+    if (!source && !target) continue;
+    // Routing can collapse coincident physical endpoints to one coordinate.
+    // Reconnecting one face must not consume the opposite endpoint's identity.
+    let points = original.length === 1 ? [{ ...original[0]! }, { ...original[0]! }] : [...original];
+    if (source) {
+      const endpoint = anchor(source);
+      const rect = placement.rectByNodeId.get(edge.sourceId);
+      if (!rect) throw new Error(`Missing cross-port dummy placement: ${edge.sourceId}`);
+      const bend = vertical ? { x: rect.x, y: endpoint.y } : { x: endpoint.x, y: rect.y };
+      points = [endpoint, bend, ...points.slice(1)];
+      addJunction(edge.id, source, bend);
+    }
+    if (target) {
+      const endpoint = anchor(target);
+      const rect = placement.rectByNodeId.get(edge.targetId);
+      if (!rect) throw new Error(`Missing cross-port dummy placement: ${edge.targetId}`);
+      const bend = vertical ? { x: rect.x, y: endpoint.y } : { x: endpoint.x, y: rect.y };
+      points = [...points.slice(0, -1), bend, endpoint];
+      addJunction(edge.id, target, bend);
+    }
+    pointsByEdgeId.set(edge.id, points);
+  }
+  return { ...routes, pointsByEdgeId, junctionPointsByEdgeId };
+}