@elabs-ai/components-flow 4.0.0 → 4.1.0

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

@@ -1,8 +1,10 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import "@xyflow/react/dist/style.css";
 import { type Edge } from "@xyflow/react";
+import { expect, waitFor } from "storybook/test";
 import { CanvasShell } from "../canvas-shell";
-import { FlowNode, type BrandFlowNode } from "../flow-node";
+import { FLOW_ALL_SIDE_HANDLES, FlowNode, type BrandFlowNode } from "../flow-node";
+import { edgePaths, endpointsOffHandles } from "../testing/edge-anchors";
 import { FlowSmartEdge } from "./flow-smart-edge";
 
 const nodeTypes = { brand: FlowNode };
@@ -17,6 +19,19 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+/**
+ * Every smart edge must terminate ON a handle dot. Before the anchoring fix the
+ * shipped anchors missed the nearest dot by ~22px on all-side nodes and ~124px
+ * on nodes carrying only the default top/bottom handles — the latter because a
+ * left/right side with no handle at all could be chosen.
+ */
+async function expectEdgesAnchoredToHandles(canvasElement: HTMLElement, edgeCount: number) {
+  await waitFor(() => {
+    expect(edgePaths(canvasElement, "flow-smart-edge")).toHaveLength(edgeCount);
+    expect(endpointsOffHandles(canvasElement, "flow-smart-edge")).toEqual([]);
+  });
+}
+
 /**
  * Multi-side nodes (handles on all four sides) connected by `FlowSmartEdge`.
  * Drag a node around another and the edge re-picks the closest source/target
@@ -24,10 +39,6 @@ type Story = StoryObj<typeof meta>;
  */
 export const Default: Story = {
   render: () => {
-    const allSides = {
-      source: ["top", "right", "bottom", "left"],
-      target: ["top", "right", "bottom", "left"],
-    } as const;
     const nodes: BrandFlowNode[] = [
       {
         id: "a",
@@ -37,7 +48,7 @@ export const Default: Story = {
           kind: "Source",
           title: "Ingest",
           tone: "accent",
-          handles: { source: [...allSides.source], target: [...allSides.target] },
+          handles: FLOW_ALL_SIDE_HANDLES,
         },
       },
       {
@@ -47,7 +58,7 @@ export const Default: Story = {
         data: {
           kind: "Process",
           title: "Transform",
-          handles: { source: [...allSides.source], target: [...allSides.target] },
+          handles: FLOW_ALL_SIDE_HANDLES,
         },
       },
       {
@@ -58,7 +69,7 @@ export const Default: Story = {
           kind: "Output",
           title: "Publish",
           tone: "success",
-          handles: { source: [...allSides.source], target: [...allSides.target] },
+          handles: FLOW_ALL_SIDE_HANDLES,
         },
       },
     ];
@@ -72,4 +83,40 @@ export const Default: Story = {
       </div>
     );
   },
+  play: async ({ canvasElement }) => {
+    await expectEdgesAnchoredToHandles(canvasElement, 2);
+  },
+};
+
+/**
+ * Nodes with **no** `data.handles` config — they render `FlowNode`'s default
+ * single top target + bottom source. A smart edge must anchor to those two real
+ * dots; it must not invent a left/right anchor on a side that has no handle.
+ */
+export const DefaultNodeHandles: Story = {
+  render: () => {
+    const nodes: BrandFlowNode[] = [
+      {
+        id: "a",
+        type: "brand",
+        position: { x: 60, y: 40 },
+        data: { kind: "Source", title: "Ingest" },
+      },
+      {
+        id: "b",
+        type: "brand",
+        position: { x: 360, y: 260 },
+        data: { kind: "Output", title: "Publish", tone: "success" },
+      },
+    ];
+    const edges: Edge[] = [{ id: "a-b", source: "a", target: "b", type: "smart" }];
+    return (
+      <div className="h-[420px]">
+        <CanvasShell nodes={nodes} edges={edges} nodeTypes={nodeTypes} edgeTypes={edgeTypes} />
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    await expectEdgesAnchoredToHandles(canvasElement, 1);
+  },
 };

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,