@elabs-ai/components-flow 4.0.0 → 4.2.0

package/src/flow-layout/flow-layout.ts

@@ -2,6 +2,20 @@ import dagre from "@dagrejs/dagre";
 import { Position } from "@xyflow/react";
 import type { Edge, Node } from "@xyflow/react";
 
+/** The graphlib graph `dagre.graphlib.Graph` produces — dagre exports no standalone type for it. */
+type DagreGraph = InstanceType<typeof dagre.graphlib.Graph>;
+
+/**
+ * The fields dagre writes back onto a node label during `layout()`. `rank` is
+ * absent from dagre's own `.d.ts` (it is documented output, not declared
+ * output), so it is narrowed here rather than asserted at the call site.
+ */
+interface DagreNodeLabel {
+  x: number;
+  y: number;
+  rank?: number;
+}
+
 /** Direction dagre lays the graph out in — top-to-bottom, left-to-right, etc. */
 export type FlowLayoutDirection = "TB" | "LR" | "BT" | "RL";
 
@@ -35,6 +49,22 @@ export interface FlowLayoutOptions {
 export interface FlowLayoutResult<NodeType extends Node = Node, EdgeType extends Edge = Edge> {
   nodes: NodeType[];
   edges: EdgeType[];
+  /**
+   * Ids of edges that run **against** the layout direction — a rework / retry
+   * loop in a process graph. dagre breaks cycles by reversing such edges
+   * internally and never surfaces which ones it reversed, so this is derived
+   * from the ranks dagre stamps on the laid-out graph: an edge whose source
+   * ranks at or after its target went backwards. Render these with
+   * `FlowWeightedEdge`'s `variant="back"`.
+   */
+  backEdges: string[];
+  /**
+   * Ids of edges whose `source === target`. dagre does not lay out self-loops,
+   * so they are withheld from the graph entirely (never `setEdge`-ed) and are
+   * returned unchanged in `edges` — they take part in no rank computation and
+   * cannot distort the layout. Render these with `FlowSelfLoopEdge`.
+   */
+  selfLoops: string[];
 }
 
 /** Fallback size used when a node hasn't been measured yet (React Flow's own default node width). */
@@ -58,6 +88,11 @@ function nodeSize(node: Node): { width: number; height: number } {
  * `node.height`, then a sensible default. Node identity and `data` are left
  * untouched — only `position` changes.
  *
+ * Also reports the graph's two structural signals — `backEdges` (edges that run
+ * against the layout direction) and `selfLoops` (`source === target`). Both are
+ * additive fields on the result; a caller that only destructures
+ * `{ nodes, edges }` is unaffected.
+ *
  * Pair with `useFlowLayout` to apply the result to a live canvas.
  */
 export function layoutFlow<NodeType extends Node = Node, EdgeType extends Edge = Edge>(
@@ -76,12 +111,22 @@ export function layoutFlow<NodeType extends Node = Node, EdgeType extends Edge =
     graph.setNode(node.id, { width, height });
   }
 
+  // Self-loops are withheld from dagre entirely: dagre does not lay them out,
+  // and feeding them in only perturbs the ranks of a graph they say nothing
+  // about. They are re-attached untouched in the returned `edges`.
+  const selfLoops: string[] = [];
   for (const edge of edges) {
+    if (edge.source === edge.target) {
+      selfLoops.push(edge.id);
+      continue;
+    }
     graph.setEdge(edge.source, edge.target);
   }
 
   dagre.layout(graph);
 
+  const backEdges = collectBackEdges(graph, edges);
+
   const handles = HANDLE_BY_DIRECTION[direction];
   const layoutedNodes = nodes.map((node) => {
     const dagreNode = graph.node(node.id);
@@ -100,5 +145,36 @@ export function layoutFlow<NodeType extends Node = Node, EdgeType extends Edge =
     };
   });
 
-  return { nodes: layoutedNodes, edges };
+  return { nodes: layoutedNodes, edges, backEdges, selfLoops };
+}
+
+/**
+ * Which edges dagre had to run backwards, derived from the ranks it stamps on
+ * the laid-out graph (`graph.node(id).rank`).
+ *
+ * The obvious alternative — reading `graph.edge(e).reversed` after dagre's
+ * `acyclic.run` — is **not usable on the pinned `@dagrejs/dagre` 3.0.0**:
+ * cycle breaking happens on an internal copy of the graph, and the caller's
+ * graph carries no `reversed` flag once `dagre.layout()` returns (verified
+ * against the installed version — every edge label is bare `{ points }`).
+ * `rank` *is* on the public graph, and is direction-independent: it counts up
+ * along the flow for every `rankdir`, so `rank(source) >= rank(target)` means
+ * "this edge does not advance the process" in TB, BT, LR and RL alike.
+ *
+ * `>=` rather than `>` on purpose: a same-rank edge between two siblings is
+ * not forward progress either, and dagre would have had to reverse or flatten
+ * it. Self-loops never reach here — they are filtered out before layout.
+ * An edge naming a node that isn't in the graph has no ranks to compare and is
+ * left out rather than guessed at.
+ */
+function collectBackEdges(graph: DagreGraph, edges: Edge[]): string[] {
+  const backEdges: string[] = [];
+  for (const edge of edges) {
+    if (edge.source === edge.target) continue;
+    const sourceRank = (graph.node(edge.source) as DagreNodeLabel | undefined)?.rank;
+    const targetRank = (graph.node(edge.target) as DagreNodeLabel | undefined)?.rank;
+    if (typeof sourceRank !== "number" || typeof targetRank !== "number") continue;
+    if (sourceRank >= targetRank) backEdges.push(edge.id);
+  }
+  return backEdges;
 }

package/src/flow-layout/layout-graph.test.ts

@@ -36,7 +36,13 @@ function distance(p: { x: number; y: number }, q: { x: number; y: number } = { x
 describe("layoutGraph", () => {
   describe("empty / disconnected input", () => {
     it("returns [] for an empty graph, for every algorithm", () => {
-      for (const algorithm of ["concentric", "force", "layered-lr", "grid"] as const) {
+      for (const algorithm of [
+        "concentric",
+        "force",
+        "layered-lr",
+        "layered-tb",
+        "grid",
+      ] as const) {
         expect(layoutGraph([], [], { algorithm })).toEqual([]);
       }
     });
@@ -45,7 +51,13 @@ describe("layoutGraph", () => {
       const nodes = ["a", "b", "c", "isolated1", "isolated2"].map(node);
       const edges = [edge("a", "b"), edge("b", "c")];
 
-      for (const algorithm of ["concentric", "force", "layered-lr", "grid"] as const) {
+      for (const algorithm of [
+        "concentric",
+        "force",
+        "layered-lr",
+        "layered-tb",
+        "grid",
+      ] as const) {
         const laidOut = layoutGraph(nodes, edges, { algorithm, iterations: 20 });
         for (const n of laidOut) {
           expect(Number.isFinite(n.position.x)).toBe(true);
@@ -254,4 +266,73 @@ describe("layoutGraph", () => {
       expect(first.map((n) => n.position)).toEqual(second.map((n) => n.position));
     });
   });
+  describe("layered-tb", () => {
+    it("delegates to layoutFlow direction=TB, ordering a chain top-to-bottom", () => {
+      const { nodes, edges } = chainGraph();
+      const laidOut = layoutGraph(nodes, edges, { algorithm: "layered-tb" });
+      const [a, b, c] = laidOut as [Node, Node, Node];
+      expect(a.position.y).toBeLessThan(b.position.y);
+      expect(b.position.y).toBeLessThan(c.position.y);
+    });
+
+    it("stamps bottom-out / top-in handle sides (not just position)", () => {
+      const { nodes, edges } = chainGraph();
+      const [a] = layoutGraph(nodes, edges, { algorithm: "layered-tb" }) as [Node];
+      expect(a.sourcePosition).toBe("bottom");
+      expect(a.targetPosition).toBe("top");
+    });
+
+    it("maps spacing.y onto rank spacing (the axis TB ranks along)", () => {
+      const { nodes, edges } = chainGraph();
+      const tight = layoutGraph(nodes, edges, {
+        algorithm: "layered-tb",
+        spacing: { x: 10, y: 10 },
+      });
+      const wide = layoutGraph(nodes, edges, {
+        algorithm: "layered-tb",
+        spacing: { x: 10, y: 500 },
+      });
+      const tightGap = tight[1]!.position.y - tight[0]!.position.y;
+      const wideGap = wide[1]!.position.y - wide[0]!.position.y;
+      expect(wideGap).toBeGreaterThan(tightGap);
+    });
+
+    it("respects a custom nodeSize without permanently resizing the nodes", () => {
+      const nodes: Node[] = [
+        { id: "a", type: "brand", position: { x: 0, y: 0 }, data: {} },
+        { id: "b", type: "brand", position: { x: 0, y: 0 }, data: {} },
+      ];
+      const laidOut = layoutGraph(nodes, [edge("a", "b")], {
+        algorithm: "layered-tb",
+        nodeSize: () => ({ width: 200, height: 400 }),
+      });
+      expect(laidOut[1]!.position.y - laidOut[0]!.position.y).toBeGreaterThanOrEqual(400 + 72 - 1);
+      expect(laidOut[0]).not.toHaveProperty("measured");
+    });
+
+    it("is the same layout as layered-lr with the axes swapped", () => {
+      // A fork exercises BOTH axes: a rank progression and a within-rank stack.
+      // Square nodes + isotropic spacing make the two layouts exact mirrors, so
+      // the assertion is "x and y trade places", not "the numbers look similar".
+      const nodes = ["a", "b", "c"].map(node);
+      const edges = [edge("a", "b"), edge("a", "c")];
+      const options = {
+        spacing: { x: 150, y: 150 },
+        nodeSize: () => ({ width: 100, height: 100 }),
+      };
+      const lr = layoutGraph(nodes, edges, { ...options, algorithm: "layered-lr" });
+      const tb = layoutGraph(nodes, edges, { ...options, algorithm: "layered-tb" });
+
+      expect(tb.map((n) => n.position)).toEqual(
+        lr.map((n) => ({ x: n.position.y, y: n.position.x })),
+      );
+    });
+
+    it("is deterministic", () => {
+      const { nodes, edges } = chainGraph();
+      const first = layoutGraph(nodes, edges, { algorithm: "layered-tb" });
+      const second = layoutGraph(nodes, edges, { algorithm: "layered-tb" });
+      expect(first.map((n) => n.position)).toEqual(second.map((n) => n.position));
+    });
+  });
 });

package/src/flow-layout/layout-graph.ts

@@ -8,12 +8,12 @@ import {
   type SimulationNodeDatum,
 } from "d3-force";
 import type { Edge, Node } from "@xyflow/react";
-import { HANDLE_BY_DIRECTION, layoutFlow } from "./flow-layout";
+import { HANDLE_BY_DIRECTION, layoutFlow, type FlowLayoutDirection } from "./flow-layout";
 
 /** Which generic graph-geometry algorithm `layoutGraph` should run. */
-export type LayoutAlgorithm = "concentric" | "force" | "layered-lr" | "grid";
+export type LayoutAlgorithm = "concentric" | "force" | "layered-lr" | "layered-tb" | "grid";
 
-/** Horizontal/vertical gap used by the `"grid"` and `"layered-lr"` algorithms. */
+/** Horizontal/vertical gap used by the `"grid"` and `"layered-*"` algorithms. */
 export interface LayoutSpacing {
   x: number;
   y: number;
@@ -31,7 +31,7 @@ export interface LayoutOptions {
   ringRadius?: number;
   /** `"force"` only — number of synchronous simulation ticks to run. @default 300 */
   iterations?: number;
-  /** `"grid"` / `"layered-lr"` — gap between nodes. @default {x:200,y:120} for grid. */
+  /** `"grid"` / `"layered-lr"` / `"layered-tb"` — gap between nodes. @default {x:200,y:120} for grid. */
   spacing?: LayoutSpacing;
   /** Resolve a node's size by id. Falls back to `measured`/`width`/`height`/a sensible default. */
   nodeSize?: (id: string) => { width: number; height: number };
@@ -66,7 +66,10 @@ function resolveNodeSize(
  * Node identity and `data` are left untouched — only `position` changes.
  * Pair with `useAutoLayout` for a memoized hook form.
  *
- * - `"layered-lr"` delegates to the dagre-powered `layoutFlow` (direction `"LR"`).
+ * - `"layered-lr"` / `"layered-tb"` delegate to the dagre-powered `layoutFlow`
+ *   (direction `"LR"` / `"TB"`). `spacing.x` is always the horizontal gap and
+ *   `spacing.y` the vertical one, so the two differ only in which axis carries
+ *   the ranks.
  * - `"concentric"` places `centerId` (or the highest-degree node) at the
  *   origin, with BFS shells at `ring × ringRadius`; disconnected nodes land in
  *   one extra outer ring so positions are never `NaN`.
@@ -83,7 +86,9 @@ export function layoutGraph<NodeType extends Node = Node, EdgeType extends Edge
 
   switch (options.algorithm) {
     case "layered-lr":
-      return layoutLayeredLr(nodes, edges, options);
+      return layoutLayered(nodes, edges, options, "LR");
+    case "layered-tb":
+      return layoutLayered(nodes, edges, options, "TB");
     case "concentric":
       return layoutConcentric(nodes, edges, options);
     case "force":
@@ -97,10 +102,11 @@ export function layoutGraph<NodeType extends Node = Node, EdgeType extends Edge
   }
 }
 
-function layoutLayeredLr<NodeType extends Node, EdgeType extends Edge>(
+function layoutLayered<NodeType extends Node, EdgeType extends Edge>(
   nodes: NodeType[],
   edges: EdgeType[],
   options: LayoutOptions,
+  direction: FlowLayoutDirection,
 ): NodeType[] {
   const { spacing, nodeSize } = options;
 
@@ -114,17 +120,19 @@ function layoutLayeredLr<NodeType extends Node, EdgeType extends Edge>(
       })
     : nodes;
 
+  // Ranks progress along the layout axis and nodes stack across it, so the two
+  // directions map the SAME `spacing.x`/`spacing.y` onto dagre's rank/node sep
+  // with the axes swapped: LR ranks horizontally (x), TB ranks vertically (y).
+  const horizontalRanks = direction === "LR" || direction === "RL";
   const { nodes: laidOut } = layoutFlow(sizedNodes, edges, {
-    direction: "LR",
-    // For an LR flow, ranks progress horizontally (x) and nodes within a rank
-    // stack vertically (y) — map spacing accordingly onto dagre's rank/node sep.
-    nodeSpacing: spacing?.y,
-    rankSpacing: spacing?.x,
+    direction,
+    nodeSpacing: horizontalRanks ? spacing?.y : spacing?.x,
+    rankSpacing: horizontalRanks ? spacing?.x : spacing?.y,
   });
 
-  // Carry the LR handle sides (right-out / left-in) that layoutFlow stamped on,
-  // not just the position — otherwise the layout flips positions but leaves the
-  // anchors on top/bottom.
+  // Carry the handle sides layoutFlow stamped on (LR right-out/left-in, TB
+  // bottom-out/top-in), not just the position — otherwise the layout moves the
+  // nodes but leaves the anchors on the wrong sides.
   return nodes.map((node, i) => ({
     ...node,
     sourcePosition: laidOut[i]!.sourcePosition,

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,106 @@ 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);
+    };
+
+    // Measure the SETTLED paint, not the frame the theme switched in. The preview's
+    // `ThemeBoundary` writes `data-theme` in an effect, after the canvas has already
+    // rendered once under the `:root` (light) fallback. The storybook Vitest project runs
+    // with `reducedMotion: "reduce"`, and the tokens' reduced-motion backstop clamps
+    // `transition-duration` to 0.01ms on EVERY element — whose `transition-property`
+    // defaults to `all` — so the light→dark swap becomes a one-frame colour transition.
+    // Read synchronously, `getComputedStyle` still returns the transition's START value
+    // (the light panel's white) while the node rects, mounted after the switch, are
+    // already dark: a false 2.47:1 in the dark theme only. Awaiting the running
+    // transitions on the panel and its rects reads what the browser actually paints.
+    await Promise.all(
+      minimap.getAnimations({ subtree: true }).map((animation) =>
+        // A transition superseded by another change rejects `finished`; the settled
+        // value is still what the readback below measures.
+        animation.finished.catch(() => undefined),
+      ),
+    );
+    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");
+    });
+  },
+};