@elabs-ai/components-process 4.1.0

package/dist/index.d.ts

@@ -0,0 +1,1153 @@
+import { Node, Edge, NodeProps, EdgeProps, XYPosition } from '@xyflow/react';
+import * as react from 'react';
+import { HTMLAttributes, KeyboardEvent } from 'react';
+import { FlowLayoutDirection } from '@elabs-ai/components-flow';
+
+/**
+ * The framework-free event-log and process-graph model — RM-049.
+ *
+ * Every downstream item in the process-mining track (RM-050 abstraction, RM-051 the
+ * process map, RM-052 the variant explorer, RM-053 the case table, RM-054 the coverage
+ * strip) reads these shapes, so they are the wave's frozen contract. Keep additions
+ * additive: a required field added here is a breaking change for five items at once.
+ *
+ * NOTHING in this module — or anywhere under `src/core/` — may import React, React Flow,
+ * visx, d3 or an `@elabs-ai/components-*` package. See `.claude/rules/process-components.md`
+ * and `pnpm process:reuse:check`.
+ */
+/**
+ * One raw row of an event log, before normalization.
+ *
+ * `timestamp` accepts the three shapes tabular sources actually produce — an ISO string,
+ * an epoch number, or a `Date` — because the adapters hand rows through unchanged and a
+ * consumer should not have to pre-convert. {@link normalizeLog} resolves all three to
+ * epoch milliseconds.
+ */
+interface EventRow {
+    /** Case (process instance) this event belongs to. */
+    caseId: string;
+    /** Activity name. This is the node identity in the discovered graph. */
+    activity: string;
+    /** When the event completed (or, for a `lifecycle: "start"` row, when it started). */
+    timestamp: string | number | Date;
+    /**
+     * Optional explicit start of an interval event. Ignored when the row is one half of a
+     * `lifecycle` pair — the paired `"start"` row wins, because it is the observed value.
+     */
+    startTimestamp?: string | number | Date;
+    /** Who or what executed the event (a user, a queue, a system). */
+    resource?: string;
+    /** Lifecycle transition. Absent means the row is an atomic (already-complete) event. */
+    lifecycle?: "start" | "complete";
+    /** Free-form event-level attributes carried through normalization untouched. */
+    attributes?: Record<string, string | number | boolean | null>;
+}
+/** A raw event log: the rows, plus optional per-case attributes keyed by `caseId`. */
+interface EventLog {
+    events: EventRow[];
+    caseAttributes?: Record<string, Record<string, unknown>>;
+}
+/**
+ * Summary statistics over a set of duration samples, in milliseconds.
+ *
+ * All seven members are always present; an empty sample set yields zeros rather than
+ * `null`, so a renderer never has to branch on absence.
+ */
+interface DurationStats {
+    min: number;
+    max: number;
+    mean: number;
+    median: number;
+    p90: number;
+    sum: number;
+    /** Mean after discarding the lowest and highest 10% of samples. */
+    trimmedMean: number;
+}
+/** Per-activity aggregates in a discovered graph. */
+interface ActivityStats {
+    /** Stable node identity — the activity name. */
+    id: string;
+    /** Human-readable label. Equal to `id` unless a caller relabels the graph. */
+    label: string;
+    /** Total occurrences across all cases. */
+    instances: number;
+    /** Number of distinct cases the activity occurs in at least once. */
+    cases: number;
+    /** True when the activity starts at least one case. */
+    isStart: boolean;
+    /** True when the activity ends at least one case. */
+    isEnd: boolean;
+    /** Distribution of the activity's own execution durations. */
+    duration: DurationStats;
+}
+/** Per-edge aggregates in a discovered graph (a directly-follows relation). */
+interface TransitionStats {
+    source: string;
+    target: string;
+    /** Total occurrences of the directly-follows pair across all cases. */
+    count: number;
+    /** Number of distinct cases the pair occurs in at least once. */
+    caseCount: number;
+    /** Distribution of the flow time between the two activities. */
+    duration: DurationStats;
+    /** `source === target`. */
+    isSelfLoop: boolean;
+    /**
+     * Whether the edge points backwards in the laid-out graph. Discovery does not lay out,
+     * so this is always `false` here; a layout pass sets it (RM-044).
+     */
+    isBackEdge: boolean;
+}
+/** A directly-follows graph plus its totals. */
+interface ProcessGraph {
+    activities: ActivityStats[];
+    transitions: TransitionStats[];
+    /** Activity name → number of cases that start with it. */
+    startActivities: Record<string, number>;
+    /** Activity name → number of cases that end with it. */
+    endActivities: Record<string, number>;
+    totals: {
+        cases: number;
+        events: number;
+        variants: number;
+    };
+}
+/** One distinct activity sequence, with the cases that follow it. */
+interface Variant {
+    /** Stable, reproducible id derived from the sequence — see `variantId`. */
+    id: string;
+    sequence: string[];
+    /** Number of cases following this sequence. */
+    count: number;
+    /** `count / totalCases`. */
+    share: number;
+    /** Running share across the descending-frequency order — monotonically non-decreasing. */
+    cumulativeShare: number;
+    /** Case ids following this sequence, in first-appearance order. */
+    caseIds: string[];
+    /** Distribution of the end-to-end case durations of `caseIds`. */
+    duration: DurationStats;
+}
+/** How an edge or node frequency is expressed to the reader. */
+type FrequencyMode = "absolute" | "absolute_case" | "relative" | "relative_case" | "relative_antecedent" | "relative_consequent" | "max_repetitions";
+/** Which member of a {@link DurationStats} a performance view reads. */
+type PerformanceAgg = "median" | "mean" | "min" | "max" | "sum" | "p90" | "trimmed_mean";
+
+/**
+ * Rework detection — RM-050.
+ *
+ * "Rework" is the part of a process that happens more than once inside a single case: a
+ * step retried immediately (a SELF-LOOP), or a step the case comes back to after going
+ * somewhere else (a LOOP). Both are repeats, and separating them matters — a self-loop is
+ * usually a retry or a batch, a loop is usually a rejection sending work backwards, and
+ * the two lead to different conversations about the process.
+ *
+ * Counted per OCCURRENCE, over the normalized trace: the first execution of an activity in
+ * a case is never rework, and every later one is exactly one of the two kinds. So
+ * `selfLoops + loops` is precisely the number of repeated executions in the log.
+ *
+ * Deterministic and framework-free, like everything else in `/core`.
+ */
+
+/** Per-activity rework tallies. */
+interface ActivityRework {
+    /** Repeats of this activity immediately after itself. */
+    selfLoops: number;
+    /** Repeats of this activity later in the same case, with something else in between. */
+    loops: number;
+}
+/** What {@link detectRework} answers. */
+interface ReworkStats {
+    /** Adjacent repeats across the whole log. */
+    selfLoops: number;
+    /** Non-adjacent repeats across the whole log. */
+    loops: number;
+    /** Fraction of cases carrying at least one self-loop or loop. `0` for an empty log. */
+    caseReworkRate: number;
+    /**
+     * Every activity in the log, in ascending name order, with its own two tallies. An
+     * activity that never repeats is present with zeros — a renderer joining this against
+     * a graph's activities never has to distinguish "no rework" from "unknown activity".
+     */
+    perActivity: Record<string, ActivityRework>;
+}
+
+/**
+ * Case-level log filtering — RM-050.
+ *
+ * Every filter in a process-mining tool is a CASE predicate, not an event predicate:
+ * "cases that contain Reject Order", "cases that took longer than a day". Removing single
+ * events would rewrite traces and invent directly-follows relations that never happened,
+ * so a filter here only ever keeps or drops a case whole. That is what makes the result
+ * safe to hand straight back to `discoverGraph` / `extractVariants`.
+ *
+ * Specs AND together — an empty list keeps everything.
+ */
+
+/** One case-level predicate. {@link filterLog} ANDs a list of them. */
+type FilterSpec = 
+/** The case contains `activity` at least once. */
+{
+    kind: "with";
+    activity: string;
+}
+/** The case never contains `activity`. */
+ | {
+    kind: "without";
+    activity: string;
+}
+/** The case's FIRST activity is `activity`. */
+ | {
+    kind: "startsWith";
+    activity: string;
+}
+/** The case's LAST activity is `activity`. */
+ | {
+    kind: "endsWith";
+    activity: string;
+}
+/**
+ * `b` follows `a` in the case — directly (adjacent) when `direct`, otherwise eventually
+ * (anywhere later in the trace).
+ */
+ | {
+    kind: "follower";
+    a: string;
+    b: string;
+    direct?: boolean;
+}
+/** An attribute comparison — see {@link caseMatchesFilters} for how `key` is resolved. */
+ | {
+    kind: "attribute";
+    key: string;
+    op: "eq" | "ne" | "gt" | "lt" | "in";
+    value: unknown;
+}
+/** The case's throughput time, in milliseconds. Both bounds are INCLUSIVE. */
+ | {
+    kind: "duration";
+    min?: number;
+    max?: number;
+}
+/** The case follows one of these variants (see `variantId`). */
+ | {
+    kind: "variant";
+    ids: string[];
+}
+/** The case is one of these case ids. */
+ | {
+    kind: "cases";
+    ids: string[];
+};
+
+/**
+ * map-model — the pure `ProcessGraph → React Flow nodes/edges` mapping (RM-051).
+ *
+ * Everything the process map DECIDES about a graph lives here, and nothing here renders:
+ * no React, no DOM, no engine calls. That is deliberate and load-bearing in three ways.
+ *
+ * 1. **The canvas and the accessible `TableView` twin read ONE model.** Both surfaces are
+ *    built from the same {@link ProcessMapModel}, so a number can never drift between the
+ *    picture and the table a screen-reader user is actually given.
+ * 2. **Encoding is testable without a browser.** Stroke widths, saturations, printed
+ *    labels and selection states are plain data here, so a unit test can assert the
+ *    encoding rules instead of screenshotting them.
+ * 3. **Layout can be cached independently of metric.** The model changes whenever the
+ *    metric changes; the STRUCTURE key (see {@link processGraphStructureKey}) does not, so
+ *    `useProcessLayout` reuses positions across a metric switch.
+ *
+ * ## The encoding contract (WCAG 1.4.1 — colour is never the only channel)
+ *
+ * Two flow-layer defects (#321 edge colour collapsing on a low-chroma palette, #297 edge
+ * colour not refreshing on a theme switch) mean edge COLOUR cannot be trusted to separate
+ * two values. This module is designed so it never has to be:
+ *
+ * - an **edge** metric reaches the reader through `weight` (stroke width, the
+ *   `[1.5, 8]` px linear min-max clamp `computeEdgeWeightScale` applies) AND through a
+ *   printed `label` pill — colour (`value`/`valueDomain`) is the third channel, never the
+ *   first;
+ * - a **node** metric reaches the reader through a printed value AND a bar whose LENGTH is
+ *   the same fraction the fill saturation encodes — saturation alone would be colour-only;
+ * - **self-loop**, **back-edge** and each **selection** state carry a shape, dash or
+ *   opacity change, not a hue change.
+ *
+ * Render any story in greyscale and two different metric values are still distinguishable.
+ */
+
+/**
+ * What a node or an edge is painted with: a frequency reading of the discovered counts,
+ * or an aggregate of the measured durations.
+ */
+type ProcessMetric = FrequencyMode | PerformanceAgg;
+/** The three metric slots a process map paints from. */
+interface ProcessMetricSpec {
+    /** Drives node saturation, the node's meter bar and the node's printed value. */
+    node: ProcessMetric;
+    /** Drives edge stroke width and the edge's printed label pill. */
+    edge: ProcessMetric;
+    /** Optional second reading, printed beside the first on both nodes and edges. */
+    secondary?: ProcessMetric;
+}
+/** Which half of the graph a selection points at. */
+type ProcessSelectionKind = "activity" | "transition";
+/**
+ * A coordinated selection. `id` is the ACTIVITY NAME for `"activity"` and the
+ * `source`+separator+`target` edge key (see {@link processEdgeId}) for `"transition"` —
+ * the same keys `/core` uses, so a selection round-trips through `filterLog` and a URL
+ * unchanged.
+ */
+interface ProcessSelection {
+    kind: ProcessSelectionKind;
+    id: string;
+}
+/**
+ * What the map's filter menu emits. A strict subset of `/core`'s `FilterSpec`, so a
+ * consumer can hand it straight to `filterLog` with no translation layer — which is the
+ * point: an intent the map invents and nothing can consume is not an intent.
+ */
+type ProcessFilterIntent = Extract<FilterSpec, {
+    kind: "with";
+} | {
+    kind: "without";
+} | {
+    kind: "startsWith";
+} | {
+    kind: "endsWith";
+}>;
+/** The four intents the map's own menu offers, in menu order. */
+declare const PROCESS_FILTER_INTENT_KINDS: readonly ["with", "without", "startsWith", "endsWith"];
+/** Human wording for each intent, used by the menu's VISIBLE item text. */
+declare const PROCESS_FILTER_INTENT_LABELS: Readonly<Record<ProcessFilterIntent["kind"], string>>;
+/**
+ * The locale message key for each intent's ACCESSIBLE name (#346), one activity's block at
+ * a time — the visible text alone ({@link PROCESS_FILTER_INTENT_LABELS}) is not unique for
+ * a transition's menu, which offers the same four intents once per endpoint: eight items,
+ * four distinct visible strings, each doubled. Each message takes an `{activity}` var, so
+ * the accessible name states which activity the item filters by even though the visible
+ * text (kept unsuffixed, so the menu stays visually compact) does not.
+ */
+declare const PROCESS_FILTER_INTENT_MESSAGE_KEYS: Readonly<Record<ProcessFilterIntent["kind"], string>>;
+/**
+ * How an element relates to the current selection AND the active filter.
+ *
+ * - `"selected"` — the element the reader picked.
+ * - `"associated"` — ordinary; either nothing is selected, or this element touches the
+ *   selection, and no active filter excludes it.
+ * - `"excluded"` — outside the selection's neighbourhood, or dropped by the active filter;
+ *   dimmed, but still fully operable. Clicking an excluded element is how a reader filters
+ *   it back in, so it is never `aria-disabled` — see {@link resolveSelectionState}. The
+ *   dimming is a REDUNDANT cue: `activityAriaLabel`/`transitionAriaLabel` already append the
+ *   word "excluded" to the element's accessible name, so the state reaches assistive
+ *   technology through real text, not only through opacity.
+ */
+type ProcessSelectionState = "selected" | "associated" | "excluded";
+/**
+ * The ONE ghosting rung a filter-excluded element dims against, shared by every call site
+ * that owns a non-text mark: the activity node's meter fill, the transition edge's stroke
+ * (`ProcessTransitionEdge`'s wrapping `<g>`), and — via `labelProps.className` — the
+ * transition's own label pill's frame (`FlowWeightedEdge`/`FlowSelfLoopEdge`). Before #351/
+ * #352 this was TWO separate literals (`opacity-35` on the activity node's whole subtree,
+ * `EXCLUDED_OPACITY` on the edge) and the pill had no ghost treatment at all.
+ *
+ * **This value dims marks, never text ink.** `ProcessActivityNode` and the pill's own label
+ * text are deliberately excluded from it — measured (see #352's follow-up), a `0.35` alpha
+ * over EITHER's own already-modest undimmed contrast (5.97:1–6.08:1 for the eyebrow, higher
+ * for the title/label) composites well under the WCAG 4.5:1 floor in both reference themes.
+ * Ghosted TEXT stays at full ink; the excluded state instead reaches the reader through the
+ * activity node's `border-strong` boundary swap and the pill's dashed frame — non-opacity,
+ * non-colour-alone channels (WCAG 1.4.1) — plus the accessible name's own appended
+ * "excluded" word, same as before.
+ */
+declare const GHOST_OPACITY = 0.35;
+/**
+ * Per-element selection/filter states, sparse — an id with no entry defaults through
+ * {@link resolveSelectionState}'s own rules. Keyed exactly like {@link ProcessSelection}:
+ * activity name for `activities`, {@link processEdgeId} for `transitions`.
+ *
+ * `variants` is carried here for API symmetry with the other two namespaces even though
+ * `ProcessMap` does not read it (the variant LIST narrows rather than ghosts — decision
+ * `RM-052-tristate-decision.md` §3); a future variant-explorer view may.
+ */
+interface ProcessSelectionStates {
+    activities?: Readonly<Record<string, ProcessSelectionState>>;
+    transitions?: Readonly<Record<string, ProcessSelectionState>>;
+    variants?: Readonly<Record<string, ProcessSelectionState>>;
+}
+/** `data` carried by every {@link ProcessMapNode}. */
+interface ProcessActivityNodeData extends Record<string, unknown> {
+    /** Activity name — the node identity and its visible title. */
+    title: string;
+    /** What the primary number MEANS ("Cases", "Median duration"), shown as the eyebrow. */
+    metricLabel: string;
+    /** The primary metric, already formatted for display. */
+    primaryLabel: string;
+    /** The primary metric as a number, for the meter and for tests. */
+    primaryValue: number;
+    /** The secondary metric, already formatted. Absent when `metric.secondary` is unset. */
+    secondaryLabel?: string;
+    /** `primaryValue` as a `0..1` fraction of the graph's node-metric domain. */
+    saturation: number;
+    isStart: boolean;
+    isEnd: boolean;
+    /** Repeat executions of this activity across the log; omitted when no rework data. */
+    reworkCount?: number;
+    selectionState: ProcessSelectionState;
+}
+/** `data` carried by every {@link ProcessMapEdge}. */
+interface ProcessTransitionEdgeData extends Record<string, unknown> {
+    source: string;
+    target: string;
+    /** Drives stroke width through `computeEdgeWeightScale`'s `[1.5, 8]` px min-max clamp. */
+    weight: number;
+    /** Drives stroke colour — the THIRD channel, never the first. */
+    value: number;
+    /** `[min, max]` the colour ramp interpolates `value` across. */
+    valueDomain: [number, number];
+    /** The printed pill — the second, colour-free channel for the same measure as `weight`. */
+    label: string;
+    secondaryLabel?: string;
+    isSelfLoop: boolean;
+    isBackEdge: boolean;
+    selectionState: ProcessSelectionState;
+}
+/** A process-map activity node. Register as `nodeTypes={{ "process-activity": … }}`. */
+type ProcessMapNode = Node<ProcessActivityNodeData, "process-activity">;
+/** A process-map transition edge. Register as `edgeTypes={{ "process-transition": … }}`. */
+type ProcessMapEdge = Edge<ProcessTransitionEdgeData, "process-transition">;
+/** One row of the accessible `TableView` twin — activities half. */
+interface ProcessActivityRow {
+    id: string;
+    title: string;
+    primaryLabel: string;
+    secondaryLabel?: string;
+    reworkCount?: number;
+    role: string;
+    selectionState: ProcessSelectionState;
+}
+/** One row of the accessible `TableView` twin — transitions half. */
+interface ProcessTransitionRow {
+    id: string;
+    source: string;
+    target: string;
+    primaryLabel: string;
+    secondaryLabel?: string;
+    shape: string;
+    selectionState: ProcessSelectionState;
+}
+/** Everything the canvas and the table are both rendered from. */
+interface ProcessMapModel {
+    nodes: ProcessMapNode[];
+    edges: ProcessMapEdge[];
+    /** `[min, max]` of the node metric across the graph. */
+    nodeDomain: [number, number];
+    /** `[min, max]` of the edge metric across the graph — the `Legend` scale's domain. */
+    edgeDomain: [number, number];
+    /** What the node metric means, e.g. "Cases". */
+    nodeMetricLabel: string;
+    /** What the edge metric means, e.g. "Transitions". */
+    edgeMetricLabel: string;
+    activityRows: ProcessActivityRow[];
+    transitionRows: ProcessTransitionRow[];
+    /** Format one edge-metric value the way the map prints it — used by the `Legend`. */
+    formatEdgeValue: (value: number) => string;
+    /**
+     * How many activities/transitions the active selection or filter has excluded (#375) —
+     * derived once here so the canvas branch, the table branch and any future consumer read
+     * one number instead of recomputing it three times, and so the summary is unit-testable
+     * without a render.
+     */
+    excludedCounts: ProcessMapExcludedCounts;
+}
+/** See {@link ProcessMapModel.excludedCounts}. */
+interface ProcessMapExcludedCounts {
+    activities: number;
+    totalActivities: number;
+    transitions: number;
+    totalTransitions: number;
+}
+/**
+ * The frequency readings an ACTIVITY can actually answer from `ActivityStats`.
+ *
+ * `relative_antecedent` / `relative_consequent` are edge-only readings (they are shares of
+ * a source's or a target's traffic — a node has no antecedent), and `max_repetitions`
+ * needs the per-case maximum, which discovery does not retain. Rather than invent a
+ * number for those three, {@link resolveActivityFrequencyMode} maps them onto the nearest
+ * reading the data supports and the RESOLVED mode is what labels the value — so the map
+ * never prints one measure under another measure's name.
+ */
+type ActivityFrequencyMode = Extract<FrequencyMode, "absolute" | "absolute_case" | "relative" | "relative_case">;
+/** See {@link ActivityFrequencyMode} — a total, documented, tested resolution. */
+declare function resolveActivityFrequencyMode(mode: FrequencyMode): ActivityFrequencyMode;
+/**
+ * The frequency readings a TRANSITION can answer from `TransitionStats`.
+ *
+ * Only `max_repetitions` is unsupported — the per-case maximum is not retained by
+ * discovery — and it resolves to `absolute`, the count it is a maximum of.
+ */
+type TransitionFrequencyMode = Exclude<FrequencyMode, "max_repetitions">;
+/** See {@link TransitionFrequencyMode}. */
+declare function resolveTransitionFrequencyMode(mode: FrequencyMode): TransitionFrequencyMode;
+/** Whether a metric names a duration aggregate rather than a frequency reading. */
+declare function isPerformanceMetric(metric: ProcessMetric): metric is PerformanceAgg;
+/** What a node's metric is CALLED once resolved — the eyebrow and the a11y name use it. */
+declare function nodeMetricLabel(metric: ProcessMetric): string;
+/** What an edge's metric is CALLED once resolved. */
+declare function edgeMetricLabel(metric: ProcessMetric): string;
+/** The node metric of one activity, as a plain number. Pure and total. */
+declare function activityMetricValue(activity: ActivityStats, metric: ProcessMetric, totals: ProcessGraph["totals"]): number;
+/** Denominators the two per-endpoint edge shares need, computed once per graph. */
+interface ProcessEdgeDenominators {
+    /** Total of every transition count in the graph. */
+    total: number;
+    /** Activity → total count of the transitions LEAVING it. */
+    outgoing: Map<string, number>;
+    /** Activity → total count of the transitions ENTERING it. */
+    incoming: Map<string, number>;
+}
+/** Build the per-graph denominators the antecedent/consequent shares divide by. */
+declare function processEdgeDenominators(transitions: readonly TransitionStats[]): ProcessEdgeDenominators;
+/** The edge metric of one transition, as a plain number. Pure and total. */
+declare function transitionMetricValue(transition: TransitionStats, metric: ProcessMetric, totals: ProcessGraph["totals"], denominators: ProcessEdgeDenominators): number;
+/**
+ * A duration in milliseconds, spoken in the largest unit that leaves a number at or above
+ * one.
+ *
+ * One decimal below 10 and none above, so "3.4 d" and "18 h" both read as measurements
+ * rather than as false precision. A non-finite or negative input answers an em dash — a
+ * process map has legitimate holes (an activity that never followed anything), and a
+ * printed `NaN` is worse than a printed dash.
+ */
+declare function formatDurationMs(ms: number): string;
+/** A count, grouped by the runtime locale; a share, as a percentage with one decimal. */
+declare function formatMetricValue(value: number, metric: ProcessMetric): string;
+/**
+ * The stable id of a transition: source, {@link EDGE_KEY_SEPARATOR}, target — keyed
+ * exactly the way `/core` keys it. A selection, a performance-layer lookup and a React
+ * Flow edge therefore all name the same edge with the same string, with no translation.
+ */
+declare function processEdgeId(source: string, target: string): string;
+/**
+ * A cheap, order-independent key over the graph's STRUCTURE — node ids and edge ids only,
+ * never a metric. `useProcessLayout` caches on it, which is what lets a metric switch
+ * reuse the existing positions instead of re-running dagre.
+ */
+declare function processGraphStructureKey(graph: ProcessGraph): string;
+/** The activities and transitions a selection keeps in play. */
+interface ProcessSelectionNeighbourhood {
+    activities: Set<string>;
+    transitions: Set<string>;
+}
+/**
+ * Which activities and transitions a selection keeps in play.
+ *
+ * Selecting an ACTIVITY keeps that activity, every activity directly connected to it, and
+ * every edge incident to it. Selecting a TRANSITION keeps its two endpoints and itself.
+ * Everything else becomes `"excluded"` — dimmed, but never `aria-disabled` (see
+ * {@link resolveSelectionState}).
+ */
+declare function selectionNeighbourhood(graph: ProcessGraph, selection: ProcessSelection | null | undefined): ProcessSelectionNeighbourhood | null;
+/**
+ * Resolve one element's tri-state {@link ProcessSelectionState} from BOTH the coordinated
+ * click selection and the active filter's per-element states — the two channels
+ * `ProcessMap` renders together. Five rules, in precedence order (RM-052 round 2, #227):
+ *
+ * 1. **The element IS the click target** → `"selected"`. This wins over everything else,
+ *    including an active filter's own `"excluded"` — clicking an excluded element is how a
+ *    reader re-focuses it, so the click must always win.
+ * 2. **`states` already says `"excluded"`** → `"excluded"`. This must be checked BEFORE
+ *    rule 3: a filter-excluded element stays excluded even when it happens to sit inside
+ *    the neighbourhood of whatever is currently click-selected — the filter's exclusion is
+ *    not something a click's neighbourhood should be able to override.
+ * 3. **A click target exists and this element sits outside its neighbourhood** →
+ *    `"excluded"`.
+ * 4. **`states` carries an entry for this element** → that entry (`"associated"` or
+ *    `"selected"` from a filter's own point of view — reserved for a future filter shape
+ *    that can name a "primary" match; today filters only ever produce `"excluded"`
+ *    entries, which rule 2 already handles).
+ * 5. **Otherwise** → `"associated"`, the default.
+ */
+declare function resolveSelectionState(id: string, kind: ProcessSelectionKind, selection: ProcessSelection | null | undefined, neighbourhood: ProcessSelectionNeighbourhood | null, states?: ProcessSelectionStates): ProcessSelectionState;
+/** Inputs to {@link buildProcessMapModel}. */
+interface BuildProcessMapModelOptions {
+    graph: ProcessGraph;
+    metric: ProcessMetricSpec;
+    /** Optional rework tallies (from `/core`'s `detectRework`) for the node badge. */
+    rework?: ReworkStats;
+    selection?: ProcessSelection | null;
+    /**
+     * Per-element states an active filter contributes (RM-052 round 2, #227) — merged with
+     * the click `selection` by {@link resolveSelectionState}. Omitting it reproduces the
+     * pre-filter behaviour exactly: every element resolves through rules 1/3/5 alone.
+     */
+    selectionStates?: ProcessSelectionStates;
+    /**
+     * Edge ids `layoutFlow` reported as running against the layout direction. Supplied on
+     * the SECOND pass, after a layout exists — the first pass has no ranks to read, so
+     * every edge starts `isBackEdge: false` exactly as `discoverGraph` leaves it.
+     */
+    backEdgeIds?: ReadonlySet<string>;
+}
+/**
+ * Map a discovered (or abstracted) graph plus a metric choice into everything both the
+ * canvas and the table render. Pure: same inputs, same model, no clock and no DOM.
+ */
+declare function buildProcessMapModel({ graph, metric, rework, selection, selectionStates, backEdgeIds, }: BuildProcessMapModelOptions): ProcessMapModel;
+/**
+ * The word for an activity's position in the process — printed in the table's own column
+ * and folded into the node's accessible name, so "this is where cases start" survives
+ * without the start/end glyph.
+ */
+declare function activityRole(data: ProcessActivityNodeData): string;
+/** The word for an edge's shape — the non-colour channel, said in text. */
+declare function transitionShape(data: ProcessTransitionEdgeData): string;
+/**
+ * The CANONICAL (English, un-localized) word for a row's selection/filter state (#373) —
+ * this module is pure data shaping with no locale seam of its own, so it cannot resolve a
+ * translation. It stays exported for a non-React caller (tests, a console, a non-locale
+ * context). The State column's own rendered CELLS resolve the localized text instead, via
+ * {@link PROCESS_SELECTION_STATE_MESSAGE_KEYS} + `t()` at the render site
+ * (`process-map.tsx`) — see that key map's own comment (#413 review). `"associated"` is the
+ * ordinary case and prints nothing, so the column reads as a marker for the two states that
+ * matter, not as noise repeated on every row.
+ */
+declare function selectionStateLabel(state: ProcessSelectionState): string;
+/**
+ * The locale message key for each NON-ORDINARY selection/filter state (#413 review,
+ * PRRT_kwDOT6D7ts6gJX2C) — the State column's cells are the table twin's own
+ * screen-reader channel for row state (#373), so leaving them printing
+ * {@link selectionStateLabel}'s bare English word left a non-English `LocaleProvider`
+ * with untranslated visible AND accessible content. `"associated"` has no entry: it is the
+ * ordinary case and the column prints nothing for it, same as {@link selectionStateLabel}.
+ */
+declare const PROCESS_SELECTION_STATE_MESSAGE_KEYS: Readonly<Partial<Record<ProcessSelectionState, string>>>;
+/** The accessible name of one activity node. */
+declare function activityAriaLabel(data: ProcessActivityNodeData): string;
+/** The accessible name of one transition edge. */
+declare function transitionAriaLabel(data: ProcessTransitionEdgeData, metricLabel: string): string;
+
+/** Options for {@link abstractGraph}. Both fractions are `0..1` and both are required. */
+interface AbstractionOptions {
+    /** Fraction of activities to KEEP, `0..1`. At least one activity is always kept. */
+    activities: number;
+    /** Fraction of paths (transitions) to KEEP, `0..1`, over the kept-activity subgraph. */
+    paths: number;
+    /**
+     * Re-add whatever it takes to keep every kept activity reachable from a start activity
+     * and able to reach an end activity. Defaults to `true` — an island reads as a broken
+     * process, not a simplified one.
+     */
+    keepConnected?: boolean;
+    /** Hide the MOST frequent instead of the least — the "what is rare here" view. */
+    invert?: boolean;
+}
+/** What {@link abstractGraph} returns: a `ProcessGraph` plus what it left out. */
+interface AbstractedGraph extends ProcessGraph {
+    hidden: {
+        /** Activities present in the input graph and absent from this one. */
+        activities: number;
+        /** Transitions present in the input graph and absent from this one. */
+        paths: number;
+    };
+}
+
+/**
+ * The zoom the map refuses to open below, however big the process is.
+ *
+ * A discovered log is routinely wider than any pane, and a fit that shows ALL of it shows
+ * none of it: the 24-activity fixture frames at 0.28, where the activity name (14 px on
+ * the card) prints at 3.9 px and the card is a grey smudge. The floor is set from the
+ * card's own type rather than from a graph size: at 0.75 the name renders at 10.5 px and
+ * the secondary line (12 px) at 9 px, which is the smallest either stays a word.
+ *
+ * It is the OPENING zoom only — {@link MIN_ZOOM} still lets the reader pull all the way
+ * back to an overview, and the minimap says where in the process the pane is sitting. A
+ * fit clamped by this floor is anchored on the START of the process, not its middle;
+ * `CanvasShell` does that (see `anchorToStartWhenClamped`).
+ */
+declare const PROCESS_MAP_LEGIBLE_ZOOM = 0.75;
+/** Props for {@link ProcessMap}. `onSelect` shadows the DOM handler, so it is omitted. */
+interface ProcessMapProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+    /** A discovered graph. Takes precedence over {@link log} when both are given. */
+    graph?: ProcessGraph;
+    /**
+     * An event log to discover from, for a surface with no explorer around it. Runs
+     * `/core`'s `discoverGraph` and `detectRework` internally, memoized on the log.
+     */
+    log?: EventLog;
+    /** Fractions of activities / paths to KEEP, as `/core`'s `abstractGraph` reads them. */
+    abstraction?: Pick<AbstractionOptions, "activities" | "paths">;
+    /** Which readings the nodes and edges paint. */
+    metric: ProcessMetricSpec;
+    /** Rework tallies for the node badge. Derived from {@link log} when that is given. */
+    rework?: ReworkStats;
+    /** Controlled selection. Omit for an uncontrolled map that owns its own. */
+    selection?: ProcessSelection | null;
+    /**
+     * Per-element states an active filter contributes (RM-052 round 2, #227) — e.g. from
+     * `useProcessExplorer`'s own `selectionStates`. Applying or clearing a filter never adds
+     * or removes a node or an edge (Invariant F): it only re-inks the elements a filter
+     * dropped as `"excluded"` (dimmed, never `aria-disabled`). Omit for a map with no
+     * filtering, which reproduces today's selection-only behaviour exactly.
+     */
+    selectionStates?: ProcessSelectionStates;
+    /** Fires with the new selection, or `null` when the reader deselects. */
+    onSelect?: (target: ProcessSelection | null) => void;
+    /** Fires with an intent from the filter menu — hand it straight to `filterLog`. */
+    onFilterIntent?: (intent: ProcessFilterIntent) => void;
+    /** @default "TB" */
+    direction?: FlowLayoutDirection;
+    /** @default true */
+    showMiniMap?: boolean;
+    /** @default true */
+    showLegend?: boolean;
+    /** Render the accessible table twin instead of the canvas. @default false */
+    tableView?: boolean;
+    /** No graph yet. Renders the loading panel rather than an empty canvas. */
+    loading?: boolean;
+    /**
+     * Accessible name for the canvas region. Defaults to the localized
+     * `process.map.label` message.
+     */
+    label?: string;
+}
+/**
+ * The process map.
+ *
+ * @example
+ * ```tsx
+ * <ProcessMap log={log} metric={{ node: "absolute_case", edge: "absolute" }} />
+ * ```
+ */
+declare function ProcessMap({ graph, log, abstraction, metric, rework, selection, selectionStates, onSelect, onFilterIntent, direction, showMiniMap, showLegend, tableView, loading, label, className, ...props }: ProcessMapProps): react.JSX.Element;
+
+/** What the node and edge components read while something is hovered. */
+interface ProcessMapHoverState {
+    /** The hovered activity id, or `null` when the pointer is not on a node. */
+    activityId: string | null;
+    /** Ids of the edges incident to {@link activityId}. Empty when nothing is hovered. */
+    incidentEdgeIds: ReadonlySet<string>;
+}
+/** The resting value — nothing hovered. Frozen and shared, so it is referentially stable. */
+declare const EMPTY_PROCESS_MAP_HOVER: ProcessMapHoverState;
+/**
+ * Hover state for one process map. `ProcessMap` provides it; `ProcessActivityNode` and
+ * `ProcessTransitionEdge` consume it. Default is {@link EMPTY_PROCESS_MAP_HOVER}, so both
+ * components render correctly outside a `ProcessMap` (in a story or a unit test).
+ */
+declare const ProcessMapHoverContext: react.Context<ProcessMapHoverState>;
+/** Read the current hover state. `use()` per the repo's new-context-read convention. */
+declare function useProcessMapHover(): ProcessMapHoverState;
+/**
+ * How an edge hands a key press back to the map (RM-051).
+ *
+ * An edge's label pill is rendered through React Flow's `EdgeLabelRenderer`, which is a
+ * PORTAL: the button lands in `.react-flow__edgelabel-renderer`, outside the edge's own
+ * `<g>`, so it has no `[data-id]` ancestor for the map's root key handler to read. React
+ * portal events still bubble up the REACT tree, though — so `ProcessTransitionEdge`, which
+ * knows its own `id`, catches the key on its wrapper `<g>` and calls this. It is the ONLY
+ * way `Enter` and `f` stay usable on a transition now that the edge `<g>` itself is not a
+ * tab stop.
+ *
+ * The default is a no-op, so `ProcessTransitionEdge` renders standalone (a story, a unit
+ * test) without a provider.
+ */
+type ProcessMapEdgeKeyHandler = (edgeId: string, event: KeyboardEvent) => void;
+/** Provided by `ProcessMap`; consumed by `ProcessTransitionEdge`. */
+declare const ProcessMapEdgeKeyContext: react.Context<ProcessMapEdgeKeyHandler>;
+/** Read the map's edge key handler. `use()` per the repo's new-context-read convention. */
+declare function useProcessMapEdgeKeys(): ProcessMapEdgeKeyHandler;
+
+/**
+ * Branded process-map activity node. Register it in
+ * `nodeTypes={{ "process-activity": ProcessActivityNode }}` and build nodes with
+ * `buildProcessMapModel` rather than by hand — the model is what keeps the canvas and the
+ * `TableView` twin printing the same numbers.
+ */
+declare function ProcessActivityNode(props: NodeProps<ProcessMapNode>): react.JSX.Element;
+
+/**
+ * The `scaleGroup` every process-map edge shares, so `computeEdgeWeightScale` min-maxes
+ * the whole map against ONE domain — the `Legend variant="scale"` beside it reads that
+ * same domain, which is what stops the key and the picture from disagreeing.
+ */
+declare const PROCESS_MAP_EDGE_SCALE_GROUP = "process-map";
+/**
+ * Branded process-map transition edge. Register it in
+ * `edgeTypes={{ "process-transition": ProcessTransitionEdge }}`; build edges with
+ * `buildProcessMapModel`.
+ */
+declare function ProcessTransitionEdge(props: EdgeProps<ProcessMapEdge>): react.JSX.Element;
+
+/** How long a RE-layout waits for the structure to settle. */
+declare 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.
+ */
+declare const PROCESS_MAP_NODE_MOTION_CLASS: string;
+/** One cached dagre result: where every node sits, plus the structure dagre reported. */
+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}. */
+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. */
+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;
+}
+/** Apply a cached snapshot to a fresh set of nodes, matching on id. */
+declare function applyLayoutSnapshot(nodes: ProcessMapNode[], snapshot: ProcessLayoutSnapshot): ProcessMapNode[];
+/**
+ * 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.
+ */
+declare function useProcessLayout({ nodes, edges, structureKey, direction, debounceMs, }: UseProcessLayoutOptions): UseProcessLayoutResult;
+
+interface AbstractionControlsProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+    /** The current abstraction — both fractions, `invert`, and (read-only here) `keepConnected`. */
+    abstraction: AbstractionOptions;
+    /** Called with a PARTIAL patch — mirrors `useProcessExplorer`'s own `setAbstraction`. */
+    onAbstractionChange(next: Partial<AbstractionOptions>): void;
+    /** The CURRENT (already-abstracted) graph — only `activities.length` is read. */
+    graph: Pick<ProcessGraph, "activities">;
+    /** What the current abstraction hides, straight from `AbstractedGraph.hidden`. */
+    hiddenCounts: {
+        activities: number;
+        paths: number;
+    };
+    /** Node budget the "Auto" button searches for. Default `25`. */
+    autoMaxActivities?: number;
+    /** Accessible name for the control group. Default from locale. */
+    label?: string;
+}
+declare const AbstractionControls: react.ForwardRefExoticComponent<AbstractionControlsProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Auto abstraction heuristic — RM-052 (issue #227).
+ *
+ * The "Auto" button on {@link AbstractionControls} picks an activities fraction that fits
+ * a node budget, so a reader opens a busy graph and gets a readable one in one click
+ * instead of hand-dragging a slider. This module is pure and framework-free on purpose —
+ * it is a small, independently testable piece of judgment, not a UI concern.
+ *
+ * ## The heuristic
+ *
+ * "Smallest activities % whose graph fits the budget" is the phrase this feature is
+ * usually described by, but taken literally it is degenerate: a fraction near 0 always
+ * fits any budget, so the "smallest fraction" reading is trivially satisfied by hiding
+ * almost everything. What a reader actually wants from "Auto" is the OPPOSITE end of
+ * that: the LARGEST fraction — the most detail — that still fits the budget. This module
+ * implements that reading.
+ *
+ * ## Bounded and terminating, by construction
+ *
+ * The search is a fixed-iteration binary search over the fraction range `[minFraction,
+ * 1]` — `maxSteps` (default 8) iterations, no early-exit convergence check, no
+ * data-dependent loop bound. That makes termination a property of the `for` loop itself,
+ * not of the input: `computeAutoAbstraction` always does at most `maxSteps` probes of
+ * `keptAt(fraction)`, regardless of how many activities the graph has. See
+ * `auto-abstraction.test.ts` for the explicit bound assertion.
+ *
+ * ## Known limitation: this heuristic is topology-blind (RM-052 round 2, #227, F2)
+ *
+ * `keptActivityCount` predicts how many activities a fraction keeps from the COUNT alone —
+ * `round(total * fraction)`. It has no visibility into which activities `abstractGraph`
+ * would actually drop, or how they connect. `abstractGraph`'s default `keepConnected: true`
+ * adds activities back in to restore reachability to a start/end activity that truncation
+ * would otherwise strand — and on a graph with no bypass edges (a strict, unbranched chain,
+ * where every activity's only path to the end activity runs through every activity after
+ * it), dropping ANY suffix forces the ENTIRE remainder back in. The naive prediction and the
+ * real, reconnected result can then diverge by the graph's full size: a 30-activity chain
+ * with `maxActivities: 10` predicts a fraction that keeps 10 activities, but
+ * `abstractGraph(graph, { activities: fraction, keepConnected: true })` actually keeps all
+ * 30 — see `auto-abstraction.test.ts`'s "known limitation" describe block, which measures
+ * this exact case and isolates `keepConnected` as the sole cause (turning it off makes the
+ * real result match the naive prediction exactly).
+ *
+ * This is accepted as a best-effort gap, not fixed here: fixing it precisely would mean this
+ * module accepting a real `ProcessGraph` and searching against `abstractGraph`'s actual
+ * output rather than a plain count — a signature change that would also require updating
+ * `AbstractionControls`'s call site (`handleAuto`), which sits outside this round's write-set
+ * (RM-052-fix-brief.md / RM-052-tristate-decision.md §10). A future round that wants an exact
+ * search should route that signature change through `brand-ui-design-system-architect` (it
+ * changes this module's public contract) rather than patching around it here.
+ */
+interface AutoAbstractionOptions {
+    /** Largest number of activities the resulting view should keep. Default `25`. */
+    maxActivities?: number;
+    /** Maximum fraction candidates probed before returning the best found so far. Default `8`. */
+    maxSteps?: number;
+    /** The smallest fraction ever offered — "Auto" never hides everything. Default `0.05`. */
+    minFraction?: number;
+}
+interface AutoAbstractionResult {
+    /** The activities fraction to hand to `setAbstraction`. */
+    activities: number;
+    /** How many fraction candidates were actually probed — always `<= maxSteps`. */
+    steps: number;
+}
+/**
+ * Picks the activities fraction "Auto" applies, from a plain activity COUNT — not a graph.
+ * Paths are left to `abstractGraph`'s own connectivity repair, and duration/statistic
+ * fields never enter the search, so this heuristic's result cannot be perturbed by the
+ * discovery layer's own reservoir-sampling nondeterminism. Taking a count rather than a
+ * `ProcessGraph` also lets a caller pass the graph's PRE-abstraction total — e.g.
+ * `graph.activities.length + hiddenCounts.activities` — without building a throwaway array.
+ */
+declare function computeAutoAbstraction(totalActivities: number, opts?: AutoAbstractionOptions): AutoAbstractionResult;
+
+type MetricLayer = "frequency" | "performance" | "rework";
+interface MetricLayerSwitchMetric {
+    node: ProcessMetric;
+    edge: ProcessMetric;
+}
+interface MetricLayerSwitchProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+    layer: MetricLayer;
+    onLayerChange(layer: MetricLayer): void;
+    metric: MetricLayerSwitchMetric;
+    onMetricChange(next: Partial<MetricLayerSwitchMetric>): void;
+    /** Controlled lock state. Omit to let the component manage it (`defaultLocked`). */
+    locked?: boolean;
+    /** Initial lock state when uncontrolled. Default `true`. */
+    defaultLocked?: boolean;
+    onLockedChange?(locked: boolean): void;
+    label?: string;
+}
+declare const MetricLayerSwitch: react.ForwardRefExoticComponent<MetricLayerSwitchProps & react.RefAttributes<HTMLDivElement>>;
+
+interface ProcessKpiStripKpis {
+    cases: number;
+    events: number;
+    variants: number;
+    medianThroughput: number;
+    reworkRate: number;
+}
+type ProcessKpiStripTrendKey = keyof ProcessKpiStripKpis | "conformance";
+interface ProcessKpiStripProps extends HTMLAttributes<HTMLDivElement> {
+    kpis: ProcessKpiStripKpis;
+    /** `0..1`, or `null`/`undefined` when no conformance model has been fitted. */
+    conformance?: number | null;
+    /** Optional per-tile trend series (oldest -> newest), keyed by KPI. */
+    trends?: Partial<Record<ProcessKpiStripTrendKey, number[]>>;
+    loading?: boolean;
+}
+declare function ProcessKpiStrip({ kpis, conformance, trends, loading, className, ...props }: ProcessKpiStripProps): react.JSX.Element;
+
+/**
+ * Off-thread discovery — RM-050.
+ *
+ * Discovering a graph from a raw log is O(events) with a couple of hash lookups per event;
+ * on a 200 000-row import that is long enough to drop frames, and a dropped frame during a
+ * file import is exactly the moment an app reads as broken. So the derivation moves to a
+ * worker — but ONLY as an optimization: the caller never branches on the environment.
+ *
+ * **Degrade, never fail.** When there is no `Worker` (a server render, a Node test, an
+ * embedded webview), when constructing one throws, or when a live one errors, the same
+ * functions run inline on the calling thread and the promise still resolves with the same
+ * answer. `handleProcessRequest` is literally shared with the worker entry, so "the inline
+ * path agrees with the worker path" is a property of the code, not of a test.
+ *
+ * **Normalize once.** Every method takes an `AnyLog`; hand it an already-normalized log
+ * (`asNormalizedLog`) and neither side re-parses. A `NormalizedLog` is plain data and
+ * clones across `postMessage` unchanged.
+ */
+
+/**
+ * The slice of the `Worker` interface this module uses.
+ *
+ * Narrow on purpose: it is the seam a test (or a bundler with its own worker construction)
+ * substitutes, and demanding the full DOM `Worker` surface for that would be pointless
+ * ceremony. A real `Worker` satisfies it.
+ */
+interface ProcessWorkerLike {
+    postMessage(message: unknown): void;
+    terminate(): void;
+    addEventListener(type: "message" | "error" | "messageerror", listener: (event: unknown) => void): void;
+}
+/** Options for {@link createProcessWorker}. */
+interface CreateProcessWorkerOptions {
+    /** Skip the worker entirely and run inline. Useful for benchmarks and for tests. */
+    forceInline?: boolean;
+    /**
+     * Build the worker yourself.
+     *
+     * The default construction is
+     * `new Worker(new URL("./process-worker.ts", import.meta.url), { type: "module" })`.
+     * A bundler compiling THIS SOURCE (Vite, webpack) rewrites that literal itself; a
+     * consumer of the BUILT package gets `dist/core/process-worker.js`, which
+     * `tsup.config.ts` emits as its own pass and points the built bundle at — a bundler
+     * rewrites the source it compiles, never a `dist` it merely consumes, so that file has
+     * to be real. A host that needs its own URL supplies this instead. Throwing from it is
+     * safe: the handle falls back to the inline path.
+     */
+    createWorker?: () => ProcessWorkerLike;
+}
+
+/** What a node or an edge is painted with — the same domain `ProcessMap`'s metric reads. */
+type ProcessExplorerMetric = FrequencyMode | PerformanceAgg;
+/** The two metric slots a process explorer coordinates. */
+interface ProcessExplorerMetricSpec {
+    node: ProcessExplorerMetric;
+    edge: ProcessExplorerMetric;
+}
+/**
+ * Every intent this hook's `applyIntent` accepts — wider than `ProcessMap`'s own menu.
+ *
+ * `ProcessFilterIntent` (RM-051) is the four kinds `ProcessMap`'s filter-intent menu
+ * offers (`with`/`without`/`startsWith`/`endsWith`) and stays scoped to exactly that menu.
+ * This hook's `FilterIntent` widens it with `{ kind: "variant" }` (RM-052 round 2, #227) so
+ * a variant-explorer view can drive the SAME `applyIntent`/`intents` pair to filter by a
+ * variant selection — a case a click on the process map can never produce, but a click on a
+ * variant row can. The widening is local to this hook's own type alias; it does not touch
+ * `ProcessFilterIntent` or `ProcessMap`'s menu, which still only ever emits the original four.
+ */
+type FilterIntent = ProcessFilterIntent | Extract<FilterSpec, {
+    kind: "variant";
+}>;
+/** Options for {@link useProcessExplorer}. */
+interface ProcessExplorerOptions {
+    /** Initial abstraction sliders. Default: `{ activities: 1, paths: 1 }` — the identity. */
+    abstraction?: Partial<AbstractionOptions>;
+    /** Initial metric choice. Default: `{ node: "absolute", edge: "absolute" }`. */
+    metric?: Partial<ProcessExplorerMetricSpec>;
+    /** Initial metric layer — feed straight into `MetricLayerSwitch`'s `layer` prop. Default `"frequency"`. */
+    layer?: MetricLayer;
+    /**
+     * Event count above which discovery and variant extraction move to a worker (RM-050's
+     * own stated figure). Default `50_000`. Lower it in a test that wants to exercise the
+     * worker path without a 50k-row fixture.
+     */
+    workerThreshold?: number;
+    /**
+     * Forwarded verbatim to `createProcessWorker` — override `forceInline`/`createWorker`
+     * for a test or a host with its own worker construction. The handle is created lazily,
+     * on the first request that crosses `workerThreshold`, so passing this costs nothing in
+     * a session that never does.
+     */
+    worker?: CreateProcessWorkerOptions;
+}
+/** What {@link useProcessExplorer} returns. See the module docblock for the recompute rules. */
+interface UseProcessExplorerResult {
+    /** The graph to render — already abstracted. Superset of `ProcessGraph`; see `hidden`. */
+    graph: AbstractedGraph;
+    /** Variants of the FILTERED (not abstracted — variants have no node/edge concept) log. */
+    variants: Variant[];
+    abstraction: AbstractionOptions;
+    setAbstraction(next: Partial<AbstractionOptions>): void;
+    metric: ProcessExplorerMetricSpec;
+    setMetric(next: Partial<ProcessExplorerMetricSpec>): void;
+    /** The single explicit selection — `ProcessMap`'s own `selection` prop shape. */
+    selection: ProcessSelection | null;
+    /** Pass straight through as `ProcessMap`'s `onSelect`. */
+    onSelect(next: ProcessSelection | null): void;
+    applyIntent(intent: FilterIntent): void;
+    clearIntent(index: number): void;
+    intents: FilterIntent[];
+    filteredLog: EventLog;
+    /**
+     * Per-element states the active filter contributes — pass straight into `ProcessMap`'s
+     * `selectionStates` prop (RM-052 round 2, #227, Invariant F). Every activity/transition an
+     * intent excluded is marked `"excluded"` here; nothing is ever removed from `graph` itself.
+     * `variants` (RM-052 round 3, #227, G2) marks every id named by an active
+     * `{ kind: "variant" }` intent `"selected"` — read by `VariantExplorer` (RM-054), not by
+     * `ProcessMap`, which has no variant nodes.
+     */
+    selectionStates: ProcessSelectionStates;
+    /** Activities/paths abstraction is currently hiding — sourced from `abstractGraph`'s own `hidden` field. */
+    hiddenCounts: {
+        activities: number;
+        paths: number;
+    };
+    /**
+     * Activities/transitions the active FILTER excluded — rendered, dimmed, never removed.
+     * Disjoint from `hiddenCounts` by construction: `hiddenCounts` is what abstraction removed
+     * from the render entirely, `excludedCounts` is what the filter re-inked but kept drawn.
+     */
+    excludedCounts: {
+        activities: number;
+        paths: number;
+    };
+    /** The active metric layer — feed straight into `MetricLayerSwitch`'s `layer` prop. */
+    layer: MetricLayer;
+    /** Pass straight through as `MetricLayerSwitch`'s `onLayerChange` — a plain setter; the
+     * frequency/performance metric coercion lives in `MetricLayerSwitch` itself, not here. */
+    setLayer(next: MetricLayer): void;
+    kpis: {
+        cases: number;
+        events: number;
+        variants: number;
+        /** Median case throughput time, in milliseconds. */
+        medianThroughput: number;
+        /** Fraction of cases carrying at least one repeated activity. */
+        reworkRate: number;
+    };
+    /** Full rework tallies — feed straight into `ProcessMap`'s `rework` prop. */
+    rework: ReworkStats;
+    /**
+     * `true` while a discovery/variant request for the CURRENT `filteredLog` is running off
+     * a worker. Always `false` when `filteredLog` stays at or under `workerThreshold` — the
+     * synchronous path has no gap to express. See loading-states.md: this is `loading`, not
+     * `isStreaming` — a settled recomputation, not token-by-token output.
+     */
+    loading: boolean;
+}
+/**
+ * Coordinate abstraction, metric choice, selection and filter intents over one event log
+ * into everything `ProcessMap` / `AbstractionControls` / `MetricLayerSwitch` /
+ * `ProcessKpiStrip` need. See the module docblock.
+ */
+declare function useProcessExplorer(log: EventLog, opts?: ProcessExplorerOptions): UseProcessExplorerResult;
+
+export { AbstractionControls, type AbstractionControlsProps, type ActivityFrequencyMode, type AutoAbstractionOptions, type AutoAbstractionResult, type BuildProcessMapModelOptions, DEFAULT_LAYOUT_DEBOUNCE_MS, EMPTY_PROCESS_MAP_HOVER, type FilterIntent, GHOST_OPACITY, type MetricLayer, MetricLayerSwitch, type MetricLayerSwitchMetric, type MetricLayerSwitchProps, PROCESS_FILTER_INTENT_KINDS, PROCESS_FILTER_INTENT_LABELS, PROCESS_FILTER_INTENT_MESSAGE_KEYS, PROCESS_MAP_EDGE_SCALE_GROUP, PROCESS_MAP_LEGIBLE_ZOOM, PROCESS_MAP_NODE_MOTION_CLASS, PROCESS_SELECTION_STATE_MESSAGE_KEYS, ProcessActivityNode, type ProcessActivityNodeData, type ProcessActivityRow, type ProcessEdgeDenominators, type ProcessExplorerMetric, type ProcessExplorerMetricSpec, type ProcessExplorerOptions, type ProcessFilterIntent, ProcessKpiStrip, type ProcessKpiStripKpis, type ProcessKpiStripProps, type ProcessKpiStripTrendKey, type ProcessLayoutSnapshot, ProcessMap, type ProcessMapEdge, ProcessMapEdgeKeyContext, type ProcessMapEdgeKeyHandler, type ProcessMapExcludedCounts, ProcessMapHoverContext, type ProcessMapHoverState, type ProcessMapModel, type ProcessMapNode, type ProcessMapProps, type ProcessMetric, type ProcessMetricSpec, type ProcessSelection, type ProcessSelectionKind, type ProcessSelectionNeighbourhood, type ProcessSelectionState, type ProcessSelectionStates, ProcessTransitionEdge, type ProcessTransitionEdgeData, type ProcessTransitionRow, type TransitionFrequencyMode, type UseProcessExplorerResult, type UseProcessLayoutOptions, type UseProcessLayoutResult, activityAriaLabel, activityMetricValue, activityRole, applyLayoutSnapshot, buildProcessMapModel, computeAutoAbstraction, edgeMetricLabel, formatDurationMs, formatMetricValue, isPerformanceMetric, nodeMetricLabel, processEdgeDenominators, processEdgeId, processGraphStructureKey, resolveActivityFrequencyMode, resolveSelectionState, resolveTransitionFrequencyMode, selectionNeighbourhood, selectionStateLabel, transitionAriaLabel, transitionMetricValue, transitionShape, useProcessExplorer, useProcessLayout, useProcessMapEdgeKeys, useProcessMapHover };