@elabs-ai/components-flow 4.0.0 → 4.2.0

package/src/flow-self-loop-edge/flow-self-loop-edge.tsx

@@ -0,0 +1,172 @@
+import { useMemo } from "react";
+import { useEdges, useInternalNode, type Edge, type EdgeProps } from "@xyflow/react";
+import { FlowEdgePath } from "../flow-edge-path";
+import {
+  computeEdgeWeightScale,
+  DEFAULT_EDGE_WIDTH_RANGE,
+  EdgeLabelPill,
+  type EdgeLabelPillProps,
+  type WeightedEdgeLike,
+} from "../flow-weighted-edge";
+import { DEFAULT_LOOP_RADIUS, selfLoopHandleArc, selfLoopPath } from "./self-loop-geometry";
+
+export interface FlowSelfLoopEdgeData extends Record<string, unknown> {
+  /**
+   * Frequency/volume this loop carries. Scaled into stroke width by the SAME
+   * `computeEdgeWeightScale` domain as `FlowWeightedEdge`, so a loop's weight
+   * is directly comparable with the forward edges around it.
+   */
+  weight?: number;
+  /** Edges sharing a `scaleGroup` share one min-max width domain. @default all edges in the flow */
+  scaleGroup?: string;
+  /** Primary edge-label-pill text, e.g. a repeat count. */
+  label?: string;
+  /** Secondary edge-label-pill text, e.g. an average duration. */
+  secondaryLabel?: string;
+  /** Radius of the arc, in px. @default 28 */
+  loopRadius?: number;
+  /**
+   * Overrides the accessible name given to the loop's graphic. Defaults to
+   * "Self-loop on <node> — this step repeats".
+   */
+  loopLabel?: string;
+  /**
+   * Passed straight through to the rendered `EdgeLabelPill`'s `className`/`...props`
+   * (see `EdgeLabelPillProps`) — the seam a composing package (e.g.
+   * `@elabs-ai/components-process`'s `ProcessTransitionEdge`) uses to reach the pill's
+   * own root button from outside this component, without a new semantic prop here.
+   */
+  labelProps?: Omit<EdgeLabelPillProps, "label" | "secondaryLabel" | "x" | "y" | "selected">;
+}
+
+export type BrandFlowSelfLoopEdge = Edge<FlowSelfLoopEdgeData, "self-loop">;
+
+/** Node `data` shapes a title can be read from — `FlowNode`'s is `{ title }`. */
+function nodeName(data: unknown, fallback: string): string {
+  if (data && typeof data === "object" && "title" in data) {
+    const title = (data as { title?: unknown }).title;
+    if (typeof title === "string" && title.length > 0) return title;
+  }
+  return fallback;
+}
+
+/**
+ * Branded self-loop edge: an edge whose `source === target` — the "this step
+ * repeated" signal of a process map. Register it in
+ * `edgeTypes={{ "self-loop": FlowSelfLoopEdge }}` and create edges with
+ * `type: "self-loop"` and `data: FlowSelfLoopEdgeData`.
+ *
+ * dagre cannot lay a self-loop out, so `layoutFlow` withholds them from the
+ * graph entirely and reports their ids in `selfLoops` — this component draws
+ * the arc itself, from the node's own live geometry (`useInternalNode`).
+ *
+ * ## It terminates ON the handle dots, like every other brand edge
+ *
+ * The two handle points of a self-loop sit on OPPOSITE sides of one node, so they
+ * describe no useful straight line — which is why this edge used to ignore them and
+ * arc over the node's top edge instead, with its feet on bare border a loop-radius
+ * away from the nearest dot. Measured on the process map, that read as a detached
+ * arc floating above the card: 24 px clear of any dot in a top-to-bottom layout, and
+ * 69 px in a left-to-right one, where the loop stayed stubbornly on TOP while the
+ * flow (and the handles) had moved to the sides. Both are the "an edge terminates on
+ * a handle dot" rule being broken, just by a component that had declared itself
+ * exempt.
+ *
+ * `selfLoopHandleArc` keeps the loop a SHAPE — it just bulges clear of the node on
+ * the side a quarter turn from the source handle's own normal, so it lassos down the
+ * right in a top-to-bottom layout and arcs over the top in a left-to-right one,
+ * without this component knowing which direction is in force. Before the node is
+ * measured there is nothing to clear, so it falls back to the node-box arc
+ * (`selfLoopPath`) rather than to `NaN`.
+ *
+ * The loop is distinguished from a forward edge by its SHAPE, not by colour —
+ * a closed arc above the node, legible in greyscale and in every theme — and
+ * publishes that meaning as a real accessible name, because a `data-slot` is
+ * invisible to assistive technology. Its label is an `EdgeLabelPill` at the
+ * arc's apex, a genuine keyboard tab stop with a visible focus ring.
+ *
+ * Stroke width comes from the same `computeEdgeWeightScale` domain
+ * `FlowWeightedEdge` uses, so a loop weighted 8 reads as thick as a forward
+ * edge weighted 8. Nothing animates, so there is no motion to reduce.
+ *
+ * The arc is drawn through `FlowEdgePath`, so it inherits the shared keyboard
+ * focus indicator (#286) rather than having to opt into it.
+ */
+export function FlowSelfLoopEdge({
+  id,
+  source,
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  markerEnd,
+  style,
+  selected,
+  data,
+}: EdgeProps<BrandFlowSelfLoopEdge>) {
+  const edges = useEdges();
+  const widthByEdgeId = useMemo(
+    () => computeEdgeWeightScale(edges as unknown as WeightedEdgeLike[]),
+    [edges],
+  );
+  const node = useInternalNode(source);
+
+  const measuredWidth = node?.measured?.width;
+  const measuredHeight = node?.measured?.height;
+  const loopRadius = data?.loopRadius ?? DEFAULT_LOOP_RADIUS;
+
+  const { path, labelX, labelY } = useMemo(() => {
+    if (node && measuredWidth && measuredHeight) {
+      return selfLoopHandleArc(
+        {
+          sourceX,
+          sourceY,
+          targetX,
+          targetY,
+          centerX: node.internals.positionAbsolute.x + measuredWidth / 2,
+          centerY: node.internals.positionAbsolute.y + measuredHeight / 2,
+          width: measuredWidth,
+          height: measuredHeight,
+        },
+        loopRadius,
+      );
+    }
+    // Before measurement lands there is no box to clear, and the two handle points
+    // still bracket the node — draw the plain arc above them.
+    return selfLoopPath(
+      { centerX: (sourceX + targetX) / 2, topY: Math.min(sourceY, targetY) },
+      loopRadius,
+    );
+  }, [node, measuredWidth, measuredHeight, sourceX, sourceY, targetX, targetY, loopRadius]);
+
+  const scaledWidth = widthByEdgeId.get(id) ?? DEFAULT_EDGE_WIDTH_RANGE[0];
+  const stroke = selected ? "var(--ring)" : "var(--flow-edge)";
+  const strokeWidth = selected ? scaledWidth + 1.5 : scaledWidth;
+
+  const accessibleName =
+    data?.loopLabel ?? `Self-loop on ${nodeName(node?.data, source)} — this step repeats`;
+
+  return (
+    <>
+      <g role="img" aria-label={accessibleName}>
+        <FlowEdgePath
+          id={id}
+          path={path}
+          markerEnd={markerEnd}
+          data-slot="flow-self-loop-edge"
+          stroke={stroke}
+          strokeWidth={strokeWidth}
+          style={{ fill: "none", ...style }}
+        />
+      </g>
+      <EdgeLabelPill
+        label={data?.label}
+        secondaryLabel={data?.secondaryLabel}
+        x={labelX}
+        y={labelY}
+        selected={selected}
+        {...data?.labelProps}
+      />
+    </>
+  );
+}

package/src/flow-self-loop-edge/index.ts

@@ -0,0 +1,13 @@
+export {
+  FlowSelfLoopEdge,
+  type FlowSelfLoopEdgeData,
+  type BrandFlowSelfLoopEdge,
+} from "./flow-self-loop-edge";
+export {
+  selfLoopPath,
+  selfLoopHandleArc,
+  DEFAULT_LOOP_RADIUS,
+  type SelfLoopAnchor,
+  type SelfLoopHandleAnchor,
+  type SelfLoopPath,
+} from "./self-loop-geometry";

package/src/flow-self-loop-edge/self-loop-geometry.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_LOOP_RADIUS, selfLoopHandleArc, selfLoopPath } from "./self-loop-geometry";
+
+const numbersIn = (path: string) =>
+  (path.match(/-?\d+(\.\d+)?/g) ?? []).map((n) => Number.parseFloat(n));
+
+describe("selfLoopPath", () => {
+  it("leaves the node's top-right and re-enters at its top-left", () => {
+    const { path } = selfLoopPath({ centerX: 100, topY: 50 }, 28);
+    // M <start> C <c1> <c2> <end>
+    expect(path.startsWith("M 128,50 C ")).toBe(true);
+    expect(path.endsWith(" 72,50")).toBe(true);
+  });
+
+  it("anchors the label at the arc's apex, above the node and centred on it", () => {
+    const { labelX, labelY } = selfLoopPath({ centerX: 100, topY: 50 }, 28);
+    expect(labelX).toBe(100);
+    // 3/4 of the control reach (2.4r) — the midpoint of a symmetric cubic.
+    expect(labelY).toBeCloseTo(50 - 1.8 * 28, 6);
+    expect(labelY).toBeLessThan(50);
+  });
+
+  it("scales with loopRadius — a bigger radius reaches higher and wider", () => {
+    const small = selfLoopPath({ centerX: 0, topY: 0 }, 10);
+    const big = selfLoopPath({ centerX: 0, topY: 0 }, 40);
+    expect(big.labelY).toBeLessThan(small.labelY);
+    expect(Math.min(...numbersIn(big.path))).toBeLessThan(Math.min(...numbersIn(small.path)));
+  });
+
+  it("never emits NaN — non-finite anchors fall back to 0, bad radii to the default", () => {
+    for (const bad of [
+      selfLoopPath({ centerX: Number.NaN, topY: Number.NaN }, 28),
+      selfLoopPath({ centerX: 0, topY: 0 }, Number.NaN),
+      selfLoopPath({ centerX: 0, topY: 0 }, 0),
+      selfLoopPath({ centerX: 0, topY: 0 }, -5),
+    ]) {
+      expect(bad.path).not.toMatch(/NaN/);
+      expect(Number.isFinite(bad.labelX)).toBe(true);
+      expect(Number.isFinite(bad.labelY)).toBe(true);
+      for (const n of numbersIn(bad.path)) expect(Number.isFinite(n)).toBe(true);
+    }
+    // A zero/negative radius is treated as "use the default", not as "no loop".
+    expect(selfLoopPath({ centerX: 0, topY: 0 }, 0)).toEqual(
+      selfLoopPath({ centerX: 0, topY: 0 }, DEFAULT_LOOP_RADIUS),
+    );
+  });
+
+  it("is deterministic — the same input always yields the same path", () => {
+    expect(selfLoopPath({ centerX: 12.5, topY: -3 }, 28)).toEqual(
+      selfLoopPath({ centerX: 12.5, topY: -3 }, 28),
+    );
+  });
+});
+
+describe("selfLoopHandleArc", () => {
+  /** A 200×60 card at (100, 200): its two handle points, top-to-bottom. */
+  const topToBottom = {
+    sourceX: 200,
+    sourceY: 260,
+    targetX: 200,
+    targetY: 200,
+    centerX: 200,
+    centerY: 230,
+    width: 200,
+    height: 60,
+  };
+
+  it("starts on the source handle and ends on the target handle", () => {
+    const { path } = selfLoopHandleArc(topToBottom, 28);
+    expect(path).toMatch(/^M 200,260 C /);
+    expect(path).toMatch(/ 200,200$/);
+  });
+
+  it("bulges past the card, not across it", () => {
+    // The apex is the card's own half-width (100) plus the loop radius (28) clear of its
+    // centre — the number a cubic actually reaches, which is 3/4 of its control reach and
+    // not the control reach itself. Getting that factor wrong draws the loop ON the card.
+    const { labelX, labelY } = selfLoopHandleArc(topToBottom, 28);
+    expect(labelX).toBe(200 + 100 + 28);
+    expect(labelY).toBe(230);
+  });
+
+  it("turns with the handles: a left-to-right node loops over its top, not its side", () => {
+    // Same card, handles now on the right (source) and left (target).
+    const { labelX, labelY } = selfLoopHandleArc(
+      { ...topToBottom, sourceX: 300, sourceY: 230, targetX: 100, targetY: 230 },
+      28,
+    );
+    // Half the card's HEIGHT (30) plus the radius, above the centre — no direction prop
+    // was passed, and none exists: the bulge is derived from the handles themselves.
+    expect(labelX).toBe(200);
+    expect(labelY).toBe(230 - 30 - 28);
+  });
+
+  it("scales with loopRadius", () => {
+    const small = selfLoopHandleArc(topToBottom, 28);
+    const large = selfLoopHandleArc(topToBottom, 60);
+    expect(large.labelX - 200).toBeGreaterThan(small.labelX - 200);
+    expect(large.labelX).toBe(200 + 100 + 60);
+  });
+
+  it("never emits NaN — non-finite anchors fall back to 0, bad radii to the default", () => {
+    const { path, labelX, labelY } = selfLoopHandleArc(
+      {
+        sourceX: Number.NaN,
+        sourceY: Number.POSITIVE_INFINITY,
+        targetX: Number.NaN,
+        targetY: Number.NaN,
+        centerX: Number.NaN,
+        centerY: Number.NaN,
+        width: Number.NaN,
+        height: Number.NaN,
+      },
+      -5,
+    );
+    expect(path).not.toMatch(/NaN|Infinity/);
+    expect(Number.isFinite(labelX)).toBe(true);
+    expect(Number.isFinite(labelY)).toBe(true);
+  });
+
+  it("falls back to a downward normal when a handle sits on the node's centre", () => {
+    const degenerate = selfLoopHandleArc(
+      { ...topToBottom, sourceX: 200, sourceY: 230, targetX: 200, targetY: 230 },
+      28,
+    );
+    expect(degenerate.path).not.toMatch(/NaN/);
+  });
+});

package/src/flow-self-loop-edge/self-loop-geometry.ts

@@ -0,0 +1,165 @@
+/**
+ * self-loop-geometry — pure, framework-free arc math for a self-referencing edge.
+ *
+ * Kept out of the component (and out of React) so the loop's shape can be
+ * unit-tested without a canvas, and so a sibling that needs the same apex
+ * point (a legend, an overlay, a screenshot harness) can compute it directly.
+ */
+
+/** Default arc radius, in px. A loop this size clears `FlowNode`'s header without dominating it. */
+export const DEFAULT_LOOP_RADIUS = 28;
+
+/**
+ * How far the cubic's control points reach sideways and upwards, as multiples
+ * of `loopRadius`. Tuned so the arc reads as a closed loop rather than a bump:
+ * the horizontal reach opens the throat of the loop, the vertical reach sets
+ * its height.
+ */
+const CONTROL_REACH_X = 1.2;
+const CONTROL_REACH_Y = 2.4;
+/** A symmetric cubic's midpoint sits at 3/4 of its control-point height — see `selfLoopPath`. */
+const APEX_FACTOR = (3 / 4) * CONTROL_REACH_Y;
+
+/** The box a self-loop is drawn above. Matches a React Flow `InternalNode` structurally. */
+export interface SelfLoopAnchor {
+  /** Horizontal centre of the node the loop belongs to. */
+  centerX: number;
+  /** Top edge of that node — the loop is drawn above this line. */
+  topY: number;
+}
+
+export interface SelfLoopPath {
+  /** SVG `d` for the arc. */
+  path: string;
+  /** Where a label belongs: the arc's apex. */
+  labelX: number;
+  labelY: number;
+}
+
+/**
+ * A cubic arc that leaves the node's top-RIGHT, bulges up over the node, and
+ * re-enters at its top-LEFT — the conventional "this step repeated" mark in a
+ * process map, and a SHAPE rather than a colour, so it survives greyscale.
+ *
+ * The curve is symmetric about `centerX`, which puts its `t = 0.5` midpoint
+ * exactly at `(centerX, topY - APEX_FACTOR × loopRadius)` — the apex the label
+ * is anchored to. Never returns `NaN`: a non-finite input falls back to `0`
+ * and a non-positive radius falls back to the default.
+ */
+export function selfLoopPath(anchor: SelfLoopAnchor, loopRadius: number): SelfLoopPath {
+  const cx = Number.isFinite(anchor.centerX) ? anchor.centerX : 0;
+  const ay = Number.isFinite(anchor.topY) ? anchor.topY : 0;
+  const r = Number.isFinite(loopRadius) && loopRadius > 0 ? loopRadius : DEFAULT_LOOP_RADIUS;
+
+  const startX = cx + r;
+  const endX = cx - r;
+  const controlY = ay - r * CONTROL_REACH_Y;
+
+  return {
+    path: `M ${startX},${ay} C ${startX + r * CONTROL_REACH_X},${controlY} ${
+      endX - r * CONTROL_REACH_X
+    },${controlY} ${endX},${ay}`,
+    labelX: cx,
+    labelY: ay - r * APEX_FACTOR,
+  };
+}
+
+/**
+ * The two handle anchors a self-loop actually joins, plus the box it has to clear.
+ *
+ * A self-loop's `sourceX/sourceY` and `targetX/targetY` are the SAME node's two handle
+ * points, which is why they describe no useful straight line — but they are still the
+ * only two points on the canvas the reader recognises as connectors, so the arc has to
+ * start and end exactly on them. {@link selfLoopHandleArc} is the geometry that does
+ * that; {@link selfLoopPath} remains the node-box arc used before a node is measured.
+ */
+export interface SelfLoopHandleAnchor {
+  /** Where the loop leaves the node — React Flow's own SOURCE handle anchor. */
+  sourceX: number;
+  sourceY: number;
+  /** Where it re-enters — React Flow's own TARGET handle anchor. */
+  targetX: number;
+  targetY: number;
+  /** The node's centre. Decides which way is "out of the card". */
+  centerX: number;
+  centerY: number;
+  /** The node's rendered size, so the arc clears the card instead of crossing it. */
+  width: number;
+  height: number;
+}
+
+/** Unit vector from the node's centre to a handle point, or `fallback` when degenerate. */
+function outward(
+  x: number,
+  y: number,
+  centerX: number,
+  centerY: number,
+  fallback: readonly [number, number],
+): readonly [number, number] {
+  const dx = x - centerX;
+  const dy = y - centerY;
+  const length = Math.hypot(dx, dy);
+  if (!Number.isFinite(length) || length < 1e-6) return fallback;
+  return [dx / length, dy / length];
+}
+
+/**
+ * A cubic that leaves the SOURCE handle dot, bulges clear of the node on one side, and
+ * re-enters at the TARGET handle dot.
+ *
+ * It is direction-agnostic by construction: the bulge is the source normal rotated a
+ * quarter turn, so a top-to-bottom layout (handles on the bottom and top) gets a lasso
+ * down the node's right-hand side, and a left-to-right layout (handles on the right and
+ * left) gets an arc over the top — with no `direction` prop, and no list of cases to keep
+ * in step with `layoutFlow`'s `HANDLE_BY_DIRECTION`.
+ *
+ * `loopRadius` is how far the curve shoots straight out of each dot before it turns, and
+ * also the gap the arc's widest point keeps from the card's edge. The label sits at that
+ * widest point — the cubic's `t = 0.5` midpoint — so it is off the node by construction.
+ *
+ * Never returns `NaN`: non-finite inputs fall back to `0`, a non-positive radius to
+ * {@link DEFAULT_LOOP_RADIUS}, and a handle point sitting on the node's centre (nothing
+ * measured yet) to a downward source normal.
+ */
+export function selfLoopHandleArc(anchor: SelfLoopHandleAnchor, loopRadius: number): SelfLoopPath {
+  const num = (value: number) => (Number.isFinite(value) ? value : 0);
+  const sx = num(anchor.sourceX);
+  const sy = num(anchor.sourceY);
+  const tx = num(anchor.targetX);
+  const ty = num(anchor.targetY);
+  const cx = num(anchor.centerX);
+  const cy = num(anchor.centerY);
+  const width = Math.max(0, num(anchor.width));
+  const height = Math.max(0, num(anchor.height));
+  const r = Number.isFinite(loopRadius) && loopRadius > 0 ? loopRadius : DEFAULT_LOOP_RADIUS;
+
+  const [osx, osy] = outward(sx, sy, cx, cy, [0, 1]);
+  const [otx, oty] = outward(tx, ty, cx, cy, [-osx, -osy]);
+  // A quarter turn from the source normal: the side the loop bulges out on.
+  const lx = osy;
+  const ly = -osx;
+  // How far the card extends along the bulge, plus the clearance we want beyond it.
+  const clearance = Math.abs(lx) * (width / 2) + Math.abs(ly) * (height / 2) + r;
+  // A cubic reaches only 3/4 of the way to its control points at the midpoint — its
+  // WIDEST point — so `clearance` has to be divided by that factor, not used directly.
+  // Used directly (the first cut of this function did) the apex lands at 0.75 × clearance,
+  // which for a 176 px card is 87 px against an 88 px half-width: the loop is drawn ON the
+  // card it is supposed to encircle, and its label — anchored at that same midpoint —
+  // prints on top of the activity's own name. Measured on the process map: one collision
+  // per direction that no amount of layout spacing could remove, because the arc's reach
+  // is a property of the node it belongs to, not of the gap to its neighbours.
+  const reach = (4 / 3) * clearance;
+
+  const c1x = sx + osx * r + lx * reach;
+  const c1y = sy + osy * r + ly * reach;
+  const c2x = tx + otx * r + lx * reach;
+  const c2y = ty + oty * r + ly * reach;
+
+  return {
+    path: `M ${sx},${sy} C ${c1x},${c1y} ${c2x},${c2y} ${tx},${ty}`,
+    // A cubic's midpoint is (P0 + 3·C1 + 3·C2 + P3) / 8 — the arc's apex, which `reach`
+    // above places `loopRadius` clear of the card, so the label sits off the node.
+    labelX: (sx + 3 * c1x + 3 * c2x + tx) / 8,
+    labelY: (sy + 3 * c1y + 3 * c2y + ty) / 8,
+  };
+}

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);
+  },
 };