@elabs-ai/components-process 4.1.0 → 5.0.0

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);
+  });
+});

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

@@ -0,0 +1,220 @@
+/**
+ * Conformance states on the process map — RM-062.
+ *
+ * Reads a `ConformanceResult` (RM-061's `tokenReplay`) as the three-colour overlay the
+ * analysis names (§2): every activity and every observed transition is in the log AND the
+ * model (`"both"`), in the log only (`"logOnly"`), or expected by the model but missing
+ * from the log (`"modelOnly"`).
+ *
+ * ## How the state is derived — without the reference model in hand
+ *
+ * A `ConformanceResult` does not carry the model it was replayed against, and it does not
+ * need to: token replay charges an `undesired` deviation to EVERY observed event whose
+ * activity the model does not contain, so an observed activity is outside the model
+ * exactly when it carries an `undesired` deviation. The rules, in precedence order:
+ *
+ * | element    | state        | when                                                         |
+ * | ---------- | ------------ | ------------------------------------------------------------ |
+ * | activity   | `logOnly`    | at least one `undesired` deviation names it                  |
+ * | activity   | `modelOnly`  | at least one `skipped` deviation names it (cases jumped it)   |
+ * | activity   | `both`       | otherwise                                                    |
+ * | transition | `logOnly`    | deviations are charged to it, or either endpoint is `logOnly` |
+ * | transition | `both`       | otherwise                                                    |
+ *
+ * A transition is never `modelOnly`: every edge on the map was observed. A model step
+ * that NO case ever reached is not on the graph at all, so it cannot be painted here —
+ * `ViolationList` still counts the cases that skipped it.
+ *
+ * ## Never colour alone (WCAG 1.4.1, analysis §5.4)
+ *
+ * Each state pairs a status tone with a distinct glyph AND a distinct line style —
+ * solid circle / hollow triangle / dashed square — so the three read apart in greyscale.
+ * {@link CONFORMANCE_STATE_ENCODING} is the one table every surface reads it from.
+ */
+import { Circle, SquareDashed, Triangle, type LucideIcon } from "lucide-react";
+import type { ConformanceResult } from "../core/conformance";
+import { EDGE_KEY_SEPARATOR } from "../core/discover-graph";
+import type { ProcessMapEdge, ProcessMapNode } from "../process-map/map-model";
+
+/** Where an element sits relative to the reference model. */
+export type ConformanceState = "both" | "logOnly" | "modelOnly";
+
+/** Every {@link ConformanceState}, in legend order. */
+export const CONFORMANCE_STATES: readonly ConformanceState[] = ["both", "logOnly", "modelOnly"];
+
+/** The status tone a state is painted with. */
+export type ConformanceTone = "success" | "warning" | "destructive";
+
+/** The line style a state is drawn with — the second non-colour channel. */
+export type ConformanceDash = "solid" | "dotted" | "dashed";
+
+/** Everything that encodes one state, colour included. */
+export interface ConformanceStateEncoding {
+  tone: ConformanceTone;
+  /** Stable glyph name, mirrored to `data-glyph` so a test can assert distinctness. */
+  glyph: "circle" | "triangle" | "square";
+  /** Lucide glyph drawn for the state. */
+  icon: LucideIcon;
+  /** Whether the glyph is filled (`true`) or an outline. */
+  filled: boolean;
+  dash: ConformanceDash;
+  /** SVG `stroke-dasharray` for a transition stroke; `undefined` keeps the edge's own. */
+  strokeDasharray: string | undefined;
+  /** Mark (fill-rung) utility for a glyph or swatch. */
+  markClass: string;
+  /** Ink (`-text` rung) utility for coloured text. */
+  textClass: string;
+  /** Border utilities: the tone's fill rung plus the line style. */
+  borderClass: string;
+  /** CSS colour reference for a stroke or a `--border` override. */
+  colorVar: string;
+}
+
+/** The single source of truth for how each state looks. */
+export const CONFORMANCE_STATE_ENCODING: Readonly<
+  Record<ConformanceState, ConformanceStateEncoding>
+> = Object.freeze({
+  both: {
+    tone: "success",
+    glyph: "circle",
+    icon: Circle,
+    filled: true,
+    dash: "solid",
+    strokeDasharray: undefined,
+    markClass: "text-success fill-success",
+    textClass: "text-success-text",
+    borderClass: "border-success border-solid",
+    colorVar: "var(--success)",
+  },
+  logOnly: {
+    tone: "warning",
+    glyph: "triangle",
+    icon: Triangle,
+    filled: false,
+    dash: "dotted",
+    strokeDasharray: "2 4",
+    markClass: "text-warning",
+    textClass: "text-warning-text",
+    borderClass: "border-warning border-dotted",
+    colorVar: "var(--warning)",
+  },
+  modelOnly: {
+    tone: "destructive",
+    glyph: "square",
+    icon: SquareDashed,
+    filled: false,
+    dash: "dashed",
+    strokeDasharray: "6 4",
+    markClass: "text-destructive",
+    textClass: "text-destructive-text",
+    borderClass: "border-destructive border-dashed",
+    colorVar: "var(--destructive)",
+  },
+});
+
+/** The words for each state. Override through a component's `labels` to localize. */
+export interface ConformanceStateLabels {
+  both: string;
+  logOnly: string;
+  modelOnly: string;
+  /** The table twin's column header and the legend's title. */
+  column: string;
+}
+
+/** The shipped English words for each state. */
+export const CONFORMANCE_STATE_DEFAULT_LABELS: Readonly<ConformanceStateLabels> = Object.freeze({
+  column: "Conformance",
+  both: "Conforms — in log and model",
+  logOnly: "Log only — not in the model",
+  modelOnly: "Model only — skipped in the log",
+});
+
+/** Per-element conformance states for one `ConformanceResult`. */
+export interface ConformanceStates {
+  /** Keyed by activity id. An activity absent here is `"both"`. */
+  activities: ReadonlyMap<string, ConformanceState>;
+  /**
+   * Keyed `source + EDGE_KEY_SEPARATOR + target` — the id `discoverGraph` and the map give
+   * the transition. A transition absent here is resolved by {@link transitionConformance}.
+   */
+  transitions: ReadonlyMap<string, ConformanceState>;
+}
+
+/** Derive activity and transition states from a replay result. See this module's docblock. */
+export function resolveConformanceStates(conformance: ConformanceResult): ConformanceStates {
+  const activities = new Map<string, ConformanceState>();
+  for (const trace of conformance.traces) {
+    for (const deviation of trace.deviations) {
+      if (deviation.activity === undefined) continue;
+      if (deviation.type === "undesired") activities.set(deviation.activity, "logOnly");
+      else if (deviation.type === "skipped" && activities.get(deviation.activity) !== "logOnly") {
+        activities.set(deviation.activity, "modelOnly");
+      }
+    }
+  }
+  const transitions = new Map<string, ConformanceState>();
+  for (const [key, { deviations }] of Object.entries(conformance.perEdge)) {
+    if (deviations > 0) transitions.set(key, "logOnly");
+  }
+  return { activities, transitions };
+}
+
+/** The state of one activity. */
+export function activityConformance(states: ConformanceStates, activity: string): ConformanceState {
+  return states.activities.get(activity) ?? "both";
+}
+
+/** The state of one observed transition. */
+export function transitionConformance(
+  states: ConformanceStates,
+  source: string,
+  target: string,
+): ConformanceState {
+  const charged = states.transitions.get(`${source}${EDGE_KEY_SEPARATOR}${target}`);
+  if (charged) return charged;
+  if (
+    activityConformance(states, source) === "logOnly" ||
+    activityConformance(states, target) === "logOnly"
+  ) {
+    return "logOnly";
+  }
+  return "both";
+}
+
+/**
+ * A map node with its conformance state folded in: `data.conformance` for the glyph and
+ * dash, `data-conformance` on React Flow's own node element (additive to
+ * `data-selection`), and the state's word appended to the accessible name — so the state
+ * reaches assistive technology as text, never as colour.
+ */
+export function withActivityConformance(
+  node: ProcessMapNode,
+  states: ConformanceStates,
+  labels: ConformanceStateLabels = CONFORMANCE_STATE_DEFAULT_LABELS,
+): ProcessMapNode {
+  const state = activityConformance(states, node.id);
+  return {
+    ...node,
+    data: { ...node.data, conformance: state },
+    ariaLabel: node.ariaLabel ? `${node.ariaLabel}, ${labels[state]}` : labels[state],
+    domAttributes: {
+      ...node.domAttributes,
+      "data-conformance": state,
+    } as ProcessMapNode["domAttributes"],
+  };
+}
+
+/** A map edge with its conformance state folded in. See {@link withActivityConformance}. */
+export function withTransitionConformance(
+  edge: ProcessMapEdge,
+  states: ConformanceStates,
+  labels: ConformanceStateLabels = CONFORMANCE_STATE_DEFAULT_LABELS,
+): ProcessMapEdge {
+  const state = transitionConformance(states, edge.source, edge.target);
+  const ariaLabel = edge.ariaLabel ? `${edge.ariaLabel}, ${labels[state]}` : labels[state];
+  return {
+    ...edge,
+    ariaLabel,
+    data: edge.data ? { ...edge.data, conformance: state, ariaLabel } : edge.data,
+  };
+}

package/src/conformance-overlay/index.ts

@@ -0,0 +1,4 @@
+/** ConformanceOverlay (RM-062) — public surface. */
+export * from "./conformance-overlay";
+export * from "./conformance-legend";
+export * from "./conformance-state";

package/src/core/activity-color-scale.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  ACTIVITY_COLOR_SLOTS,
+  ACTIVITY_OTHER_TOKEN,
+  activityColorScale,
+} from "./activity-color-scale";
+import { discoverGraph } from "./discover-graph";
+import { generateSyntheticLog } from "./fixtures/synthetic-log";
+import type { ActivityStats, ProcessGraph } from "./types";
+
+const ZERO = { min: 0, max: 0, mean: 0, median: 0, p90: 0, sum: 0, trimmedMean: 0 };
+
+function graphOf(entries: [id: string, cases: number][]): ProcessGraph {
+  const activities: ActivityStats[] = entries.map(([id, cases]) => ({
+    id,
+    label: id,
+    instances: cases,
+    cases,
+    isStart: false,
+    isEnd: false,
+    duration: ZERO,
+  }));
+  return {
+    activities,
+    transitions: [],
+    startActivities: {},
+    endActivities: {},
+    totals: { cases: 0, events: 0, variants: 0 },
+  };
+}
+
+describe("activityColorScale", () => {
+  it("ranks by cases descending and assigns --chart-1.. in rank order", () => {
+    const scale = activityColorScale(
+      graphOf([
+        ["Low", 1],
+        ["High", 9],
+        ["Mid", 5],
+      ]),
+    );
+    expect(scale.legend.map((e) => [e.activityId, e.token])).toEqual([
+      ["High", "--chart-1"],
+      ["Mid", "--chart-2"],
+      ["Low", "--chart-3"],
+    ]);
+    expect(scale.colorFor("Mid")).toEqual({ token: "--chart-2" });
+  });
+
+  it("breaks ties by id, independent of input order", () => {
+    const a = activityColorScale(
+      graphOf([
+        ["B", 3],
+        ["A", 3],
+        ["C", 3],
+      ]),
+    );
+    const b = activityColorScale(
+      graphOf([
+        ["C", 3],
+        ["B", 3],
+        ["A", 3],
+      ]),
+    );
+    expect(a.legend).toEqual(b.legend);
+    expect(a.legend.map((e) => e.activityId)).toEqual(["A", "B", "C"]);
+  });
+
+  it("gives the top eleven distinct tokens and everything else the hatched other bucket", () => {
+    const entries = Array.from(
+      { length: 15 },
+      (_, i) => [`Activity ${String(i).padStart(2, "0")}`, 100 - i] as [string, number],
+    );
+    const scale = activityColorScale(graphOf(entries));
+    const tokens = scale.legend.slice(0, ACTIVITY_COLOR_SLOTS).map((e) => e.token);
+    expect(new Set(tokens).size).toBe(ACTIVITY_COLOR_SLOTS);
+    expect(tokens).not.toContain(ACTIVITY_OTHER_TOKEN);
+    for (const entry of scale.legend.slice(ACTIVITY_COLOR_SLOTS)) {
+      expect(entry.token).toBe(ACTIVITY_OTHER_TOKEN);
+      expect(entry.pattern).toBe("other");
+    }
+    expect(scale.colorFor("never seen")).toEqual({ token: ACTIVITY_OTHER_TOKEN, pattern: "other" });
+  });
+
+  it("derives two-character codes unique within the scale", () => {
+    const scale = activityColorScale(
+      graphOf([
+        ["Create Order", 5],
+        ["Cancel Order", 4],
+        ["Approve", 3],
+        ["Approve Credit", 2],
+      ]),
+    );
+    const codes = scale.legend.map((e) => e.code);
+    expect(codes[0]).toBe("CO");
+    expect(new Set(codes).size).toBe(codes.length);
+    for (const code of codes) expect(code).toHaveLength(2);
+    expect(scale.codeFor("Approve")).toBe(scale.legend[2]?.code);
+  });
+
+  it("is deterministic on a real discovered graph", () => {
+    const log = generateSyntheticLog({ cases: 120, seed: 7 });
+    expect(activityColorScale(discoverGraph(log)).legend).toEqual(
+      activityColorScale(discoverGraph(log)).legend,
+    );
+  });
+});

package/src/core/activity-color-scale.ts

@@ -0,0 +1,133 @@
+/**
+ * Activity colour scale — RM-054.
+ *
+ * One activity, one colour, across every process view. `ProcessMap` paints the colour as
+ * a small accent mark on the activity node; `VariantExplorer` paints it on the sequence
+ * chips. Both read the SAME scale instance built from one graph, so "Create Order" is the
+ * same swatch in the map and in the variant list.
+ *
+ * ## The colour budget
+ *
+ * The chart palette ships twelve series tokens (`--chart-1` … `--chart-12`). The eleven
+ * most frequent activities (ranked by the number of cases they occur in) take
+ * `--chart-1` … `--chart-11`; every remaining activity shares `--chart-12` and is flagged
+ * `pattern: "other"`, which the views render as a hatch so "other" never reads as a
+ * twelfth distinct activity. Colour is never the only channel: every view that paints a
+ * swatch also prints the activity label (or its two-letter {@link ActivityColorScale.codeFor}
+ * code) as text.
+ *
+ * Pure and framework-free: returns token NAMES, never resolved colours, so a theme switch
+ * re-inks every swatch with no recomputation.
+ */
+import type { ProcessGraph } from "./types";
+
+/** How many activities get a distinct palette slot before the rest share "other". */
+export const ACTIVITY_COLOR_SLOTS = 11;
+
+/** The token every activity outside the top {@link ACTIVITY_COLOR_SLOTS} shares. */
+export const ACTIVITY_OTHER_TOKEN = "--chart-12";
+
+/** The colour one activity is painted with. */
+export interface ActivityColor {
+  /** A CSS custom-property NAME, e.g. `"--chart-3"`. Paint with `var(${token})`. */
+  token: string;
+  /** Present for the shared "other" bucket — render the hatch, not a flat swatch. */
+  pattern?: "other";
+}
+
+/** One legend entry, in rank order. */
+export interface ActivityColorLegendEntry extends ActivityColor {
+  activityId: string;
+  label: string;
+  /** A two-character code unique within the scale, for abbreviated ("DNA strip") chips. */
+  code: string;
+}
+
+/** The shared activity→colour mapping. */
+export interface ActivityColorScale {
+  /** The colour for an activity. An id the graph never contained is "other". */
+  colorFor(activityId: string): ActivityColor;
+  /** The two-character code for an activity; derived from the id when it is unknown. */
+  codeFor(activityId: string): string;
+  /** The activity's display label; the id itself when it is unknown. */
+  labelFor(activityId: string): string;
+  /** Every activity in the graph, ranked by case count descending, ties by id. */
+  legend: ActivityColorLegendEntry[];
+}
+
+const OTHER: ActivityColor = Object.freeze({ token: ACTIVITY_OTHER_TOKEN, pattern: "other" });
+
+/** Upper-cased letters and digits of a label — the material codes are built from. */
+function alphanumerics(label: string): string {
+  return label.replace(/[^\p{L}\p{N}]/gu, "").toUpperCase();
+}
+
+/**
+ * Candidate two-character codes for a label, most readable first: initials of the first
+ * two words ("Create Order" → "CO"), the first two letters ("Approve" → "AP"), then the
+ * first letter paired with every later letter, then the first letter plus a digit.
+ */
+function codeCandidates(label: string): string[] {
+  const out: string[] = [];
+  const words = label.split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+  const first = words[0];
+  const second = words[1];
+  if (first && second) out.push(`${first[0]}${second[0]}`.toUpperCase());
+  const letters = alphanumerics(label);
+  const head = letters[0] ?? "?";
+  if (letters.length >= 2) out.push(letters.slice(0, 2));
+  for (let i = 2; i < letters.length; i += 1) out.push(`${head}${letters[i]}`);
+  for (let digit = 1; digit <= 9; digit += 1) out.push(`${head}${digit}`);
+  return out;
+}
+
+/** A code for a label, avoiding every code already in `taken`. */
+function uniqueCode(label: string, taken: Set<string>): string {
+  for (const candidate of codeCandidates(label)) {
+    if (!taken.has(candidate)) return candidate;
+  }
+  // Pathological: more than ~40 activities sharing one first letter. Fall back to a
+  // base-36 counter so the code is still two characters and still unique.
+  for (let n = 0; n < 36 * 36; n += 1) {
+    const candidate = n.toString(36).toUpperCase().padStart(2, "0");
+    if (!taken.has(candidate)) return candidate;
+  }
+  return (alphanumerics(label).slice(0, 2) || "??").padEnd(2, "?");
+}
+
+/**
+ * Build the shared colour scale for a graph.
+ *
+ * Deterministic: the same graph always yields the same assignment, regardless of the
+ * order `graph.activities` arrives in. Build it from the FULL (unfiltered, unabstracted)
+ * graph so colours stay put while a reader filters or abstracts.
+ */
+export function activityColorScale(graph: ProcessGraph): ActivityColorScale {
+  const ranked = [...graph.activities].sort(
+    (a, b) => b.cases - a.cases || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0),
+  );
+
+  const colors = new Map<string, ActivityColor>();
+  const codes = new Map<string, string>();
+  const labels = new Map<string, string>();
+  const taken = new Set<string>();
+  const legend: ActivityColorLegendEntry[] = ranked.map((activity, index) => {
+    const color: ActivityColor =
+      index < ACTIVITY_COLOR_SLOTS ? { token: `--chart-${index + 1}` } : OTHER;
+    const label = activity.label || activity.id;
+    const code = uniqueCode(label, taken);
+    taken.add(code);
+    colors.set(activity.id, color);
+    codes.set(activity.id, code);
+    labels.set(activity.id, label);
+    return { activityId: activity.id, label, code, ...color };
+  });
+
+  return {
+    colorFor: (activityId) => colors.get(activityId) ?? OTHER,
+    codeFor: (activityId) =>
+      codes.get(activityId) ?? (alphanumerics(activityId).slice(0, 2) || "??").padEnd(2, "?"),
+    labelFor: (activityId) => labels.get(activityId) ?? activityId,
+    legend,
+  };
+}