@elabs-ai/components-flow 4.1.0 → 5.0.0

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

@@ -0,0 +1,399 @@
+import type { Edge, Node, XYPosition } from "@xyflow/react";
+import type { FlowElkBackbone } from "./backbone";
+import {
+  HANDLE_BY_DIRECTION,
+  layoutFlow,
+  type FlowLayoutDirection,
+  type FlowLayoutResult,
+} from "./flow-layout";
+
+/**
+ * elkjs layout adapter — RM-067.
+ *
+ * dagre has no self-loop layout, no edge routing and weak compound nodes. ELK (Eclipse
+ * Layout Kernel, EPL-2.0) has all three, and it is large — so it is an OPTIONAL peer of this
+ * package, reached ONLY through `import()` inside {@link layoutFlowElk}'s body. A consumer
+ * that never calls it never downloads it, and a consumer that calls it without installing
+ * elkjs gets `layoutFlow`'s dagre answer plus a development-only console warning, never a
+ * crash.
+ *
+ * The default engine runs inline on the calling thread (elkjs's own in-thread worker
+ * stand-in). The package deliberately ships NO worker entry: a `new Worker(new URL(…,
+ * import.meta.url))` pointing at a file the tsup build does not emit breaks some consumer
+ * bundlers at build time. A host that wants the layout off the main thread supplies
+ * `loadEngine` with its own worker, e.g.
+ *
+ * ```ts
+ * loadEngine: async () => {
+ *   const { default: ELK } = await import("elkjs/lib/elk-api.js");
+ *   return new ELK({ workerUrl: new URL("elkjs/lib/elk-worker.min.js", import.meta.url).href });
+ * }
+ * ```
+ *
+ * No remote origin is involved either way.
+ */
+
+/** Options for {@link layoutFlowElk}. */
+export interface FlowLayoutElkOptions {
+  /** Layout direction. @default "TB" */
+  direction?: FlowLayoutDirection;
+  /** How ELK routes edges. @default "splines" */
+  edgeRouting?: "orthogonal" | "splines";
+  /** Route back-edges as ELK feedback edges (around the graph, not through it). @default true */
+  feedbackEdges?: boolean;
+  /** Gap between nodes in the same layer. @default 48 */
+  nodeSpacing?: number;
+  /** Gap between layers. @default 72 */
+  rankSpacing?: number;
+  /**
+   * Compound nodes. Each `id` names a node already in `nodes` (typically a `FlowGroupNode`);
+   * its `children` are laid out inside it and come back with `parentId` set, positioned
+   * relative to the group, and the group comes back sized to fit them.
+   */
+  groups?: { id: string; children: string[] }[];
+  /** A pinned straight path — see `pinBackbone`. */
+  backbone?: FlowElkBackbone;
+  /**
+   * Supply the engine yourself: a host with its own worker URL, or a test. Rejecting (for
+   * example because elkjs is not installed) falls back to dagre exactly like the default
+   * loader does.
+   */
+  loadEngine?: () => Promise<FlowElkEngine>;
+}
+
+/** A graph in ELK's JSON format — the minimal shape this adapter reads and writes. */
+export interface FlowElkGraph {
+  id: string;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  layoutOptions?: Record<string, string>;
+  children?: FlowElkGraph[];
+  edges?: {
+    id: string;
+    sources: string[];
+    targets: string[];
+    layoutOptions?: Record<string, string>;
+  }[];
+}
+
+/** A running ELK engine. `new ELK()` from elkjs satisfies it. */
+export interface FlowElkEngine {
+  layout(graph: FlowElkGraph): Promise<FlowElkGraph>;
+}
+
+/** What {@link layoutFlowElk} answers — `layoutFlow`'s result plus which engine produced it. */
+export interface FlowLayoutElkResult<
+  NodeType extends Node = Node,
+  EdgeType extends Edge = Edge,
+> extends FlowLayoutResult<NodeType, EdgeType> {
+  /** `"elk"`, or `"dagre"` when elkjs could not be loaded or failed and dagre answered. */
+  engine: "elk" | "dagre";
+}
+
+const ELK_DIRECTION: Record<FlowLayoutDirection, string> = {
+  TB: "DOWN",
+  BT: "UP",
+  LR: "RIGHT",
+  RL: "LEFT",
+};
+
+/** Room above a group's children for its header, matching `groupNodes`' own offset. */
+const GROUP_PADDING = "[top=60,left=16,bottom=16,right=16]";
+
+/**
+ * Straightness priority for backbone edges, against the default `0` of every other edge —
+ * enough for network-simplex placement to favour them in every tie it breaks.
+ */
+const BACKBONE_STRAIGHTNESS = "100";
+
+const DEFAULT_NODE_WIDTH = 172;
+const DEFAULT_NODE_HEIGHT = 40;
+
+function nodeSize(node: Node): { width: number; height: number } {
+  return {
+    width: node.measured?.width ?? node.width ?? DEFAULT_NODE_WIDTH,
+    height: node.measured?.height ?? node.height ?? DEFAULT_NODE_HEIGHT,
+  };
+}
+
+/** CommonJS interop: elkjs ships CJS, which bundlers and Node wrap in `default` differently. */
+function interopDefault<T>(mod: unknown): T {
+  let value = mod as { default?: unknown };
+  while (value && typeof value === "object" && "default" in value && value.default) {
+    value = value.default as { default?: unknown };
+  }
+  return value as T;
+}
+
+type ElkConstructor = new (args: { workerFactory: (url?: string) => unknown }) => FlowElkEngine;
+
+type FakeWorkerConstructor = new (url?: string) => unknown;
+
+/** The default engine: elkjs run inline on the calling thread (see the module docblock). */
+async function loadDefaultEngine(): Promise<FlowElkEngine> {
+  const ELK = interopDefault<ElkConstructor>(await import("elkjs/lib/elk-api.js"));
+  // `elk-worker.min.js` exports `{ default: FakeWorker, Worker: FakeWorker }` outside a worker.
+  // @ts-expect-error -- elkjs ships no declaration for the minified worker; the shape is narrowed below.
+  const mod = (await import("elkjs/lib/elk-worker.min.js")) as {
+    Worker?: FakeWorkerConstructor;
+    default?: FakeWorkerConstructor | { Worker?: FakeWorkerConstructor };
+  };
+  const FakeWorker =
+    mod.Worker ?? (typeof mod.default === "function" ? mod.default : mod.default?.Worker);
+  if (FakeWorker === undefined) throw new Error("elkjs inline worker not found");
+  return new ELK({ workerFactory: (url) => new FakeWorker(url) });
+}
+
+function warnFallback(error: unknown): void {
+  if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
+  console.warn(
+    "[@elabs-ai/components-flow] layoutFlowElk could not run elkjs (is the optional peer " +
+      "`elkjs` installed?) — falling back to the dagre layout.",
+    error,
+  );
+}
+
+/** Build ELK's hierarchical graph, nesting grouped nodes under their group. */
+function toElkGraph(nodes: Node[], edges: Edge[], options: FlowLayoutElkOptions): FlowElkGraph {
+  const {
+    direction = "TB",
+    edgeRouting = "splines",
+    feedbackEdges = true,
+    nodeSpacing = 48,
+    rankSpacing = 72,
+    groups = [],
+    backbone,
+  } = options;
+
+  const ids = new Set(nodes.map((n) => n.id));
+  const straight = new Set(backbone?.edgeIds ?? []);
+  const parentOf = new Map<string, string>();
+  const groupIds = new Set<string>();
+  for (const group of groups) {
+    if (!ids.has(group.id)) continue;
+    groupIds.add(group.id);
+    for (const child of group.children) {
+      if (ids.has(child) && child !== group.id) parentOf.set(child, group.id);
+    }
+  }
+
+  const elkNodes = new Map<string, FlowElkGraph>();
+  for (const node of nodes) {
+    const isGroup = groupIds.has(node.id);
+    elkNodes.set(node.id, {
+      id: node.id,
+      // A group is sized by ELK from its children; a leaf keeps its measured size.
+      ...(isGroup ? { layoutOptions: { "elk.padding": GROUP_PADDING } } : nodeSize(node)),
+    });
+  }
+
+  const root: FlowElkGraph = {
+    id: "__flow_elk_root__",
+    layoutOptions: {
+      "elk.algorithm": "layered",
+      "elk.direction": ELK_DIRECTION[direction],
+      "elk.edgeRouting": edgeRouting === "orthogonal" ? "ORTHOGONAL" : "SPLINES",
+      "elk.spacing.nodeNode": String(nodeSpacing),
+      "elk.layered.spacing.nodeNodeBetweenLayers": String(rankSpacing),
+      "elk.layered.feedbackEdges": String(feedbackEdges),
+      // Break cycles by input order, as a reader would: the edge pointing back to an
+      // EARLIER node is the reversed one — the same edge dagre reports.
+      "elk.layered.cycleBreaking.strategy": "MODEL_ORDER",
+      "elk.hierarchyHandling": groupIds.size > 0 ? "INCLUDE_CHILDREN" : "INHERIT",
+      ...(backbone && backbone.nodeIds.length > 0
+        ? { "elk.layered.nodePlacement.strategy": "NETWORK_SIMPLEX" }
+        : {}),
+    },
+    children: [],
+    edges: edges
+      .filter((edge) => ids.has(edge.source) && ids.has(edge.target))
+      .map((edge) => ({
+        id: edge.id,
+        sources: [edge.source],
+        targets: [edge.target],
+        ...(straight.has(edge.id)
+          ? { layoutOptions: { "elk.layered.priority.straightness": BACKBONE_STRAIGHTNESS } }
+          : {}),
+      })),
+  };
+
+  for (const node of nodes) {
+    const elkNode = elkNodes.get(node.id)!;
+    const parent = resolveParent(node.id, parentOf);
+    const container = parent === undefined ? root : elkNodes.get(parent)!;
+    (container.children ??= []).push(elkNode);
+  }
+  return root;
+}
+
+/** A node's group, ignoring any parent chain that would loop back onto itself. */
+function resolveParent(id: string, parentOf: Map<string, string>): string | undefined {
+  const parent = parentOf.get(id);
+  if (parent === undefined) return undefined;
+  const seen = new Set([id]);
+  let cursor: string | undefined = parent;
+  while (cursor !== undefined) {
+    if (seen.has(cursor)) return undefined;
+    seen.add(cursor);
+    cursor = parentOf.get(cursor);
+  }
+  return parent;
+}
+
+interface PlacedNode {
+  relative: XYPosition;
+  absolute: XYPosition;
+  width?: number;
+  height?: number;
+  parentId?: string;
+}
+
+function collectPlacements(
+  graph: FlowElkGraph,
+  origin: XYPosition,
+  parentId: string | undefined,
+  out: Map<string, PlacedNode>,
+): void {
+  for (const child of graph.children ?? []) {
+    const relative = { x: child.x ?? 0, y: child.y ?? 0 };
+    const absolute = { x: origin.x + relative.x, y: origin.y + relative.y };
+    out.set(child.id, {
+      relative,
+      absolute,
+      width: child.width,
+      height: child.height,
+      ...(parentId === undefined ? {} : { parentId }),
+    });
+    if (child.children && child.children.length > 0) {
+      collectPlacements(child, absolute, child.id, out);
+    }
+  }
+}
+
+/**
+ * Put the backbone's nodes on one line by translating each of their LAYERS along the cross
+ * axis. ELK's straightness priority gets close but does not guarantee a line; shifting a
+ * whole layer does, and cannot overlap two nodes of that layer. Only top-level nodes are
+ * moved — a node inside a group is positioned relative to it.
+ */
+function straightenBackbone(
+  placements: Map<string, PlacedNode>,
+  nodeIds: readonly string[],
+  direction: FlowLayoutDirection,
+): void {
+  const along = direction === "LR" || direction === "RL" ? "x" : "y";
+  const cross = along === "x" ? "y" : "x";
+  const extent = (p: PlacedNode, axis: "x" | "y") => (axis === "x" ? p.width : p.height) ?? 0;
+  const centerOf = (p: PlacedNode) => p.absolute[cross] + extent(p, cross) / 2;
+
+  const pinned = nodeIds
+    .map((id) => placements.get(id))
+    .filter((p): p is PlacedNode => p !== undefined && p.parentId === undefined);
+  const first = pinned[0];
+  if (first === undefined) return;
+  const line = centerOf(first);
+
+  const topLevel = [...placements.values()].filter((p) => p.parentId === undefined);
+  const moved = new Set<PlacedNode>();
+  for (const anchor of pinned) {
+    const delta = line - centerOf(anchor);
+    if (delta === 0) continue;
+    const start = anchor.absolute[along];
+    const end = start + extent(anchor, along);
+    for (const p of topLevel) {
+      if (moved.has(p)) continue;
+      const pStart = p.absolute[along];
+      if (pStart >= end || pStart + extent(p, along) <= start) continue;
+      p.absolute = { ...p.absolute, [cross]: p.absolute[cross] + delta };
+      p.relative = { ...p.relative, [cross]: p.relative[cross] + delta };
+      moved.add(p);
+    }
+  }
+}
+
+/**
+ * Lay a graph out with ELK's layered algorithm — `layoutFlow`'s async sibling.
+ *
+ * Same result shape as `layoutFlow` (`nodes`, `edges`, `backEdges`, `selfLoops`), so a
+ * caller can swap engines without a different consumption path; `engine` says which one
+ * actually answered. Self-loops are laid out by ELK (it routes them around their node) and
+ * still reported in `selfLoops`; `backEdges` are the edges whose source sits at or after
+ * their target along the layout direction.
+ *
+ * elkjs is imported lazily inside this function. If it is not installed, or ELK throws,
+ * the result is `layoutFlow`'s dagre layout with `engine: "dagre"`.
+ */
+export async function layoutFlowElk<NodeType extends Node = Node, EdgeType extends Edge = Edge>(
+  nodes: NodeType[],
+  edges: EdgeType[],
+  options: FlowLayoutElkOptions = {},
+): Promise<FlowLayoutElkResult<NodeType, EdgeType>> {
+  const direction = options.direction ?? "TB";
+
+  let laidOut: FlowElkGraph;
+  try {
+    const engine = await (options.loadEngine ?? loadDefaultEngine)();
+    laidOut = await engine.layout(toElkGraph(nodes, edges, options));
+  } catch (error) {
+    warnFallback(error);
+    return {
+      ...layoutFlow(nodes, edges, {
+        direction,
+        ...(options.nodeSpacing === undefined ? {} : { nodeSpacing: options.nodeSpacing }),
+        ...(options.rankSpacing === undefined ? {} : { rankSpacing: options.rankSpacing }),
+      }),
+      engine: "dagre",
+    };
+  }
+
+  const placements = new Map<string, PlacedNode>();
+  collectPlacements(laidOut, { x: 0, y: 0 }, undefined, placements);
+  if (options.backbone) straightenBackbone(placements, options.backbone.nodeIds, direction);
+
+  const handles = HANDLE_BY_DIRECTION[direction];
+  const groupIds = new Set((options.groups ?? []).map((group) => group.id));
+  const layoutedNodes = nodes.map((node) => {
+    const placed = placements.get(node.id);
+    if (!placed) return node;
+    const next: NodeType = {
+      ...node,
+      sourcePosition: handles.source,
+      targetPosition: handles.target,
+      position: placed.relative,
+    };
+    if (placed.parentId !== undefined) {
+      next.parentId = placed.parentId;
+      next.extent = "parent";
+    }
+    if (groupIds.has(node.id) && placed.width !== undefined && placed.height !== undefined) {
+      next.width = placed.width;
+      next.height = placed.height;
+    }
+    return next;
+  });
+
+  const selfLoops: string[] = [];
+  const backEdges: string[] = [];
+  const axis = direction === "LR" || direction === "RL" ? "x" : "y";
+  const sign = direction === "BT" || direction === "RL" ? -1 : 1;
+  const center = (id: string): number | undefined => {
+    const placed = placements.get(id);
+    if (!placed) return undefined;
+    const size = axis === "x" ? (placed.width ?? 0) : (placed.height ?? 0);
+    return sign * (placed.absolute[axis] + size / 2);
+  };
+  for (const edge of edges) {
+    if (edge.source === edge.target) {
+      selfLoops.push(edge.id);
+      continue;
+    }
+    const source = center(edge.source);
+    const target = center(edge.target);
+    if (source === undefined || target === undefined) continue;
+    if (source >= target) backEdges.push(edge.id);
+  }
+
+  return { nodes: layoutedNodes, edges, backEdges, selfLoops, engine: "elk" };
+}

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

@@ -135,6 +135,26 @@ export const Default: Story = {
       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.
+    // Transitions keep starting after the first batch settles: a child's inherited
+    // colour starts its own once the parent's has ended, and a superseded one rejects
+    // `finished` while its replacement is still running. So keep waiting
+    // until none is left; awaiting only the first batch still read the white panel
+    // once on CI.
+    for (;;) {
+      const running = minimap.getAnimations({ subtree: true });
+      if (running.length === 0) break;
+      await Promise.allSettled(running.map((animation) => animation.finished));
+    }
     const panelBackground = getComputedStyle(minimap).backgroundColor;
 
     // The whole point of this helper is that a blank minimap must FAIL the check — lock

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

@@ -204,6 +204,43 @@ export const FocusIndicator: Story = {
       return (hi! + 0.05) / (lo! + 0.05);
     };
 
+    // Since ADR 0027 Amendment 2 (commit 779c040b), the shared `focus-ring*`
+    // composite always paints its ring as three `box-shadow` layers: a
+    // `var(--background)`-coloured "gap" segment and an inset echo segment
+    // that both have zero offset/blur/spread by construction at this node's
+    // default geometry (they exist for OTHER call sites with a non-zero
+    // `--focus-ring-offset`), plus the one visible ring segment in between.
+    // A zero-geometry layer paints nothing, so comparing the raw `boxShadow`
+    // string byte-for-byte (its old shape, before Amendment 2, had no such
+    // padding layers) now reports a difference where nothing actually
+    // renders differently. Splitting into layers and keeping only the ones
+    // with a non-zero length lets the assertion below compare what is
+    // genuinely PAINTED — the resting selection ring plus the node's
+    // elevation shadow — while staying just as strict: drop the ring
+    // entirely, or change its colour/width, and the visible layers stop
+    // matching.
+    const splitShadowLayers = (shadowValue: string): string[] => {
+      const layers: string[] = [];
+      let depth = 0;
+      let current = "";
+      for (const char of shadowValue) {
+        if (char === "(") depth += 1;
+        if (char === ")") depth -= 1;
+        if (char === "," && depth === 0) {
+          layers.push(current.trim());
+          current = "";
+        } else {
+          current += char;
+        }
+      }
+      if (current.trim()) layers.push(current.trim());
+      return layers;
+    };
+    const isVisibleShadowLayer = (layer: string): boolean =>
+      [...layer.matchAll(/(-?[\d.]+)px/g)].some((match) => Number(match[1]) !== 0);
+    const visibleShadow = (shadowValue: string): string =>
+      splitShadowLayers(shadowValue).filter(isVisibleShadowLayer).join(", ");
+
     let plainWrapper!: HTMLElement;
     let plainDiv!: HTMLElement;
     let chosenWrapper!: HTMLElement;
@@ -283,7 +320,9 @@ export const FocusIndicator: Story = {
     await waitFor(() => {
       expect(getComputedStyle(chosenDiv).outlineStyle).toBe("solid");
     });
-    await expect(getComputedStyle(chosenDiv).boxShadow).toBe(restingChosenShadow);
+    await expect(visibleShadow(getComputedStyle(chosenDiv).boxShadow)).toBe(
+      visibleShadow(restingChosenShadow),
+    );
 
     // Blur restores the resting state.
     await userEvent.tab();

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

@@ -194,3 +194,41 @@ describe("FlowSelfLoopEdge", () => {
     expect(pill.parentElement!.style.transform).toContain(`translate(${labelX}px, ${labelY}px)`);
   });
 });
+
+// RM-065 prerequisite — `data.tokens` draws `FlowEdgeTokens` on the loop's own arc.
+describe("FlowSelfLoopEdge data.tokens", () => {
+  it("renders exactly the same markup with an empty list as with the field absent", () => {
+    internalNodeBox.current = measuredNode();
+    const absent = render(<FlowSelfLoopEdge {...makeEdgeProps()} />);
+    const absentHtml = absent.container.innerHTML;
+    expect(absent.container.querySelector('[data-slot="flow-edge-tokens"]')).toBeNull();
+    absent.unmount();
+    const empty = render(<FlowSelfLoopEdge {...makeEdgeProps({ data: { tokens: [] } })} />);
+    expect(empty.container.innerHTML).toBe(absentHtml);
+  });
+
+  it("starts and ends its tokens on the arc's own endpoints, outside the named graphic", () => {
+    internalNodeBox.current = measuredNode();
+    const { container } = render(
+      <FlowSelfLoopEdge
+        {...makeEdgeProps({
+          data: {
+            tokens: [
+              { id: "start", progress: 0 },
+              { id: "end", progress: 1 },
+            ],
+          },
+        })}
+      />,
+    );
+    const [start, end] = Array.from(
+      container.querySelectorAll<SVGCircleElement>('[data-slot="flow-edge-tokens-token"]'),
+    );
+    const arc = fixtureArc().path;
+    const [sx, sy] = arc.slice(2).split(" ")[0]!.split(",").map(Number);
+    expect(start!.style.transform).toBe(`translate(${sx}px, ${sy}px)`);
+    const [ex, ey] = arc.trim().split(" ").at(-1)!.split(",").map(Number);
+    expect(end!.style.transform).toBe(`translate(${ex}px, ${ey}px)`);
+    expect(screen.getByRole("img").querySelector('[data-slot="flow-edge-tokens"]')).toBeNull();
+  });
+});

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

@@ -1,6 +1,7 @@
 import { useMemo } from "react";
 import { useEdges, useInternalNode, type Edge, type EdgeProps } from "@xyflow/react";
 import { FlowEdgePath } from "../flow-edge-path";
+import { FlowEdgeTokens, type FlowEdgeToken } from "../flow-edge-tokens";
 import {
   computeEdgeWeightScale,
   DEFAULT_EDGE_WIDTH_RANGE,
@@ -37,6 +38,11 @@ export interface FlowSelfLoopEdgeData extends Record<string, unknown> {
    * own root button from outside this component, without a new semantic prop here.
    */
   labelProps?: Omit<EdgeLabelPillProps, "label" | "secondaryLabel" | "x" | "y" | "selected">;
+  /**
+   * Markers travelling along the loop's computed arc (see `FlowEdgeTokens`). The parent
+   * drives each token's `progress`; omitted or empty renders exactly the edge without them.
+   */
+  tokens?: readonly FlowEdgeToken[];
 }
 
 export type BrandFlowSelfLoopEdge = Edge<FlowSelfLoopEdgeData, "self-loop">;
@@ -159,6 +165,7 @@ export function FlowSelfLoopEdge({
           style={{ fill: "none", ...style }}
         />
       </g>
+      {data?.tokens?.length ? <FlowEdgeTokens path={path} tokens={data.tokens} /> : null}
       <EdgeLabelPill
         label={data?.label}
         secondaryLabel={data?.secondaryLabel}

package/src/flow-weighted-edge/edge-label-pill.test.tsx

@@ -62,4 +62,24 @@ describe("EdgeLabelPill", () => {
     render(<EdgeLabelPill x={0} y={0} label="128×" data-selection="excluded" />);
     expect(screen.getByRole("button")).toHaveAttribute("data-selection", "excluded");
   });
+
+  // #354 — a caller-supplied `aria-label` (the seam #351 built) must win over the pill's
+  // own computed `[label, secondaryLabel].join(" · ")` string, since a composing package
+  // (e.g. `@elabs-ai/components-process`'s `ProcessTransitionEdge`) uses it to replace a
+  // bare printed number with a full, disambiguating sentence naming both endpoints.
+  it("lets a caller-supplied aria-label win over the computed label · secondaryLabel name", () => {
+    render(
+      <EdgeLabelPill
+        x={0}
+        y={0}
+        label="213"
+        aria-label="Transition from Check Credit to Approve Order, Transitions 213"
+      />,
+    );
+    expect(
+      screen.getByRole("button", {
+        name: "Transition from Check Credit to Approve Order, Transitions 213",
+      }),
+    ).toBeInTheDocument();
+  });
 });

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

@@ -406,6 +406,7 @@ export const TenEdgesMixed: Story = {
  * add" for the full trap. Do not "simplify" `nameOf` away.
  */
 export const NamingContractEdges: Story = {
+  name: "Edge names come from node titles, never ids",
   render: function NamingContractEdgesStory() {
     const nodes: BrandFlowNode[] = [
       { id: "n1", type: "brand", position: { x: 0, y: 0 }, data: { kind: "Step", title: "Start" } },

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

@@ -403,3 +403,43 @@ describe("edge focus contour contrast (#286)", () => {
     },
   );
 });
+
+// RM-065 prerequisite — `data.tokens` draws `FlowEdgeTokens` on the edge's own path.
+describe("FlowWeightedEdge data.tokens", () => {
+  it("renders exactly the same markup with an empty list as with the field absent", () => {
+    edgesBox.current = [{ id: "test-edge", data: { weight: 4, label: "4×" } }];
+    const absent = render(
+      <FlowWeightedEdge {...makeEdgeProps({ data: { weight: 4, label: "4×" } })} />,
+    );
+    const absentHtml = absent.container.innerHTML;
+    expect(absent.container.querySelector('[data-slot="flow-edge-tokens"]')).toBeNull();
+    absent.unmount();
+    const empty = render(
+      <FlowWeightedEdge {...makeEdgeProps({ data: { weight: 4, label: "4×", tokens: [] } })} />,
+    );
+    expect(empty.container.innerHTML).toBe(absentHtml);
+  });
+
+  it("draws one token per entry along the SAME path the edge draws", () => {
+    edgesBox.current = [{ id: "test-edge", data: {} }];
+    // The mocked getSmoothStepPath returns a straight `M0,0 L100,100`.
+    const { container } = render(
+      <FlowWeightedEdge
+        {...makeEdgeProps({
+          data: {
+            path: "smoothstep",
+            tokens: [
+              { id: "c1", progress: 0 },
+              { id: "c2", progress: 0.5 },
+            ],
+          },
+        })}
+      />,
+    );
+    const tokens = container.querySelectorAll<SVGCircleElement>(
+      '[data-slot="flow-edge-tokens-token"]',
+    );
+    expect(tokens).toHaveLength(2);
+    expect(tokens[1]!.style.transform).toBe("translate(50px, 50px)");
+  });
+});

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

@@ -11,6 +11,7 @@ import {
 } from "@xyflow/react";
 import { resolveTokenColor } from "@elabs-ai/components-tokens";
 import { FlowEdgePath } from "../flow-edge-path";
+import { FlowEdgeTokens, type FlowEdgeToken } from "../flow-edge-tokens";
 import { EdgeLabelPill, type EdgeLabelPillProps } from "./edge-label-pill";
 import { backEdgeDetour, type BackEdgeNodeRect } from "./back-edge-geometry";
 import {
@@ -63,6 +64,11 @@ export interface FlowWeightedEdgeData extends Record<string, unknown> {
    * own root button from outside this component, without a new semantic prop here.
    */
   labelProps?: Omit<EdgeLabelPillProps, "label" | "secondaryLabel" | "x" | "y" | "selected">;
+  /**
+   * Markers travelling along this edge's computed path (see `FlowEdgeTokens`). The parent
+   * drives each token's `progress`; omitted or empty renders exactly the edge without them.
+   */
+  tokens?: readonly FlowEdgeToken[];
 }
 
 export type BrandFlowWeightedEdge = Edge<FlowWeightedEdgeData, "weighted">;
@@ -295,6 +301,7 @@ export function FlowWeightedEdge({
       ) : (
         edge
       )}
+      {data?.tokens?.length ? <FlowEdgeTokens path={edgePath} tokens={data.tokens} /> : null}
       <EdgeLabelPill
         label={data?.label}
         secondaryLabel={data?.secondaryLabel}

package/src/index.ts

@@ -44,3 +44,16 @@ export * from "./flow-weighted-edge";
 
 // FlowSelfLoopEdge — RM-044
 export * from "./flow-self-loop-edge";
+
+// FlowEdgeTokens — RM-065 prerequisite
+export * from "./flow-edge-tokens";
+
+// elkjs adapter — RM-067
+export {
+  layoutFlowElk,
+  type FlowElkEngine,
+  type FlowElkGraph,
+  type FlowLayoutElkOptions,
+  type FlowLayoutElkResult,
+} from "./flow-layout/layout-flow-elk";
+export { pinBackbone, type FlowElkBackbone } from "./flow-layout/backbone";