@elabs-ai/components-flow 4.0.0 → 4.2.0

package/src/flow-smart-edge/flow-smart-edge.tsx

@@ -1,19 +1,24 @@
 import {
-  BaseEdge,
   getBezierPath,
   useInternalNode,
   type EdgeProps,
   type InternalNode,
+  type Node,
+  type Position,
 } from "@xyflow/react";
-import type { FlowNodeData } from "../flow-node";
+import { FlowEdgePath } from "../flow-edge-path";
+import type { FlowHandleSide, FlowNodeData } from "../flow-node";
 import {
+  pickClosestAnchors,
   pickClosestHandles,
-  rectCenter,
+  positionToSide,
   sideToPosition,
-  slideAnchor,
+  type HandleAnchor,
   type NodeRect,
 } from "./smart-edge-geometry";
 
+type HandleKind = "source" | "target";
+
 function toRect(node: InternalNode): NodeRect {
   return {
     x: node.internals.positionAbsolute.x,
@@ -24,52 +29,137 @@ function toRect(node: InternalNode): NodeRect {
 }
 
 /**
- * Branded edge that picks the closest source/target handle pair (from a node's
- * multi-side `FlowNodeHandles` config) and routes a bezier between them. Anchors
- * are recomputed every render, so they flip as nodes are dragged. Register it in
- * `edgeTypes={{ smart: FlowSmartEdge }}` and give the connected nodes a
- * `data.handles` config. Uses the `--flow-edge` token, matching `FlowEdge`.
+ * The candidate anchors for one end of the edge, read from React Flow's
+ * **measured** handle bounds — the DOM truth about where each dot was painted.
+ *
+ * `handleBounds` entries are node-relative, so the node's absolute position is
+ * added back; the dot's centre is the entry's own box centre, which is why this
+ * tracks any handle size or offset the node's CSS chooses instead of assuming
+ * the dot sits on the side's midpoint.
+ *
+ * `handleId` pins the result to one handle when the edge names one
+ * (`sourceHandle`/`targetHandle`), so an explicitly wired edge is never
+ * re-routed to a different dot.
+ */
+function anchorsOf(
+  node: InternalNode,
+  kind: HandleKind,
+  handleId: string | null | undefined,
+): HandleAnchor[] {
+  const bounds = node.internals.handleBounds?.[kind] ?? [];
+  const origin = node.internals.positionAbsolute;
+  return bounds
+    .filter((handle) => (handleId ? handle.id === handleId : true))
+    .map((handle) => ({
+      id: handle.id ?? null,
+      x: origin.x + handle.x + handle.width / 2,
+      y: origin.y + handle.y + handle.height / 2,
+      side: positionToSide[handle.position],
+    }));
+}
+
+/**
+ * The sides a `FlowNode` genuinely renders a handle on, for the pre-measurement
+ * fallback only: its `data.handles` config when it has one, otherwise the
+ * single default handle React Flow's layout direction placed
+ * (`targetPosition`/`sourcePosition`, defaulting to top-in / bottom-out).
+ */
+function declaredSides(node: InternalNode, kind: HandleKind): FlowHandleSide[] {
+  const userNode = node.internals.userNode as Node<Record<string, unknown>>;
+  const data = userNode.data as FlowNodeData | undefined;
+  const configured = data?.handles?.[kind];
+  if (configured?.length) return [...configured];
+  const position = (kind === "target" ? userNode.targetPosition : userNode.sourcePosition) as
+    | Position
+    | undefined;
+  if (position) return [positionToSide[position]];
+  return [kind === "target" ? "top" : "bottom"];
+}
+
+/**
+ * Branded edge that picks the closest source/target **handle** pair and routes a
+ * bezier between them. Anchors are recomputed every render, so they flip as
+ * nodes are dragged. Register it in `edgeTypes={{ smart: FlowSmartEdge }}`; give
+ * the connected nodes a `data.handles` config (e.g. `FLOW_ALL_SIDE_HANDLES`) to
+ * offer it more than the default two anchors. Uses the `--flow-edge` token,
+ * matching `FlowEdge`.
+ *
+ * ## The path terminates ON the handle dot
+ *
+ * The endpoints come from React Flow's **measured `handleBounds`** — the centre
+ * of the rendered dot — not from a point derived from the node's rectangle.
+ * That is a correctness property, not a refinement: an earlier version slid each
+ * anchor along the chosen side toward the other node (to fan out edges sharing a
+ * side) and picked sides from a four-way fallback list, so a line could meet the
+ * node up to half a side away from any dot — measured at ~22px on multi-side
+ * nodes and ~124px on nodes carrying only the default top/bottom handles, where
+ * a left/right side with no handle at all could be chosen. Two edges leaving the
+ * same handle now leave from the same point and diverge, exactly as React Flow's
+ * own edges do.
  */
-export function FlowSmartEdge({ id, source, target, markerEnd, style }: EdgeProps) {
+export function FlowSmartEdge({
+  id,
+  source,
+  target,
+  sourceHandleId,
+  targetHandleId,
+  markerEnd,
+  style,
+}: EdgeProps) {
   const sourceNode = useInternalNode(source);
   const targetNode = useInternalNode(target);
   if (!sourceNode || !targetNode) return null;
 
-  const sourceData = sourceNode.internals.userNode.data as FlowNodeData | undefined;
-  const targetData = targetNode.internals.userNode.data as FlowNodeData | undefined;
-
-  const sourceRect = toRect(sourceNode);
-  const targetRect = toRect(targetNode);
-
-  // Pick which side of each node the edge exits/enters (the facing handle side).
-  const { sourceSide, targetSide } = pickClosestHandles(
-    sourceRect,
-    sourceData?.handles?.source ?? [],
-    targetRect,
-    targetData?.handles?.target ?? [],
+  const picked = pickClosestAnchors(
+    anchorsOf(sourceNode, "source", sourceHandleId),
+    anchorsOf(targetNode, "target", targetHandleId),
   );
 
-  // Then slide each anchor along its chosen side toward the OTHER node, so
-  // edges sharing a side fan out to distinct, target-facing points instead of
-  // stacking on the side midpoint.
-  const sourceAnchor = slideAnchor(sourceRect, sourceSide, rectCenter(targetRect));
-  const targetAnchor = slideAnchor(targetRect, targetSide, rectCenter(sourceRect));
+  let sx: number;
+  let sy: number;
+  let tx: number;
+  let ty: number;
+  let sourcePosition: Position;
+  let targetPosition: Position;
+
+  if (picked) {
+    ({ x: sx, y: sy } = picked.source);
+    ({ x: tx, y: ty } = picked.target);
+    sourcePosition = sideToPosition[picked.source.side];
+    targetPosition = sideToPosition[picked.target.side];
+  } else {
+    // Handles not measured yet (first render). Fall back to the side midpoints
+    // of the sides the nodes actually declare, so the edge is drawn sanely for
+    // the frame or two before React Flow reports real handle bounds.
+    const fallback = pickClosestHandles(
+      toRect(sourceNode),
+      declaredSides(sourceNode, "source"),
+      toRect(targetNode),
+      declaredSides(targetNode, "target"),
+    );
+    ({ sx, sy, tx, ty } = fallback);
+    sourcePosition = sideToPosition[fallback.sourceSide];
+    targetPosition = sideToPosition[fallback.targetSide];
+  }
 
   const [edgePath] = getBezierPath({
-    sourceX: sourceAnchor.x,
-    sourceY: sourceAnchor.y,
-    sourcePosition: sideToPosition[sourceSide],
-    targetX: targetAnchor.x,
-    targetY: targetAnchor.y,
-    targetPosition: sideToPosition[targetSide],
+    sourceX: sx,
+    sourceY: sy,
+    sourcePosition,
+    targetX: tx,
+    targetY: ty,
+    targetPosition,
   });
 
   return (
-    <BaseEdge
+    <FlowEdgePath
       id={id}
       path={edgePath}
       markerEnd={markerEnd}
-      style={{ stroke: "var(--flow-edge)", strokeWidth: 1.5, ...style }}
+      data-slot="flow-smart-edge"
+      stroke="var(--flow-edge)"
+      strokeWidth={1.5}
+      style={style}
     />
   );
 }

package/src/flow-smart-edge/index.ts

@@ -2,8 +2,12 @@ export { FlowSmartEdge } from "./flow-smart-edge";
 export {
   HANDLE_SIDES,
   sideToPosition,
+  positionToSide,
   handlePoint,
+  pickClosestAnchors,
   pickClosestHandles,
-  type NodeRect,
+  type ClosestAnchors,
   type ClosestHandles,
+  type HandleAnchor,
+  type NodeRect,
 } from "./smart-edge-geometry";

package/src/flow-smart-edge/smart-edge-geometry.test.ts

@@ -8,11 +8,12 @@ vi.mock("@xyflow/react", () => ({
 
 import {
   handlePoint,
+  pickClosestAnchors,
   pickClosestHandles,
-  rectCenter,
+  positionToSide,
   sideToPosition,
-  slideAnchor,
   HANDLE_SIDES,
+  type HandleAnchor,
   type NodeRect,
 } from "./smart-edge-geometry";
 
@@ -23,6 +24,13 @@ const rect = (x: number, y: number, width = 100, height = 60): NodeRect => ({
   height,
 });
 
+const anchor = (
+  id: HandleAnchor["id"],
+  x: number,
+  y: number,
+  side: HandleAnchor["side"],
+): HandleAnchor => ({ id, x, y, side });
+
 describe("handlePoint", () => {
   it("returns the midpoint of each side", () => {
     const r = rect(0, 0, 100, 60);
@@ -33,20 +41,81 @@ describe("handlePoint", () => {
   });
 });
 
-describe("sideToPosition", () => {
+describe("sideToPosition / positionToSide", () => {
   it("maps every side to the matching Position value", () => {
     expect(sideToPosition.top).toBe("top");
     expect(sideToPosition.right).toBe("right");
     expect(sideToPosition.bottom).toBe("bottom");
     expect(sideToPosition.left).toBe("left");
   });
+
+  it("round-trips every side", () => {
+    for (const side of HANDLE_SIDES) {
+      expect(positionToSide[sideToPosition[side]]).toBe(side);
+    }
+  });
 });
 
-describe("pickClosestHandles", () => {
+describe("pickClosestAnchors", () => {
+  // A node at (0,0,100,60) with all-side handles, and one 300px to its right.
+  const leftNode: HandleAnchor[] = [
+    anchor("top", 50, 0, "top"),
+    anchor("right", 100, 30, "right"),
+    anchor("bottom", 50, 60, "bottom"),
+    anchor("left", 0, 30, "left"),
+  ];
+  const rightNode: HandleAnchor[] = [
+    anchor("top", 350, 0, "top"),
+    anchor("right", 400, 30, "right"),
+    anchor("bottom", 350, 60, "bottom"),
+    anchor("left", 300, 30, "left"),
+  ];
+
+  it("returns the closest facing pair", () => {
+    const picked = pickClosestAnchors(leftNode, rightNode);
+    expect(picked?.source.id).toBe("right");
+    expect(picked?.target.id).toBe("left");
+  });
+
+  it("returns the anchor coordinates VERBATIM — never a derived point", () => {
+    // This is the whole contract: the edge terminates exactly where the dot was
+    // measured, so no arithmetic may sit between the two.
+    const picked = pickClosestAnchors(leftNode, rightNode);
+    expect(picked?.source).toEqual(anchor("right", 100, 30, "right"));
+    expect(picked?.target).toEqual(anchor("left", 300, 30, "left"));
+  });
+
+  it("picks a stacked pair when the other node is below", () => {
+    const below = rightNode.map((a) => ({ ...a, x: a.x - 300, y: a.y + 300 }));
+    const picked = pickClosestAnchors(leftNode, below);
+    expect(picked?.source.id).toBe("bottom");
+    expect(picked?.target.id).toBe("top");
+  });
+
+  it("uses the only handle a node has, whatever side it faces", () => {
+    // A default FlowNode: one bottom source, one top target. It must never be
+    // routed to a left/right anchor it does not render.
+    const picked = pickClosestAnchors(
+      [anchor(null, 50, 60, "bottom")],
+      [anchor(null, 350, 0, "top")],
+    );
+    expect(picked?.source.side).toBe("bottom");
+    expect(picked?.target.side).toBe("top");
+    expect(picked?.source).toEqual({ id: null, x: 50, y: 60, side: "bottom" });
+  });
+
+  it("returns undefined when either end has no measured handle", () => {
+    expect(pickClosestAnchors([], rightNode)).toBeUndefined();
+    expect(pickClosestAnchors(leftNode, [])).toBeUndefined();
+  });
+});
+
+describe("pickClosestHandles (pre-measurement fallback)", () => {
   it("target to the right → source uses its right handle, target its left", () => {
-    const source = rect(0, 0);
-    const target = rect(300, 0);
-    const picked = pickClosestHandles(source, ["right", "left"], target, ["left", "right"]);
+    const picked = pickClosestHandles(rect(0, 0), ["right", "left"], rect(300, 0), [
+      "left",
+      "right",
+    ]);
 
     expect(picked.sourceSide).toBe("right");
     expect(picked.targetSide).toBe("left");
@@ -70,51 +139,23 @@ describe("pickClosestHandles", () => {
     expect(["bottom", "right"]).toContain(picked.targetSide);
   });
 
+  it("honours a single declared side instead of widening to all four", () => {
+    // A default FlowNode declares bottom-out / top-in only. Even with the other
+    // node straight to the right, the anchor stays on a side that has a handle.
+    const picked = pickClosestHandles(rect(0, 0), ["bottom"], rect(300, 0), ["top"]);
+    expect(picked.sourceSide).toBe("bottom");
+    expect(picked.targetSide).toBe("top");
+  });
+
   it("falls back to all four sides when a side list is empty", () => {
     const picked = pickClosestHandles(rect(0, 0), [], rect(300, 0), []);
     expect(picked.sourceSide).toBe("right");
     expect(picked.targetSide).toBe("left");
   });
-});
-
-describe("rectCenter", () => {
-  it("returns the node's centre", () => {
-    expect(rectCenter(rect(0, 0, 100, 60))).toEqual({ x: 50, y: 30 });
-  });
-});
-
-describe("slideAnchor", () => {
-  const r = rect(0, 0, 100, 60); // usable right/left span [12, 48], top/bottom span [12, 88]
-
-  it("stays on the chosen side's axis", () => {
-    expect(slideAnchor(r, "right", { x: 999, y: 30 }).x).toBe(100);
-    expect(slideAnchor(r, "left", { x: -999, y: 30 }).x).toBe(0);
-    expect(slideAnchor(r, "top", { x: 30, y: -999 }).y).toBe(0);
-    expect(slideAnchor(r, "bottom", { x: 30, y: 999 }).y).toBe(60);
-  });
-
-  it("slides toward the target and clamps within the inset", () => {
-    // Target far above → clamp to the top of the usable range (inset 12).
-    expect(slideAnchor(r, "right", { x: 100, y: -500 }).y).toBe(12);
-    // Target far below → clamp to the bottom of the usable range.
-    expect(slideAnchor(r, "right", { x: 100, y: 500 }).y).toBe(48);
-    // Target within range → follows it.
-    expect(slideAnchor(r, "right", { x: 100, y: 30 }).y).toBe(30);
-  });
-
-  it("fans two edges on the same side to distinct anchors", () => {
-    // The Ingest→Transform (up) vs Ingest→Publish (down) case, both leaving right.
-    const up = slideAnchor(r, "right", { x: 400, y: -200 });
-    const down = slideAnchor(r, "right", { x: 400, y: 200 });
-    expect(up.y).toBeLessThan(down.y);
-    expect(up.y).not.toBe(down.y);
-  });
 
-  it("never inverts the range on a tiny node", () => {
-    const tiny = rect(0, 0, 10, 10); // inset (12) capped to width/2 = 5
-    const p = slideAnchor(tiny, "right", { x: 100, y: -100 });
-    expect(p.x).toBe(10);
-    expect(p.y).toBeGreaterThanOrEqual(0);
-    expect(p.y).toBeLessThanOrEqual(10);
+  it("anchors on side midpoints, never a slid point", () => {
+    const picked = pickClosestHandles(rect(0, 0), ["right"], rect(300, -500), ["left"]);
+    // The target is far above; the anchor stays on the side's midpoint.
+    expect(picked.sy).toBe(30);
   });
 });

package/src/flow-smart-edge/smart-edge-geometry.ts

@@ -20,40 +20,71 @@ export const sideToPosition: Record<FlowHandleSide, Position> = {
   left: Position.Left,
 };
 
-/** Center point of a node rectangle. */
-export function rectCenter(rect: NodeRect): { x: number; y: number } {
-  return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+/** Maps a React Flow `Position` back to the handle side it names. */
+export const positionToSide: Record<Position, FlowHandleSide> = {
+  [Position.Top]: "top",
+  [Position.Right]: "right",
+  [Position.Bottom]: "bottom",
+  [Position.Left]: "left",
+};
+
+/**
+ * One candidate connection point: the **measured centre of a rendered handle
+ * dot**, in absolute flow coordinates, plus the side it sits on.
+ *
+ * This is the unit `FlowSmartEdge` routes between. Anchoring on a measured
+ * handle — rather than on a point derived from the node's rectangle — is what
+ * guarantees the drawn path terminates exactly on the dot the user sees,
+ * whatever the handle's size, offset or CSS. See {@link pickClosestAnchors}.
+ */
+export interface HandleAnchor {
+  /** The handle's `id`, when it has one (`FlowNode` uses the side name). */
+  id: string | null;
+  /** Absolute x of the handle dot's centre. */
+  x: number;
+  /** Absolute y of the handle dot's centre. */
+  y: number;
+  /** The node side the handle sits on — the bezier's control direction. */
+  side: FlowHandleSide;
+}
+
+/** The chosen source/target anchor pair. */
+export interface ClosestAnchors {
+  source: HandleAnchor;
+  target: HandleAnchor;
 }
 
 /**
- * The connection point on `side` of `rect`, slid along that side toward
- * `toward` and clamped `inset` px from the corners. This is what stops two
- * edges that both leave the same side (e.g. both targets sit to the right)
- * from piling onto the side's midpoint: each edge's anchor slides toward its
- * own target, so an up-going edge exits the upper part of the side and a
- * down-going edge the lower part — each visibly meeting the node on the side
- * that faces its target instead of stacking in the middle.
+ * Picks the source/target pair of **rendered handles** with the shortest
+ * straight-line distance between them.
+ *
+ * Returns `undefined` when either side has no candidates, so the caller can
+ * fall back to rectangle geometry for a node whose handles have not been
+ * measured yet (React Flow populates `handleBounds` on its first measurement
+ * pass; before that there is nothing to anchor to).
  */
-export function slideAnchor(
-  rect: NodeRect,
-  side: FlowHandleSide,
-  toward: { x: number; y: number },
-  inset = 12,
-): { x: number; y: number } {
-  const clamp = (v: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, v));
-  // Never let the inset invert the usable range on a small node.
-  const ix = Math.min(inset, rect.width / 2);
-  const iy = Math.min(inset, rect.height / 2);
-  switch (side) {
-    case "top":
-      return { x: clamp(toward.x, rect.x + ix, rect.x + rect.width - ix), y: rect.y };
-    case "bottom":
-      return { x: clamp(toward.x, rect.x + ix, rect.x + rect.width - ix), y: rect.y + rect.height };
-    case "left":
-      return { x: rect.x, y: clamp(toward.y, rect.y + iy, rect.y + rect.height - iy) };
-    case "right":
-      return { x: rect.x + rect.width, y: clamp(toward.y, rect.y + iy, rect.y + rect.height - iy) };
+export function pickClosestAnchors(
+  sources: HandleAnchor[],
+  targets: HandleAnchor[],
+): ClosestAnchors | undefined {
+  if (!sources.length || !targets.length) return undefined;
+
+  let best: ClosestAnchors | undefined;
+  let bestDist = Infinity;
+
+  for (const source of sources) {
+    for (const target of targets) {
+      const dx = target.x - source.x;
+      const dy = target.y - source.y;
+      const dist = dx * dx + dy * dy;
+      if (dist < bestDist) {
+        bestDist = dist;
+        best = { source, target };
+      }
+    }
   }
+
+  return best;
 }
 
 /** Absolute coordinate of a handle on the given side (the side's midpoint). */
@@ -70,7 +101,7 @@ export function handlePoint(rect: NodeRect, side: FlowHandleSide): { x: number;
   }
 }
 
-/** The chosen source/target handle pair plus their absolute anchor points. */
+/** The side pair picked by {@link pickClosestHandles}, with both anchor points. */
 export interface ClosestHandles {
   sourceSide: FlowHandleSide;
   targetSide: FlowHandleSide;
@@ -81,9 +112,14 @@ export interface ClosestHandles {
 }
 
 /**
- * Picks the source/target handle pair (one handle per node) with the shortest
- * straight-line distance between their anchor points. Empty side lists fall
- * back to all four sides so an edge always resolves to a pair.
+ * Rectangle-only fallback: picks the closest pair of **side midpoints** from the
+ * candidate sides of each node.
+ *
+ * `FlowSmartEdge` prefers {@link pickClosestAnchors} (measured handle centres)
+ * and only reaches for this before React Flow has measured the nodes. Pass the
+ * sides each node genuinely renders a handle on — passing sides that carry no
+ * handle produces an anchor floating on a bare border, which is the defect this
+ * module exists to avoid.
  */
 export function pickClosestHandles(
   source: NodeRect,

package/src/flow-weighted-edge/back-edge-geometry.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { backEdgeDetour, type BackEdgeNodeRect } from "./back-edge-geometry";
+
+/** Three cards on one rank, the shape a rework edge has to get around. */
+const rank: BackEdgeNodeRect[] = [
+  { x: 0, y: 200, width: 176, height: 83 },
+  { x: 220, y: 200, width: 176, height: 83 },
+  { x: 440, y: 200, width: 176, height: 83 },
+];
+
+describe("backEdgeDetour", () => {
+  it("clears the OUTERMOST card in the band, not just the edge's own two nodes", () => {
+    // The edge runs between the rank above (y 0) and the rank at y 200. Clearing only
+    // its own endpoints would put the leg at 396 + 40 — inside the third card.
+    expect(backEdgeDetour(rank, "vertical", [283, 100], 40)).toBe(656);
+  });
+
+  it("ignores a card on another rank entirely", () => {
+    const withFarRank = [...rank, { x: 2000, y: 600, width: 176, height: 83 }];
+    expect(backEdgeDetour(withFarRank, "vertical", [283, 100], 40)).toBe(656);
+  });
+
+  it("includes a card the span only touches at its edge", () => {
+    // Span ends exactly on the rank's top edge: the leg still has to pass it.
+    expect(backEdgeDetour(rank, "vertical", [100, 200], 40)).toBe(656);
+  });
+
+  it("measures along the other axis in a left-to-right layout", () => {
+    // Ranks advance horizontally, so the return leg runs BELOW the cards.
+    expect(backEdgeDetour(rank, "horizontal", [0, 616], 40)).toBe(323);
+  });
+
+  it("skips unmeasured cards rather than treating them as zero-size boxes at the origin", () => {
+    const unmeasured = [{ x: 900, y: 200, width: 0, height: 0 }, ...rank];
+    expect(backEdgeDetour(unmeasured, "vertical", [283, 100], 40)).toBe(656);
+  });
+
+  it("returns null when nothing is measured, so React Flow's own midpoint stands", () => {
+    expect(backEdgeDetour([], "vertical", [283, 100], 40)).toBeNull();
+    expect(
+      backEdgeDetour([{ x: 0, y: 0, width: 0, height: 0 }], "vertical", [0, 1], 40),
+    ).toBeNull();
+  });
+
+  it("reads the span in either order", () => {
+    expect(backEdgeDetour(rank, "vertical", [100, 283], 40)).toBe(
+      backEdgeDetour(rank, "vertical", [283, 100], 40),
+    );
+  });
+
+  it("returns null when every card sits outside the span", () => {
+    expect(backEdgeDetour(rank, "vertical", [400, 500], 40)).toBeNull();
+  });
+});

package/src/flow-weighted-edge/back-edge-geometry.ts

@@ -0,0 +1,60 @@
+/**
+ * Where a back edge's return leg runs, so it stays VISIBLE.
+ *
+ * A back edge is drawn as a smoothstep with one long cross-segment running against the
+ * layout direction. React Flow puts that segment halfway between the two handles by
+ * default, and a fixed nudge off the midpoint does not help: in a top-down layout the
+ * midpoint of a rework edge sits between two ranks, i.e. squarely inside the column of
+ * cards it is supposed to run past. Edges paint UNDER nodes, so the segment vanishes
+ * behind the cards and all the reader is left with is a dashed stub below one node and
+ * another above the other — which reads as a stray rectangle, not as a loop back.
+ *
+ * So the leg is placed OUTSIDE every card it would otherwise pass behind: past the far
+ * side of every node whose extent overlaps the span the edge crosses. That is how a
+ * process-mining tool draws a rework loop — out, around the rank, back in — and it is
+ * the only placement that is correct for a graph rather than for a pair of nodes.
+ */
+
+/** One node's laid-out box, in flow coordinates. */
+export interface BackEdgeNodeRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Which axis the layout's ranks advance along. */
+export type BackEdgeAxis = "vertical" | "horizontal";
+
+/**
+ * The `centerX` (vertical layout) or `centerY` (horizontal layout) to hand
+ * `getSmoothStepPath`, or `null` when nothing is measured yet and React Flow's own
+ * midpoint should stand.
+ *
+ * @param rects  Every laid-out node on the canvas. Nodes that cannot be hit are filtered
+ *               out here rather than by the caller, so the caller stays a plain map.
+ * @param span   The interval the edge crosses on the RANK axis (`[min, max]` of the two
+ *               handle coordinates) — a node outside it is never behind this edge.
+ * @param clearance  Gap left between the leg and the outermost card it clears.
+ */
+export function backEdgeDetour(
+  rects: readonly BackEdgeNodeRect[],
+  axis: BackEdgeAxis,
+  span: readonly [number, number],
+  clearance: number,
+): number | null {
+  const [lo, hi] = span[0] <= span[1] ? span : [span[1], span[0]];
+  let far = Number.NEGATIVE_INFINITY;
+
+  for (const rect of rects) {
+    if (!(rect.width > 0) || !(rect.height > 0)) continue;
+    // Overlap on the RANK axis (the one the edge travels along): a node beside the
+    // corridor but on another rank cannot be crossed by this leg.
+    const [near, beyond] =
+      axis === "vertical" ? [rect.y, rect.y + rect.height] : [rect.x, rect.x + rect.width];
+    if (beyond < lo || near > hi) continue;
+    far = Math.max(far, axis === "vertical" ? rect.x + rect.width : rect.y + rect.height);
+  }
+
+  return Number.isFinite(far) ? far + clearance : null;
+}