@elabs-ai/components-process 4.2.0 → 5.1.0

package/src/case-timeline/case-timeline.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+/**
+ * CaseTimeline — the single-case Gantt every case drill-down opens into (RM-055, issue
+ * #204, §4 R12): "single-case timeline with activity durations and waiting time".
+ *
+ * A THIN wrapper: it computes {@link buildCaseTimelineInstances}'s model and renders
+ * `@elabs-ai/components-charts`'s `Gantt` — it does not draw a bar, a gap band or a grid
+ * line itself (`.claude/rules/data.md` — "primitives go down, compositions go up"). Waiting
+ * time reuses RM-047's `GanttTask.gaps` hatched-band rendering directly; there is no second
+ * idle-time renderer here.
+ *
+ * ## The parallel flag carries a text channel, not just a colour
+ *
+ * Two overlapping instances get `status="info"` (an existing `Gantt` tone — no new color,
+ * per the RM's own instruction), but WCAG 1.4.1 forbids colour as the ONLY channel for a
+ * status. `name` (a `ReactNode` `Gantt` already supports) carries a visible "Parallel" tag
+ * plus an `sr-only` explanation for anyone who cannot see the tone at all.
+ */
+import { forwardRef, useMemo, type HTMLAttributes } from "react";
+import { Gantt, type GanttGap, type GanttTask } from "@elabs-ai/components-charts";
+import { Badge, useLocale } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import type { EventRow } from "../core/types";
+import { formatDurationMs } from "../process-map/map-model";
+import {
+  buildCaseTimelineInstances,
+  type CaseTimelineInstance,
+  type CaseTimelineModelOptions,
+} from "./case-timeline-model";
+
+export interface CaseTimelineProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect">, CaseTimelineModelOptions {
+  caseId: string;
+  /** This case's own events, straight from `core`'s `EventLog.events`. */
+  events: EventRow[];
+}
+
+function instanceName(
+  instance: CaseTimelineInstance,
+  t: ReturnType<typeof useLocale>["t"],
+): GanttTask["name"] {
+  if (!instance.isParallel) return instance.activity;
+  return (
+    <span className="inline-flex items-center gap-1.5">
+      <span>{instance.activity}</span>
+      <Badge variant="info">{t("process.caseTimeline.parallelLabel")}</Badge>
+      <span className="sr-only">, {t("process.caseTimeline.parallelSuffix")}</span>
+    </span>
+  );
+}
+
+function instanceGaps(
+  instance: CaseTimelineInstance,
+  t: ReturnType<typeof useLocale>["t"],
+): GanttGap[] | undefined {
+  if (!instance.gap) return undefined;
+  return [
+    {
+      start: instance.gap.start,
+      end: instance.gap.end,
+      label: t("process.caseTimeline.gapLabel", {
+        duration: formatDurationMs(instance.gap.durationMs),
+      }),
+    },
+  ];
+}
+
+export const CaseTimeline = forwardRef<HTMLDivElement, CaseTimelineProps>(function CaseTimeline(
+  { caseId, events, parallelismThreshold, className, ...props },
+  ref,
+) {
+  const { t } = useLocale();
+
+  const instances = useMemo(
+    () => buildCaseTimelineInstances(events, { parallelismThreshold }),
+    [events, parallelismThreshold],
+  );
+
+  const tasks = useMemo<GanttTask[]>(
+    () =>
+      instances.map((instance) => {
+        const task: GanttTask = {
+          id: `${caseId}-${instance.id}`,
+          name: instanceName(instance, t),
+          start: instance.start,
+          end: instance.end,
+        };
+        if (instance.isParallel) task.status = "info";
+        const gaps = instanceGaps(instance, t);
+        if (gaps) task.gaps = gaps;
+        return task;
+      }),
+    [instances, caseId, t],
+  );
+
+  return (
+    <Gantt
+      ref={ref}
+      data-slot="case-timeline"
+      aria-label={t("process.caseTimeline.label")}
+      tasks={tasks}
+      defaultViewMode="auto"
+      labelPosition="end"
+      className={cn(className)}
+      {...props}
+    />
+  );
+});

package/src/case-timeline/index.ts

@@ -0,0 +1,9 @@
+export { CaseTimeline } from "./case-timeline";
+export type { CaseTimelineProps } from "./case-timeline";
+
+export { buildCaseTimelineInstances } from "./case-timeline-model";
+export type {
+  CaseTimelineGap,
+  CaseTimelineInstance,
+  CaseTimelineModelOptions,
+} from "./case-timeline-model";

package/src/conformance-overlay/conformance-fixture.ts

@@ -0,0 +1,59 @@
+/**
+ * The conformance fixture RM-062's components, tests and stories share — a small,
+ * hand-built purchase-approval log replayed against its happy path, so every number a
+ * story shows can be checked by hand.
+ *
+ * Happy path: Register → Check credit → Approve → Pay (every step required).
+ *
+ * | cases     | trace                                          | deviation    |
+ * | --------- | ---------------------------------------------- | ------------ |
+ * | c01 … c06 | Register, Check credit, Approve, Pay           | none         |
+ * | c07, c08  | Register, Approve, Pay                         | `skipped`    |
+ * | c09       | Register, Check credit, Escalate, Approve, Pay | `undesired`  |
+ * | c10       | Register, Check credit, Approve                | `incomplete` |
+ *
+ * Cases start one per fortnight from 2026-01-05 (UTC), so a monthly
+ * `conformanceRateSeries` has more than one point.
+ *
+ * Framework-free: no React, so a unit test and a story import the same data.
+ */
+import type { HappyPath } from "../core/reference-model";
+import type { EventLog, EventRow } from "../core/types";
+
+/** The fixture's prescribed process. */
+export const CONFORMANCE_FIXTURE_PATH: HappyPath = {
+  id: "purchase-approval",
+  label: "Purchase approval",
+  steps: [
+    { activity: "Register" },
+    { activity: "Check credit" },
+    { activity: "Approve" },
+    { activity: "Pay" },
+  ],
+};
+
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+const FIRST_START = Date.UTC(2026, 0, 5, 9);
+
+const TRACES: ReadonlyArray<readonly [string, readonly string[]]> = [
+  ["c01", ["Register", "Check credit", "Approve", "Pay"]],
+  ["c02", ["Register", "Check credit", "Approve", "Pay"]],
+  ["c03", ["Register", "Check credit", "Approve", "Pay"]],
+  ["c04", ["Register", "Check credit", "Approve", "Pay"]],
+  ["c05", ["Register", "Check credit", "Approve", "Pay"]],
+  ["c06", ["Register", "Check credit", "Approve", "Pay"]],
+  ["c07", ["Register", "Approve", "Pay"]],
+  ["c08", ["Register", "Approve", "Pay"]],
+  ["c09", ["Register", "Check credit", "Escalate", "Approve", "Pay"]],
+  ["c10", ["Register", "Check credit", "Approve"]],
+];
+
+function rows(caseId: string, start: number, trace: readonly string[]): EventRow[] {
+  return trace.map((activity, i) => ({ caseId, activity, timestamp: start + i * HOUR }));
+}
+
+/** The fixture event log. */
+export const CONFORMANCE_FIXTURE_LOG: EventLog = {
+  events: TRACES.flatMap(([caseId, trace], i) => rows(caseId, FIRST_START + i * 14 * DAY, trace)),
+};

package/src/conformance-overlay/conformance-legend.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+/**
+ * ConformanceLegend — the key for the conformance overlay (RM-062).
+ *
+ * Follows `@elabs-ai/components-flow`'s `Legend` pattern (a titled swatch list on a
+ * raised surface) but cannot BE that `Legend`: its categorical variant keys by colour
+ * alone, and analysis §5.4 forbids a bare colour key. Each entry here pairs three
+ * channels — the tone, the glyph (circle / triangle / square) and a line sample in the
+ * state's dash (solid / dotted / dashed) — plus the state's word, all read from the one
+ * {@link CONFORMANCE_STATE_ENCODING} table the map's nodes and edges also read.
+ *
+ * Built from HTML and Lucide glyphs only; no SVG is authored here.
+ */
+import { forwardRef, type HTMLAttributes } from "react";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import {
+  CONFORMANCE_STATE_DEFAULT_LABELS,
+  CONFORMANCE_STATE_ENCODING,
+  CONFORMANCE_STATES,
+  type ConformanceState,
+  type ConformanceStateLabels,
+} from "./conformance-state";
+
+/** Props for {@link ConformanceStateMark}. */
+export interface ConformanceStateMarkProps extends HTMLAttributes<HTMLSpanElement> {
+  state: ConformanceState;
+  /** Override the state's word. */
+  labels?: Partial<ConformanceStateLabels>;
+}
+
+/**
+ * One state as glyph + coloured word — the text form a table cell prints. The glyph is
+ * `aria-hidden`; the word is the accessible reading.
+ */
+export const ConformanceStateMark = forwardRef<HTMLSpanElement, ConformanceStateMarkProps>(
+  function ConformanceStateMark({ state, labels, className, ...props }, ref) {
+    const encoding = CONFORMANCE_STATE_ENCODING[state];
+    const Glyph = encoding.icon;
+    const word = labels?.[state] ?? CONFORMANCE_STATE_DEFAULT_LABELS[state];
+    return (
+      <span
+        ref={ref}
+        data-slot="conformance-state-mark"
+        data-conformance={state}
+        data-glyph={encoding.glyph}
+        className={cn("inline-flex min-w-0 items-center gap-1.5", className)}
+        {...props}
+      >
+        <Glyph aria-hidden="true" className={cn("size-3.5 shrink-0", encoding.markClass)} />
+        <span className={encoding.textClass}>{word}</span>
+      </span>
+    );
+  },
+);
+
+/** Props for {@link ConformanceLegend}. */
+export interface ConformanceLegendProps extends HTMLAttributes<HTMLDivElement> {
+  /** Override any state word or the title. */
+  labels?: Partial<ConformanceStateLabels>;
+}
+
+/** The three-state key: tone + glyph + dash + word per entry. */
+export const ConformanceLegend = forwardRef<HTMLDivElement, ConformanceLegendProps>(
+  function ConformanceLegend({ labels: labelOverrides, className, ...props }, ref) {
+    const labels = { ...CONFORMANCE_STATE_DEFAULT_LABELS, ...labelOverrides };
+    return (
+      <div
+        ref={ref}
+        role="group"
+        aria-label={labels.column}
+        data-slot="conformance-legend"
+        className={cn(
+          "flex flex-col gap-1.5 rounded-lg bg-surface-elevated p-3 shadow-ring-sm",
+          className,
+        )}
+        {...props}
+      >
+        <div aria-hidden="true" className="text-caption font-medium text-foreground">
+          {labels.column}
+        </div>
+        <ul className="flex flex-wrap gap-x-4 gap-y-1.5">
+          {CONFORMANCE_STATES.map((state) => {
+            const encoding = CONFORMANCE_STATE_ENCODING[state];
+            const Glyph = encoding.icon;
+            return (
+              <li
+                key={state}
+                data-slot="conformance-legend-item"
+                data-conformance={state}
+                data-glyph={encoding.glyph}
+                data-dash={encoding.dash}
+                className="flex items-center gap-2 text-caption text-muted-foreground"
+              >
+                <Glyph aria-hidden="true" className={cn("size-3.5 shrink-0", encoding.markClass)} />
+                <span
+                  aria-hidden="true"
+                  data-slot="conformance-legend-dash"
+                  className={cn("w-6 shrink-0 border-t-2", encoding.borderClass)}
+                />
+                {labels[state]}
+              </li>
+            );
+          })}
+        </ul>
+      </div>
+    );
+  },
+);

package/src/conformance-overlay/conformance-overlay.stories.tsx

@@ -0,0 +1,116 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import "@xyflow/react/dist/style.css";
+import { expect, waitFor, within } from "storybook/test";
+import { discoverGraph } from "../core/discover-graph";
+import { liftHappyPath } from "../core/reference-model";
+import { tokenReplay } from "../core/token-replay";
+import { CONFORMANCE_FIXTURE_LOG, CONFORMANCE_FIXTURE_PATH } from "./conformance-fixture";
+import { ConformanceLegend } from "./conformance-legend";
+import { ConformanceOverlay } from "./conformance-overlay";
+
+const graph = discoverGraph(CONFORMANCE_FIXTURE_LOG);
+const conformance = tokenReplay(CONFORMANCE_FIXTURE_LOG, liftHappyPath(CONFORMANCE_FIXTURE_PATH));
+
+const meta = {
+  title: "Process/ConformanceOverlay",
+  component: ConformanceOverlay,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "A `ProcessMap` painted with a token-replay result: every activity and transition " +
+          "is `both` (in log and model), `logOnly` (the log does it, the model does not) or " +
+          "`modelOnly` (the model expects it, cases skipped it). Each state carries a status " +
+          "tone, a glyph, a line style and a word in its accessible name — never colour alone. " +
+          "`data-conformance` is added beside `data-selection`, never in place of it.",
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="h-[40rem] w-full bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+  args: { graph, conformance },
+} satisfies Meta<typeof ConformanceOverlay>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** The canvas: glyph marker + frame dash per activity, dash + pill glyph per transition. */
+export const Default: Story = {
+  play: async ({ canvasElement }) => {
+    await waitFor(
+      () =>
+        expect(canvasElement.querySelectorAll(".react-flow__node[data-conformance]").length).toBe(
+          graph.activities.length,
+        ),
+      { timeout: 5000 },
+    );
+    // Every state on the canvas pairs with ONE glyph and ONE dash, and no two states share
+    // either — the greyscale test, asserted.
+    const glyphByState = new Map<string, string>();
+    const dashByState = new Map<string, string>();
+    for (const marker of canvasElement.querySelectorAll<HTMLElement>(
+      '[data-slot="process-activity-node-conformance"]',
+    )) {
+      const state = marker.closest("[data-conformance]")!.getAttribute("data-conformance")!;
+      const glyph = marker.getAttribute("data-glyph")!;
+      const dash = marker.getAttribute("data-dash")!;
+      if (glyphByState.has(state)) await expect(glyphByState.get(state)).toBe(glyph);
+      glyphByState.set(state, glyph);
+      dashByState.set(state, dash);
+    }
+    await expect([...glyphByState.keys()].sort()).toEqual(["both", "logOnly", "modelOnly"]);
+    await expect(new Set(glyphByState.values()).size).toBe(3);
+    await expect(new Set(dashByState.values()).size).toBe(3);
+
+    const skipped = canvasElement.querySelector('.react-flow__node[data-id="Check credit"]')!;
+    await expect(skipped).toHaveAttribute("data-conformance", "modelOnly");
+    await expect(skipped.getAttribute("aria-label")).toMatch(/Model only/);
+
+    const legend = within(canvasElement).getByRole("group", { name: "Conformance" });
+    await expect(within(legend).getAllByRole("listitem")).toHaveLength(3);
+  },
+};
+
+/** The accessible twin: a Conformance column whose cell prints the glyph and the word. */
+export const TableView: Story = {
+  args: { tableView: true },
+  decorators: [
+    (Story) => (
+      <div className="h-[40rem] w-full overflow-auto">
+        <Story />
+      </div>
+    ),
+  ],
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const activities = await canvas.findByRole("table", { name: /Activities/ });
+    await expect(
+      within(activities).getByRole("columnheader", { name: "Conformance" }),
+    ).toBeVisible();
+    const row = within(activities).getByRole("row", { name: /Check credit/ });
+    await expect(row).toHaveAttribute("data-conformance", "modelOnly");
+    await expect(within(row).getByText(/Model only/)).toBeVisible();
+  },
+};
+
+/** No replay yet — the map's own loading panel; the legend waits with it. */
+export const Loading: Story = {
+  args: { loading: true },
+};
+
+/** The legend on its own, for a toolbar or side panel beside the map. */
+export const Legend: Story = {
+  render: () => <ConformanceLegend />,
+  play: async ({ canvasElement }) => {
+    const items = canvasElement.querySelectorAll('[data-slot="conformance-legend-item"]');
+    await expect(items).toHaveLength(3);
+    await expect(new Set([...items].map((item) => item.getAttribute("data-glyph"))).size).toBe(3);
+    await expect(new Set([...items].map((item) => item.getAttribute("data-dash"))).size).toBe(3);
+  },
+};

package/src/conformance-overlay/conformance-overlay.test.tsx

@@ -0,0 +1,88 @@
+import { cleanup, render, screen, waitFor, within } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { discoverGraph } from "../core/discover-graph";
+import { liftHappyPath } from "../core/reference-model";
+import { tokenReplay } from "../core/token-replay";
+import { ProcessMap } from "../process-map/process-map";
+import { CONFORMANCE_FIXTURE_LOG, CONFORMANCE_FIXTURE_PATH } from "./conformance-fixture";
+import { ConformanceLegend } from "./conformance-legend";
+import { ConformanceOverlay } from "./conformance-overlay";
+
+// jsdom has no `DOMMatrixReadOnly`, which React Flow's transform math needs to mount the
+// canvas at all — the same missing-browser-API fill `process-map.test.tsx` documents.
+if (typeof globalThis.DOMMatrixReadOnly === "undefined") {
+  class DOMMatrixReadOnlyPolyfill {
+    m22 = 1;
+    constructor(_init?: unknown) {}
+  }
+  globalThis.DOMMatrixReadOnly = DOMMatrixReadOnlyPolyfill as unknown as typeof DOMMatrixReadOnly;
+}
+
+afterEach(cleanup);
+
+const graph = discoverGraph(CONFORMANCE_FIXTURE_LOG);
+const conformance = tokenReplay(CONFORMANCE_FIXTURE_LOG, liftHappyPath(CONFORMANCE_FIXTURE_PATH));
+const metric = { node: "absolute_case", edge: "absolute" } as const;
+
+describe("ConformanceLegend", () => {
+  it("pairs every state with a distinct glyph and dash, and names it in text", () => {
+    render(<ConformanceLegend />);
+    const legend = screen.getByRole("group", { name: "Conformance" });
+    const items = legend.querySelectorAll('[data-slot="conformance-legend-item"]');
+    expect(items).toHaveLength(3);
+    const glyphs = new Set([...items].map((item) => item.getAttribute("data-glyph")));
+    const dashes = new Set([...items].map((item) => item.getAttribute("data-dash")));
+    expect(glyphs.size).toBe(3);
+    expect(dashes.size).toBe(3);
+    expect(within(legend).getByText(/Model only/)).toBeInTheDocument();
+  });
+});
+
+describe("ConformanceOverlay — table twin", () => {
+  it("adds a Conformance column whose rows carry data-conformance and a word", () => {
+    render(<ConformanceOverlay graph={graph} conformance={conformance} tableView />);
+    const activityTable = document.querySelector<HTMLElement>(
+      '[data-slot="process-map-activity-table"]',
+    )!;
+    expect(within(activityTable).getByRole("columnheader", { name: "Conformance" })).toBeVisible();
+    const skipped = within(activityTable).getByRole("row", { name: /Check credit/ });
+    expect(skipped).toHaveAttribute("data-conformance", "modelOnly");
+    expect(within(skipped).getByText(/Model only/)).toBeInTheDocument();
+
+    const transitionTable = document.querySelector<HTMLElement>(
+      '[data-slot="process-map-transition-table"]',
+    )!;
+    const diverged = [...transitionTable.querySelectorAll("tbody tr")].find(
+      (row) => row.textContent?.startsWith("RegisterApprove") ?? false,
+    );
+    expect(diverged).toHaveAttribute("data-conformance", "logOnly");
+  });
+
+  it("hides the legend while loading", () => {
+    render(<ConformanceOverlay graph={graph} conformance={conformance} loading />);
+    expect(document.querySelector('[data-slot="conformance-legend"]')).toBeNull();
+    expect(screen.getByRole("status")).toBeInTheDocument();
+  });
+});
+
+describe("ProcessMap — conformance is additive", () => {
+  it("renders no conformance column or attribute without the prop", () => {
+    render(<ProcessMap graph={graph} metric={metric} tableView />);
+    expect(screen.queryByRole("columnheader", { name: "Conformance" })).toBeNull();
+    expect(document.querySelector("[data-conformance]")).toBeNull();
+  });
+
+  it("puts data-conformance on React Flow's node element and a glyph marker inside", async () => {
+    render(<ConformanceOverlay graph={graph} conformance={conformance} />);
+    await waitFor(() =>
+      expect(document.querySelectorAll(".react-flow__node").length).toBe(graph.activities.length),
+    );
+    const node = document.querySelector<HTMLElement>('.react-flow__node[data-id="Check credit"]')!;
+    expect(node).toHaveAttribute("data-conformance", "modelOnly");
+    expect(node).toHaveAttribute("data-selection", "associated");
+    expect(node).toHaveAttribute("aria-label", expect.stringMatching(/Model only/));
+    const marker = node.querySelector('[data-slot="process-activity-node-conformance"]');
+    expect(marker).toHaveAttribute("data-glyph", "square");
+    expect(marker).toHaveAttribute("data-dash", "dashed");
+  });
+});

package/src/conformance-overlay/conformance-overlay.tsx

@@ -0,0 +1,107 @@
+"use client";
+
+/**
+ * ConformanceOverlay — the process map read against a reference model (RM-062).
+ *
+ * A thin composition: `ProcessMap` with its `conformance` prop always set, plus a
+ * {@link ConformanceLegend} explaining the three states. It authors no node or edge
+ * rendering of its own — the tone, glyph and dash per element come from `ProcessMap`'s own
+ * activity node and transition edge, so the overlay and the plain map can never drift
+ * (`pnpm check --rule process-reuse`).
+ *
+ * Every state reaches the reader on three visual channels (tone, glyph, line style) and as
+ * text (the accessible name on the canvas, a Conformance column in `tableView`), so the
+ * overlay never relies on colour alone (analysis §5.4, WCAG 1.4.1).
+ */
+import { forwardRef, type HTMLAttributes } from "react";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import type { FlowLayoutDirection } from "@elabs-ai/components-flow";
+import type { ConformanceResult } from "../core/conformance";
+import type { ProcessGraph } from "../core/types";
+import type { ProcessMetricSpec, ProcessSelection } from "../process-map/map-model";
+import { ProcessMap, type ProcessMapProps } from "../process-map/process-map";
+import { ConformanceLegend } from "./conformance-legend";
+import type { ConformanceStateLabels } from "./conformance-state";
+
+/** The metric the overlay paints when none is given: case frequency on both marks. */
+export const CONFORMANCE_OVERLAY_DEFAULT_METRIC: ProcessMetricSpec = Object.freeze({
+  node: "absolute_case",
+  edge: "absolute",
+}) as ProcessMetricSpec;
+
+/** Props for {@link ConformanceOverlay}. `onSelect` shadows the DOM handler, so it is omitted. */
+export interface ConformanceOverlayProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+  /** The discovered graph to overlay. */
+  graph: ProcessGraph;
+  /** The replay result (`tokenReplay`) against the reference model. */
+  conformance: ConformanceResult;
+  /** Which readings the nodes and edges print. @default case frequency */
+  metric?: ProcessMetricSpec;
+  /** @default "TB" */
+  direction?: FlowLayoutDirection;
+  /** Controlled selection, passed straight to `ProcessMap`. */
+  selection?: ProcessSelection | null;
+  onSelect?: ProcessMapProps["onSelect"];
+  onFilterIntent?: ProcessMapProps["onFilterIntent"];
+  /** Render the accessible table twin instead of the canvas. @default false */
+  tableView?: boolean;
+  /** No graph or replay yet. Renders the map's loading panel and hides the legend. */
+  loading?: boolean;
+  /** Override the legend's words. */
+  labels?: Partial<ConformanceStateLabels>;
+}
+
+/**
+ * The conformance overlay.
+ *
+ * @example
+ * ```tsx
+ * const model = useMemo(() => liftHappyPath(happyPath), [happyPath]);
+ * const conformance = useMemo(() => tokenReplay(log, model), [log, model]);
+ * <ConformanceOverlay graph={graph} conformance={conformance} />
+ * ```
+ */
+export const ConformanceOverlay = forwardRef<HTMLDivElement, ConformanceOverlayProps>(
+  function ConformanceOverlay(
+    {
+      graph,
+      conformance,
+      metric = CONFORMANCE_OVERLAY_DEFAULT_METRIC,
+      direction,
+      selection,
+      onSelect,
+      onFilterIntent,
+      tableView = false,
+      loading = false,
+      labels,
+      className,
+      ...props
+    },
+    ref,
+  ) {
+    return (
+      <div
+        ref={ref}
+        data-slot="conformance-overlay"
+        data-view={tableView ? "table" : "canvas"}
+        className={cn("flex size-full min-h-0 flex-col gap-3", className)}
+        {...props}
+      >
+        {loading ? null : <ConformanceLegend labels={labels} className="self-start" />}
+        <div data-slot="conformance-overlay-map" className="min-h-64 flex-1">
+          <ProcessMap
+            graph={graph}
+            metric={metric}
+            conformance={conformance}
+            direction={direction}
+            selection={selection}
+            onSelect={onSelect}
+            onFilterIntent={onFilterIntent}
+            tableView={tableView}
+            loading={loading}
+          />
+        </div>
+      </div>
+    );
+  },
+);

package/src/conformance-overlay/conformance-state.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { tokenReplay } from "../core/token-replay";
+import { liftHappyPath } from "../core/reference-model";
+import { discoverGraph } from "../core/discover-graph";
+import { buildProcessMapModel } from "../process-map/map-model";
+import { CONFORMANCE_FIXTURE_LOG, CONFORMANCE_FIXTURE_PATH } from "./conformance-fixture";
+import {
+  activityConformance,
+  CONFORMANCE_STATE_ENCODING,
+  CONFORMANCE_STATES,
+  resolveConformanceStates,
+  transitionConformance,
+  withActivityConformance,
+  withTransitionConformance,
+} from "./conformance-state";
+
+const conformance = tokenReplay(CONFORMANCE_FIXTURE_LOG, liftHappyPath(CONFORMANCE_FIXTURE_PATH));
+const states = resolveConformanceStates(conformance);
+
+describe("resolveConformanceStates — the RM-062 acceptance fixture", () => {
+  it("marks the deliberately skipped step modelOnly", () => {
+    expect(activityConformance(states, "Check credit")).toBe("modelOnly");
+  });
+
+  it("marks an activity outside the model logOnly and conforming steps both", () => {
+    expect(activityConformance(states, "Escalate")).toBe("logOnly");
+    expect(activityConformance(states, "Register")).toBe("both");
+    expect(activityConformance(states, "Pay")).toBe("both");
+    // An `incomplete` deviation does not move a modelled activity out of the model.
+    expect(activityConformance(states, "Approve")).toBe("both");
+  });
+
+  it("marks the edges where the log diverged logOnly", () => {
+    // The skip: cases jumped straight from Register to Approve.
+    expect(transitionConformance(states, "Register", "Approve")).toBe("logOnly");
+    // Into and out of the undesired activity.
+    expect(transitionConformance(states, "Check credit", "Escalate")).toBe("logOnly");
+    expect(transitionConformance(states, "Escalate", "Approve")).toBe("logOnly");
+    // The prescribed arcs.
+    expect(transitionConformance(states, "Register", "Check credit")).toBe("both");
+    expect(transitionConformance(states, "Approve", "Pay")).toBe("both");
+  });
+});
+
+describe("CONFORMANCE_STATE_ENCODING — never colour alone", () => {
+  it("gives each state a distinct tone, glyph and dash", () => {
+    for (const channel of ["tone", "glyph", "dash"] as const) {
+      const values = CONFORMANCE_STATES.map((state) => CONFORMANCE_STATE_ENCODING[state][channel]);
+      expect(new Set(values).size).toBe(CONFORMANCE_STATES.length);
+    }
+  });
+});
+
+describe("withActivityConformance / withTransitionConformance", () => {
+  const model = buildProcessMapModel({
+    graph: discoverGraph(CONFORMANCE_FIXTURE_LOG),
+    metric: { node: "absolute_case", edge: "absolute" },
+  });
+
+  it("adds data-conformance beside data-selection and names the state", () => {
+    const node = model.nodes.find((n) => n.id === "Check credit")!;
+    const decorated = withActivityConformance(node, states);
+    expect(decorated.data.conformance).toBe("modelOnly");
+    expect(decorated.domAttributes).toMatchObject({
+      "data-selection": node.data.selectionState,
+      "data-conformance": "modelOnly",
+    });
+    expect(decorated.ariaLabel).toMatch(/Model only/);
+    expect(decorated.ariaLabel?.startsWith(node.ariaLabel ?? "")).toBe(true);
+  });
+
+  it("folds the state into the edge's label-pill name as well as the edge's own", () => {
+    const edge = model.edges.find((e) => e.source === "Register" && e.target === "Approve")!;
+    const decorated = withTransitionConformance(edge, states);
+    expect(decorated.data?.conformance).toBe("logOnly");
+    expect(decorated.ariaLabel).toMatch(/Log only/);
+    expect(decorated.data?.ariaLabel).toBe(decorated.ariaLabel);
+  });
+});