@elabs-ai/components-flow 4.0.0 → 4.2.0

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

@@ -0,0 +1,149 @@
+import type { CSSProperties, SVGProps } from "react";
+import { BaseEdge } from "@xyflow/react";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+/**
+ * Extra stroke width, in px, of the `--ring` band drawn around a focused edge.
+ * The band sits *outside* the edge's own stroke, so it is visible whatever the
+ * edge's resting width is.
+ */
+export const FLOW_EDGE_FOCUS_RING_WIDTH = 3;
+
+/**
+ * Extra stroke width, in px, of the neutral contour drawn outside the `--ring`
+ * band. This is the layer that carries the WCAG 1.4.11 bar: `--foreground`
+ * measures 12.50:1 against `--canvas` in `light` and 16.25:1 in `dark`, where
+ * `--ring` alone measures 1.30:1 in `light` (issue #286).
+ */
+export const FLOW_EDGE_FOCUS_CONTOUR_WIDTH = 6;
+
+export interface FlowEdgePathProps extends Omit<
+  SVGProps<SVGPathElement>,
+  "path" | "stroke" | "strokeWidth" | "style" | "ref"
+> {
+  /** SVG path `d` for this edge, from `getBezierPath`/`getSmoothStepPath`/… */
+  path: string;
+  /** Resting stroke paint — a `var(--token)` reference or a resolved colour. */
+  stroke: string;
+  /** Resting stroke width in px. The focus layers are drawn wider than this. */
+  strokeWidth: number;
+  /** Dash pattern, applied to the edge AND to both focus layers so a dashed edge keeps its shape when focused. */
+  strokeDasharray?: string;
+  /** Stroke opacity for the edge itself. Never applied to the focus layers. */
+  strokeOpacity?: number;
+  /** React Flow marker url, e.g. from `EdgeProps.markerEnd`. */
+  markerEnd?: string;
+  /** React Flow marker url, e.g. from `EdgeProps.markerStart`. */
+  markerStart?: string;
+  /** Width of the invisible pointer-target path React Flow draws over the edge. */
+  interactionWidth?: number;
+  /** Merged onto the edge path, last — so a consumer's `style.stroke` still wins. */
+  style?: CSSProperties;
+}
+
+/**
+ * The edge path every brand edge type draws, with the keyboard focus indicator
+ * built in. **Use this instead of React Flow's `BaseEdge`** — a custom edge that
+ * reaches for `BaseEdge` directly ships with no focus indicator at all, which is
+ * the defect issue #286 records (and `no-raw-base-edge.test.ts` fails on).
+ *
+ * ## Why the indicator is drawn rather than restyled
+ *
+ * React Flow zeroes the native outline on a focused edge
+ * (`.react-flow__edge:focus-visible { outline: none }`) and substitutes a stroke
+ * recolour on `.react-flow__edge-path`. Every brand edge passes its stroke as an
+ * **inline style** on that exact path — `BaseEdge` spreads `style` onto it — and
+ * an inline declaration beats any stylesheet rule, so the substitute never
+ * painted. Focusing an edge changed nothing on screen: WCAG 2.4.7 failed on
+ * every edge of every canvas, in both themes.
+ *
+ * The obvious repair — move the stroke into a custom property so a stylesheet
+ * rule can reach it — does **not** work here, and that was measured rather than
+ * assumed: React Flow's own `.react-flow__edge-path { stroke: … }` ships
+ * **unlayered**, and unlayered CSS outranks anything in `@layer utilities`,
+ * where Tailwind puts every utility. A `stroke-[var(--flow-edge-stroke)]` class
+ * would therefore lose to React Flow's `#b1b1b7` default and repaint every edge
+ * in the library. `!important` and setting `--xy-edge-stroke-selected` were both
+ * rejected in the issue.
+ *
+ * So the indicator is drawn on two paths this component owns, under the edge and
+ * on the same geometry. Nothing can shadow them: not React Flow's stylesheet,
+ * not a consumer's inline `style.stroke`, not a future edge type's own painting.
+ * They are hidden (`opacity-0`) until the ancestor `g.react-flow__edge` matches
+ * `:focus-visible`, which is a plain descendant selector on classes only this
+ * component uses.
+ *
+ * ## Compound, because one colour is not enough
+ *
+ * The indicator is two layers, per the compound-indicator recipe in
+ * `.claude/rules/theming.md`: a neutral `--foreground` contour at
+ * `strokeWidth + 6`, and the `--ring` band at `strokeWidth + 3` over it. The
+ * contour is the layer that clears WCAG 1.4.11's 3:1 bar against `--canvas` in
+ * both reference themes (12.50:1 `light`, 16.25:1 `dark`); a bare `--ring`
+ * stroke would not (1.30:1 in `light`). It is opacity + stroke only — no
+ * shadow — so it survives `data-decoration="8|9|10"`, which goes shadowless.
+ */
+export function FlowEdgePath({
+  path,
+  stroke,
+  strokeWidth,
+  strokeDasharray,
+  strokeOpacity,
+  markerEnd,
+  markerStart,
+  interactionWidth,
+  className,
+  style,
+  ...props
+}: FlowEdgePathProps) {
+  // The focus layers repeat the edge's own dash pattern so a dashed edge (the
+  // `"back"` variant) does not gain a solid halo. `"none"` is explicit rather
+  // than omitted because React Flow's `.react-flow__edge.animated path` rule
+  // sets a dasharray on *every* path inside an animated edge, ours included.
+  const focusDash = strokeDasharray ?? "none";
+
+  return (
+    <>
+      {/* Outer neutral contour — the layer that carries the 3:1 bar. */}
+      <path
+        d={path}
+        fill="none"
+        aria-hidden="true"
+        data-slot="flow-edge-focus-contour"
+        className="pointer-events-none stroke-foreground opacity-0 [.react-flow\_\_edge:focus-visible_&]:opacity-100"
+        strokeWidth={strokeWidth + FLOW_EDGE_FOCUS_CONTOUR_WIDTH}
+        strokeDasharray={focusDash}
+        strokeLinecap="round"
+      />
+      {/* Inner --ring band, drawn over the contour and under the edge. */}
+      <path
+        d={path}
+        fill="none"
+        aria-hidden="true"
+        data-slot="flow-edge-focus-ring"
+        className="pointer-events-none stroke-ring opacity-0 [.react-flow\_\_edge:focus-visible_&]:opacity-100"
+        strokeWidth={strokeWidth + FLOW_EDGE_FOCUS_RING_WIDTH}
+        strokeDasharray={focusDash}
+        strokeLinecap="round"
+      />
+      <BaseEdge
+        {...props}
+        path={path}
+        markerEnd={markerEnd}
+        markerStart={markerStart}
+        interactionWidth={interactionWidth}
+        className={cn(
+          "transition-[stroke,stroke-width] duration-fast ease-standard motion-reduce:transition-none",
+          className,
+        )}
+        style={{
+          stroke,
+          strokeWidth,
+          ...(strokeDasharray ? { strokeDasharray } : null),
+          ...(strokeOpacity !== undefined ? { strokeOpacity } : null),
+          ...style,
+        }}
+      />
+    </>
+  );
+}

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

@@ -0,0 +1 @@
+export * from "./flow-edge-path";

package/src/flow-edge-path/no-raw-base-edge.test.ts

@@ -0,0 +1,45 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+/**
+ * #286 tripwire. React Flow's `BaseEdge` ships with a focus indicator that any
+ * inline `stroke` silently disables — which is how every brand edge in this
+ * package came to have no keyboard focus indicator at all. `FlowEdgePath` is
+ * the repair, and this test is what stops the next edge type from reaching past
+ * it: a custom edge that imports `BaseEdge` directly is, by construction, an
+ * edge with no focus indicator.
+ *
+ * A component that genuinely needs the primitive can extend `FlowEdgePath`
+ * instead — that is the one place the import is allowed.
+ */
+// The jsdom environment gives `import.meta.url` an http: scheme, so resolve
+// from the Vitest root (this package) instead.
+const SRC = join(process.cwd(), "src");
+const ALLOWED = new Set(["flow-edge-path/flow-edge-path.tsx"]);
+
+function walk(dir: string, prefix = ""): string[] {
+  return readdirSync(dir).flatMap((entry) => {
+    const abs = join(dir, entry);
+    const rel = prefix ? `${prefix}/${entry}` : entry;
+    if (statSync(abs).isDirectory()) return walk(abs, rel);
+    if (!/\.tsx?$/.test(entry) || /\.(test|stories)\.tsx?$/.test(entry)) return [];
+    return [rel];
+  });
+}
+
+describe("no edge type reaches past FlowEdgePath (#286)", () => {
+  it("imports BaseEdge from @xyflow/react in exactly one shipped module", () => {
+    const offenders = walk(SRC).filter((rel) => {
+      if (ALLOWED.has(rel)) return false;
+      const source = readFileSync(join(SRC, rel), "utf8");
+      // Only an IMPORT counts — prose mentioning the name in a doc comment does not.
+      return /import\s+[^;]*\bBaseEdge\b[^;]*from\s+["']@xyflow\/react["']/s.test(source);
+    });
+    expect(
+      offenders,
+      `These modules import React Flow's BaseEdge directly, so their edges have no keyboard ` +
+        `focus indicator (#286). Draw through FlowEdgePath instead: ${offenders.join(", ")}`,
+    ).toEqual([]);
+  });
+});

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

@@ -1,4 +1,5 @@
-import { BaseEdge, getBezierPath, useInternalNode, type EdgeProps } from "@xyflow/react";
+import { getBezierPath, useInternalNode, type EdgeProps } from "@xyflow/react";
+import { FlowEdgePath } from "../flow-edge-path";
 import { getEdgeParams } from "./floating-edge-geometry";
 
 /** Optional per-edge `data` for {@link FlowFloatingEdge}. */
@@ -45,11 +46,14 @@ export function FlowFloatingEdge({ id, source, target, markerEnd, style, data }:
 
   return (
     <>
-      <BaseEdge
+      <FlowEdgePath
         id={id}
         path={edgePath}
         markerEnd={markerEnd}
-        style={{ stroke: "var(--flow-edge)", strokeWidth: 1.5, ...style }}
+        data-slot="flow-floating-edge"
+        stroke="var(--flow-edge)"
+        strokeWidth={1.5}
+        style={style}
       />
       {showAnchors ? (
         <g

package/src/flow-group-node/flow-group-node.stories.tsx

@@ -11,7 +11,7 @@ import { FlowGroupNode } from "./flow-group-node";
 const nodeTypes = { brand: FlowNode, group: FlowGroupNode };
 
 const toolbarButton =
-  "rounded-md border border-input bg-surface-elevated px-3 py-1.5 text-body shadow-sm hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50";
+  "rounded-md border border-input bg-surface-elevated px-3 py-1.5 text-body shadow-sm hover:bg-accent focus-ring disabled:opacity-50";
 
 const meta = {
   title: "Flow/FlowGroupNode",

package/src/flow-group-node/flow-group-node.tsx

@@ -3,6 +3,7 @@ import { Handle, NodeResizer, Position, useNodes, type Node, type NodeProps } fr
 import { ChevronDown, ChevronRight } from "lucide-react";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { useFlowGroups } from "../use-flow-groups";
+import { FLOW_HANDLE_ANCHOR_CLASS } from "../flow-handle/flow-handle-anchor";
 
 /** Visual accent for a group container. */
 export type FlowGroupTone = "default" | "accent" | "success" | "warning" | "destructive";
@@ -29,18 +30,33 @@ export interface FlowGroupNodeData extends Record<string, unknown> {
 
 export type BrandFlowGroupNode = Node<FlowGroupNodeData, "group">;
 
-const toneAccent: Record<FlowGroupTone, string> = {
+// #124 split this map in two: it used to serve both the icon slot (a MARK,
+// >=3:1) and the child-count text badge (running text, >=4.5:1) from one set
+// of values, which is exactly the fill-rung-as-text shape #124 fixes
+// elsewhere. `accent` is unchanged (`#399` already put it on the ink rung for
+// both slots — legal, since the ink rung clears the 3:1 mark bar trivially).
+
+/** Icon-slot tone (the leading glyph next to the title) — the 3:1 mark rung. */
+const toneMark: Record<FlowGroupTone, string> = {
   default: "text-muted-foreground",
-  // #399 — the group LABEL is text on the canvas, so it takes the on-surface
-  // `-text` rung. (The status rows below stay on their fill rungs; those are a
-  // separate, still-open question, not part of #399's enumerated call sites.)
   accent: "text-primary-text",
   success: "text-success",
   warning: "text-warning",
   destructive: "text-destructive",
 };
 
-const handleClassName = "!size-2 !border-2 !border-flow-group-border !bg-flow-group";
+/** Child-count badge tone — running text, so it takes the >=4.5:1 ink rung. */
+const toneInk: Record<FlowGroupTone, string> = {
+  default: "text-muted-foreground",
+  accent: "text-primary-text",
+  success: "text-success-text",
+  warning: "text-warning-text",
+  destructive: "text-destructive-text",
+};
+
+// `FLOW_HANDLE_ANCHOR_CLASS` last: a connector dot must never be in flight when React
+// Flow measures it. See `flow-handle/flow-handle-anchor.ts`.
+const handleClassName = `!size-2 !border-2 !border-flow-group-border !bg-flow-group ${FLOW_HANDLE_ANCHOR_CLASS}`;
 
 /**
  * Branded group container node. Register it as `nodeTypes={{ group: FlowGroupNode }}`
@@ -103,7 +119,7 @@ export function FlowGroupNode({ id, data, selected }: NodeProps<BrandFlowGroupNo
           className={cn(
             "-ml-1 grid size-5 shrink-0 place-items-center rounded",
             "text-muted-foreground hover:bg-muted hover:text-foreground",
-            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            "focus-ring",
           )}
         >
           {collapsed ? (
@@ -114,7 +130,7 @@ export function FlowGroupNode({ id, data, selected }: NodeProps<BrandFlowGroupNo
         </button>
 
         {data.icon ? (
-          <span className={cn("[&_svg]:size-4", toneAccent[tone])}>{data.icon}</span>
+          <span className={cn("[&_svg]:size-4", toneMark[tone])}>{data.icon}</span>
         ) : null}
 
         <span className="min-w-0 flex-1 truncate text-body font-medium">{data.title}</span>
@@ -122,7 +138,7 @@ export function FlowGroupNode({ id, data, selected }: NodeProps<BrandFlowGroupNo
         <span
           className={cn(
             "shrink-0 rounded-full bg-muted px-1.5 py-0.5 text-meta font-medium tabular-nums",
-            toneAccent[tone],
+            toneInk[tone],
           )}
           aria-label={`${childCount} ${childCount === 1 ? "node" : "nodes"}`}
         >

package/src/flow-handle/flow-handle-anchor.test.tsx

@@ -0,0 +1,97 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * The engine is mocked so the handle's CLASS LIST is observable in jsdom, which has no
+ * layout and therefore cannot reproduce the defect itself. The real lock on the picture
+ * is `Process/ProcessMap > Left To Right`, a Chromium story test that measures every
+ * edge endpoint against the dot it should terminate on; this file locks the mechanism
+ * that story exposed — a connector dot that carries no transition, so it is never in
+ * flight when React Flow measures `handleBounds`.
+ */
+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 {
+    Handle: ({ type, className }: { type: string; className?: string }) =>
+      React.createElement("div", { "data-testid": `handle-${type}`, className }),
+    NodeResizer: () => React.createElement("div", { "data-testid": "node-resizer" }),
+    Position: { Top: "top", Bottom: "bottom", Left: "left", Right: "right" },
+    useNodes: () => [] as unknown[],
+    useReactFlow: () => ({
+      getNodes: () => [],
+      getEdges: () => [],
+      setNodes: () => {},
+      setEdges: () => {},
+    }),
+    getNodesBounds: () => ({ x: 0, y: 0, width: 0, height: 0 }),
+  };
+});
+
+import type { Node, NodeProps } from "@xyflow/react";
+import { FlowGroupNode, type BrandFlowGroupNode } from "../flow-group-node/flow-group-node";
+import { FlowNode, type BrandFlowNode } from "../flow-node/flow-node";
+import {
+  FlowPlaceholderNode,
+  type BrandFlowPlaceholderNode,
+} from "../flow-placeholder-node/flow-placeholder-node";
+import { FLOW_HANDLE_ANCHOR_CLASS } from "./flow-handle-anchor";
+
+afterEach(cleanup);
+
+function makeProps<NodeType extends Node>(id: string, data: NodeType["data"]): NodeProps<NodeType> {
+  return {
+    id,
+    data,
+    selected: false,
+    dragging: false,
+    zIndex: 0,
+    isConnectable: true,
+    draggable: true,
+    deletable: true,
+    selectable: true,
+    positionAbsoluteX: 0,
+    positionAbsoluteY: 0,
+    width: 160,
+    height: 48,
+    type: "brand",
+  } as NodeProps<NodeType>;
+}
+
+describe("FLOW_HANDLE_ANCHOR_CLASS", () => {
+  it("switches transitions off rather than shortening them", () => {
+    // A duration is not enough: the tokens reduced-motion backstop already forces
+    // `transition-duration: 0.01ms !important` on every element, and it is that
+    // one-frame transition — on `transition-property: all` — which the handle has to
+    // be out of. Only `transition-property: none` takes a dot out of it.
+    expect(FLOW_HANDLE_ANCHOR_CLASS).toBe("transition-none");
+  });
+
+  it.each([
+    [
+      "FlowNode",
+      () => render(<FlowNode {...makeProps<BrandFlowNode>("node", { title: "Node" })} />),
+    ],
+    [
+      "FlowGroupNode",
+      () =>
+        render(<FlowGroupNode {...makeProps<BrandFlowGroupNode>("group", { title: "Group" })} />),
+    ],
+    [
+      "FlowPlaceholderNode",
+      () =>
+        render(
+          <FlowPlaceholderNode
+            {...makeProps<BrandFlowPlaceholderNode>("placeholder", { label: "Add node" })}
+          />,
+        ),
+    ],
+  ])("%s renders every handle as a static anchor", (_name, renderNode) => {
+    renderNode();
+    const handles = screen.getAllByTestId(/^handle-/);
+    expect(handles.length).toBeGreaterThan(0);
+    for (const handle of handles) {
+      expect(handle.className.split(/\s+/)).toContain(FLOW_HANDLE_ANCHOR_CLASS);
+    }
+  });
+});

package/src/flow-handle/flow-handle-anchor.ts

@@ -0,0 +1,36 @@
+/**
+ * The class every React Flow `<Handle>` in this package carries — and the one a
+ * consumer's own custom node must carry too.
+ *
+ * A connector dot is a MEASUREMENT ANCHOR, not a moving part. React Flow measures
+ * `handleBounds` from the DOM exactly once per layout change (`updateNodeInternals`,
+ * fired from the effect that sees `sourcePosition`/`targetPosition` change) and then
+ * draws every edge endpoint from that stored number until something invalidates it.
+ * So a dot that is still ON ITS WAY to its new side when that measurement is taken is
+ * measured at the wrong place — permanently, because nothing measures again.
+ *
+ * That is not hypothetical, and it is not only about author-written transitions:
+ *
+ * - `@elabs-ai/components-tokens`' reduced-motion backstop (`themes.css`, MOTION GATE)
+ *   sets `transition-duration: 0.01ms !important` on `*` so third-party engines that
+ *   ignore the `--t-*` tokens (Monaco, `@xyflow/react`, Streamdown) cannot animate.
+ *   `transition-property` is left at its initial value, `all` — so under
+ *   `prefers-reduced-motion: reduce` that rule does not remove a transition from a
+ *   handle, it CREATES one: every geometric property of every element becomes
+ *   transitioned, for one frame.
+ * - One frame is all it takes. Measured on `ProcessMap direction="LR"`: at the commit
+ *   that flips the handles from top/bottom to left/right, the dot's computed box was
+ *   still the OLD one (`getAnimations()` on it returned live `left`+`top`+`transform`
+ *   transitions), React Flow measured `{ x: 164, y: 45.5 }` where the settled DOM has
+ *   `{ x: 172, y: 37.5 }`, and every edge on the map then terminated up to 67 px away
+ *   from the dot it points at — for reduced-motion readers only, forever.
+ *
+ * `transition-property: none` is the fix at the right layer: it costs nothing under
+ * normal motion (no rule animates a handle there anyway) and it makes the reposition
+ * synchronous, so whenever React Flow measures, it measures the settled dot.
+ *
+ * The literal is written out here rather than assembled, because Tailwind extracts
+ * candidates from source TEXT: this file is scanned, so the utility is emitted, and
+ * components may interpolate the constant freely.
+ */
+export const FLOW_HANDLE_ANCHOR_CLASS = "transition-none";

package/src/flow-handle/index.ts

@@ -0,0 +1 @@
+export { FLOW_HANDLE_ANCHOR_CLASS } from "./flow-handle-anchor";

package/src/flow-layout/flow-layout.stories.tsx

@@ -65,7 +65,7 @@ function AutoLayoutButton({ direction }: { direction: FlowLayoutDirection }) {
       type="button"
       disabled={layouting}
       onClick={() => layout(direction)}
-      className="rounded-md border border-input bg-surface-elevated px-3 py-1.5 text-body shadow-sm hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+      className="rounded-md border border-input bg-surface-elevated px-3 py-1.5 text-body shadow-sm hover:bg-accent focus-ring disabled:opacity-50"
     >
       Auto layout ({direction === "TB" ? "top → bottom" : "left → right"})
     </button>
@@ -127,7 +127,7 @@ function AutoLayoutGraphButton({ algorithm }: { algorithm: LayoutAlgorithm }) {
       type="button"
       disabled={layouting}
       onClick={handleClick}
-      className="rounded-md border border-input bg-surface-elevated px-3 py-1.5 text-body shadow-sm hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+      className="rounded-md border border-input bg-surface-elevated px-3 py-1.5 text-body shadow-sm hover:bg-accent focus-ring disabled:opacity-50"
     >
       Auto layout ({ALGORITHM_LABEL[algorithm]})
     </button>

package/src/flow-layout/flow-layout.test.tsx

@@ -130,4 +130,95 @@ describe("layoutFlow", () => {
     const wideGap = wide.nodes[1]!.position.y - wide.nodes[0]!.position.y;
     expect(wideGap).toBeGreaterThan(tightGap);
   });
+  describe("back edges and self-loops (RM-044)", () => {
+    /** The canonical rework fixture: A → B → C, C loops back to B, and B repeats itself. */
+    function reworkGraph(): { nodes: Node[]; edges: Edge[] } {
+      return {
+        nodes: chainNodes(),
+        edges: [
+          { id: "e-ab", source: "a", target: "b" },
+          { id: "e-bc", source: "b", target: "c" },
+          { id: "e-cb", source: "c", target: "b" },
+          { id: "e-bb", source: "b", target: "b" },
+        ],
+      };
+    }
+
+    it("reports the reversed edge in backEdges and the self-loop in selfLoops", () => {
+      const { nodes, edges } = reworkGraph();
+      const result = layoutFlow(nodes, edges);
+
+      expect(result.backEdges).toEqual(["e-cb"]);
+      expect(result.selfLoops).toEqual(["e-bb"]);
+      // Both classifications are disjoint — a self-loop is never a back edge.
+      expect(result.backEdges).not.toContain("e-bb");
+    });
+
+    it("keeps the self-loop out of the rank computation", () => {
+      const { nodes, edges } = reworkGraph();
+      const withLoop = layoutFlow(nodes, edges);
+      const withoutLoop = layoutFlow(
+        nodes,
+        edges.filter((e) => e.id !== "e-bb"),
+      );
+
+      // Identical positions: the loop contributed nothing to the layout.
+      expect(withLoop.nodes.map((n) => n.position)).toEqual(
+        withoutLoop.nodes.map((n) => n.position),
+      );
+    });
+
+    it("returns every edge untouched, self-loops included", () => {
+      const { nodes, edges } = reworkGraph();
+      const result = layoutFlow(nodes, edges);
+      expect(result.edges).toBe(edges);
+      expect(result.edges.map((e) => e.id)).toContain("e-bb");
+    });
+
+    it("produces no NaN position on the rework fixture", () => {
+      const { nodes, edges } = reworkGraph();
+      for (const n of layoutFlow(nodes, edges).nodes) {
+        expect(Number.isFinite(n.position.x)).toBe(true);
+        expect(Number.isFinite(n.position.y)).toBe(true);
+      }
+    });
+
+    it("classifies the same edge as a back edge in every direction", () => {
+      const { nodes, edges } = reworkGraph();
+      for (const direction of ["TB", "BT", "LR", "RL"] as const) {
+        expect(layoutFlow(nodes, edges, { direction }).backEdges).toEqual(["e-cb"]);
+      }
+    });
+
+    it("reports nothing for an acyclic, loop-free graph", () => {
+      const result = layoutFlow(chainNodes(), chainEdges());
+      expect(result.backEdges).toEqual([]);
+      expect(result.selfLoops).toEqual([]);
+    });
+
+    it("counts a same-rank edge as a back edge — it does not advance the process", () => {
+      const nodes: Node[] = [
+        { id: "a", position: { x: 0, y: 0 }, data: {} },
+        { id: "b", position: { x: 0, y: 0 }, data: {} },
+      ];
+      // Two mutually-referencing nodes: dagre has to break the cycle somewhere.
+      const result = layoutFlow(nodes, [
+        { id: "e-ab", source: "a", target: "b" },
+        { id: "e-ba", source: "b", target: "a" },
+      ]);
+      expect(result.backEdges).toEqual(["e-ba"]);
+    });
+
+    it("pins node positions on the rework fixture (regression snapshot)", () => {
+      const { nodes, edges } = reworkGraph();
+      const positions = Object.fromEntries(
+        layoutFlow(nodes, edges).nodes.map((n) => [n.id, n.position]),
+      );
+      expect(positions).toEqual({
+        a: { x: 0, y: 0 },
+        b: { x: 0, y: 112 },
+        c: { x: 0, y: 224 },
+      });
+    });
+  });
 });