@elabs-ai/components-flow 4.0.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elabs-ai/components-flow",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -32,8 +32,8 @@
     "@xyflow/react": "^12.11.1",
     "react": "^18.2.0 || ^19.0.0",
     "react-dom": "^18.2.0 || ^19.0.0",
-    "@elabs-ai/components-tokens": "4.0.0",
-    "@elabs-ai/components-ui": "4.0.0"
+    "@elabs-ai/components-tokens": "4.1.0",
+    "@elabs-ai/components-ui": "4.1.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
@@ -51,10 +51,10 @@
     "tsup": "^8.3.5",
     "typescript": "^5.7.3",
     "vitest": "^3.0.2",
+    "@elabs-ai/components-tokens": "4.1.0",
+    "@elabs-ai/components-icons": "4.1.0",
     "@elabs-ai/components-eslint-config": "0.1.0",
-    "@elabs-ai/components-tokens": "4.0.0",
-    "@elabs-ai/components-ui": "4.0.0",
-    "@elabs-ai/components-icons": "4.0.0",
+    "@elabs-ai/components-ui": "4.1.0",
     "@elabs-ai/components-typescript-config": "0.1.0"
   },
   "scripts": {

package/src/canvas-shell/canvas-shell.tsx

@@ -1,16 +1,21 @@
-import { type ReactNode } from "react";
+import { useEffect, type ReactNode } from "react";
 import {
   Background,
   ReactFlow,
   ReactFlowProvider,
+  useNodesInitialized,
+  useReactFlow,
+  useStoreApi,
   type AriaLabelConfig,
   type Edge,
+  type FitViewOptions,
   type Node,
   type ReactFlowProps,
 } from "@xyflow/react";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { HelperLines } from "../helper-lines/helper-lines";
 import { useHelperLines } from "../helper-lines/use-helper-lines";
+import { useMeasuredNodes } from "./use-measured-nodes";
 
 export interface CanvasShellProps<
   NodeType extends Node = Node,
@@ -27,6 +32,26 @@ export interface CanvasShellProps<
    * use the exported `useHelperLines` + `<HelperLines>` directly.
    */
   helperLines?: boolean;
+  /**
+   * Re-fit the viewport whenever this value changes.
+   *
+   * React Flow's own `fitView` prop fits ONCE, as soon as the nodes are first measured,
+   * and then never again. A canvas whose positions arrive AFTER that first paint —
+   * anything laid out asynchronously, e.g. a debounced `layoutFlow` pass — therefore gets
+   * fitted to the pre-layout positions (typically every node still stacked at the origin)
+   * and stays there. Measured on the process map: the viewport pinned at React Flow's
+   * `maxZoom` of 2 with 2 of 11 nodes on screen, while the layout underneath was correct
+   * the whole time.
+   *
+   * Pass the key the layout is cached on (structure + direction), NOT something that
+   * changes on every render and not a metric: a re-fit is a viewport jump, so it must
+   * happen when the picture genuinely moved and never while the reader is reading. The
+   * fit waits for `useNodesInitialized`, so it measures real node boxes rather than
+   * fitting a degenerate bounding box a second time.
+   */
+  fitViewKey?: string | number;
+  /** Options for the {@link fitViewKey} re-fit. Ignored without one. */
+  fitViewKeyOptions?: FitViewOptions;
   /** Overlays rendered inside the flow (ZoomControls, Legend, Panels). */
   children?: ReactNode;
   className?: string;
@@ -91,23 +116,113 @@ function CanvasShellBase<NodeType extends Node, EdgeType extends Edge>({
   children,
   className,
   ariaLabelConfig,
+  nodes,
+  onNodesChange,
+  fitViewKey,
+  fitViewKeyOptions,
   ...props
 }: CanvasShellInnerProps<NodeType, EdgeType>) {
+  const measured = useMeasuredNodes<NodeType>(nodes, onNodesChange);
   return (
     <div className={cn("h-full w-full bg-canvas", className)}>
       <ReactFlow
         fitView
         proOptions={{ hideAttribution: true }}
         ariaLabelConfig={{ ...DEFAULT_ARIA_LABEL_CONFIG, ...ariaLabelConfig }}
+        nodes={measured.nodes}
+        onNodesChange={measured.onNodesChange}
         {...props}
       >
         {background ? <Background gap={20} size={1} color="var(--canvas-grid)" /> : null}
+        {fitViewKey === undefined ? null : (
+          <FitViewOnKey fitViewKey={fitViewKey} options={fitViewKeyOptions} />
+        )}
         {children}
       </ReactFlow>
     </div>
   );
 }
 
+/**
+ * Re-fits the viewport when `fitViewKey` changes and the nodes have been measured.
+ *
+ * Rendered as a CHILD of `<ReactFlow>` because `useReactFlow`/`useNodesInitialized` need
+ * the flow context, which only exists below it. It renders nothing.
+ */
+function FitViewOnKey({
+  fitViewKey,
+  options,
+}: {
+  fitViewKey: string | number;
+  options?: FitViewOptions;
+}) {
+  const { fitView, getNodes, getNodesBounds, setViewport } = useReactFlow();
+  const store = useStoreApi();
+  const nodesInitialized = useNodesInitialized();
+  useEffect(() => {
+    if (!nodesInitialized) return;
+    void fitView(options).then(() =>
+      anchorToStartWhenClamped(store, setViewport, getNodesBounds, getNodes(), options),
+    );
+    // `options` is deliberately absent: an inline object literal would re-fit on every
+    // render, which is a viewport jump under the reader's cursor. The key is the trigger.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [fitViewKey, nodesInitialized, fitView, getNodes, getNodesBounds, setViewport, store]);
+  return null;
+}
+
+/**
+ * After a fit that could NOT show everything, show the BEGINNING rather than the middle.
+ *
+ * `fitView` always centres. That is right when the content fits — and wrong the moment a
+ * `minZoom` floor stops it from shrinking far enough, because centring a graph that
+ * overflows puts its first rank off the top of the pane and opens the canvas on the
+ * middle of a process nobody has read the start of yet. Every layout this shell is used
+ * with runs from an origin (top for `TB`, left for `LR`), so the content's own top-left
+ * corner IS the beginning, in both.
+ *
+ * Applied PER AXIS, and only to an axis that actually overflows: a tall graph in a wide
+ * pane is pinned to the top and stays horizontally centred, which is what a reader
+ * expects. A canvas whose content fits is left exactly as `fitView` left it.
+ */
+function anchorToStartWhenClamped(
+  store: ReturnType<typeof useStoreApi>,
+  setViewport: ReturnType<typeof useReactFlow>["setViewport"],
+  // The HOOK's `getNodesBounds`, never the top-level export: the standalone one warns in
+  // development when it is handed no `nodeLookup` ("Please use `getNodesBounds` from
+  // `useReactFlow`…") and measures a parent's own `position` instead of resolving a
+  // nested node's absolute one, so a keyed re-fit on a canvas with sub-flows anchors to
+  // the wrong corner.
+  getNodesBounds: ReturnType<typeof useReactFlow>["getNodesBounds"],
+  nodes: Node[],
+  options: FitViewOptions | undefined,
+): void {
+  if (nodes.length === 0) return;
+  const { width, height, transform, panZoom } = store.getState();
+  const [x, y, zoom] = transform;
+  if (!width || !height || !zoom) return;
+
+  const bounds = getNodesBounds(nodes);
+  // The same fraction-of-the-pane padding `fitView` itself applies, so the anchored
+  // corner sits exactly where a fitted one would.
+  const padding = typeof options?.padding === "number" ? options.padding : 0.1;
+  const padX = width * padding;
+  const padY = height * padding;
+
+  const overflowsX = bounds.width * zoom > width - padX * 2 + 1;
+  const overflowsY = bounds.height * zoom > height - padY * 2 + 1;
+  if (!overflowsX && !overflowsY) return;
+
+  const next = {
+    x: overflowsX ? padX - bounds.x * zoom : x,
+    y: overflowsY ? padY - bounds.y * zoom : y,
+    zoom,
+  };
+  // `setViewport` is a no-op before the pan/zoom instance exists (the very first commit).
+  if (!panZoom) return;
+  void setViewport(next);
+}
+
 function CanvasShellWithHelperLines<NodeType extends Node, EdgeType extends Edge>({
   onNodesChange,
   children,

package/src/canvas-shell/use-measured-nodes.ts

@@ -0,0 +1,101 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import type { Node, NodeChange, OnNodesChange } from "@xyflow/react";
+
+/**
+ * Feed React Flow's own measurements back onto the node objects a CONTROLLED canvas
+ * renders.
+ *
+ * React Flow measures every node in the DOM and keeps the result on its INTERNAL node
+ * record; the objects the consumer passed in `nodes` are never touched. That is fine for
+ * the renderer — edges and the viewport read the internal record — but three shipped
+ * surfaces read `node.measured` off the USER object instead, and each of them silently
+ * degrades when it is absent:
+ *
+ * - **`<MiniMap>`** bails out per node in `nodeHasDimensions(internals.userNode)` and
+ *   renders NOTHING. Measured: a `CanvasShell` with 11 nodes drew 0 minimap rects while
+ *   the minimap's own `viewBox` (computed from the internal records) was correct — a
+ *   blank white panel, in the flow package's own `FlowMiniMap` story as much as in a
+ *   composing package's.
+ * - **`layoutFlow`** falls back to `DEFAULT_NODE_WIDTH`/`DEFAULT_NODE_HEIGHT`
+ *   (172×40) and hands dagre a node half the height of the real card, so ranks are laid
+ *   out too close together and edge labels collide with the nodes below them.
+ * - Any consumer arithmetic over `node.measured` — the same trap, one layer out.
+ *
+ * React Flow's own examples never hit this because they drive the canvas with
+ * `useNodesState`, whose `onNodesChange` applies the `dimensions` change back into the
+ * array. A canvas driven from derived data (a discovered process graph, a layout hook)
+ * legitimately has no such setter, and gets a half-working canvas with no error. This
+ * hook closes that gap centrally so no consumer has to know about it: it remembers the
+ * dimensions React Flow reports and merges them into the nodes on the way past.
+ *
+ * It is deliberately a NO-OP in the two cases where React Flow already does the right
+ * thing: an UNCONTROLLED canvas (`defaultNodes`, where `hasDefaultNodes` makes React Flow
+ * apply the changes itself) never reaches here because `nodes` is undefined, and a
+ * controlled canvas whose consumer already applies dimension changes finds `measured`
+ * equal to the cached value and returns the very same array identity.
+ */
+export interface MeasuredNodesResult<NodeType extends Node> {
+  /** `nodes`, with React Flow's measured dimensions merged in. Same identity when nothing changed. */
+  nodes: NodeType[] | undefined;
+  /** The handler to give React Flow — records dimensions, then calls the consumer's own. */
+  onNodesChange: OnNodesChange<NodeType> | undefined;
+}
+
+export function useMeasuredNodes<NodeType extends Node>(
+  nodes: NodeType[] | undefined,
+  onNodesChange: OnNodesChange<NodeType> | undefined,
+): MeasuredNodesResult<NodeType> {
+  const measured = useRef(new Map<string, { width: number; height: number }>());
+  // A version counter, not the map itself: the map is a ref so the change handler stays
+  // stable, and this is what tells the memo below that its contents moved.
+  const [version, setVersion] = useState(0);
+
+  const handleNodesChange = useCallback<OnNodesChange<NodeType>>(
+    (changes: NodeChange<NodeType>[]) => {
+      let touched = false;
+      for (const change of changes) {
+        if (change.type !== "dimensions" || !change.dimensions) continue;
+        const previous = measured.current.get(change.id);
+        if (
+          previous?.width === change.dimensions.width &&
+          previous.height === change.dimensions.height
+        ) {
+          continue;
+        }
+        measured.current.set(change.id, { ...change.dimensions });
+        touched = true;
+      }
+      onNodesChange?.(changes);
+      if (touched) setVersion((n) => n + 1);
+    },
+    [onNodesChange],
+  );
+
+  const mergedNodes = useMemo(() => {
+    if (!nodes) return nodes;
+    // `version` is read so this recomputes when the ref's contents move; the map itself
+    // is intentionally not a dependency (a ref never changes identity).
+    void version;
+    let changed = false;
+    const next = nodes.map((node) => {
+      const dimensions = measured.current.get(node.id);
+      if (!dimensions) return node;
+      if (
+        node.measured?.width === dimensions.width &&
+        node.measured?.height === dimensions.height
+      ) {
+        return node;
+      }
+      changed = true;
+      return { ...node, measured: dimensions };
+    });
+    return changed ? next : nodes;
+  }, [nodes, version]);
+
+  return {
+    nodes: mergedNodes,
+    // Only take the handler over when there is something to measure INTO. An uncontrolled
+    // canvas is left exactly as it was.
+    onNodesChange: nodes ? handleNodesChange : onNodesChange,
+  };
+}

package/src/flow-button-edge/flow-button-edge.stories.tsx

@@ -2,10 +2,12 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
 import "@xyflow/react/dist/style.css";
 import { useCallback, useEffect, useRef } from "react";
 import { useEdgesState, useNodesState } from "@xyflow/react";
+import { expect, waitFor } from "storybook/test";
 import { CanvasShell } from "../canvas-shell";
 import { FlowNode, type BrandFlowNode } from "../flow-node";
 import { useFlowLayout } from "../flow-layout";
 import { ZoomControls } from "../zoom-controls";
+import { edgePaths, endpointsOffHandles } from "../testing/edge-anchors";
 import { FlowButtonEdge, type BrandFlowButtonEdge } from "./flow-button-edge";
 
 const nodeTypes = { brand: FlowNode };
@@ -20,6 +22,14 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+/** Every edge must terminate ON a handle dot — see `testing/edge-anchors`. */
+async function expectAnchoredToHandles(canvasElement: HTMLElement, edgeCount: number) {
+  await waitFor(() => {
+    expect(edgePaths(canvasElement, "flow-button-edge")).toHaveLength(edgeCount);
+    expect(endpointsOffHandles(canvasElement, "flow-button-edge")).toEqual([]);
+  });
+}
+
 /** Two nodes joined by a button edge — hover/focus the "+" to see it. */
 export const Default: Story = {
   render: () => {
@@ -46,6 +56,9 @@ export const Default: Story = {
       </div>
     );
   },
+  play: async ({ canvasElement }) => {
+    await expectAnchoredToHandles(canvasElement, 1);
+  },
 };
 
 // ---------------------------------------------------------------------------

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

@@ -1,11 +1,6 @@
-import {
-  BaseEdge,
-  EdgeLabelRenderer,
-  getBezierPath,
-  type Edge,
-  type EdgeProps,
-} from "@xyflow/react";
+import { EdgeLabelRenderer, getBezierPath, type Edge, type EdgeProps } from "@xyflow/react";
 import { Plus } from "lucide-react";
+import { FlowEdgePath } from "../flow-edge-path";
 
 export interface FlowButtonEdgeData extends Record<string, unknown> {
   /** aria-label for the insert button. @default "Insert node on edge" */
@@ -51,11 +46,14 @@ export function FlowButtonEdge({
 
   return (
     <>
-      <BaseEdge
+      <FlowEdgePath
         id={id}
         path={edgePath}
         markerEnd={markerEnd}
-        style={{ stroke: "var(--flow-edge)", strokeWidth: 1.5, ...style }}
+        data-slot="flow-button-edge"
+        stroke="var(--flow-edge)"
+        strokeWidth={1.5}
+        style={style}
       />
       <EdgeLabelRenderer>
         <div
@@ -69,7 +67,7 @@ export function FlowButtonEdge({
             type="button"
             aria-label={label}
             onClick={() => data?.onInsert?.()}
-            className="flex size-5 items-center justify-center rounded-full border border-flow-group-border bg-flow-node text-flow-node-foreground shadow-sm 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"
+            className="flex size-5 items-center justify-center rounded-full border border-flow-group-border bg-flow-node text-flow-node-foreground shadow-sm transition-colors duration-fast ease-standard hover:bg-accent hover:text-accent-foreground focus-ring"
           >
             <Plus className="size-3" aria-hidden="true" />
           </button>

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

@@ -1,8 +1,10 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import "@xyflow/react/dist/style.css";
 import { type Edge } from "@xyflow/react";
+import { expect, waitFor } from "storybook/test";
 import { CanvasShell } from "../canvas-shell";
 import { FlowNode, type BrandFlowNode } from "../flow-node";
+import { edgePaths, endpointsOffHandles } from "../testing/edge-anchors";
 import { FlowEdge } from "./flow-edge";
 
 const nodeTypes = { brand: FlowNode };
@@ -17,6 +19,18 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+/**
+ * Every edge must terminate ON a handle dot — see `testing/edge-anchors`. React
+ * Flow's native anchors land on the dot's outer rim; the assertion allows
+ * anywhere on the dot, and fails on a line that meets a bare stretch of border.
+ */
+async function expectAnchoredToHandles(canvasElement: HTMLElement, edgeCount: number) {
+  await waitFor(() => {
+    expect(edgePaths(canvasElement, "flow-edge")).toHaveLength(edgeCount);
+    expect(endpointsOffHandles(canvasElement, "flow-edge")).toEqual([]);
+  });
+}
+
 /** Two nodes connected by a single branded bezier edge. */
 export const Default: Story = {
   render: () => {
@@ -41,6 +55,9 @@ export const Default: Story = {
       </div>
     );
   },
+  play: async ({ canvasElement }) => {
+    await expectAnchoredToHandles(canvasElement, 1);
+  },
 };
 
 /** A small pipeline with multiple branded edges. */
@@ -76,4 +93,7 @@ export const Pipeline: Story = {
       </div>
     );
   },
+  play: async ({ canvasElement }) => {
+    await expectAnchoredToHandles(canvasElement, 2);
+  },
 };

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

@@ -1,8 +1,12 @@
-import { BaseEdge, getBezierPath, type EdgeProps } from "@xyflow/react";
+import { getBezierPath, type EdgeProps } from "@xyflow/react";
+import { FlowEdgePath } from "../flow-edge-path";
 
 /**
  * Branded bezier edge using the `--flow-edge` token. Register it in
  * `edgeTypes={{ brand: FlowEdge }}` and create edges with `type: "brand"`.
+ *
+ * Drawn through `FlowEdgePath`, so it carries the shared keyboard focus
+ * indicator (#286) — never reach for React Flow's `BaseEdge` directly.
  */
 export function FlowEdge({
   id,
@@ -24,11 +28,14 @@ export function FlowEdge({
     targetPosition,
   });
   return (
-    <BaseEdge
+    <FlowEdgePath
       id={id}
       path={edgePath}
       markerEnd={markerEnd}
-      style={{ stroke: "var(--flow-edge)", strokeWidth: 1.5, ...style }}
+      data-slot="flow-edge"
+      stroke="var(--flow-edge)"
+      strokeWidth={1.5}
+      style={style}
     />
   );
 }

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