@elabs-ai/components-process 4.2.0 → 5.1.0

package/src/happy-path-editor/happy-path-step-node.tsx

@@ -0,0 +1,175 @@
+"use client";
+
+/**
+ * HappyPathStepNode — one prescribed step on the happy-path canvas (RM-062).
+ *
+ * Composes `@elabs-ai/components-flow`'s `FlowNode` (frame, handles, focus treatment) and
+ * puts the step's controls in its `footer` slot: the activity (a `Select` over
+ * `availableActivities`, or free text), the `optional`/`repeatable` `Switch`es that map
+ * one-to-one onto `HappyPathStep`, and a remove button. It holds no state — every control
+ * writes straight back through the editor context.
+ *
+ * A repeatable step shows a repeat glyph and an optional one a skip glyph beside its
+ * title, and both words join the node's accessible name, so neither flag is carried by a
+ * switch position alone.
+ */
+import { useId, useMemo } from "react";
+import { Redo2, Repeat, Trash2 } from "lucide-react";
+import {
+  Button,
+  Input,
+  Label,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  Switch,
+} from "@elabs-ai/components-ui";
+import { FlowNode, type FlowNodeData } from "@elabs-ai/components-flow";
+import type { Node, NodeProps } from "@xyflow/react";
+import type { HappyPathStep } from "../core/reference-model";
+import { fillLabel } from "../variant-explorer/variant-explorer-model";
+import { useHappyPathEditor } from "./happy-path-editor-context";
+
+/** `data` carried by a {@link HappyPathStepFlowNode}. */
+export interface HappyPathStepNodeData extends Record<string, unknown> {
+  /** Zero-based position in the path. */
+  index: number;
+  step: HappyPathStep;
+}
+
+/** A happy-path step node. Register as `nodeTypes={{ "happy-path-step": … }}`. */
+export type HappyPathStepFlowNode = Node<HappyPathStepNodeData, "happy-path-step">;
+
+/** One step of the happy-path editor. */
+export function HappyPathStepNode(props: NodeProps<HappyPathStepFlowNode>) {
+  const { index, step } = props.data;
+  const { labels, availableActivities, updateStep, removeStep } = useHappyPathEditor();
+  const optionalId = useId();
+  const repeatableId = useId();
+  const n = index + 1;
+  const activityName = step.activity || labels.untitled;
+
+  const options = useMemo(() => {
+    if (!availableActivities) return undefined;
+    return step.activity && !availableActivities.includes(step.activity)
+      ? [step.activity, ...availableActivities]
+      : [...availableActivities];
+  }, [availableActivities, step.activity]);
+
+  const flowData = useMemo<FlowNodeData>(
+    () => ({
+      title: activityName,
+      kind: fillLabel(labels.step, { n }),
+      icon:
+        step.repeatable || step.optional ? (
+          <span className="flex items-center gap-0.5">
+            {step.optional ? <Redo2 aria-hidden="true" /> : null}
+            {step.repeatable ? <Repeat aria-hidden="true" /> : null}
+          </span>
+        ) : undefined,
+      footer: (
+        <div
+          data-slot="happy-path-step-node-controls"
+          // `nodrag nopan`: typing, toggling and clicking here must never pan the canvas
+          // or start a node drag.
+          className="nodrag nopan flex flex-col gap-2"
+        >
+          {options ? (
+            <Select
+              value={step.activity || undefined}
+              onValueChange={(activity) => updateStep(index, { activity })}
+            >
+              <SelectTrigger
+                size="sm"
+                aria-label={fillLabel(labels.activity, { n })}
+                data-slot="happy-path-step-node-activity"
+                className="w-full"
+              >
+                <SelectValue placeholder={labels.activityPlaceholder} />
+              </SelectTrigger>
+              <SelectContent>
+                {options.map((activity) => (
+                  <SelectItem key={activity} value={activity}>
+                    {activity}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          ) : (
+            <Input
+              value={step.activity}
+              onChange={(event) => updateStep(index, { activity: event.target.value })}
+              aria-label={fillLabel(labels.activity, { n })}
+              placeholder={labels.activityPlaceholder}
+              data-slot="happy-path-step-node-activity"
+              className="h-control-sm"
+            />
+          )}
+          <div className="flex items-center justify-between gap-3">
+            <Label htmlFor={optionalId} className="text-caption">
+              {labels.optional}
+            </Label>
+            <Switch
+              id={optionalId}
+              data-slot="happy-path-step-node-optional"
+              aria-label={fillLabel(labels.optionalFor, { activity: activityName })}
+              checked={step.optional === true}
+              onCheckedChange={(optional) => updateStep(index, { optional })}
+            />
+          </div>
+          <div className="flex items-center justify-between gap-3">
+            <Label htmlFor={repeatableId} className="text-caption">
+              {labels.repeatable}
+            </Label>
+            <Switch
+              id={repeatableId}
+              data-slot="happy-path-step-node-repeatable"
+              aria-label={fillLabel(labels.repeatableFor, { activity: activityName })}
+              checked={step.repeatable === true}
+              onCheckedChange={(repeatable) => updateStep(index, { repeatable })}
+            />
+          </div>
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            data-slot="happy-path-step-node-remove"
+            aria-label={fillLabel(labels.removeFor, { activity: activityName })}
+            className="self-end gap-1.5"
+            onClick={() => removeStep(index)}
+          >
+            <Trash2 aria-hidden="true" className="size-3.5" />
+            {labels.remove}
+          </Button>
+        </div>
+      ),
+    }),
+    [
+      activityName,
+      labels,
+      n,
+      index,
+      step.activity,
+      step.optional,
+      step.repeatable,
+      options,
+      optionalId,
+      repeatableId,
+      updateStep,
+      removeStep,
+    ],
+  );
+
+  return (
+    <div
+      data-slot="happy-path-step-node"
+      data-optional={step.optional ? "true" : undefined}
+      data-repeatable={step.repeatable ? "true" : undefined}
+      className="w-56"
+    >
+      <FlowNode {...props} type="brand" data={flowData} />
+    </div>
+  );
+}

package/src/happy-path-editor/index.ts

@@ -0,0 +1,4 @@
+/** HappyPathEditor (RM-062) — public surface. */
+export * from "./happy-path-editor";
+export * from "./happy-path-editor-context";
+export * from "./happy-path-step-node";

package/src/index.ts

@@ -5,7 +5,7 @@
  * `-charts`, `-data` and `-ui`, and nothing depends on it. The binding rule is
  * "primitives go down, compositions go up" — a generic edge, mark, table, scale or
  * control belongs in the base package that owns it, never here. See
- * `.claude/rules/process-components.md` and `pnpm process:reuse:check`.
+ * `.claude/rules/data.md` ("Process mining" section) and `pnpm check --rule process-reuse`.
  *
  * Wave-1 items APPEND their exports at the end of the block below, each under a
  * `// <Name> — RM-NNN` comment, so concurrent branches merge as appends.
@@ -27,3 +27,53 @@ export * from "./abstraction-controls";
 export * from "./metric-layer-switch";
 export * from "./process-kpi-strip";
 export * from "./use-process-explorer";
+
+// VariantExplorer — RM-054
+export * from "./variant-explorer";
+export {
+  ACTIVITY_COLOR_SLOTS,
+  ACTIVITY_OTHER_TOKEN,
+  activityColorScale,
+} from "./core/activity-color-scale";
+export type {
+  ActivityColor,
+  ActivityColorLegendEntry,
+  ActivityColorScale,
+} from "./core/activity-color-scale";
+
+// ProcessFilterBar — RM-056
+export * from "./process-filter-bar";
+
+// CaseTable / CaseTimeline — RM-055
+export * from "./case-table";
+export * from "./case-timeline";
+
+// DottedChart — RM-059
+export * from "./dotted-chart";
+
+// PerformanceSpectrum — RM-060
+export * from "./performance-spectrum";
+
+// ConformanceOverlay / ViolationList / HappyPathEditor — RM-062
+export * from "./conformance-overlay";
+export * from "./violation-list";
+export * from "./happy-path-editor";
+
+// ProcessCompare — RM-064
+export * from "./process-compare";
+
+// ProcessReplay — RM-065
+export * from "./process-replay";
+
+// Object-centric — RM-066
+export type {
+  AbstractedObjectCentricGraph,
+  ObjectCentricActivityStats,
+  ObjectCentricGraph,
+  ObjectTypeActivityCounts,
+} from "./core/discover-object-centric-graph";
+export { OBJECT_TYPE_ABSTRACTION_DEFAULT_LABELS } from "./abstraction-controls/abstraction-controls";
+export type {
+  ObjectTypeAbstraction,
+  ObjectTypeAbstractionLabels,
+} from "./abstraction-controls/abstraction-controls";

package/src/performance-spectrum/aggregate-segments.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+
+import { segmentKey, type SegmentOccurrence } from "../core/segments";
+import {
+  aggregateSegmentBins,
+  buildSpectrumRows,
+  casesInRange,
+  spectrumDomain,
+  spectrumTicks,
+} from "./aggregate-segments";
+
+const AB = segmentKey("A", "B");
+const BC = segmentKey("B", "C");
+
+const occ = (segment: string, caseId: string, start: number, end: number): SegmentOccurrence => ({
+  segment,
+  caseId,
+  start,
+  end,
+  duration: end - start,
+});
+
+const OCCURRENCES: SegmentOccurrence[] = [
+  occ(AB, "c2", 20, 40),
+  occ(AB, "c1", 0, 10),
+  occ(AB, "c3", 30, 60),
+  occ(AB, "c4", 35, 75),
+  occ(BC, "c1", 10, 100),
+  occ(BC, "c2", 40, 50),
+];
+
+describe("buildSpectrumRows", () => {
+  const rows = buildSpectrumRows(
+    [
+      { from: "A", to: "B" },
+      { from: "B", to: "C" },
+      { from: "A", to: "B" },
+      { from: "C", to: "D" },
+    ],
+    OCCURRENCES,
+  );
+
+  it("keeps one row per distinct definition, in order, including empty ones", () => {
+    expect(rows.map((r) => r.key)).toEqual([AB, BC, segmentKey("C", "D")]);
+    expect(rows[2]?.lines).toEqual([]);
+    expect(rows[2]?.caseCount).toBe(0);
+  });
+
+  it("sorts lines by start and reads quartiles against the row's own distribution", () => {
+    const ab = rows[0]!;
+    expect(ab.lines.map((l) => [l.caseId, l.duration, l.quartile])).toEqual([
+      ["c1", 10, 1],
+      ["c2", 20, 2],
+      ["c3", 30, 3],
+      ["c4", 40, 4],
+    ]);
+    // B→C has only two samples: 90 is slow FOR B→C even though A→B never saw it.
+    expect(rows[1]!.lines.map((l) => [l.caseId, l.quartile])).toEqual([
+      ["c1", 4],
+      ["c2", 1],
+    ]);
+  });
+
+  it("computes case count, median and p90 per row", () => {
+    expect(rows[0]).toMatchObject({ caseCount: 4, medianDuration: 25, p90Duration: 37 });
+  });
+});
+
+describe("aggregateSegmentBins", () => {
+  const [ab] = buildSpectrumRows([{ from: "A", to: "B" }], OCCURRENCES);
+
+  it("buckets by entry time, returns only non-empty bins, with a median quartile", () => {
+    expect(aggregateSegmentBins(ab!, 25, 0)).toEqual([
+      { segment: AB, start: 0, end: 25, count: 2, medianDuration: 15, quartile: 2 },
+      { segment: AB, start: 25, end: 50, count: 2, medianDuration: 35, quartile: 4 },
+    ]);
+  });
+
+  it("treats a non-positive bin size as 1 ms rather than looping forever", () => {
+    expect(aggregateSegmentBins(ab!, 0, 0)).toHaveLength(4);
+  });
+});
+
+describe("spectrumDomain / spectrumTicks / casesInRange", () => {
+  const rows = buildSpectrumRows(
+    [
+      { from: "A", to: "B" },
+      { from: "B", to: "C" },
+    ],
+    OCCURRENCES,
+  );
+
+  it("spans every row's first start to last end, widening a degenerate domain", () => {
+    expect(spectrumDomain(rows)).toEqual([0, 100]);
+    expect(spectrumDomain([])).toEqual([0, 1000]);
+  });
+
+  it("spaces ticks evenly, ends included", () => {
+    expect(spectrumTicks([0, 100], 5)).toEqual([0, 25, 50, 75, 100]);
+  });
+
+  it("finds cases whose occurrences overlap the range, in row then time order", () => {
+    expect(casesInRange(rows, 45, 55)).toEqual(["c3", "c4", "c1", "c2"]);
+    expect(casesInRange(rows, 12, 18)).toEqual(["c1"]);
+    expect(casesInRange(rows, 101, 200)).toEqual([]);
+  });
+});

package/src/performance-spectrum/aggregate-segments.ts

@@ -0,0 +1,174 @@
+/**
+ * The pure model behind `PerformanceSpectrum` — RM-060.
+ *
+ * Everything here is React-free and unit-tested on its own: grouping occurrences into
+ * rows (with each occurrence's quartile read against ITS OWN segment), the aggregated
+ * mode's time bins, the shared time domain and ticks, and the brush's case lookup. The
+ * component only lays these out and paints them.
+ */
+import {
+  durationQuartileThresholds,
+  quartileOf,
+  segmentKey,
+  type DurationQuartile,
+  type SegmentDefinition,
+  type SegmentOccurrence,
+} from "../core/segments";
+import { ascending, quantileSorted } from "../core/scale";
+
+/** One occurrence, ready to paint: its quartile is already resolved. */
+export interface SpectrumLine extends SegmentOccurrence {
+  quartile: DurationQuartile;
+}
+
+/** One `binSize` bucket of one row in aggregated mode. */
+export interface SpectrumBin {
+  segment: string;
+  /** Bucket start, epoch ms (inclusive). */
+  start: number;
+  /** Bucket end, epoch ms (exclusive). */
+  end: number;
+  /** Occurrences entering the segment inside the bucket. */
+  count: number;
+  /** Median duration of those occurrences, ms. */
+  medianDuration: number;
+  /** The median of their quartiles, rounded up — the bar's fill. */
+  quartile: DurationQuartile;
+}
+
+/** One spectrum row: a segment and everything drawn in it. */
+export interface SpectrumRow {
+  key: string;
+  definition: SegmentDefinition;
+  /** Sorted by `start`, then `end`, then `caseId` — the keyboard cursor's walk order. */
+  lines: SpectrumLine[];
+  /** Distinct cases with at least one occurrence. */
+  caseCount: number;
+  medianDuration: number;
+  p90Duration: number;
+}
+
+function compareLines(a: SegmentOccurrence, b: SegmentOccurrence): number {
+  return (
+    a.start - b.start || a.end - b.end || (a.caseId < b.caseId ? -1 : a.caseId > b.caseId ? 1 : 0)
+  );
+}
+
+/** Median of an ascending-sorted array's rounded-up middle — for small integer quartiles. */
+function medianQuartile(quartiles: DurationQuartile[]): DurationQuartile {
+  const sorted = [...quartiles].sort(ascending);
+  return Math.ceil(quantileSorted(sorted, 0.5)) as DurationQuartile;
+}
+
+/**
+ * Groups `occurrences` into one row per definition in `order` (duplicates dropped),
+ * resolving each occurrence's quartile against its own segment's distribution.
+ */
+export function buildSpectrumRows(
+  order: readonly SegmentDefinition[],
+  occurrences: readonly SegmentOccurrence[],
+): SpectrumRow[] {
+  const byKey = new Map<string, SegmentOccurrence[]>();
+  for (const occurrence of occurrences) {
+    const bucket = byKey.get(occurrence.segment);
+    if (bucket) bucket.push(occurrence);
+    else byKey.set(occurrence.segment, [occurrence]);
+  }
+
+  const rows: SpectrumRow[] = [];
+  const seen = new Set<string>();
+  for (const definition of order) {
+    const key = segmentKey(definition.from, definition.to);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const own = byKey.get(key) ?? [];
+    const durations = own.map((o) => o.duration).sort(ascending);
+    const thresholds = durationQuartileThresholds(durations);
+    const lines = own
+      .map((o) => ({ ...o, quartile: quartileOf(o.duration, thresholds) }))
+      .sort(compareLines);
+    const cases = new Set<string>();
+    for (const o of own) cases.add(o.caseId);
+    rows.push({
+      key,
+      definition,
+      lines,
+      caseCount: cases.size,
+      medianDuration: durations.length ? quantileSorted(durations, 0.5) : 0,
+      p90Duration: durations.length ? quantileSorted(durations, 0.9) : 0,
+    });
+  }
+  return rows;
+}
+
+/**
+ * The aggregated mode's bars for one row: occurrences bucketed by the time they ENTER the
+ * segment, `binSize` ms wide, aligned to `origin`. Only non-empty buckets are returned,
+ * in time order, so a sparse year at a one-minute bin costs nothing for the empty minutes.
+ */
+export function aggregateSegmentBins(
+  row: SpectrumRow,
+  binSize: number,
+  origin: number,
+): SpectrumBin[] {
+  const size = Number.isFinite(binSize) && binSize > 0 ? binSize : 1;
+  const buckets = new Map<number, SpectrumLine[]>();
+  for (const line of row.lines) {
+    const index = Math.floor((line.start - origin) / size);
+    const bucket = buckets.get(index);
+    if (bucket) bucket.push(line);
+    else buckets.set(index, [line]);
+  }
+  return [...buckets.keys()].sort(ascending).map((index) => {
+    const lines = buckets.get(index) as SpectrumLine[];
+    const durations = lines.map((l) => l.duration).sort(ascending);
+    return {
+      segment: row.key,
+      start: origin + index * size,
+      end: origin + (index + 1) * size,
+      count: lines.length,
+      medianDuration: quantileSorted(durations, 0.5),
+      quartile: medianQuartile(lines.map((l) => l.quartile)),
+    };
+  });
+}
+
+/**
+ * The shared time domain `[min start, max end]` across every row. A degenerate domain
+ * (one instant, or nothing at all) is widened by one second so a scale never divides by 0.
+ */
+export function spectrumDomain(rows: readonly SpectrumRow[]): [number, number] {
+  let lo = Number.POSITIVE_INFINITY;
+  let hi = Number.NEGATIVE_INFINITY;
+  for (const row of rows) {
+    for (const line of row.lines) {
+      if (line.start < lo) lo = line.start;
+      if (line.end > hi) hi = line.end;
+    }
+  }
+  if (!Number.isFinite(lo) || !Number.isFinite(hi)) return [0, 1000];
+  return hi > lo ? [lo, hi] : [lo, lo + 1000];
+}
+
+/** `count` evenly spaced tick instants across `domain`, both ends included. */
+export function spectrumTicks(domain: readonly [number, number], count = 5): number[] {
+  const n = Math.max(2, Math.floor(count));
+  const [lo, hi] = domain;
+  return Array.from({ length: n }, (_, i) => lo + ((hi - lo) * i) / (n - 1));
+}
+
+/**
+ * Case ids with at least one occurrence overlapping `[from, to]` (inclusive), in the order
+ * they are first met walking rows top to bottom and each row in time order.
+ */
+export function casesInRange(rows: readonly SpectrumRow[], from: number, to: number): string[] {
+  const lo = Math.min(from, to);
+  const hi = Math.max(from, to);
+  const ids = new Set<string>();
+  for (const row of rows) {
+    for (const line of row.lines) {
+      if (line.start <= hi && line.end >= lo) ids.add(line.caseId);
+    }
+  }
+  return [...ids];
+}

package/src/performance-spectrum/index.ts

@@ -0,0 +1,25 @@
+/**
+ * PerformanceSpectrum (RM-060) — public surface: the view, its labels, and the pure row /
+ * bin model a host can reuse (e.g. to print the same numbers in a report).
+ */
+export {
+  PERFORMANCE_SPECTRUM_DEFAULT_BIN_SIZE,
+  PERFORMANCE_SPECTRUM_ROW_HEIGHT,
+  PERFORMANCE_SPECTRUM_SEGMENT_LIMIT,
+  PerformanceSpectrum,
+} from "./performance-spectrum";
+export type {
+  PerformanceSpectrumFilterIntent,
+  PerformanceSpectrumOrder,
+  PerformanceSpectrumProps,
+} from "./performance-spectrum";
+export { PERFORMANCE_SPECTRUM_DEFAULT_LABELS } from "./performance-spectrum-context";
+export type { PerformanceSpectrumLabels } from "./performance-spectrum-context";
+export {
+  aggregateSegmentBins,
+  buildSpectrumRows,
+  casesInRange,
+  spectrumDomain,
+  spectrumTicks,
+} from "./aggregate-segments";
+export type { SpectrumBin, SpectrumLine, SpectrumRow } from "./aggregate-segments";

package/src/performance-spectrum/performance-spectrum-context.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+/**
+ * The context `PerformanceSpectrum` shares with its rows — RM-060.
+ *
+ * Every row paints against the SAME time domain, ticks, ramp and formatters; lifting
+ * them into one provider keeps the row component prop-light and guarantees two rows can
+ * never disagree about where an instant sits on the shared x-axis.
+ */
+import { createContext, useContext } from "react";
+import type { SpectrumLine } from "./aggregate-segments";
+
+/** Every user-visible string `PerformanceSpectrum` renders. `{name}` placeholders fill. */
+export interface PerformanceSpectrumLabels {
+  /** Accessible name of the whole view. */
+  label: string;
+  /** `{from}`, `{to}` — a row's accessible name and default visible label. */
+  segment: string;
+  /** Appended to a selected row's accessible name. */
+  selected: string;
+  /** `{count}`, `{cases}`, `{median}`, `{p90}` — a row's parallel summary. */
+  rowSummary: string;
+  /** `{caseId}`, `{start}`, `{end}`, `{duration}`, `{quartile}` — one line, spoken. */
+  occurrence: string;
+  /** `{start}`, `{end}`, `{count}`, `{median}`, `{quartile}` — one aggregated bar, spoken. */
+  bin: string;
+  tooltipSegment: string;
+  tooltipStart: string;
+  tooltipEnd: string;
+  tooltipDuration: string;
+  tooltipQuartile: string;
+  tooltipCount: string;
+  tooltipMedian: string;
+  /** `{n}` — a quartile's short name. */
+  quartile: string;
+  quartileFastest: string;
+  quartileSlowest: string;
+  /** Heading of the colour key. */
+  legend: string;
+  /** Accessible name of the time-axis brush track. */
+  brush: string;
+  brushHint: string;
+  /** `{start}`, `{end}`, `{count}` — announced when a range is set. */
+  brushRange: string;
+  columnSegment: string;
+  columnCases: string;
+  columnMedian: string;
+  columnP90: string;
+  tableCaption: string;
+  loading: string;
+  empty: string;
+  emptyBody: string;
+}
+
+/** The shipped English labels. */
+export const PERFORMANCE_SPECTRUM_DEFAULT_LABELS: Readonly<PerformanceSpectrumLabels> =
+  Object.freeze({
+    label: "Performance spectrum",
+    segment: "{from} → {to}",
+    selected: "selected",
+    rowSummary: "{count} occurrences across {cases} cases, median {median}, 90th percentile {p90}",
+    occurrence: "Case {caseId}, {start} to {end}, took {duration}, {quartile}",
+    bin: "{start} to {end}: {count} cases entered, median {median}, {quartile}",
+    tooltipSegment: "Segment",
+    tooltipStart: "Start",
+    tooltipEnd: "End",
+    tooltipDuration: "Duration",
+    tooltipQuartile: "Quartile",
+    tooltipCount: "Cases entered",
+    tooltipMedian: "Median duration",
+    quartile: "Quartile {n}",
+    quartileFastest: "fastest",
+    quartileSlowest: "slowest",
+    legend: "Duration quartile, per segment",
+    brush: "Time range",
+    brushHint:
+      "Drag across the axis, or use Shift with the arrow keys, to pick a time range. Press Enter to filter to cases in the range, Escape to clear.",
+    brushRange: "{start} to {end}, {count} cases",
+    columnSegment: "Segment",
+    columnCases: "Cases",
+    columnMedian: "Median duration",
+    columnP90: "90th percentile duration",
+    tableCaption: "Performance spectrum — cases and duration per segment",
+    loading: "Loading segment occurrences…",
+    empty: "No segment occurrences",
+    emptyBody: "None of the chosen segments occur in this log.",
+  });
+
+/** What every spectrum row reads. */
+export interface PerformanceSpectrumContextValue {
+  labels: PerformanceSpectrumLabels;
+  mode: "lines" | "aggregated";
+  binSize: number;
+  domain: readonly [number, number];
+  ticks: readonly number[];
+  rowHeight: number;
+  /** The four quartile inks as `var(--…)` references, quartile 1 first. */
+  quartileColors: readonly string[];
+  formatInstant: (ms: number) => string;
+  formatDuration: (ms: number) => string;
+  quartileName: (quartile: number) => string;
+  onCaseSelect?: (caseId: string, occurrence: SpectrumLine) => void;
+}
+
+const PerformanceSpectrumContext = createContext<PerformanceSpectrumContextValue | null>(null);
+
+export const PerformanceSpectrumProvider = PerformanceSpectrumContext.Provider;
+
+/** Reads the spectrum context. Throws outside a `PerformanceSpectrum`. */
+export function usePerformanceSpectrum(): PerformanceSpectrumContextValue {
+  const value = useContext(PerformanceSpectrumContext);
+  if (!value) {
+    throw new Error("usePerformanceSpectrum must be used inside a PerformanceSpectrum");
+  }
+  return value;
+}