@elabs-ai/components-process 4.1.0

package/src/process-map/use-process-layout.ts

@@ -0,0 +1,315 @@
+"use client";
+
+/**
+ * useProcessLayout — the process map's cached, debounced dagre layout (RM-051).
+ *
+ * A process map is re-rendered constantly for reasons that do NOT move a node: switching
+ * the metric from frequency to duration, selecting an activity, hovering a path. Laying
+ * the graph out again for any of those is both wasteful and visually wrong — the picture
+ * would twitch while the reader's eye is on it. So this hook separates two things the
+ * naive version conflates:
+ *
+ * - **STRUCTURE** — which activities and transitions exist, and which way the graph runs.
+ *   Only a change here can move a node, and only a change here runs dagre.
+ * - **EVERYTHING ELSE** — metric, formatting, selection, rework badges. These rebuild the
+ *   model (cheap, pure) and are re-applied onto the CACHED positions.
+ *
+ * The cache is keyed on `structureKey` (see `processGraphStructureKey`) plus the layout
+ * direction, and it stores POSITIONS BY NODE ID rather than node objects — which is
+ * exactly what lets a metric switch reuse a layout: the node objects are all new, their
+ * ids are not.
+ *
+ * `layoutRuns` is returned so the "no second `layoutFlow` call for a metric-only change"
+ * acceptance criterion is something a test can ASSERT rather than something a comment
+ * claims.
+ *
+ * ## Debounce
+ *
+ * A structural change that arrives while another is still settling (dragging an
+ * abstraction slider emits one graph per pointer move) is debounced by
+ * {@link DEFAULT_LAYOUT_DEBOUNCE_MS}. The FIRST layout for a given hook instance is never
+ * debounced — an empty canvas for 80 ms on mount is a worse trade than one extra dagre
+ * run — so the debounce only ever delays a RE-layout.
+ *
+ * ## Motion
+ *
+ * Position deltas animate via a CSS transform transition on the React Flow node element
+ * (see `PROCESS_MAP_NODE_MOTION_CLASS`), so nodes slide rather than re-mount, and the
+ * whole thing is neutralized under `prefers-reduced-motion`.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { XYPosition } from "@xyflow/react";
+import { layoutFlow, type FlowLayoutDirection } from "@elabs-ai/components-flow";
+import type { ProcessMapEdge, ProcessMapNode } from "./map-model";
+
+/**
+ * Within-rank spacing, wider than `layoutFlow`'s generic 48.
+ *
+ * Every transition on this canvas carries a label pill, and the pill is portalled OUTSIDE
+ * the SVG — it contributes nothing to dagre's routing and nothing to React Flow's fitted
+ * bounds, so a gap that reads fine for bare arrows is exactly one pill too narrow, and
+ * nothing in the layout maths notices. At 48 the shipped eleven-activity fixture printed
+ * three pills on top of activity cards in each direction; at 72, none.
+ */
+const NODE_SPACING = 72;
+
+/**
+ * Between-rank spacing, per direction — and the asymmetry is the point.
+ *
+ * The rank gap is the one a label pill sits IN: a transition's pill is anchored at its
+ * path's midpoint, which falls between two ranks. A pill is a wide, short shape (a number,
+ * sometimes a number and a duration), so the gap it needs is not a single number — it is
+ * the pill's extent ALONG the rank axis, and that axis turns with the layout:
+ *
+ * - **Top-to-bottom** ranks stack vertically, so the gap only has to clear the pill's
+ *   HEIGHT — one line of `text-meta`. `layoutFlow`'s default 72 already does.
+ * - **Left-to-right** ranks run horizontally, so the same gap has to clear the pill's
+ *   WIDTH, several times larger. Measured on the same fixture: at 72 and at 96 two pills
+ *   still printed over activity cards; at 120 none did.
+ *
+ * The two reversed directions take the number for their own axis: `BT` is vertical like
+ * `TB`, `RL` horizontal like `LR`. Neither is reachable from `ProcessMap`'s own
+ * `direction` prop today, and both are spelled out anyway rather than defaulted, so a
+ * future map that offers them inherits the reasoning instead of a silent fallback.
+ *
+ * Using the left-to-right number in both directions would be the tidier-looking constant
+ * and the wrong call — a top-to-bottom map is height-constrained, so it would spend 22% of
+ * the opening zoom (0.430 → 0.334 on the same fixture) buying clearance for an axis that
+ * never needed it.
+ */
+const RANK_SPACING: Record<FlowLayoutDirection, number> = { TB: 72, BT: 72, LR: 120, RL: 120 };
+
+/** How long a RE-layout waits for the structure to settle. */
+export const DEFAULT_LAYOUT_DEBOUNCE_MS = 80;
+
+/**
+ * The class that animates node position deltas.
+ *
+ * React Flow writes `transform: translate(x, y)` onto its own node element, so the
+ * transition has to live there — not on anything this package renders. The element is
+ * addressed as `div[data-id]` rather than by React Flow's own `.react-flow__node` class
+ * on purpose: that class contains underscores, which have to be backslash-escaped inside
+ * a Tailwind arbitrary variant and would then be eaten by JavaScript string escaping the
+ * moment the class string passes through `cn()`. Nodes are `div`s and edges are `g`s, so
+ * the attribute form is both simpler and correctly scoped. Same reasoning as the ancestor
+ * selector in `FlowNode`'s focus indicator.
+ *
+ * ## The `:not([data-handlepos])` is load-bearing
+ *
+ * React Flow renders a `<Handle>` as a `<div>` carrying BOTH `data-id` and
+ * `data-handlepos`, so a bare `div[data-id]` also matched every connector dot — and a dot
+ * changes sides when the layout direction flips (bottom/top becomes right/left). The dot
+ * then ANIMATED to its new side, React Flow measured `handleBounds` while it was in
+ * flight, and never measured again: the stored bounds said `x: 164` where the DOM had
+ * settled at `172`, and every edge on the map terminated in mid-air. Measured at 69 px of
+ * drift left-to-right, 24 px top-to-bottom.
+ *
+ * A handle is not a node position; it has no delta to animate, and it must be measurable
+ * the instant it is placed. Excluding it is the fix, not a workaround.
+ */
+/*
+ * WRITTEN OUT IN FULL, deliberately. Tailwind extracts candidates from source TEXT and
+ * never evaluates JavaScript, so a class assembled by interpolating a `MOTION_TARGET`
+ * constant produces no CSS at all: `new Scanner().scanFiles()` returns only `["const",
+ * "export"]` for the interpolated form and all four utilities for this one. The selector
+ * therefore repeats instead of being factored into a constant — the duplication is what
+ * keeps the animation alive.
+ */
+export const PROCESS_MAP_NODE_MOTION_CLASS =
+  "[&_div[data-id]:not([data-handlepos])]:transition-transform " +
+  "[&_div[data-id]:not([data-handlepos])]:duration-base " +
+  "[&_div[data-id]:not([data-handlepos])]:ease-standard " +
+  "motion-reduce:[&_div[data-id]:not([data-handlepos])]:transition-none";
+
+/** One cached dagre result: where every node sits, plus the structure dagre reported. */
+export interface ProcessLayoutSnapshot {
+  positions: Record<string, XYPosition>;
+  /** Node id → the handle side edges LEAVE from, as `layoutFlow` set it per direction. */
+  sourcePosition: Record<string, ProcessMapNode["sourcePosition"]>;
+  /** Node id → the handle side edges ENTER on. */
+  targetPosition: Record<string, ProcessMapNode["targetPosition"]>;
+  /** Edge ids running against the layout direction (`layoutFlow`'s `backEdges`). */
+  backEdges: string[];
+  /** Edge ids whose source equals their target (`layoutFlow`'s `selfLoops`). */
+  selfLoops: string[];
+  /** Wall-clock cost of the `layoutFlow` call that produced this, in milliseconds. */
+  durationMs: number;
+}
+
+/** Inputs to {@link useProcessLayout}. */
+export interface UseProcessLayoutOptions {
+  nodes: ProcessMapNode[];
+  edges: ProcessMapEdge[];
+  /** Structure-only cache key — see `processGraphStructureKey`. NEVER include a metric. */
+  structureKey: string;
+  direction: FlowLayoutDirection;
+  /** @default {@link DEFAULT_LAYOUT_DEBOUNCE_MS} */
+  debounceMs?: number;
+}
+
+/** What {@link useProcessLayout} answers. */
+export interface UseProcessLayoutResult {
+  /** `nodes`, positioned. Identity changes whenever `nodes` does, so metrics stay live. */
+  nodes: ProcessMapNode[];
+  /** Edge ids `layoutFlow` reported as running backwards, for the back-edge shape. */
+  backEdgeIds: ReadonlySet<string>;
+  /** Edge ids `layoutFlow` withheld as self-loops. */
+  selfLoopIds: ReadonlySet<string>;
+  /** How many times `layoutFlow` has actually run for this hook instance. */
+  layoutRuns: number;
+  /** Cost of the most recent `layoutFlow` call, in milliseconds. `0` before the first. */
+  lastLayoutMs: number;
+  /** True between a structural change and the debounced layout that answers it. */
+  pending: boolean;
+}
+
+const EMPTY_SET: ReadonlySet<string> = new Set<string>();
+
+/** Snapshot a `layoutFlow` result into the id-keyed shape the cache stores. */
+function toSnapshot(
+  result: ReturnType<typeof layoutFlow<ProcessMapNode, ProcessMapEdge>>,
+  durationMs: number,
+): ProcessLayoutSnapshot {
+  const positions: Record<string, XYPosition> = {};
+  const sourcePosition: ProcessLayoutSnapshot["sourcePosition"] = {};
+  const targetPosition: ProcessLayoutSnapshot["targetPosition"] = {};
+  for (const node of result.nodes) {
+    positions[node.id] = node.position;
+    sourcePosition[node.id] = node.sourcePosition;
+    targetPosition[node.id] = node.targetPosition;
+  }
+  return {
+    positions,
+    sourcePosition,
+    targetPosition,
+    backEdges: result.backEdges,
+    selfLoops: result.selfLoops,
+    durationMs,
+  };
+}
+
+/** Apply a cached snapshot to a fresh set of nodes, matching on id. */
+export function applyLayoutSnapshot(
+  nodes: ProcessMapNode[],
+  snapshot: ProcessLayoutSnapshot,
+): ProcessMapNode[] {
+  return nodes.map((node) => {
+    const position = snapshot.positions[node.id];
+    if (!position) return node;
+    return {
+      ...node,
+      position,
+      sourcePosition: snapshot.sourcePosition[node.id],
+      targetPosition: snapshot.targetPosition[node.id],
+    };
+  });
+}
+
+/**
+ * Lay a process graph out, reusing a cached layout whenever the structure is unchanged.
+ *
+ * @see {@link UseProcessLayoutResult.layoutRuns} — the observable proof that a metric-only
+ * change does not re-run dagre.
+ */
+export function useProcessLayout({
+  nodes,
+  edges,
+  structureKey,
+  direction,
+  debounceMs = DEFAULT_LAYOUT_DEBOUNCE_MS,
+}: UseProcessLayoutOptions): UseProcessLayoutResult {
+  const cacheKey = `${structureKey}::${direction}`;
+  const cache = useRef(new Map<string, ProcessLayoutSnapshot>());
+  const runs = useRef(0);
+  // The layout the render below reads. Held in state (not a ref) because producing a new
+  // one must re-render; keyed so a cache hit for a DIFFERENT key is never mistaken for a
+  // hit for this one.
+  const [applied, setApplied] = useState<{ key: string; snapshot: ProcessLayoutSnapshot } | null>(
+    null,
+  );
+
+  const compute = useCallback(
+    (key: string, currentNodes: ProcessMapNode[], currentEdges: ProcessMapEdge[]) => {
+      const started = performance.now();
+      const result = layoutFlow<ProcessMapNode, ProcessMapEdge>(currentNodes, currentEdges, {
+        direction,
+        nodeSpacing: NODE_SPACING,
+        rankSpacing: RANK_SPACING[direction],
+      });
+      const snapshot = toSnapshot(result, performance.now() - started);
+      runs.current += 1;
+      cache.current.set(key, snapshot);
+      setApplied({ key, snapshot });
+    },
+    [direction],
+  );
+
+  // The nodes/edges the (possibly debounced) layout should run against. Held in a ref so
+  // the effect below depends on the STRUCTURE key alone — re-running it whenever a metric
+  // produced new node objects is precisely the bug the cache exists to prevent.
+  const latest = useRef({ nodes, edges });
+  latest.current = { nodes, edges };
+
+  const cachedForKey = cache.current.get(cacheKey);
+  const hasLayout = applied?.key === cacheKey || cachedForKey !== undefined;
+
+  useEffect(() => {
+    const cached = cache.current.get(cacheKey);
+    if (cached) {
+      setApplied((current) =>
+        current?.key === cacheKey ? current : { key: cacheKey, snapshot: cached },
+      );
+      return;
+    }
+    if (latest.current.nodes.length === 0) {
+      setApplied({
+        key: cacheKey,
+        snapshot: {
+          positions: {},
+          sourcePosition: {},
+          targetPosition: {},
+          backEdges: [],
+          selfLoops: [],
+          durationMs: 0,
+        },
+      });
+      return;
+    }
+    // First layout of this hook instance renders immediately; a RE-layout waits for the
+    // structure to settle (an abstraction slider emits one graph per pointer move).
+    if (runs.current === 0 || debounceMs <= 0) {
+      compute(cacheKey, latest.current.nodes, latest.current.edges);
+      return;
+    }
+    const timer = setTimeout(
+      () => compute(cacheKey, latest.current.nodes, latest.current.edges),
+      debounceMs,
+    );
+    return () => clearTimeout(timer);
+  }, [cacheKey, compute, debounceMs]);
+
+  const snapshot = applied?.key === cacheKey ? applied.snapshot : cachedForKey;
+
+  const positionedNodes = useMemo(
+    () => (snapshot ? applyLayoutSnapshot(nodes, snapshot) : nodes),
+    [nodes, snapshot],
+  );
+
+  const backEdgeIds = useMemo(
+    () => (snapshot ? new Set(snapshot.backEdges) : EMPTY_SET),
+    [snapshot],
+  );
+  const selfLoopIds = useMemo(
+    () => (snapshot ? new Set(snapshot.selfLoops) : EMPTY_SET),
+    [snapshot],
+  );
+
+  return {
+    nodes: positionedNodes,
+    backEdgeIds,
+    selfLoopIds,
+    layoutRuns: runs.current,
+    lastLayoutMs: snapshot?.durationMs ?? 0,
+    pending: !hasLayout && nodes.length > 0,
+  };
+}

package/src/test/contract.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  assertProcessContract,
+  buildProcessDoublePayload,
+  ProcessContractError,
+  readProcessDoubleProps,
+  type ProcessContractSpec,
+} from "./contract";
+import type { ProcessGraph, Variant } from "../core/types";
+
+const GRAPH_SPEC: ProcessContractSpec = { dataProp: "graph" };
+const VARIANTS_SPEC: ProcessContractSpec = { dataProp: "variants" };
+
+const emptyGraph: ProcessGraph = {
+  activities: [],
+  transitions: [],
+  startActivities: {},
+  endActivities: {},
+  totals: { cases: 0, events: 0, variants: 0 },
+};
+
+const oneVariant: Variant[] = [
+  {
+    id: "v1",
+    sequence: ["A", "B"],
+    count: 1,
+    share: 1,
+    cumulativeShare: 1,
+    caseIds: ["c1"],
+    duration: { min: 0, max: 0, mean: 0, median: 0, p90: 0, sum: 0, trimmedMean: 0 },
+  },
+];
+
+describe("assertProcessContract", () => {
+  it("passes for a valid graph payload", () => {
+    expect(() =>
+      assertProcessContract("ProcessMapDouble", { graph: emptyGraph }, GRAPH_SPEC),
+    ).not.toThrow();
+  });
+
+  it("passes for a valid variants payload", () => {
+    expect(() =>
+      assertProcessContract("VariantExplorerDouble", { variants: oneVariant }, VARIANTS_SPEC),
+    ).not.toThrow();
+  });
+
+  it("throws ProcessContractError when the graph prop is missing", () => {
+    expect(() => assertProcessContract("ProcessMapDouble", {}, GRAPH_SPEC)).toThrow(
+      ProcessContractError,
+    );
+  });
+
+  it("throws ProcessContractError when the variants prop is not an array", () => {
+    expect(() =>
+      assertProcessContract("VariantExplorerDouble", { variants: "nope" }, VARIANTS_SPEC),
+    ).toThrow(ProcessContractError);
+  });
+
+  it("throws when a required prop is undefined", () => {
+    const spec: ProcessContractSpec = { dataProp: "graph", requiredProps: ["onSelectionChange"] };
+    expect(() => assertProcessContract("ProcessMapDouble", { graph: emptyGraph }, spec)).toThrow(
+      /missing required prop "onSelectionChange"/,
+    );
+  });
+});
+
+describe("buildProcessDoublePayload / readProcessDoubleProps round-trip", () => {
+  it("carries the graph's activity count and the current selection", () => {
+    const graph: ProcessGraph = { ...emptyGraph, activities: [...emptyGraph.activities] };
+    const payload = buildProcessDoublePayload(
+      "ProcessMapDouble",
+      { graph, selection: { kind: "node", id: "A" } },
+      GRAPH_SPEC,
+    );
+    expect(payload).toEqual({
+      component: "ProcessMapDouble",
+      dataLength: 0,
+      selection: { kind: "node", id: "A" },
+    });
+
+    const el = document.createElement("div");
+    el.setAttribute("data-process-props", JSON.stringify(payload));
+    expect(readProcessDoubleProps(el)).toEqual(payload);
+  });
+
+  it("counts variants length for a variants-shaped double", () => {
+    const payload = buildProcessDoublePayload(
+      "VariantExplorerDouble",
+      { variants: oneVariant },
+      VARIANTS_SPEC,
+    );
+    expect(payload.dataLength).toBe(1);
+  });
+
+  it("readProcessDoubleProps returns null when the attribute is absent", () => {
+    expect(readProcessDoubleProps(document.createElement("div"))).toBeNull();
+  });
+});

package/src/test/contract.ts

@@ -0,0 +1,118 @@
+/**
+ * The double contract engine — RM-053.
+ *
+ * Mirrors `@elabs-ai/components-charts/src/test/contract.ts` (issue #364): a real component
+ * whose rendering depends on a heavy engine (here, the `flow`-composed process views) gets a
+ * `vi.mock`-swappable test double that (a) validates the same required-prop contract the real
+ * component would enforce, so a broken test fails loudly instead of silently rendering
+ * nothing, (b) never imports the engine, and (c) exposes what it was given as an inspectable
+ * `data-process-props` attribute so a test can assert on props without a real graph/variant
+ * layout ever running under jsdom.
+ *
+ * `ProcessMap`, `VariantExplorer` and `ProcessKpiStrip` do not exist yet in this package's
+ * public barrel — RM-051/052/054 land them (`src/index.ts` still ships no components on
+ * purpose). The doubles built on this contract are therefore named with an explicit `Double`
+ * suffix rather than the real component name: there is no real same-named export yet for
+ * `vi.mock` to swap in for. A follow-up item that lands the real components should rename the
+ * doubles to match (dropping the suffix) so a consumer can
+ * `vi.mock("@elabs-ai/components-process", () => import("@elabs-ai/components-process/test"))`
+ * the way `@elabs-ai/components-charts` consumers do — that rename is out of this item's scope.
+ */
+import type { ProcessGraph, Variant } from "../core/types";
+
+/** Selection carried by a process view's coordinated-selection contract (RM-068 completes it). */
+export type ProcessSelection = null | { kind: "node"; id: string } | { kind: "edge"; id: string };
+
+/** What {@link assertProcessContract} checks for one double. */
+export interface ProcessContractSpec {
+  /** Name of the prop carrying the double's primary data payload. */
+  dataProp: "graph" | "variants";
+  /** Other props the real component requires; the double must not silently accept `undefined`. */
+  requiredProps?: string[];
+}
+
+/** Thrown by {@link assertProcessContract} when a double is used with an invalid prop shape. */
+export class ProcessContractError extends Error {
+  constructor(componentName: string, message: string) {
+    super(`${componentName}: ${message}`);
+    this.name = "ProcessContractError";
+  }
+}
+
+function isProcessGraph(value: unknown): value is ProcessGraph {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    Array.isArray((value as ProcessGraph).activities) &&
+    Array.isArray((value as ProcessGraph).transitions)
+  );
+}
+
+function isVariantArray(value: unknown): value is Variant[] {
+  return (
+    Array.isArray(value) &&
+    value.every((entry) => typeof entry === "object" && entry !== null && "sequence" in entry)
+  );
+}
+
+/**
+ * Validate a double's props against its contract spec. Throws {@link ProcessContractError} on
+ * a missing/invalid required prop — mirroring what the real component would fail on at
+ * runtime, so a test that gets the props wrong fails loudly rather than silently rendering an
+ * empty double.
+ */
+export function assertProcessContract(
+  componentName: string,
+  props: Record<string, unknown>,
+  spec: ProcessContractSpec,
+): void {
+  const data = props[spec.dataProp];
+  if (spec.dataProp === "graph" && !isProcessGraph(data)) {
+    throw new ProcessContractError(
+      componentName,
+      `"graph" prop must be a ProcessGraph, got ${typeof data}`,
+    );
+  }
+  if (spec.dataProp === "variants" && !isVariantArray(data)) {
+    throw new ProcessContractError(
+      componentName,
+      `"variants" prop must be a Variant[], got ${typeof data}`,
+    );
+  }
+  for (const key of spec.requiredProps ?? []) {
+    if (props[key] === undefined) {
+      throw new ProcessContractError(componentName, `missing required prop "${key}"`);
+    }
+  }
+}
+
+/** What a double records to `data-process-props`, for assertions without a real layout. */
+export interface ProcessDoublePayload {
+  component: string;
+  dataLength: number;
+  selection?: ProcessSelection;
+}
+
+/** Build the inspectable payload a double serializes into `data-process-props`. */
+export function buildProcessDoublePayload(
+  componentName: string,
+  props: Record<string, unknown>,
+  spec: ProcessContractSpec,
+): ProcessDoublePayload {
+  const data = props[spec.dataProp];
+  const dataLength =
+    spec.dataProp === "graph" && isProcessGraph(data)
+      ? data.activities.length
+      : Array.isArray(data)
+        ? data.length
+        : 0;
+  const payload: ProcessDoublePayload = { component: componentName, dataLength };
+  if ("selection" in props) payload.selection = props.selection as ProcessSelection;
+  return payload;
+}
+
+/** Read a mounted double's payload back out of the DOM (companion to {@link buildProcessDoublePayload}). */
+export function readProcessDoubleProps(el: Element): ProcessDoublePayload | null {
+  const raw = el.getAttribute("data-process-props");
+  return raw ? (JSON.parse(raw) as ProcessDoublePayload) : null;
+}

package/src/test/doubles.test.tsx

@@ -0,0 +1,51 @@
+import { render } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { discoverGraph } from "../core/discover-graph";
+import { extractVariants } from "../core/extract-variants";
+import { generateSyntheticLog } from "../core/fixtures/synthetic-log";
+import { ProcessKpiStripDouble, ProcessMapDouble, VariantExplorerDouble } from "./doubles";
+import { readProcessDoubleProps } from "./contract";
+
+const log = generateSyntheticLog({ cases: 20, seed: 7 });
+const graph = discoverGraph(log);
+const variants = extractVariants(log);
+
+describe("process test doubles", () => {
+  it("ProcessMapDouble mounts and records the graph's activity count", () => {
+    const { container } = render(<ProcessMapDouble graph={graph} />);
+    const el = container.querySelector('[data-process-double="ProcessMapDouble"]');
+    expect(el).not.toBeNull();
+    expect(readProcessDoubleProps(el as Element)?.dataLength).toBe(graph.activities.length);
+  });
+
+  it("VariantExplorerDouble mounts and records the variant count", () => {
+    const { container } = render(<VariantExplorerDouble variants={variants} />);
+    const el = container.querySelector('[data-process-double="VariantExplorerDouble"]');
+    expect(readProcessDoubleProps(el as Element)?.dataLength).toBe(variants.length);
+  });
+
+  it("ProcessKpiStripDouble mounts with the graph payload", () => {
+    const { container } = render(<ProcessKpiStripDouble graph={graph} />);
+    const el = container.querySelector('[data-process-double="ProcessKpiStripDouble"]');
+    expect(el).not.toBeNull();
+  });
+
+  it("forwards a ref to the underlying div", () => {
+    let node: HTMLDivElement | null = null;
+    render(
+      <ProcessMapDouble
+        graph={graph}
+        ref={(el) => {
+          node = el;
+        }}
+      />,
+    );
+    expect(node).toBeInstanceOf(HTMLDivElement);
+  });
+
+  it("throws a contract error when required data is missing (a broken test fails loudly)", () => {
+    // @ts-expect-error -- deliberately omitting the required `graph` prop
+    expect(() => render(<ProcessMapDouble />)).toThrow(/ProcessMapDouble/);
+  });
+});

package/src/test/doubles.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+/**
+ * Test doubles for the process package's not-yet-shipped view components — RM-053.
+ *
+ * Mirrors `@elabs-ai/components-charts/src/test/doubles.tsx`'s factory shape: each double is a
+ * plain `forwardRef<HTMLDivElement, P>` that validates its contract
+ * ({@link assertProcessContract}) then renders an inert `<div>` carrying its props as a
+ * `data-process-props` JSON attribute — cheap enough to mount by the thousand in a test, with
+ * nothing that needs a real graph/variant layout to run under jsdom.
+ */
+import { forwardRef } from "react";
+import type { HTMLAttributes } from "react";
+
+import type { ProcessGraph, Variant } from "../core/types";
+import {
+  assertProcessContract,
+  buildProcessDoublePayload,
+  type ProcessContractSpec,
+  type ProcessSelection,
+} from "./contract";
+
+interface DoubleOwnProps extends HTMLAttributes<HTMLDivElement> {
+  selection?: ProcessSelection;
+  onSelectionChange?: (selection: ProcessSelection) => void;
+}
+
+interface ProcessMapDoubleProps extends DoubleOwnProps {
+  graph: ProcessGraph;
+}
+
+interface VariantExplorerDoubleProps extends DoubleOwnProps {
+  variants: Variant[];
+}
+
+interface ProcessKpiStripDoubleProps extends HTMLAttributes<HTMLDivElement> {
+  graph: ProcessGraph;
+}
+
+const PROCESS_MAP_SPEC: ProcessContractSpec = { dataProp: "graph" };
+const VARIANT_EXPLORER_SPEC: ProcessContractSpec = { dataProp: "variants" };
+const PROCESS_KPI_STRIP_SPEC: ProcessContractSpec = { dataProp: "graph" };
+
+function createProcessDouble<P extends DoubleOwnProps>(name: string, spec: ProcessContractSpec) {
+  const Double = forwardRef<HTMLDivElement, P>(function ProcessTestDouble(props, ref) {
+    const record = props as unknown as Record<string, unknown>;
+    assertProcessContract(name, record, spec);
+    const payload = buildProcessDoublePayload(name, record, spec);
+    return (
+      <div
+        ref={ref}
+        data-slot="process-test-double"
+        data-process-double={name}
+        data-process-props={JSON.stringify(payload)}
+        className={props.className}
+        style={props.style}
+      />
+    );
+  });
+  Double.displayName = name;
+  return Double;
+}
+
+/** Stand-in for the future `ProcessMap` (RM-051). Named with a `Double` suffix — see contract.ts header. */
+export const ProcessMapDouble = createProcessDouble<ProcessMapDoubleProps>(
+  "ProcessMapDouble",
+  PROCESS_MAP_SPEC,
+);
+
+/** Stand-in for the future `VariantExplorer` (RM-052). */
+export const VariantExplorerDouble = createProcessDouble<VariantExplorerDoubleProps>(
+  "VariantExplorerDouble",
+  VARIANT_EXPLORER_SPEC,
+);
+
+/** Stand-in for the future `ProcessKpiStrip` (RM-054). */
+export const ProcessKpiStripDouble = createProcessDouble<ProcessKpiStripDoubleProps>(
+  "ProcessKpiStripDouble",
+  PROCESS_KPI_STRIP_SPEC,
+);
+
+export type { ProcessMapDoubleProps, VariantExplorerDoubleProps, ProcessKpiStripDoubleProps };