@elabs-ai/components-flow 4.0.0 → 4.1.0

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

@@ -0,0 +1,196 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// @xyflow/react needs real layout/measurement — mock the engine and assert the
+// brand component's own output, the same way `flow-weighted-edge.test.tsx`
+// does. Real rendering + a11y are covered by the Storybook interaction tests.
+//
+// `vi.mock`'s factory is hoisted above every import, so the mock state lives in
+// `vi.hoisted` to survive the hoist without a TDZ ReferenceError.
+const { edgesBox, internalNodeBox } = vi.hoisted(() => ({
+  edgesBox: { current: [] as unknown[] },
+  internalNodeBox: { current: null as unknown },
+}));
+
+vi.mock("@xyflow/react", () => {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports -- a vi.mock factory is hoisted above imports; a lazy require avoids the TDZ a top-level import would hit
+  const React = require("react");
+  return {
+    BaseEdge: ({
+      id,
+      path,
+      style,
+      className,
+      ...rest
+    }: {
+      id: string;
+      path: string;
+      style?: React.CSSProperties;
+      className?: string;
+    }) =>
+      React.createElement("svg", { "data-testid": "base-edge" }, [
+        React.createElement("path", { key: "p", d: path, id, style, className, ...rest }),
+      ]),
+    // Real EdgeLabelRenderer portals into a fixed container; a passthrough is
+    // enough here since we only assert the brand component's own output.
+    EdgeLabelRenderer: ({ children }: { children: React.ReactNode }) => children,
+    useEdges: () => edgesBox.current,
+    useInternalNode: () => internalNodeBox.current,
+    Position: { Top: "top", Bottom: "bottom", Left: "left", Right: "right" },
+  };
+});
+
+import type { EdgeProps } from "@xyflow/react";
+import { FlowSelfLoopEdge, type BrandFlowSelfLoopEdge } from "./flow-self-loop-edge";
+import { selfLoopHandleArc, selfLoopPath } from "./self-loop-geometry";
+
+afterEach(() => {
+  cleanup();
+  edgesBox.current = [];
+  internalNodeBox.current = null;
+});
+
+/** A measured `InternalNode` stand-in: 200×60 box whose top-left is (100, 200). */
+function measuredNode(data: unknown = { title: "Review" }) {
+  return {
+    id: "node-a",
+    data,
+    measured: { width: 200, height: 60 },
+    internals: { positionAbsolute: { x: 100, y: 200 } },
+  };
+}
+
+function makeEdgeProps(
+  overrides: Partial<EdgeProps<BrandFlowSelfLoopEdge>> = {},
+): EdgeProps<BrandFlowSelfLoopEdge> {
+  return {
+    id: "loop-1",
+    type: "self-loop",
+    source: "node-a",
+    target: "node-a",
+    sourceX: 200,
+    sourceY: 260,
+    targetX: 200,
+    targetY: 200,
+    sourcePosition: "bottom" as EdgeProps["sourcePosition"],
+    targetPosition: "top" as EdgeProps["targetPosition"],
+    selected: false,
+    animated: false,
+    data: {},
+    ...overrides,
+  };
+}
+
+const edgePath = () => screen.getByTestId("base-edge").querySelector("path")!;
+
+/**
+ * The arc the fixture should produce: the 200×60 card at (100, 200), entered and left at
+ * the two handle points `makeEdgeProps` supplies.
+ */
+const fixtureArc = (loopRadius = 28) =>
+  selfLoopHandleArc(
+    {
+      sourceX: 200,
+      sourceY: 260,
+      targetX: 200,
+      targetY: 200,
+      centerX: 200,
+      centerY: 230,
+      width: 200,
+      height: 60,
+    },
+    loopRadius,
+  );
+
+describe("FlowSelfLoopEdge", () => {
+  it("starts and ends ON the two handle points, clearing the measured box between them", () => {
+    internalNodeBox.current = measuredNode();
+    render(<FlowSelfLoopEdge {...makeEdgeProps()} />);
+    expect(edgePath()).toHaveAttribute("d", fixtureArc().path);
+  });
+
+  it("falls back to the handle midpoint before the node is measured — never NaN", () => {
+    internalNodeBox.current = { ...measuredNode(), measured: { width: 0, height: 0 } };
+    render(<FlowSelfLoopEdge {...makeEdgeProps()} />);
+    const d = edgePath().getAttribute("d")!;
+    expect(d).not.toMatch(/NaN/);
+    expect(d).toBe(selfLoopPath({ centerX: 200, topY: 200 }, 28).path);
+  });
+
+  it("honours data.loopRadius", () => {
+    internalNodeBox.current = measuredNode();
+    render(<FlowSelfLoopEdge {...makeEdgeProps({ data: { loopRadius: 60 } })} />);
+    expect(edgePath()).toHaveAttribute("d", fixtureArc(60).path);
+  });
+
+  it("carries its meaning as real text for assistive tech, not only a data attribute", () => {
+    internalNodeBox.current = measuredNode();
+    render(<FlowSelfLoopEdge {...makeEdgeProps()} />);
+    const graphic = screen.getByRole("img", {
+      name: "Self-loop on Review — this step repeats",
+    });
+    expect(graphic).toBeInTheDocument();
+    // The data-slot is the test/styling seam, NOT the accessibility channel.
+    expect(graphic.querySelector('[data-slot="flow-self-loop-edge"]')).not.toBeNull();
+  });
+
+  it("names the node by id when its data carries no title, and accepts an override", () => {
+    internalNodeBox.current = measuredNode({});
+    const { unmount } = render(<FlowSelfLoopEdge {...makeEdgeProps()} />);
+    expect(
+      screen.getByRole("img", { name: "Self-loop on node-a — this step repeats" }),
+    ).toBeInTheDocument();
+    unmount();
+
+    internalNodeBox.current = measuredNode();
+    render(<FlowSelfLoopEdge {...makeEdgeProps({ data: { loopLabel: "Reworked 12 times" } })} />);
+    expect(screen.getByRole("img", { name: "Reworked 12 times" })).toBeInTheDocument();
+  });
+
+  it("is distinguishable from a forward edge without colour — the shape is the signal", () => {
+    internalNodeBox.current = measuredNode();
+    render(<FlowSelfLoopEdge {...makeEdgeProps()} />);
+    const path = edgePath();
+    // A cubic that returns to its own node: it leaves the bottom handle (200, 260) and
+    // re-enters at the top one (200, 200) — the two ends bracket the card rather than
+    // spanning a gap, which is what no forward edge ever does.
+    expect(path.getAttribute("d")).toMatch(/^M 200,260 C .* 200,200$/);
+    expect(path.style.stroke).toBe("var(--flow-edge)");
+    expect(path.style.fill).toBe("none");
+  });
+
+  it("shares one weight scale with the forward edges around it", () => {
+    internalNodeBox.current = measuredNode();
+    edgesBox.current = [
+      { id: "fwd-min", data: { weight: 1 } },
+      { id: "loop-1", data: { weight: 10 } },
+      { id: "fwd-mid", data: { weight: 5 } },
+    ];
+    render(<FlowSelfLoopEdge {...makeEdgeProps({ data: { weight: 10 } })} />);
+    // Top of the shared [1.5, 8] range, because it is the heaviest edge present.
+    expect(edgePath().style.strokeWidth).toBe("8");
+  });
+
+  it("uses the --ring token when selected, matching FlowNode's selected treatment", () => {
+    internalNodeBox.current = measuredNode();
+    render(<FlowSelfLoopEdge {...makeEdgeProps({ selected: true })} />);
+    expect(edgePath().style.stroke).toBe("var(--ring)");
+  });
+
+  it("renders an EdgeLabelPill at the apex when labelled, and none when not", () => {
+    internalNodeBox.current = measuredNode();
+    const { unmount } = render(<FlowSelfLoopEdge {...makeEdgeProps()} />);
+    expect(screen.queryByRole("button")).toBeNull();
+    unmount();
+
+    render(
+      <FlowSelfLoopEdge {...makeEdgeProps({ data: { label: "12×", secondaryLabel: "2.1d" } })} />,
+    );
+    const pill = screen.getByRole("button", { name: "12× · 2.1d" });
+    // The arc's widest point: 328 is the card's right edge (300) plus the 28px loop
+    // radius, and 230 is the card's own vertical centre — i.e. beside the node, not on it.
+    const { labelX, labelY } = fixtureArc();
+    expect([labelX, labelY]).toEqual([328, 230]);
+    expect(pill.parentElement!.style.transform).toContain(`translate(${labelX}px, ${labelY}px)`);
+  });
+});

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