@elabs-ai/components-flow 4.0.0 → 4.1.0

package/src/flow-mini-map/flow-mini-map.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import "@xyflow/react/dist/style.css";
+import { expect, waitFor } from "storybook/test";
 import { CanvasShell } from "../canvas-shell";
 import { FlowNode, FLOW_ALL_SIDE_HANDLES, type BrandFlowNode } from "../flow-node";
 import { FlowSmartEdge } from "../flow-smart-edge";
@@ -71,4 +72,89 @@ export const Default: Story = {
       </CanvasShell>
     </div>
   ),
+  /**
+   * The minimap must actually DRAW the nodes — this story rendered a blank white panel
+   * for as long as it has existed, and nothing caught it: React Flow's `<MiniMap>` reads
+   * each node's dimensions off the object the CONSUMER passed (`internals.userNode`), and
+   * bails out per node when they are absent. On a controlled canvas with no
+   * `onNodesChange` applying React Flow's own `dimensions` changes back, they always were.
+   * `CanvasShell` now merges the measurements in (`useMeasuredNodes`), so the count below
+   * is the honest proof — asserting the `<svg>` merely exists passes on the broken state.
+   *
+   * The count alone is not the whole issue (#363): its second hypothesis was a
+   * `nodeColor`/`nodeStrokeColor` token resolving to nothing, which paints the same
+   * rects INVISIBLY rather than omitting them — a count-only assertion would pass on
+   * that failure too. So this also resolves the rect's actual painted fill against the
+   * panel's actual painted background and demands real contrast, at the FILL-rung floor
+   * this repo already holds status marks to (`styling-and-tokens.md`). Same
+   * canvas-readback pattern `FlowNode`'s `FocusIndicator` / `FlowWeightedEdge`'s
+   * `KeyboardFocus` locks use to turn a CSS colour string (`oklch()` included) into a
+   * real measurement instead of an assumption.
+   */
+  play: async ({ canvasElement }) => {
+    let minimap!: HTMLElement;
+    await waitFor(() => {
+      const el = canvasElement.querySelector<HTMLElement>(".react-flow__minimap");
+      expect(el).toBeTruthy();
+      expect(el!.querySelectorAll(".react-flow__minimap-node")).toHaveLength(nodes.length);
+      // The viewport mask is derived from the transform, not from node geometry — it
+      // never broke, but the fix for this issue touches nothing about it either, so
+      // this pins it as unchanged rather than leaving it unasserted.
+      expect(el!.querySelector(".react-flow__minimap-mask")).toBeTruthy();
+      minimap = el!;
+    });
+
+    // `getImageData()` reports straight (non-premultiplied) RGBA — the alpha channel is
+    // real, but reading r/g/b alone discards it: a fully transparent fill (alpha 0) still
+    // returns SOME rgb triple (typically 0,0,0), which can measure as opaque black and pass
+    // contrast against a light panel while nothing is actually painted. Compositing the
+    // fill ON TOP OF the real panel background first — the same source-over the browser
+    // performs when it paints the rect — means a zero-alpha fill reads back AS the panel
+    // background, so it can never clear the threshold below (#409 review).
+    const toSrgbOverBackground = (colour: string, background: string): [number, number, number] => {
+      const surface = document.createElement("canvas");
+      surface.width = 1;
+      surface.height = 1;
+      const ctx = surface.getContext("2d")!;
+      ctx.fillStyle = background;
+      ctx.fillRect(0, 0, 1, 1);
+      ctx.fillStyle = colour;
+      ctx.fillRect(0, 0, 1, 1);
+      const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+      return [r! / 255, g! / 255, b! / 255];
+    };
+    const luminance = ([r, g, b]: [number, number, number]) => {
+      const lin = (v: number) => (v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4));
+      return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+    };
+    const contrastOverBackground = (fill: string, background: string) => {
+      const [hi, lo] = [
+        luminance(toSrgbOverBackground(fill, background)),
+        luminance(toSrgbOverBackground(background, background)),
+      ].sort((x, y) => y - x);
+      return (hi! + 0.05) / (lo! + 0.05);
+    };
+
+    const panelBackground = getComputedStyle(minimap).backgroundColor;
+
+    // The whole point of this helper is that a blank minimap must FAIL the check — lock
+    // that directly: a fully transparent fill composites to the panel background itself,
+    // so it can never satisfy the ≥3 contrast assertion below (would incorrectly read as
+    // 21:1 "black on white" if alpha were discarded, per the #409 review finding).
+    expect(
+      contrastOverBackground("rgba(0, 0, 0, 0)", panelBackground),
+      "a fully transparent fill must not be able to satisfy the contrast check",
+    ).toBeLessThan(3);
+
+    const rects = minimap.querySelectorAll<SVGRectElement>(".react-flow__minimap-node");
+    for (const rect of rects) {
+      expect(rect.width.baseVal.value, "minimap node rect has zero width").toBeGreaterThan(0);
+      expect(rect.height.baseVal.value, "minimap node rect has zero height").toBeGreaterThan(0);
+      const fill = getComputedStyle(rect).fill;
+      expect(
+        contrastOverBackground(fill, panelBackground),
+        `minimap node fill (${fill}) is not distinguishable from the panel background (${panelBackground})`,
+      ).toBeGreaterThanOrEqual(3);
+    }
+  },
 };

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

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import "@xyflow/react/dist/style.css";
 import { type Edge } from "@xyflow/react";
+import { expect, userEvent, waitFor } from "storybook/test";
 import { CanvasShell } from "../canvas-shell";
 import { FlowNode, type BrandFlowNode } from "./flow-node";
 
@@ -141,3 +142,153 @@ export const Connected: Story = {
     );
   },
 };
+
+/**
+ * Regression lock for #312 — `FlowNode` was keyboard-focusable and painted NO
+ * focus indicator at all. React Flow puts `tabIndex`/`:focus-visible` on its
+ * own wrapper (`.react-flow__node`), one level above the `<div>` this
+ * component renders, so the lock reaches the real tab stop by keyboard alone
+ * (no synthetic `.focus()`) and reads RESOLVED computed styles on the
+ * component's own div — not just a class string — because a previous defect
+ * on this exact surface measured 0 changed pixels out of 540,000 while the
+ * class list looked correct.
+ *
+ * Two nodes: a plain one (proves focus alone paints an indicator) and a
+ * pre-selected one (proves the NEW focus outline is a distinct, additional
+ * layer over the EXISTING `selected` ring — the two never collapse into one
+ * ring, and `selected` on its own never gains the outline).
+ */
+export const FocusIndicator: Story = {
+  render: () => {
+    const nodes: BrandFlowNode[] = [
+      {
+        id: "plain",
+        type: "brand",
+        position: { x: 40, y: 40 },
+        data: { title: "Plain node" },
+      },
+      {
+        id: "chosen",
+        type: "brand",
+        position: { x: 320, y: 40 },
+        selected: true,
+        data: { kind: "Output", title: "Selected node", tone: "success" },
+      },
+    ];
+    return (
+      <div className="h-[220px]">
+        <CanvasShell nodes={nodes} edges={[]} nodeTypes={nodeTypes} />
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    // Resolve ANY CSS colour string down to sRGB so a contrast ratio is a
+    // measurement, not an assumption — same helper `FlowWeightedEdge`'s
+    // `KeyboardFocus` lock uses for the edge half of this same fix family.
+    const toSrgb = (colour: string): [number, number, number] => {
+      const surface = document.createElement("canvas");
+      surface.width = 1;
+      surface.height = 1;
+      const ctx = surface.getContext("2d")!;
+      ctx.fillStyle = colour;
+      ctx.fillRect(0, 0, 1, 1);
+      const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+      return [r! / 255, g! / 255, b! / 255];
+    };
+    const luminance = ([r, g, b]: [number, number, number]) => {
+      const lin = (v: number) => (v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4));
+      return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+    };
+    const contrast = (a: string, b: string) => {
+      const [hi, lo] = [luminance(toSrgb(a)), luminance(toSrgb(b))].sort((x, y) => y - x);
+      return (hi! + 0.05) / (lo! + 0.05);
+    };
+
+    let plainWrapper!: HTMLElement;
+    let plainDiv!: HTMLElement;
+    let chosenWrapper!: HTMLElement;
+    let chosenDiv!: HTMLElement;
+    await waitFor(() => {
+      const pw = canvasElement.querySelector<HTMLElement>('[data-testid="rf__node-plain"]');
+      const cw = canvasElement.querySelector<HTMLElement>('[data-testid="rf__node-chosen"]');
+      expect(pw).not.toBe(null);
+      expect(cw).not.toBe(null);
+      plainWrapper = pw!;
+      chosenWrapper = cw!;
+      plainDiv = pw!.querySelector<HTMLElement>("[data-tone]")!;
+      chosenDiv = cw!.querySelector<HTMLElement>("[data-tone]")!;
+      expect(plainDiv).not.toBe(null);
+      expect(chosenDiv).not.toBe(null);
+    });
+
+    // Resting: NEITHER node paints the focus outline. The pre-selected node
+    // already shows its selection ring (driven by the `selected` prop, not a
+    // CSS state) — that ring is untouched by this fix and must stay exactly
+    // as it was.
+    const restingPlainShadow = getComputedStyle(plainDiv).boxShadow;
+    const restingChosenShadow = getComputedStyle(chosenDiv).boxShadow;
+    await expect(getComputedStyle(plainDiv).outlineStyle).toBe("none");
+    await expect(getComputedStyle(chosenDiv).outlineStyle).toBe("none");
+    await expect(restingChosenShadow).not.toBe("none");
+
+    // Reach the plain node by keyboard alone — real tab order, no synthetic .focus().
+    let guard = 0;
+    while (document.activeElement !== plainWrapper && guard < 40) {
+      await userEvent.tab();
+      guard += 1;
+    }
+    await expect(document.activeElement).toBe(plainWrapper);
+
+    // Focused, unselected: a RESOLVED computed value changed, not just a
+    // class string.
+    await waitFor(() => {
+      expect(getComputedStyle(plainDiv).outlineStyle).toBe("solid");
+    });
+    await expect(getComputedStyle(plainDiv).outlineWidth).toBe("1px");
+    await expect(getComputedStyle(plainDiv).boxShadow).not.toBe(restingPlainShadow);
+
+    // The compound indicator clears WCAG 1.4.11 (3:1) against the node's own
+    // ground — via AT LEAST ONE of its two layers. Per ADR 0027 Amendment 2
+    // the bar is `max(contrast(--ring, S), contrast(--ring-contour, S)) >= 3:1`:
+    // in `dark`, `--ring-contour` is a deliberate no-op aliased to
+    // `--background` because the ring layer alone already clears the bar, so
+    // checking the contour alone (rather than the max of both layers) would
+    // fail here even though the indicator is genuinely visible. This is a
+    // rendered-surface re-check of the guarantee `themes-contrast.test.ts`'s
+    // `INDICATOR_SURFACES` already locks at the token level for
+    // `--flow-node`/`--canvas` — not a new bar.
+    const nodeGround = getComputedStyle(plainDiv).backgroundColor;
+    const contourInk = getComputedStyle(plainDiv).outlineColor;
+    const ringInk = getComputedStyle(plainDiv).getPropertyValue("--ring").trim();
+    const contourRatio = contrast(contourInk, nodeGround);
+    const ringRatio = contrast(ringInk, nodeGround);
+    const bestRatio = Math.max(contourRatio, ringRatio);
+    await expect(
+      bestRatio,
+      `focus indicator vs node ground: contour ${contourInk} = ${contourRatio.toFixed(2)}:1, ring ${ringInk} = ${ringRatio.toFixed(2)}:1`,
+    ).toBeGreaterThanOrEqual(3);
+
+    // Continue tabbing to the pre-selected node.
+    guard = 0;
+    while (document.activeElement !== chosenWrapper && guard < 40) {
+      await userEvent.tab();
+      guard += 1;
+    }
+    await expect(document.activeElement).toBe(chosenWrapper);
+
+    // Selected AND focused: the outline is the ADDITIONAL, distinguishing
+    // layer — the shared ring layer resolves to the exact same box-shadow the
+    // selection alone already painted, so "selected" never silently gains a
+    // second, indistinguishable ring; only the new outline signals focus.
+    await waitFor(() => {
+      expect(getComputedStyle(chosenDiv).outlineStyle).toBe("solid");
+    });
+    await expect(getComputedStyle(chosenDiv).boxShadow).toBe(restingChosenShadow);
+
+    // Blur restores the resting state.
+    await userEvent.tab();
+    await waitFor(() => {
+      expect(getComputedStyle(chosenDiv).outlineStyle).toBe("none");
+    });
+  },
+};

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

@@ -2,6 +2,7 @@ import { type ReactNode } from "react";
 import { Handle, Position, type Node, type NodeProps } from "@xyflow/react";
 import { Star, type LucideIcon } from "lucide-react";
 import { STATUS_TONE_ICONS } from "@elabs-ai/components-ui";
+import { FLOW_HANDLE_ANCHOR_CLASS } from "../flow-handle/flow-handle-anchor";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 
 /** A node side that can carry a handle. Doubles as the handle's stable id. */
@@ -45,6 +46,24 @@ export interface FlowNodeData extends Record<string, unknown> {
    * bottom-source (unchanged, backward-compatible).
    */
   handles?: FlowNodeHandles;
+  /**
+   * An extra row rendered INSIDE the card, below the text block — a meter bar, a
+   * sparkline, a chip row.
+   *
+   * It exists because content a composing package renders BESIDE `FlowNode` (as a sibling
+   * inside React Flow's node element) silently breaks the canvas's geometry: React Flow
+   * positions every `<Handle>` against the nearest positioned ancestor and measures the
+   * node box from its own wrapper, so a sibling row makes the node box taller than the
+   * visible card and the handles drift off the card's border by exactly that difference.
+   * Measured on the process map's activity node, whose 6px meter and 4px gap put every
+   * bottom dot 10px below the card it was supposed to sit on, and every left/right dot
+   * 5px below the card's own mid-line.
+   *
+   * Put the row here instead and the card IS the node box again, so the dots land on the
+   * card edge for free. Nothing is rendered when it is absent — existing nodes are
+   * byte-identical.
+   */
+  footer?: ReactNode;
 }
 
 export type BrandFlowNode = Node<FlowNodeData, "brand">;
@@ -101,11 +120,39 @@ const sidePosition: Record<FlowHandleSide, Position> = {
   left: Position.Left,
 };
 
-const handleClassName = "!size-2 !border-2 !border-flow-edge !bg-flow-node";
+// `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-edge !bg-flow-node ${FLOW_HANDLE_ANCHOR_CLASS}`;
 
 /**
  * Branded custom node. Register it in `nodeTypes={{ brand: FlowNode }}` and
  * create nodes with `type: "brand"` and `data: FlowNodeData`.
+ *
+ * ## Focus vs selection (#312)
+ *
+ * `selected && "ring-2 ring-ring"` below is a SELECTION marker, not a focus
+ * indicator — it is React Flow's own click-driven `selected` state and is the
+ * genuine-selection carve-out `.claude/rules/theming.md` names explicitly.
+ * Keyboard focus is a separate, independent signal this component used to omit
+ * entirely (issue #312): React Flow puts `tabIndex`/`role="group"` and the real
+ * `:focus-visible` state on **its own wrapper** (`.react-flow__node`, which
+ * also always carries a `data-id` attribute), one level ABOVE the `<div>` this
+ * component returns — so neither `focus-ring` (`:focus-visible` on self) nor
+ * `focus-ring-within` (`:focus-within`, a focused descendant) can ever fire
+ * here; focus is PROXIED to an ancestor this component doesn't render.
+ * `focus-ring-static` is the flavour built for that exact shape (ADR 0027),
+ * gated by an ancestor-selector arbitrary variant — the same idiom
+ * `FlowEdgePath` uses for `.react-flow__edge:focus-visible`, keyed on
+ * `[data-id]` here (rather than the escaped `.react-flow\_\_node` class) so
+ * the selector needs no backslash escaping inside a plain JS string — a
+ * literal `\_` in a `cn()` argument is a real JS string escape and would be
+ * silently stripped at runtime (unlike in a bare, unbraced JSX attribute,
+ * where backslashes are never processed — the reason `FlowEdgePath` can use
+ * the class form safely and this component, composing through `cn()`, cannot).
+ * The two signals compose without merging into one ring: `selected` alone
+ * paints the ring layer only, while a focused node additionally gets the
+ * `--ring-contour` outline drawn outside it, so "selected AND focused" reads
+ * as two visible layers, not the single ring "selected alone" paints.
  */
 export function FlowNode({
   data,
@@ -117,11 +164,18 @@ export function FlowNode({
   const ToneIcon = toneIcon[tone];
   return (
     <div
+      // The PAINTED card, and the box every handle dot must sit on the border of.
+      // `.react-flow__node` (the wrapper React Flow positions) can legitimately be
+      // taller than this — a composing package may render a badge or a meter beside
+      // the card — so a test that wants "is the connector on the card?" measures
+      // against this slot, never against the wrapper. See `testing/canvas-framing`.
+      data-slot="flow-node"
       data-tone={tone}
       className={cn(
         "min-w-44 rounded-lg border bg-flow-node px-3 py-2 text-flow-node-foreground shadow-sm transition-[box-shadow,border-color] duration-fast ease-standard",
         toneRing[tone],
         selected && "ring-2 ring-ring",
+        "[[data-id]:focus-visible_&]:focus-ring-static",
       )}
     >
       {data.handles ? (
@@ -184,6 +238,7 @@ export function FlowNode({
           <ToneIcon aria-hidden="true" className={cn("size-3.5 shrink-0", toneIconColor[tone])} />
         ) : null}
       </div>
+      {data.footer ? <div className="mt-2">{data.footer}</div> : null}
       {toneLabel[tone] ? <span className="sr-only">{toneLabel[tone]}</span> : null}
     </div>
   );

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

@@ -1,5 +1,6 @@
 import { Handle, Position, type Node, type NodeProps } from "@xyflow/react";
 import { Plus } from "lucide-react";
+import { FLOW_HANDLE_ANCHOR_CLASS } from "../flow-handle/flow-handle-anchor";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 
 export interface FlowPlaceholderNodeData extends Record<string, unknown> {
@@ -29,7 +30,9 @@ export function FlowPlaceholderNode({ data }: NodeProps<BrandFlowPlaceholderNode
       <Handle
         type="target"
         position={Position.Top}
-        className="!size-2 !border-2 !border-flow-edge !bg-flow-node"
+        // `FLOW_HANDLE_ANCHOR_CLASS`: a connector dot must never be in flight when
+        // React Flow measures it. See `flow-handle/flow-handle-anchor.ts`.
+        className={`!size-2 !border-2 !border-flow-edge !bg-flow-node ${FLOW_HANDLE_ANCHOR_CLASS}`}
       />
       <button
         type="button"
@@ -38,7 +41,7 @@ export function FlowPlaceholderNode({ data }: NodeProps<BrandFlowPlaceholderNode
         className={cn(
           "flex min-w-44 items-center justify-center gap-1.5 rounded-lg border border-dashed border-flow-group-border bg-flow-group px-3 py-2 text-muted-foreground",
           "transition-colors duration-fast ease-standard hover:bg-accent hover:text-accent-foreground",
-          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          "focus-ring",
         )}
       >
         <Plus className="size-4" aria-hidden="true" />

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

@@ -0,0 +1,275 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import "@xyflow/react/dist/style.css";
+import { expect, userEvent, waitFor, within } from "storybook/test";
+import { CanvasShell } from "../canvas-shell";
+import { FlowNode, type BrandFlowNode } from "../flow-node";
+import { layoutFlow } from "../flow-layout";
+import { FlowWeightedEdge, type BrandFlowWeightedEdge } from "../flow-weighted-edge";
+import { FlowSelfLoopEdge, type BrandFlowSelfLoopEdge } from "./flow-self-loop-edge";
+
+const nodeTypes = { brand: FlowNode };
+const edgeTypes = { weighted: FlowWeightedEdge, "self-loop": FlowSelfLoopEdge };
+
+type ProcessEdge = BrandFlowWeightedEdge | BrandFlowSelfLoopEdge;
+
+const meta = {
+  title: "Flow/FlowSelfLoopEdge",
+  component: FlowSelfLoopEdge,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "A branded edge for the case where source and target are the same node — the " +
+          "this-step-repeated signal in a process map — drawn as a closed arc above the node " +
+          "instead of a straight or curved line between two points, since dagre cannot lay a " +
+          "self-loop out on its own. It shares its weight-to-stroke-width scale with " +
+          "`FlowWeightedEdge`, so reach for this one only for a genuine self-loop and the " +
+          "weighted edge for everything else; see " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs).",
+      },
+    },
+  },
+} satisfies Meta<typeof FlowSelfLoopEdge>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Three steps of an order process, stacked top-to-bottom. */
+function processNodes(): BrandFlowNode[] {
+  return [
+    {
+      id: "a",
+      type: "brand",
+      position: { x: 0, y: 0 },
+      data: { kind: "Start", title: "Received" },
+    },
+    {
+      id: "b",
+      type: "brand",
+      position: { x: 0, y: 180 },
+      data: { kind: "Step", title: "Review" },
+    },
+    {
+      id: "c",
+      type: "brand",
+      position: { x: 0, y: 360 },
+      data: { kind: "End", title: "Approved" },
+    },
+  ];
+}
+
+/**
+ * Every geometry read in these play functions sits inside `waitFor`/`findBy*`:
+ * React Flow arrives in a lazy chunk and paints its edges only after it has
+ * measured node handles, so a bare `querySelector` + expect races the paint.
+ */
+const loopPaths = (root: HTMLElement) =>
+  Array.from(root.querySelectorAll<SVGPathElement>('[data-slot="flow-self-loop-edge"]'));
+const weightedPaths = (root: HTMLElement) =>
+  Array.from(root.querySelectorAll<SVGPathElement>('[data-slot="flow-weighted-edge"]'));
+/** Browsers serialise `stroke-dasharray` as "6, 4"; jsdom keeps "6 4". Normalise both. */
+const dashPattern = (path: SVGPathElement) =>
+  path.style.strokeDasharray.replace(/,/g, " ").replace(/\s+/g, " ").trim();
+
+/** A step that repeats: the arc leaves the node's top-right and re-enters top-left. Tab to reach its label. */
+export const SelfLoop: Story = {
+  render: () => {
+    const edges: ProcessEdge[] = [
+      { id: "e-ab", source: "a", target: "b", type: "weighted", data: { weight: 9 } },
+      { id: "e-bc", source: "b", target: "c", type: "weighted", data: { weight: 5 } },
+      {
+        id: "e-bb",
+        source: "b",
+        target: "b",
+        type: "self-loop",
+        data: { weight: 3, label: "12×", secondaryLabel: "2.1d avg" },
+      },
+    ];
+    return (
+      <div className="h-[520px]">
+        <CanvasShell
+          nodes={processNodes()}
+          edges={edges}
+          nodeTypes={nodeTypes}
+          edgeTypes={edgeTypes}
+        />
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // The loop is a SHAPE, not a colour: it ends left of where it started and
+    // rises above the node's top edge, which no forward edge does.
+    await waitFor(() => {
+      const [loop] = loopPaths(canvasElement);
+      expect(loop).toBeDefined();
+      expect(loop!.getAttribute("d")).toMatch(/^M [\d.-]+,[\d.-]+ C .+$/);
+    });
+
+    // …and the meaning also reaches assistive tech as real text.
+    await canvas.findByRole("img", { name: "Self-loop on Review — this step repeats" });
+
+    // The loop's label is a genuine keyboard tab stop, reached by tabbing —
+    // not by a synthetic .focus() call.
+    const pill = await canvas.findByRole("button", { name: "12× · 2.1d avg" });
+    let guard = 0;
+    while (document.activeElement !== pill && guard < 60) {
+      await userEvent.tab();
+      guard += 1;
+    }
+    await expect(pill).toHaveFocus();
+  },
+};
+
+/** A rework edge running against the flow: dashed, and routed clear of the forward edge it doubles back over. */
+export const BackEdge: Story = {
+  render: () => {
+    const edges: ProcessEdge[] = [
+      { id: "e-ab", source: "a", target: "b", type: "weighted", data: { weight: 9 } },
+      { id: "e-bc", source: "b", target: "c", type: "weighted", data: { weight: 6 } },
+      {
+        id: "e-cb",
+        source: "c",
+        target: "b",
+        type: "weighted",
+        data: { weight: 2, variant: "back", label: "18× reworked" },
+      },
+    ];
+    return (
+      <div className="h-[520px]">
+        <CanvasShell
+          nodes={processNodes()}
+          edges={edges}
+          nodeTypes={nodeTypes}
+          edgeTypes={edgeTypes}
+        />
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await waitFor(() => {
+      const paths = weightedPaths(canvasElement);
+      expect(paths).toHaveLength(3);
+      const byVariant = (variant: string) => paths.filter((p) => p.dataset.variant === variant);
+      // Greyscale-safe: the back edge is dashed, the forward ones are not.
+      expect(byVariant("back")).toHaveLength(1);
+      expect(dashPattern(byVariant("back")[0]!)).toBe("6 4");
+      expect(byVariant("forward")).toHaveLength(2);
+      for (const forward of byVariant("forward")) {
+        expect(dashPattern(forward)).toBe("");
+      }
+    });
+
+    await canvas.findByRole("img", {
+      name: "Back edge — runs against the process direction",
+    });
+  },
+};
+
+/**
+ * The acceptance fixture, laid out for real: `A → B → C` with `C → B` and a
+ * `B → B` loop. `layoutFlow` reports which edge went backwards and which is a
+ * self-loop, and the story picks the edge type from that metadata alone.
+ */
+export const ReworkLoopFromLayout: Story = {
+  render: () => {
+    const rawEdges: ProcessEdge[] = [
+      { id: "e-ab", source: "a", target: "b", type: "weighted", data: { weight: 9 } },
+      { id: "e-bc", source: "b", target: "c", type: "weighted", data: { weight: 6 } },
+      {
+        id: "e-cb",
+        source: "c",
+        target: "b",
+        type: "weighted",
+        data: { weight: 2, label: "18× reworked" },
+      },
+      {
+        id: "e-bb",
+        source: "b",
+        target: "b",
+        type: "weighted",
+        data: { weight: 3, label: "12×" },
+      },
+    ];
+    const { nodes, edges, backEdges, selfLoops } = layoutFlow(processNodes(), rawEdges, {
+      direction: "TB",
+      rankSpacing: 120,
+    });
+    const typed: ProcessEdge[] = edges.map((edge) => {
+      if (selfLoops.includes(edge.id)) {
+        return { ...edge, type: "self-loop" } as BrandFlowSelfLoopEdge;
+      }
+      if (backEdges.includes(edge.id)) {
+        return {
+          ...edge,
+          data: { ...edge.data, variant: "back" },
+        } as BrandFlowWeightedEdge;
+      }
+      return edge;
+    });
+    return (
+      <div className="h-[560px]">
+        <CanvasShell nodes={nodes} edges={typed} nodeTypes={nodeTypes} edgeTypes={edgeTypes} />
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Three greyscale-distinct signatures on one canvas: solid forward strokes,
+    // a dashed back edge, and a looping arc.
+    await waitFor(() => {
+      const weighted = weightedPaths(canvasElement);
+      expect(weighted.filter((p) => p.dataset.variant === "forward")).toHaveLength(2);
+      expect(weighted.filter((p) => p.dataset.variant === "back")).toHaveLength(1);
+      expect(loopPaths(canvasElement)).toHaveLength(1);
+    });
+
+    await canvas.findByRole("img", { name: "Back edge — runs against the process direction" });
+    await canvas.findByRole("img", { name: "Self-loop on Review — this step repeats" });
+  },
+};
+
+/** The same loop at decoration 0 and 10 — the arc and the dashes survive the drafting ground. */
+export const Decoration: Story = {
+  render: () => {
+    const edges: ProcessEdge[] = [
+      { id: "e-ab", source: "a", target: "b", type: "weighted", data: { weight: 9 } },
+      { id: "e-bc", source: "b", target: "c", type: "weighted", data: { weight: 5 } },
+      {
+        id: "e-cb",
+        source: "c",
+        target: "b",
+        type: "weighted",
+        data: { weight: 2, variant: "back" },
+      },
+      { id: "e-bb", source: "b", target: "b", type: "self-loop", data: { weight: 3 } },
+    ];
+    return (
+      <div className="grid h-[520px] grid-cols-2">
+        {([0, 10] as const).map((level) => (
+          <div key={level} data-decoration={level} className="h-full bg-background">
+            <CanvasShell
+              nodes={processNodes()}
+              edges={edges.map((edge) => ({ ...edge, id: `d${level}-${edge.id}` }))}
+              nodeTypes={nodeTypes}
+              edgeTypes={edgeTypes}
+            />
+          </div>
+        ))}
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    await waitFor(() => {
+      expect(loopPaths(canvasElement)).toHaveLength(2);
+      expect(weightedPaths(canvasElement).filter((p) => p.dataset.variant === "back")).toHaveLength(
+        2,
+      );
+    });
+  },
+};