@elabs-ai/components-flow 4.1.0 → 5.0.0

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

@@ -0,0 +1,312 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import "@xyflow/react/dist/style.css";
+import { expect, userEvent, waitFor, within } from "storybook/test";
+import { Button, Slider } from "@elabs-ai/components-ui";
+import { CanvasShell } from "../canvas-shell";
+import { FlowNode, type BrandFlowNode } from "../flow-node";
+import { FlowWeightedEdge, type BrandFlowWeightedEdge } from "../flow-weighted-edge";
+import { FlowSelfLoopEdge, type BrandFlowSelfLoopEdge } from "../flow-self-loop-edge";
+import { FlowEdgeTokens } from "./flow-edge-tokens";
+
+const nodeTypes = { brand: FlowNode };
+const edgeTypes = { weighted: FlowWeightedEdge, "self-loop": FlowSelfLoopEdge };
+
+type ProcessEdge = BrandFlowWeightedEdge | BrandFlowSelfLoopEdge;
+
+const meta = {
+  title: "Flow/FlowEdgeTokens",
+  component: FlowEdgeTokens,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "Markers (“tokens”) that sit along an edge’s path at a `progress` between 0 and 1 — " +
+          "the primitive behind process replay. The parent drives `progress`; the part keeps no " +
+          "clock. `FlowWeightedEdge` and `FlowSelfLoopEdge` draw them from `data.tokens` on their " +
+          "own computed path; a custom edge renders `FlowEdgeTokens` with the same `path` it hands " +
+          "to `FlowEdgePath`. Tokens are hidden from assistive technology, so pair them with a " +
+          "text alternative such as a live case count.",
+      },
+    },
+  },
+} satisfies Meta<typeof FlowEdgeTokens>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+function chainNodes(): BrandFlowNode[] {
+  return [
+    {
+      id: "a",
+      type: "brand",
+      position: { x: 0, y: 0 },
+      data: { kind: "Start", title: "Received" },
+    },
+    { id: "b", type: "brand", position: { x: 0, y: 200 }, data: { kind: "Step", title: "Review" } },
+    {
+      id: "c",
+      type: "brand",
+      position: { x: 0, y: 400 },
+      data: { kind: "End", title: "Approved" },
+    },
+  ];
+}
+
+const tokenEls = (root: HTMLElement) =>
+  Array.from(root.querySelectorAll<SVGCircleElement>('[data-slot="flow-edge-tokens-token"]'));
+
+/** `translate(12.5px, 40px)` → `[12.5, 40]`. */
+function tokenPosition(token: SVGCircleElement): [number, number] {
+  const m = /translate\(([-\d.e]+)px,\s*([-\d.e]+)px\)/.exec(token.style.transform);
+  if (!m) throw new Error(`unexpected token transform: ${token.style.transform}`);
+  return [Number(m[1]), Number(m[2])];
+}
+
+/**
+ * The browser's own `getPointAtLength` on the edge's rendered path is the oracle: every token
+ * must sit within a pixel and a half of it, which checks the pure sampler against the real engine.
+ */
+function expectOnPath(token: SVGCircleElement, path: SVGPathElement, progress: number) {
+  const point = path.getPointAtLength(progress * path.getTotalLength());
+  const [x, y] = tokenPosition(token);
+  expect(Math.hypot(x - point.x, y - point.y)).toBeLessThan(1.5);
+}
+
+function Canvas({ edges, caption }: { edges: ProcessEdge[]; caption: string }) {
+  return (
+    <div className="flex flex-col gap-2 p-4">
+      {/* The tokens are aria-hidden; this is the text alternative a consumer owes. */}
+      <p className="text-caption text-muted-foreground">{caption}</p>
+      <div className="h-[560px]">
+        <CanvasShell
+          nodes={chainNodes()}
+          edges={edges}
+          nodeTypes={nodeTypes}
+          edgeTypes={edgeTypes}
+        />
+      </div>
+    </div>
+  );
+}
+
+const STATIC_PROGRESS = [0, 0.25, 0.5, 0.75, 1];
+
+/** Five tokens pinned at 0, ¼, ½, ¾ and 1 of a bezier edge, and a smoothstep edge carrying one at ½. */
+export const StaticPositions: Story = {
+  args: { path: "", tokens: [] },
+  render: () => (
+    <Canvas
+      caption="Five cases between Received and Review; one case between Review and Approved."
+      edges={[
+        {
+          id: "e-ab",
+          source: "a",
+          target: "b",
+          type: "weighted",
+          data: {
+            weight: 5,
+            tokens: STATIC_PROGRESS.map((progress) => ({ id: `ab-${progress}`, progress })),
+          },
+        },
+        {
+          id: "e-bc",
+          source: "b",
+          target: "c",
+          type: "weighted",
+          data: {
+            weight: 1,
+            path: "smoothstep",
+            tokens: [{ id: "bc-half", progress: 0.5, radius: 6 }],
+          },
+        },
+      ]}
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    await waitFor(() => expect(tokenEls(canvasElement)).toHaveLength(6));
+    const [ab, bc] = Array.from(
+      canvasElement.querySelectorAll<SVGPathElement>('[data-slot="flow-weighted-edge"]'),
+    );
+    const tokens = tokenEls(canvasElement);
+    STATIC_PROGRESS.forEach((progress, i) => expectOnPath(tokens[i]!, ab!, progress));
+    expectOnPath(tokens[5]!, bc!, 0.5);
+    await expect(tokens[5]).toHaveAttribute("r", "6");
+    // Decorative to assistive technology: the caption carries the meaning.
+    for (const group of canvasElement.querySelectorAll('[data-slot="flow-edge-tokens"]')) {
+      await expect(group).toHaveAttribute("aria-hidden", "true");
+    }
+  },
+};
+
+function ScrubbedEdge() {
+  const [percent, setPercent] = useState(10);
+  return (
+    <div className="flex flex-col gap-2 p-4">
+      <div className="flex max-w-sm flex-col gap-2">
+        <p className="text-caption text-muted-foreground">
+          Case 1042 is {percent}% of the way to Review.
+        </p>
+        <Slider
+          aria-label="Case 1042 progress"
+          min={0}
+          max={100}
+          step={10}
+          value={[percent]}
+          onValueChange={(v) => setPercent(v[0] ?? 0)}
+        />
+      </div>
+      <div className="h-[520px]">
+        <CanvasShell
+          nodes={chainNodes().slice(0, 2)}
+          edges={[
+            {
+              id: "e-ab",
+              source: "a",
+              target: "b",
+              type: "weighted",
+              data: { weight: 3, tokens: [{ id: "case-1042", progress: percent / 100 }] },
+            },
+          ]}
+          nodeTypes={nodeTypes}
+          edgeTypes={edgeTypes}
+        />
+      </div>
+    </div>
+  );
+}
+
+/** The parent owns `progress`: drag or arrow-key the slider and the token follows the edge. */
+export const ParentDrivenProgress: Story = {
+  args: { path: "", tokens: [] },
+  render: () => <ScrubbedEdge />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await waitFor(() => expect(tokenEls(canvasElement)).toHaveLength(1));
+    const path = canvasElement.querySelector<SVGPathElement>('[data-slot="flow-weighted-edge"]')!;
+    const token = tokenEls(canvasElement)[0]!;
+    expectOnPath(token, path, 0.1);
+
+    const thumb = canvas.getByRole("slider", { name: "Case 1042 progress" });
+    thumb.focus();
+    await userEvent.keyboard("{ArrowRight}{ArrowRight}{ArrowRight}{ArrowRight}");
+    await canvas.findByText("Case 1042 is 50% of the way to Review.");
+    // Same element — keyed by token id — now at the new progress.
+    await waitFor(() => expectOnPath(tokenEls(canvasElement)[0]!, path, 0.5));
+    await expect(tokenEls(canvasElement)[0]).toBe(token);
+
+    await userEvent.keyboard("{End}");
+    await waitFor(() => expectOnPath(tokenEls(canvasElement)[0]!, path, 1));
+  },
+};
+
+function SteppedEdge() {
+  const [progress, setProgress] = useState(0);
+  return (
+    <div className="flex flex-col gap-2 p-4">
+      <div className="flex items-center gap-2">
+        <Button
+          size="sm"
+          variant="outline"
+          onClick={() => setProgress((p) => (p >= 1 ? 0 : p + 0.5))}
+        >
+          Advance case
+        </Button>
+        <p className="text-caption text-muted-foreground">Case 7 at {progress * 100}%.</p>
+      </div>
+      <div className="h-[520px]">
+        <CanvasShell
+          nodes={chainNodes().slice(0, 2)}
+          edges={[
+            {
+              id: "e-ab",
+              source: "a",
+              target: "b",
+              type: "weighted",
+              data: { weight: 3, tokens: [{ id: "case-7", progress }] },
+            },
+          ]}
+          nodeTypes={nodeTypes}
+          edgeTypes={edgeTypes}
+        />
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Under reduced motion a token jumps straight to its new position: the motion gate collapses the
+ * transform transition to `--motion-min`, and a reduced `useReducedMotion()` drops the transition
+ * class outright.
+ */
+export const ReducedMotion: Story = {
+  args: { path: "", tokens: [] },
+  globals: { motionPref: "reduced" },
+  render: () => <SteppedEdge />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await waitFor(() => expect(tokenEls(canvasElement)).toHaveLength(1));
+
+    await userEvent.click(canvas.getByRole("button", { name: "Advance case" }));
+    await canvas.findByText("Case 7 at 50%.");
+    const token = tokenEls(canvasElement)[0]!;
+    // No perceptible transition: either the class is gone (a reduced `useReducedMotion()`) or the
+    // motion gate has collapsed `duration-fast` to a few hundredths of a millisecond.
+    const durations = getComputedStyle(token)
+      .transitionDuration.split(",")
+      .map((d) => parseFloat(d) * (d.trim().endsWith("ms") ? 1 : 1000));
+    await expect(Math.max(...durations)).toBeLessThan(1);
+    // The painted position is the target one once the canvas settles. The path is re-queried
+    // on every attempt: React Flow may re-render the edge (a late fitView on a slow CI runner),
+    // and a path element read before that would still report the old geometry.
+    await waitFor(() => {
+      const path = canvasElement.querySelector<SVGPathElement>('[data-slot="flow-weighted-edge"]')!;
+      const point = path.getPointAtLength(0.5 * path.getTotalLength());
+      const matrix = new DOMMatrixReadOnly(getComputedStyle(tokenEls(canvasElement)[0]!).transform);
+      expect(Math.hypot(matrix.e - point.x, matrix.f - point.y)).toBeLessThan(1.5);
+    });
+  },
+};
+
+/** Tokens travel the self-loop’s own arc, from the source handle round to the target handle. */
+export const SelfLoop: Story = {
+  args: { path: "", tokens: [] },
+  render: () => (
+    <Canvas
+      caption="Three cases repeating Review."
+      edges={[
+        { id: "e-ab", source: "a", target: "b", type: "weighted", data: { weight: 6 } },
+        { id: "e-bc", source: "b", target: "c", type: "weighted", data: { weight: 4 } },
+        {
+          id: "e-bb",
+          source: "b",
+          target: "b",
+          type: "self-loop",
+          data: {
+            weight: 2,
+            tokens: [
+              { id: "r1", progress: 0.2 },
+              { id: "r2", progress: 0.5 },
+              { id: "r3", progress: 0.8 },
+            ],
+          },
+        },
+      ]}
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    await waitFor(() => {
+      expect(tokenEls(canvasElement)).toHaveLength(3);
+      expect(canvasElement.querySelector('[data-slot="flow-self-loop-edge"]')).not.toBeNull();
+    });
+    // The arc is recomputed once the node is measured — read it after it settles.
+    await waitFor(() => {
+      const loop = canvasElement.querySelector<SVGPathElement>(
+        '[data-slot="flow-self-loop-edge"]',
+      )!;
+      const tokens = tokenEls(canvasElement);
+      [0.2, 0.5, 0.8].forEach((progress, i) => expectOnPath(tokens[i]!, loop, progress));
+    });
+  },
+};

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

@@ -0,0 +1,115 @@
+import { cleanup, render } from "@testing-library/react";
+import { createRef, type ReactElement } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import { DEFAULT_EDGE_TOKEN_RADIUS, FlowEdgeTokens } from "./flow-edge-tokens";
+
+afterEach(cleanup);
+
+function renderTokens(ui: ReactElement) {
+  return render(<svg>{ui}</svg>);
+}
+
+const tokenEls = (root: HTMLElement) =>
+  Array.from(root.querySelectorAll<SVGCircleElement>('[data-slot="flow-edge-tokens-token"]'));
+
+describe("FlowEdgeTokens", () => {
+  it("places each token at its progress along the path", () => {
+    const { container } = renderTokens(
+      <FlowEdgeTokens
+        path="M0,0 L200,0"
+        tokens={[
+          { id: "a", progress: 0 },
+          { id: "b", progress: 0.5 },
+          { id: "c", progress: 1 },
+        ]}
+      />,
+    );
+    const [a, b, c] = tokenEls(container);
+    expect(a!.style.transform).toBe("translate(0px, 0px)");
+    expect(b!.style.transform).toBe("translate(100px, 0px)");
+    expect(c!.style.transform).toBe("translate(200px, 0px)");
+  });
+
+  it("moves a token when the parent changes its progress, keeping the same element", () => {
+    const { container, rerender } = renderTokens(
+      <FlowEdgeTokens path="M0,0 L200,0" tokens={[{ id: "a", progress: 0.25 }]} />,
+    );
+    const before = tokenEls(container)[0]!;
+    expect(before.style.transform).toBe("translate(50px, 0px)");
+    rerender(
+      <svg>
+        <FlowEdgeTokens path="M0,0 L200,0" tokens={[{ id: "a", progress: 0.75 }]} />
+      </svg>,
+    );
+    const after = tokenEls(container)[0]!;
+    expect(after).toBe(before);
+    expect(after.style.transform).toBe("translate(150px, 0px)");
+  });
+
+  it("is decorative to assistive technology and carries its slots", () => {
+    const { container } = renderTokens(
+      <FlowEdgeTokens path="M0,0 L10,0" tokens={[{ id: "case-1", progress: 0.2 }]} />,
+    );
+    const root = container.querySelector('[data-slot="flow-edge-tokens"]')!;
+    expect(root).toHaveAttribute("aria-hidden", "true");
+    expect(tokenEls(container)[0]).toHaveAttribute("data-token-id", "case-1");
+  });
+
+  it("uses the default radius and honours a per-token radius", () => {
+    const { container } = renderTokens(
+      <FlowEdgeTokens
+        path="M0,0 L10,0"
+        tokens={[
+          { id: "a", progress: 0 },
+          { id: "b", progress: 0, radius: 9 },
+        ]}
+      />,
+    );
+    const [a, b] = tokenEls(container);
+    expect(a).toHaveAttribute("r", String(DEFAULT_EDGE_TOKEN_RADIUS));
+    expect(b).toHaveAttribute("r", "9");
+  });
+
+  it("paints with semantic tokens only", () => {
+    const { container } = renderTokens(
+      <FlowEdgeTokens path="M0,0 L10,0" tokens={[{ id: "a", progress: 0 }]} />,
+    );
+    const cls = tokenEls(container)[0]!.getAttribute("class")!;
+    expect(cls).toContain("fill-primary");
+    expect(cls).toContain("stroke-background");
+  });
+
+  it("transitions between positions when motion is allowed (jsdom has no reduced-motion signal)", () => {
+    const { container } = renderTokens(
+      <FlowEdgeTokens path="M0,0 L10,0" tokens={[{ id: "a", progress: 0 }]} />,
+    );
+    expect(container.querySelector('[data-slot="flow-edge-tokens"]')).toHaveAttribute(
+      "data-motion",
+      "animated",
+    );
+    expect(tokenEls(container)[0]!.getAttribute("class")).toContain("transition-transform");
+  });
+
+  it("renders no tokens for a path with no geometry", () => {
+    const { container } = renderTokens(
+      <FlowEdgeTokens path="" tokens={[{ id: "a", progress: 0.5 }]} />,
+    );
+    expect(tokenEls(container)).toHaveLength(0);
+  });
+
+  it("merges className, spreads props and forwards its ref", () => {
+    const ref = createRef<SVGGElement>();
+    const { container } = renderTokens(
+      <FlowEdgeTokens
+        ref={ref}
+        path="M0,0 L10,0"
+        tokens={[]}
+        className="opacity-50"
+        data-testid="tokens"
+      />,
+    );
+    const root = container.querySelector('[data-testid="tokens"]')!;
+    expect(ref.current).toBe(root);
+    expect(root.getAttribute("class")).toBe("pointer-events-none opacity-50");
+  });
+});

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

@@ -0,0 +1,94 @@
+"use client";
+
+import { forwardRef, useMemo, type SVGProps } from "react";
+import { useReducedMotion } from "@elabs-ai/components-tokens";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { createEdgePathSampler } from "./edge-path-sampler";
+
+/** Default token radius, in px. */
+export const DEFAULT_EDGE_TOKEN_RADIUS = 4;
+
+export interface FlowEdgeToken {
+  /** Stable identity (e.g. a case id). Keys the rendered marker, so a token keeps its element — and its transition — as it moves. */
+  id: string;
+  /** Position along the path's arc length: `0` = source end, `1` = target end. Clamped; a non-finite value sits at `0`. */
+  progress: number;
+  /** Marker radius in px — e.g. scaled by congestion. @default 4 */
+  radius?: number;
+}
+
+export interface FlowEdgeTokensProps extends Omit<SVGProps<SVGGElement>, "ref" | "children"> {
+  /** SVG path `d` the tokens travel along — the same string the edge draws. */
+  path: string;
+  /** Tokens to place. The parent owns `progress`; this part keeps no clock. */
+  tokens: readonly FlowEdgeToken[];
+}
+
+/**
+ * Markers ("tokens") placed along an edge's path — the presentational primitive
+ * behind process replay. Each token is a circle at `progress` (0..1) of the
+ * path's arc length.
+ *
+ * **Parent-driven, no internal clock.** Nothing here animates on its own: the
+ * parent re-renders with new `progress` values (from a slider, a playback loop,
+ * a play function). Position is a pure function of `(path, progress)` — see
+ * `createEdgePathSampler` — so every render is deterministic and identical in
+ * jsdom, on the server and in the browser.
+ *
+ * Between two renders a token glides with a short `duration-fast` transform
+ * transition, so a parent stepping at a coarse rate still reads as motion. Under
+ * reduced motion (`useReducedMotion()`: the ThemeProvider preference, else the
+ * OS setting) the transition class is not rendered at all and a token jumps
+ * straight to its new position; the `duration-fast` token also collapses to
+ * `--motion-min` through the global motion gate (`data-motion-pref`).
+ *
+ * **Decorative to assistive technology.** The group is `aria-hidden` and ignores
+ * pointer events: a moving dot has no stable meaning to announce. The consumer
+ * owns the text alternative (a live case count, a summary). Colour is the one
+ * `--primary` fill for every token, with a `--background` halo so a token stays
+ * distinct from the edge stroke beneath it.
+ *
+ * Existing brand edges render this for you from `data.tokens`
+ * (`FlowWeightedEdge`, `FlowSelfLoopEdge`); a custom edge renders it after its
+ * `FlowEdgePath` with the same `path` string.
+ */
+export const FlowEdgeTokens = forwardRef<SVGGElement, FlowEdgeTokensProps>(function FlowEdgeTokens(
+  { path, tokens, className, ...props },
+  ref,
+) {
+  const reducedMotion = useReducedMotion();
+  const sampler = useMemo(() => createEdgePathSampler(path), [path]);
+
+  return (
+    <g
+      ref={ref}
+      aria-hidden="true"
+      data-slot="flow-edge-tokens"
+      data-motion={reducedMotion ? "reduced" : "animated"}
+      className={cn("pointer-events-none", className)}
+      {...props}
+    >
+      {sampler
+        ? tokens.map((token) => {
+            const { x, y } = sampler.pointAt(token.progress);
+            return (
+              <circle
+                key={token.id}
+                data-slot="flow-edge-tokens-token"
+                data-token-id={token.id}
+                cx={0}
+                cy={0}
+                r={token.radius ?? DEFAULT_EDGE_TOKEN_RADIUS}
+                strokeWidth={1.5}
+                className={cn(
+                  "fill-primary stroke-background",
+                  !reducedMotion && "transition-transform duration-fast ease-standard",
+                )}
+                style={{ transform: `translate(${x}px, ${y}px)` }}
+              />
+            );
+          })
+        : null}
+    </g>
+  );
+});

package/src/flow-edge-tokens/index.ts

@@ -0,0 +1,12 @@
+export {
+  FlowEdgeTokens,
+  DEFAULT_EDGE_TOKEN_RADIUS,
+  type FlowEdgeToken,
+  type FlowEdgeTokensProps,
+} from "./flow-edge-tokens";
+export {
+  createEdgePathSampler,
+  flattenEdgePath,
+  type EdgePathPoint,
+  type EdgePathSampler,
+} from "./edge-path-sampler";

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

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import type { Edge, Node } from "@xyflow/react";
+import { pinBackbone } from "./backbone";
+import { layoutFlowElk } from "./layout-flow-elk";
+
+/**
+ * A 3-variant process: the top variant runs start → register → check → approve → pay → end;
+ * a second skips `check`; a third reworks `check` via `request info`.
+ */
+function threeVariantGraph(): { nodes: Node[]; edges: Edge[] } {
+  const ids = ["start", "register", "check", "info", "approve", "reject", "pay", "end"];
+  const nodes: Node[] = ids.map((id) => ({ id, position: { x: 0, y: 0 }, data: {} }));
+  const pairs: [string, string][] = [
+    ["start", "register"],
+    ["register", "check"],
+    ["check", "approve"],
+    ["approve", "pay"],
+    ["pay", "end"],
+    ["register", "approve"],
+    ["check", "info"],
+    ["info", "check"],
+    ["check", "reject"],
+    ["reject", "end"],
+  ];
+  const edges: Edge[] = pairs.map(([source, target]) => ({
+    id: `${source}-${target}`,
+    source,
+    target,
+  }));
+  return { nodes, edges };
+}
+
+const TOP_VARIANT = ["register", "check", "approve", "pay"];
+
+describe("pinBackbone", () => {
+  it("pins the variant's nodes and the edges that join them, in order", () => {
+    const { nodes, edges } = threeVariantGraph();
+    const backbone = pinBackbone(nodes, edges, [...TOP_VARIANT, "missing", "check"]);
+    expect(backbone.nodeIds).toEqual(TOP_VARIANT);
+    expect(backbone.edgeIds).toEqual(["register-check", "check-approve", "approve-pay"]);
+  });
+
+  it("lays the top variant's four activities on one straight row (LR)", async () => {
+    const { nodes, edges } = threeVariantGraph();
+    const backbone = pinBackbone(nodes, edges, TOP_VARIANT);
+    const result = await layoutFlowElk(nodes, edges, { direction: "LR", backbone });
+    expect(result.engine).toBe("elk");
+
+    const byId = new Map(result.nodes.map((n) => [n.id, n]));
+    const rows = TOP_VARIANT.map((id) => byId.get(id)!.position.y);
+    expect(new Set(rows).size).toBe(1);
+    const columns = TOP_VARIANT.map((id) => byId.get(id)!.position.x);
+    expect(columns).toEqual([...columns].sort((p, q) => p - q));
+  });
+
+  it("lays it on one straight column (TB) and every node still connects start to end", async () => {
+    const { nodes, edges } = threeVariantGraph();
+    const backbone = pinBackbone(nodes, edges, TOP_VARIANT);
+    const result = await layoutFlowElk(nodes, edges, { direction: "TB", backbone });
+
+    const byId = new Map(result.nodes.map((n) => [n.id, n]));
+    expect(new Set(TOP_VARIANT.map((id) => byId.get(id)!.position.x)).size).toBe(1);
+
+    // Connectivity invariant: every node is reachable from start and reaches end.
+    const reach = (from: string, forward: boolean): Set<string> => {
+      const seen = new Set([from]);
+      const queue = [from];
+      while (queue.length > 0) {
+        const id = queue.pop()!;
+        for (const edge of result.edges) {
+          const [a, b] = forward ? [edge.source, edge.target] : [edge.target, edge.source];
+          if (a === id && !seen.has(b)) {
+            seen.add(b);
+            queue.push(b);
+          }
+        }
+      }
+      return seen;
+    };
+    const fromStart = reach("start", true);
+    const toEnd = reach("end", false);
+    for (const node of result.nodes) {
+      expect(fromStart.has(node.id)).toBe(true);
+      expect(toEnd.has(node.id)).toBe(true);
+      expect(Number.isFinite(node.position.x) && Number.isFinite(node.position.y)).toBe(true);
+    }
+  });
+});

package/src/flow-layout/backbone.ts

@@ -0,0 +1,58 @@
+import type { Edge, Node } from "@xyflow/react";
+
+/**
+ * One path through the graph to lay out on a single straight line (RM-067).
+ *
+ * Produced by {@link pinBackbone}, consumed by `layoutFlowElk`'s `backbone` option. Plain
+ * data, so it clones, serializes and memoizes like any other layout input.
+ */
+export interface FlowElkBackbone {
+  /** Node ids on the pinned path, in path order. */
+  nodeIds: string[];
+  /** Ids of the edges joining consecutive pinned nodes, in path order. */
+  edgeIds: string[];
+}
+
+/**
+ * Pin a variant's activity sequence to one straight row (LR/RL) or column (TB/BT) — the
+ * Apromore-style "backbone" layout (RM-067).
+ *
+ * A pre-pass, not a layout: hand the result to `layoutFlowElk` as `backbone` and the rest of
+ * the graph lays out around it. ELK gets the joining edges at the highest straightness
+ * priority, then every layer holding a pinned node is translated as a whole along the
+ * cross axis so the pinned nodes share one line — a whole-layer shift, so no two nodes of
+ * a layer can ever be pushed onto each other.
+ *
+ * `variant` is the sequence of NODE IDS — for a process graph, the most frequent variant's
+ * activities, which are the activity nodes' ids. An id with no node is skipped; a repeated
+ * activity (rework inside the variant) is pinned once, at its first occurrence, because a
+ * node cannot sit on a straight line twice.
+ *
+ * @example
+ * ```ts
+ * const backbone = pinBackbone(nodes, edges, variants[0].activities);
+ * const { nodes: laidOut } = await layoutFlowElk(nodes, edges, { direction: "LR", backbone });
+ * ```
+ */
+export function pinBackbone(
+  nodes: readonly Node[],
+  edges: readonly Edge[],
+  variant: readonly string[],
+): FlowElkBackbone {
+  const known = new Set(nodes.map((node) => node.id));
+  const nodeIds: string[] = [];
+  const seen = new Set<string>();
+  for (const id of variant) {
+    if (!known.has(id) || seen.has(id)) continue;
+    seen.add(id);
+    nodeIds.push(id);
+  }
+
+  const edgeIds: string[] = [];
+  for (let i = 0; i < nodeIds.length - 1; i += 1) {
+    const edge = edges.find((e) => e.source === nodeIds[i] && e.target === nodeIds[i + 1]);
+    if (edge) edgeIds.push(edge.id);
+  }
+
+  return { nodeIds, edgeIds };
+}