@elabs-ai/components-flow 4.0.0 → 4.2.0

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

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