@elabs-ai/components-process 4.2.0 → 5.0.0

package/src/test/contract.test.ts

@@ -57,6 +57,25 @@ describe("assertProcessContract", () => {
     ).toThrow(ProcessContractError);
   });
 
+  // DottedChart — RM-059
+  it("passes for a non-empty log with parsable timestamps, and throws otherwise", () => {
+    const spec: ProcessContractSpec = { dataProp: "log" };
+    const row = { caseId: "c1", activity: "A", timestamp: "2026-01-05T09:00:00Z" };
+    expect(() =>
+      assertProcessContract("DottedChartDouble", { log: { events: [row] } }, spec),
+    ).not.toThrow();
+    expect(() => assertProcessContract("DottedChartDouble", { log: { events: [] } }, spec)).toThrow(
+      ProcessContractError,
+    );
+    expect(() =>
+      assertProcessContract(
+        "DottedChartDouble",
+        { log: { events: [{ ...row, timestamp: "nope" }] } },
+        spec,
+      ),
+    ).toThrow(/parsable timestamps/);
+  });
+
   it("throws when a required prop is undefined", () => {
     const spec: ProcessContractSpec = { dataProp: "graph", requiredProps: ["onSelectionChange"] };
     expect(() => assertProcessContract("ProcessMapDouble", { graph: emptyGraph }, spec)).toThrow(
@@ -65,6 +84,53 @@ describe("assertProcessContract", () => {
   });
 });
 
+// PerformanceSpectrum — RM-060
+describe("assertProcessContract — log + segment order", () => {
+  const LOG_SPEC: ProcessContractSpec = { dataProp: "log", segmentOrder: true };
+  const log = {
+    events: [
+      { caseId: "c1", activity: "A", timestamp: 0 },
+      { caseId: "c1", activity: "B", timestamp: 10 },
+    ],
+  };
+
+  it("throws when the log prop is not an EventLog", () => {
+    expect(() => assertProcessContract("PerformanceSpectrumDouble", {}, LOG_SPEC)).toThrow(
+      /"log" prop must be an EventLog/,
+    );
+  });
+
+  it("passes when the order resolves to a segment present in the log", () => {
+    expect(() =>
+      assertProcessContract("PerformanceSpectrumDouble", { log }, LOG_SPEC),
+    ).not.toThrow();
+    expect(() =>
+      assertProcessContract(
+        "PerformanceSpectrumDouble",
+        { log, order: [{ from: "A", to: "B" }] },
+        LOG_SPEC,
+      ),
+    ).not.toThrow();
+  });
+
+  it("throws when the order resolves to nothing in the log", () => {
+    expect(() =>
+      assertProcessContract(
+        "PerformanceSpectrumDouble",
+        { log, order: [{ from: "B", to: "A" }] },
+        LOG_SPEC,
+      ),
+    ).toThrow(/resolves to no segment/);
+    expect(() =>
+      assertProcessContract(
+        "PerformanceSpectrumDouble",
+        { log, order: { variantId: "x" } },
+        LOG_SPEC,
+      ),
+    ).toThrow(ProcessContractError);
+  });
+});
+
 describe("buildProcessDoublePayload / readProcessDoubleProps round-trip", () => {
   it("carries the graph's activity count and the current selection", () => {
     const graph: ProcessGraph = { ...emptyGraph, activities: [...emptyGraph.activities] };

package/src/test/contract.ts

@@ -18,17 +18,37 @@
  * `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";
+import { toEpochMs } from "../core/event-log";
+import { discoverGraph } from "../core/discover-graph";
+import { extractVariants } from "../core/extract-variants";
+import {
+  segmentOrderByFrequency,
+  segmentOrderForVariant,
+  segmentsFor,
+  type SegmentDefinition,
+} from "../core/segments";
+import type { ConformanceResult } from "../core/conformance";
+import type { HappyPath } from "../core/reference-model";
+import type { EventLog, 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";
+  /**
+   * Name of the prop carrying the double's primary data payload. `conformance` is a
+   * `ConformanceResult` and `value` a `HappyPath` (RM-062).
+   */
+  dataProp: "graph" | "variants" | "log" | "conformance" | "value";
   /** Other props the real component requires; the double must not silently accept `undefined`. */
   requiredProps?: string[];
+  /**
+   * PerformanceSpectrum — RM-060: the `order` prop (default `"frequency"`) must resolve to
+   * at least one segment that actually occurs in `log`, or the real view renders only its
+   * empty panel — almost always a test wired to the wrong activity names.
+   */
+  segmentOrder?: boolean;
 }
 
 /** Thrown by {@link assertProcessContract} when a double is used with an invalid prop shape. */
@@ -48,6 +68,26 @@ function isProcessGraph(value: unknown): value is ProcessGraph {
   );
 }
 
+function isEventLog(value: unknown): value is EventLog {
+  return !!value && typeof value === "object" && Array.isArray((value as EventLog).events);
+}
+
+/** How many occurrences `order` (as `PerformanceSpectrum` reads it) finds in `log`. */
+function countSpectrumOccurrences(log: EventLog, order: unknown, limit: unknown): number {
+  const cap = typeof limit === "number" ? Math.max(0, Math.floor(limit)) : 12;
+  let definitions: SegmentDefinition[] = [];
+  if (order === undefined || order === "frequency") {
+    definitions = segmentOrderByFrequency(discoverGraph(log), cap);
+  } else if (Array.isArray(order)) {
+    definitions = (order as SegmentDefinition[]).slice(0, cap);
+  } else if (order && typeof order === "object" && "variantId" in order) {
+    const id = (order as { variantId: unknown }).variantId;
+    const variant = extractVariants(log).find((v) => v.id === id);
+    definitions = variant ? segmentOrderForVariant(variant).slice(0, cap) : [];
+  }
+  return segmentsFor(log, definitions).length;
+}
+
 function isVariantArray(value: unknown): value is Variant[] {
   return (
     Array.isArray(value) &&
@@ -55,6 +95,32 @@ function isVariantArray(value: unknown): value is Variant[] {
   );
 }
 
+// DottedChart — RM-059
+/** A non-empty event log whose every row carries a parsable timestamp. */
+function isTimedEventLog(value: unknown): value is EventLog {
+  const events = (value as EventLog | null | undefined)?.events;
+  return (
+    Array.isArray(events) &&
+    events.length > 0 &&
+    events.every(
+      (row) => !!row && typeof row === "object" && Number.isFinite(toEpochMs(row.timestamp)),
+    )
+  );
+}
+
+function isConformanceResult(value: unknown): value is ConformanceResult {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    Array.isArray((value as ConformanceResult).traces) &&
+    typeof (value as ConformanceResult).deviationCounts === "object"
+  );
+}
+
+function isHappyPath(value: unknown): value is HappyPath {
+  return !!value && typeof value === "object" && Array.isArray((value as HappyPath).steps);
+}
+
 /**
  * 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
@@ -79,6 +145,35 @@ export function assertProcessContract(
       `"variants" prop must be a Variant[], got ${typeof data}`,
     );
   }
+  if (spec.dataProp === "log" && !isTimedEventLog(data)) {
+    throw new ProcessContractError(
+      componentName,
+      `"log" prop must be an EventLog with non-empty events and parsable timestamps`,
+    );
+  }
+  if (
+    spec.segmentOrder &&
+    isEventLog(data) &&
+    data.events.length > 0 &&
+    countSpectrumOccurrences(data, props.order, props.segmentLimit) === 0
+  ) {
+    throw new ProcessContractError(
+      componentName,
+      `"order" resolves to no segment that occurs in "log"`,
+    );
+  }
+  if (spec.dataProp === "conformance" && !isConformanceResult(data)) {
+    throw new ProcessContractError(
+      componentName,
+      `"conformance" prop must be a ConformanceResult, got ${typeof data}`,
+    );
+  }
+  if (spec.dataProp === "value" && !isHappyPath(data)) {
+    throw new ProcessContractError(
+      componentName,
+      `"value" prop must be a HappyPath, got ${typeof data}`,
+    );
+  }
   for (const key of spec.requiredProps ?? []) {
     if (props[key] === undefined) {
       throw new ProcessContractError(componentName, `missing required prop "${key}"`);
@@ -103,9 +198,15 @@ export function buildProcessDoublePayload(
   const dataLength =
     spec.dataProp === "graph" && isProcessGraph(data)
       ? data.activities.length
-      : Array.isArray(data)
-        ? data.length
-        : 0;
+      : spec.dataProp === "log" && isTimedEventLog(data)
+        ? data.events.length
+        : spec.dataProp === "conformance" && isConformanceResult(data)
+          ? data.traces.length
+          : spec.dataProp === "value" && isHappyPath(data)
+            ? data.steps.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;

package/src/test/doubles.test.tsx

@@ -4,7 +4,19 @@ 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 { liftHappyPath } from "../core/reference-model";
+import { tokenReplay } from "../core/token-replay";
+import {
+  ConformanceOverlayDouble,
+  DottedChartDouble,
+  HappyPathEditorDouble,
+  PerformanceSpectrumDouble,
+  ProcessKpiStripDouble,
+  ProcessMapDouble,
+  ProcessReplayDouble,
+  VariantExplorerDouble,
+  ViolationListDouble,
+} from "./doubles";
 import { readProcessDoubleProps } from "./contract";
 
 const log = generateSyntheticLog({ cases: 20, seed: 7 });
@@ -44,8 +56,82 @@ describe("process test doubles", () => {
     expect(node).toBeInstanceOf(HTMLDivElement);
   });
 
+  // DottedChart — RM-059
+  it("DottedChartDouble mounts and records the event count", () => {
+    const { container } = render(<DottedChartDouble log={log} />);
+    const el = container.querySelector('[data-process-double="DottedChartDouble"]');
+    expect(readProcessDoubleProps(el as Element)?.dataLength).toBe(log.events.length);
+  });
+
+  it("DottedChartDouble rejects an empty log or an unparsable timestamp", () => {
+    expect(() => render(<DottedChartDouble log={{ events: [] }} />)).toThrow(/DottedChartDouble/);
+    expect(() =>
+      render(
+        <DottedChartDouble log={{ events: [{ caseId: "c", activity: "A", timestamp: "nope" }] }} />,
+      ),
+    ).toThrow(/parsable timestamps/);
+  });
+
+  // PerformanceSpectrum — RM-060
+  it("PerformanceSpectrumDouble records the event count and accepts the default order", () => {
+    const { container } = render(<PerformanceSpectrumDouble log={log} />);
+    const el = container.querySelector('[data-process-double="PerformanceSpectrumDouble"]');
+    expect(readProcessDoubleProps(el as Element)?.dataLength).toBe(log.events.length);
+  });
+
+  it("PerformanceSpectrumDouble accepts a variant path and rejects an order absent from the log", () => {
+    expect(() =>
+      render(<PerformanceSpectrumDouble log={log} order={{ variantId: variants[0]!.id }} />),
+    ).not.toThrow();
+    expect(() =>
+      render(<PerformanceSpectrumDouble log={log} order={[{ from: "Nope", to: "Never" }]} />),
+    ).toThrow(/resolves to no segment/);
+  });
+
   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/);
   });
 });
+
+describe("RM-062 doubles", () => {
+  const path = { id: "p", label: "Path", steps: [{ activity: "A" }, { activity: "B" }] };
+  const conformance = tokenReplay(log, liftHappyPath(path));
+
+  it("ConformanceOverlayDouble records the replayed case count and needs a graph", () => {
+    const { container } = render(
+      <ConformanceOverlayDouble graph={graph} conformance={conformance} />,
+    );
+    const el = container.querySelector('[data-process-double="ConformanceOverlayDouble"]');
+    expect(readProcessDoubleProps(el as Element)?.dataLength).toBe(conformance.traces.length);
+    // @ts-expect-error -- deliberately omitting the required `graph` prop
+    expect(() => render(<ConformanceOverlayDouble conformance={conformance} />)).toThrow(
+      /missing required prop "graph"/,
+    );
+  });
+
+  it("ViolationListDouble rejects a non-ConformanceResult", () => {
+    // @ts-expect-error -- deliberately passing the wrong shape
+    expect(() => render(<ViolationListDouble conformance={graph} />)).toThrow(/ConformanceResult/);
+  });
+
+  it("HappyPathEditorDouble records the step count and requires onChange", () => {
+    const { container } = render(<HappyPathEditorDouble value={path} onChange={() => {}} />);
+    const el = container.querySelector('[data-process-double="HappyPathEditorDouble"]');
+    expect(readProcessDoubleProps(el as Element)?.dataLength).toBe(2);
+    // @ts-expect-error -- deliberately omitting the required `onChange` prop
+    expect(() => render(<HappyPathEditorDouble value={path} />)).toThrow(/onChange/);
+  });
+});
+
+describe("RM-065 doubles", () => {
+  it("ProcessReplayDouble records the event count and needs a graph", () => {
+    const { container } = render(<ProcessReplayDouble graph={graph} log={log} />);
+    const el = container.querySelector('[data-process-double="ProcessReplayDouble"]');
+    expect(readProcessDoubleProps(el as Element)?.dataLength).toBe(log.events.length);
+    // @ts-expect-error -- deliberately omitting the required `graph` prop
+    expect(() => render(<ProcessReplayDouble log={log} />)).toThrow(
+      /missing required prop "graph"/,
+    );
+  });
+});

package/src/test/doubles.tsx

@@ -12,10 +12,13 @@
 import { forwardRef } from "react";
 import type { HTMLAttributes } from "react";
 
-import type { ProcessGraph, Variant } from "../core/types";
+import type { ConformanceResult } from "../core/conformance";
+import type { HappyPath } from "../core/reference-model";
+import type { EventLog, ProcessGraph, Variant } from "../core/types";
 import {
   assertProcessContract,
   buildProcessDoublePayload,
+  ProcessContractError,
   type ProcessContractSpec,
   type ProcessSelection,
 } from "./contract";
@@ -41,7 +44,10 @@ 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) {
+/** The only props the factory itself reads — a double's own contract is its `P`. */
+type DoubleRenderProps = Pick<HTMLAttributes<HTMLDivElement>, "className" | "style">;
+
+function createProcessDouble<P extends DoubleRenderProps>(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);
@@ -79,4 +85,169 @@ export const ProcessKpiStripDouble = createProcessDouble<ProcessKpiStripDoublePr
   PROCESS_KPI_STRIP_SPEC,
 );
 
-export type { ProcessMapDoubleProps, VariantExplorerDoubleProps, ProcessKpiStripDoubleProps };
+// DottedChart — RM-059
+interface DottedChartDoubleProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+  log: EventLog;
+  selectedCaseIds?: readonly string[];
+  onSelect?: (caseIds: string[]) => void;
+}
+
+/** Stand-in for `DottedChart` (RM-059). Asserts a non-empty `log.events` with parsable timestamps. */
+export const DottedChartDouble = createProcessDouble<DottedChartDoubleProps>("DottedChartDouble", {
+  dataProp: "log",
+});
+
+// PerformanceSpectrum — RM-060
+interface PerformanceSpectrumDoubleProps extends HTMLAttributes<HTMLDivElement> {
+  log: EventLog;
+  /** Explicit segments, `"frequency"` (the default) or `{ variantId }` — as the real prop. */
+  order?: Array<{ from: string; to: string; label?: string }> | "frequency" | { variantId: string };
+  segmentLimit?: number;
+  mode?: "lines" | "aggregated";
+  binSize?: number;
+  onFilterIntent?: (intent: { kind: "cases"; ids: string[] }) => void;
+  height?: number;
+  tableView?: boolean;
+  loading?: boolean;
+}
+
+const PERFORMANCE_SPECTRUM_SPEC: ProcessContractSpec = { dataProp: "log", segmentOrder: true };
+
+/** Stand-in for `PerformanceSpectrum` (RM-060); asserts `order` resolves to a segment present in `log`. */
+export const PerformanceSpectrumDouble = createProcessDouble<PerformanceSpectrumDoubleProps>(
+  "PerformanceSpectrumDouble",
+  PERFORMANCE_SPECTRUM_SPEC,
+);
+
+// ── RM-062 ───────────────────────────────────────────────────────────────────
+
+interface ConformanceOverlayDoubleProps extends DoubleOwnProps {
+  graph: ProcessGraph;
+  conformance: ConformanceResult;
+}
+
+interface ViolationListDoubleProps extends HTMLAttributes<HTMLDivElement> {
+  conformance: ConformanceResult;
+}
+
+interface HappyPathEditorDoubleProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+  value: HappyPath;
+  onChange: (path: HappyPath) => void;
+}
+
+/** Stand-in for `ConformanceOverlay` (RM-062): requires a graph AND a replay result. */
+export const ConformanceOverlayDouble = createProcessDouble<ConformanceOverlayDoubleProps>(
+  "ConformanceOverlayDouble",
+  { dataProp: "conformance", requiredProps: ["graph"] },
+);
+
+/** Stand-in for `ViolationList` (RM-062). */
+export const ViolationListDouble = createProcessDouble<ViolationListDoubleProps>(
+  "ViolationListDouble",
+  { dataProp: "conformance" },
+);
+
+/** Stand-in for `HappyPathEditor` (RM-062): a controlled editor, so `onChange` is required. */
+export const HappyPathEditorDouble = createProcessDouble<HappyPathEditorDoubleProps>(
+  "HappyPathEditorDouble",
+  { dataProp: "value", requiredProps: ["onChange"] },
+);
+
+// ── RM-065 ───────────────────────────────────────────────────────────────────
+
+interface ProcessReplayDoubleProps extends HTMLAttributes<HTMLDivElement> {
+  graph: ProcessGraph;
+  log: EventLog;
+  synchronizedStart?: boolean;
+  bucketMs?: number;
+  playing?: boolean;
+  defaultPlaying?: boolean;
+  onPlayingChange?: (playing: boolean) => void;
+  time?: number;
+  defaultTime?: number;
+  onTimeChange?: (time: number) => void;
+  speed?: number;
+  defaultSpeed?: number;
+  onSpeedChange?: (speed: number) => void;
+  congestionLimit?: number;
+  loading?: boolean;
+}
+
+/** Stand-in for `ProcessReplay` (RM-065): requires the log (per-case timing) AND the graph. */
+export const ProcessReplayDouble = createProcessDouble<ProcessReplayDoubleProps>(
+  "ProcessReplayDouble",
+  { dataProp: "log", requiredProps: ["graph"] },
+);
+
+export type {
+  ProcessReplayDoubleProps,
+  DottedChartDoubleProps,
+  PerformanceSpectrumDoubleProps,
+  ProcessMapDoubleProps,
+  VariantExplorerDoubleProps,
+  ProcessKpiStripDoubleProps,
+  ConformanceOverlayDoubleProps,
+  ViolationListDoubleProps,
+  HappyPathEditorDoubleProps,
+};
+
+// ── ProcessCompareDouble — RM-064 ────────────────────────────────────────────
+//
+// `ProcessCompare` composes `ProcessMap` twice (or once, superimposed) — a REAL component
+// this package already ships, unlike the pre-launch stand-ins above. Its own contract does
+// not fit `ProcessContractSpec` (`dataProp: "graph" | "variants"` — a single top-level
+// payload), because `ProcessCompare`'s payload is a PAIR (`a`/`b`), so this double validates
+// and serializes its own shape directly rather than stretching the shared engine.
+
+interface ProcessCompareSideDoubleProps {
+  label: string;
+  graph?: ProcessGraph;
+}
+
+interface ProcessCompareDoubleProps extends HTMLAttributes<HTMLDivElement> {
+  a: ProcessCompareSideDoubleProps;
+  b: ProcessCompareSideDoubleProps;
+  mode?: "side-by-side" | "superimposed";
+}
+
+/** What `ProcessCompareDouble` records to `data-process-props`. */
+interface ProcessCompareDoublePayload {
+  component: "ProcessCompareDouble";
+  mode: "side-by-side" | "superimposed";
+  aLabel: string;
+  bLabel: string;
+  aActivityCount: number;
+  bActivityCount: number;
+}
+
+/** Stand-in for `ProcessCompare` (RM-064) — cheap enough to mount without a real canvas. */
+export const ProcessCompareDouble = forwardRef<HTMLDivElement, ProcessCompareDoubleProps>(
+  function ProcessCompareDouble({ a, b, mode = "side-by-side", className, style }, ref) {
+    if (!a || typeof a.label !== "string") {
+      throw new ProcessContractError("ProcessCompareDouble", 'missing required prop "a.label"');
+    }
+    if (!b || typeof b.label !== "string") {
+      throw new ProcessContractError("ProcessCompareDouble", 'missing required prop "b.label"');
+    }
+    const payload: ProcessCompareDoublePayload = {
+      component: "ProcessCompareDouble",
+      mode,
+      aLabel: a.label,
+      bLabel: b.label,
+      aActivityCount: a.graph?.activities.length ?? 0,
+      bActivityCount: b.graph?.activities.length ?? 0,
+    };
+    return (
+      <div
+        ref={ref}
+        data-slot="process-test-double"
+        data-process-double="ProcessCompareDouble"
+        data-process-props={JSON.stringify(payload)}
+        className={className}
+        style={style}
+      />
+    );
+  },
+);
+
+export type { ProcessCompareDoubleProps, ProcessCompareDoublePayload };

package/src/test/index.ts

@@ -22,13 +22,37 @@ export {
 export type { ProcessContractSpec, ProcessDoublePayload, ProcessSelection } from "./contract";
 
 // Doubles
-export { ProcessKpiStripDouble, ProcessMapDouble, VariantExplorerDouble } from "./doubles";
+export {
+  PerformanceSpectrumDouble,
+  ProcessCompareDouble,
+  ProcessKpiStripDouble,
+  ProcessMapDouble,
+  VariantExplorerDouble,
+} from "./doubles";
 export type {
+  PerformanceSpectrumDoubleProps,
+  ProcessCompareDoubleProps,
   ProcessKpiStripDoubleProps,
   ProcessMapDoubleProps,
   VariantExplorerDoubleProps,
 } from "./doubles";
 
+// DottedChart — RM-059
+export { DottedChartDouble } from "./doubles";
+export type { DottedChartDoubleProps } from "./doubles";
+
+// Doubles — RM-062
+export { ConformanceOverlayDouble, HappyPathEditorDouble, ViolationListDouble } from "./doubles";
+export type {
+  ConformanceOverlayDoubleProps,
+  HappyPathEditorDoubleProps,
+  ViolationListDoubleProps,
+} from "./doubles";
+
+// Doubles — RM-065
+export { ProcessReplayDouble } from "./doubles";
+export type { ProcessReplayDoubleProps } from "./doubles";
+
 // Fixture helper
 export { withProcessFixture } from "./primitives";
 export type { ProcessFixture } from "./primitives";

package/src/use-process-explorer/use-process-explorer.test.ts

@@ -264,6 +264,50 @@ describe("useProcessExplorer — filter intents (the RM-052 acceptance criterion
   });
 });
 
+describe("useProcessExplorer — excludedByIntent (RM-056, #205)", () => {
+  it("is empty with no active intents", () => {
+    const { result } = renderHook(() => useProcessExplorer(orderToCash));
+    expect(result.current.excludedByIntent).toEqual([]);
+  });
+
+  it("hand-computed against the fixture: a three-intent chain, each entry the MARGINAL exclusion", () => {
+    // Fixture cases: case-1/2 (happy path), case-3 (Reject Order), case-4 (Amend Order,
+    // then the happy path), case-5 (happy path, Send Invoice before Ship).
+    const { result } = renderHook(() => useProcessExplorer(orderToCash));
+
+    // A: drop case-3 (the only case with "Reject Order") — 5 cases -> 4, excludes 1.
+    act(() => result.current.applyIntent({ kind: "without", activity: "Reject Order" }));
+    // B: of the remaining 4 (case-1/2/4/5), keep only "Amend Order" — just case-4 — so B
+    // alone (on top of A) excludes the other 3 (case-1/2/5).
+    act(() => result.current.applyIntent({ kind: "with", activity: "Amend Order" }));
+    // C: of the remaining 1 (case-4), "endsWith Receive Payment" still holds — excludes 0.
+    act(() => result.current.applyIntent({ kind: "endsWith", activity: "Receive Payment" }));
+
+    expect(result.current.intents).toEqual([
+      { kind: "without", activity: "Reject Order" },
+      { kind: "with", activity: "Amend Order" },
+      { kind: "endsWith", activity: "Receive Payment" },
+    ]);
+    expect(result.current.excludedByIntent).toEqual([1, 3, 0]);
+    // The chain's own final case count agrees with the KPI strip's own number — no
+    // double counting between the per-chip figures and the whole-chain total.
+    expect(result.current.kpis.cases).toBe(1);
+  });
+
+  it("stays parallel to `intents` after clearIntent drops an entry from the middle", () => {
+    const { result } = renderHook(() => useProcessExplorer(orderToCash));
+    act(() => result.current.applyIntent({ kind: "without", activity: "Reject Order" }));
+    act(() => result.current.applyIntent({ kind: "with", activity: "Amend Order" }));
+    expect(result.current.excludedByIntent).toEqual([1, 3]);
+
+    act(() => result.current.clearIntent(0));
+    expect(result.current.intents).toEqual([{ kind: "with", activity: "Amend Order" }]);
+    // Recomputed from scratch against the NEW chain — "with Amend Order" alone, against
+    // the full 5-case log, excludes the 4 cases that never touch "Amend Order".
+    expect(result.current.excludedByIntent).toEqual([4]);
+  });
+});
+
 describe("useProcessExplorer — selectionStates.variants (RM-052 round 3, #227, G2)", () => {
   it('marks each id of an active "variant" intent "selected"', () => {
     const { result } = renderHook(() => useProcessExplorer(orderToCash));