@mui/internal-benchmark 0.0.3-canary.5 → 0.0.3-canary.7

package/CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 2.0.8
 
 Test release
+dummy PR
 
 ## 2.0.7
 

package/DiscreteMetric.d.mts

@@ -0,0 +1,15 @@
+import { Metric } from "./Metric.mjs";
+import type { MetricConfig, MetricKind } from "./types.mjs";
+/**
+ * A discrete count of events or occurrences. Compared against a baseline as an exact integer
+ * (any change is significant — there is no noise band), and formatted as a whole number by default.
+ *
+ * ```ts
+ * const clicks = new DiscreteMetric({ name: 'button_clicks' });
+ * clicks.record(countClicks());
+ * ```
+ */
+export declare class DiscreteMetric extends Metric {
+  readonly kind: MetricKind;
+  constructor(config: MetricConfig | string);
+}

package/DiscreteMetric.mjs

@@ -0,0 +1,24 @@
+import { Metric } from "./Metric.mjs";
+/**
+ * A discrete count of events or occurrences. Compared against a baseline as an exact integer
+ * (any change is significant — there is no noise band), and formatted as a whole number by default.
+ *
+ * ```ts
+ * const clicks = new DiscreteMetric({ name: 'button_clicks' });
+ * clicks.record(countClicks());
+ * ```
+ */
+export class DiscreteMetric extends Metric {
+  kind = 'discrete';
+  constructor(config) {
+    const resolved = typeof config === 'string' ? {
+      name: config
+    } : config;
+    super({
+      ...resolved,
+      format: resolved.format ?? {
+        maximumFractionDigits: 0
+      }
+    });
+  }
+}

package/LICENSE

@@ -1,4 +1,4 @@
-The MIT License (MIT)
+MIT License
 
 Copyright (c) 2019 Material-UI SAS
 

package/Metric.d.mts

@@ -0,0 +1,24 @@
+import type { MetricConfig, MetricKind } from "./types.mjs";
+import "./taskMetaAugmentation.mjs";
+export interface MetricRecordOptions {
+  /** Sub-series label. Recorded under `${name}#${id}` in the report; omit for the base series. */
+  id?: string;
+}
+/**
+ * Base class for custom benchmark metrics. Use `ScalarMetric` or `DiscreteMetric`.
+ *
+ * Records are tied to the test that is running when `record()` is called (resolved via
+ * `getCurrentTest()`), so a single instance can be declared at module scope and reused across
+ * tests and loop iterations, inside or outside React.
+ */
+export declare abstract class Metric {
+  abstract readonly kind: MetricKind;
+  readonly name: string;
+  protected readonly config: MetricConfig;
+  constructor(config: MetricConfig | string);
+  /**
+   * Records a single measured value. Samples accumulate in browser memory and are aggregated
+   * once when the test finishes. Pass `options.id` to split into a labeled sub-series.
+   */
+  record(value: number, options?: MetricRecordOptions): void;
+}

package/Metric.mjs

@@ -0,0 +1,89 @@
+import { onTestFinished, TestRunner } from 'vitest';
+import { aggregateSamples } from "./stats.mjs";
+import { metricsGate } from "./metricsGate.mjs";
+// Import for TaskMeta augmentation side effect
+import "./taskMetaAugmentation.mjs";
+// Raw samples never cross the browser→runner boundary. They accumulate here per test (keyed by
+// the running task so a module-scoped metric shared across tests never mixes data) and are
+// aggregated into compact stats by an `onTestFinished` hook before being written to `task.meta`.
+const accumulators = new WeakMap();
+function flush(test, accumulator) {
+  const store = {};
+  for (const [name, entry] of accumulator) {
+    const series = {};
+    for (const [seriesId, samples] of entry.series) {
+      series[seriesId] = {
+        ...aggregateSamples(samples),
+        count: samples.length
+      };
+    }
+    store[name] = {
+      kind: entry.kind,
+      config: entry.config,
+      series
+    };
+  }
+  test.meta.benchmarkMetrics = store;
+}
+/**
+ * Base class for custom benchmark metrics. Use `ScalarMetric` or `DiscreteMetric`.
+ *
+ * Records are tied to the test that is running when `record()` is called (resolved via
+ * `getCurrentTest()`), so a single instance can be declared at module scope and reused across
+ * tests and loop iterations, inside or outside React.
+ */
+export class Metric {
+  constructor(config) {
+    this.config = typeof config === 'string' ? {
+      name: config
+    } : config;
+    this.name = this.config.name;
+    if (this.name.includes('#')) {
+      throw new Error(`Metric name "${this.name}" must not contain "#" — it is reserved as the sub-series separator.`);
+    }
+  }
+
+  /**
+   * Records a single measured value. Samples accumulate in browser memory and are aggregated
+   * once when the test finishes. Pass `options.id` to split into a labeled sub-series.
+   */
+  record(value, options) {
+    const test = TestRunner.getCurrentTest();
+    if (!test) {
+      throw new Error(`${this.constructor.name}.record() must be called inside a running Vitest test.`);
+    }
+
+    // The harness disables the gate during warmup iterations so custom metrics recorded inside a
+    // benchmark honor the same warmup exclusion as renders and `bench:paint`. Standalone `it()`
+    // loops never touch the gate, so they keep recording every value.
+    if (!metricsGate.isRecordingEnabled(test)) {
+      return;
+    }
+    let accumulator = accumulators.get(test);
+    if (!accumulator) {
+      const created = new Map();
+      accumulator = created;
+      accumulators.set(test, created);
+      onTestFinished(() => flush(test, created));
+    }
+    let entry = accumulator.get(this.name);
+    if (!entry) {
+      entry = {
+        owner: this,
+        kind: this.kind,
+        config: this.config,
+        series: new Map()
+      };
+      accumulator.set(this.name, entry);
+    } else if (entry.owner !== this) {
+      throw new Error(`Two metrics share the name "${this.name}". Metric names must be unique; reuse a single instance instead.`);
+    }
+    const seriesId = options?.id ?? '';
+    let samples = entry.series.get(seriesId);
+    if (!samples) {
+      samples = [];
+      entry.series.set(seriesId, samples);
+    }
+    samples.push(value);
+  }
+}

package/README.md

@@ -61,9 +61,44 @@ benchmark(
 );
 ```
 
+### Scoping which renders are measured
+
+By default a benchmark records every React render and paint, from the mount through the whole interaction. To measure only part of an interaction — or to exclude the mount — pause and resume recording from the interaction callback:
+
+```tsx
+benchmark(
+  'Combobox type',
+  () => <Combobox />,
+  async ({ pauseReactRecording, resumeReactRecording, waitForElementTiming }) => {
+    pauseReactRecording(); // stop recording the settling re-renders
+    await openMenu();
+    resumeReactRecording(); // measure only what follows
+    await type('hello');
+    await waitForElementTiming('results');
+  },
+);
+```
+
+`pauseReactRecording()` / `resumeReactRecording()` toggle only the harness's React render and `bench:paint` recording — your own custom metrics keep recording. They are a strict pair: pausing while already paused, or resuming while already active, throws (this catches unbalanced calls early).
+
+To exclude the mount itself, start paused with the `reactRecordingPaused` option and resume at the point you care about — the mount is captured before the interaction callback runs, so pausing inside the callback can't drop it:
+
+```tsx
+benchmark(
+  'Combobox type',
+  () => <Combobox />,
+  async ({ resumeReactRecording }) => {
+    await openMenu(); // mount + open: not recorded
+    resumeReactRecording();
+    await type('hello'); // only these renders/paint recorded
+  },
+  { reactRecordingPaused: true },
+);
+```
+
 ### Paint metrics
 
-By default, every benchmark captures a `paint:default` metric — the time from iteration start until the browser actually paints the rendered output. This uses the [Element Timing API](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceElementTiming) via an invisible sentinel element that the benchmark harness renders automatically.
+By default, every benchmark captures a `bench:paint` metric — the time from iteration start until the browser actually paints the rendered output. This uses the [Element Timing API](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceElementTiming) via an invisible sentinel element that the benchmark harness renders automatically. The harness owns the `bench:` namespace, so avoid it for your own metric names.
 
 You can track additional paint metrics by placing `<ElementTiming>` markers and awaiting them in an interaction callback. The component renders an invisible `<span>` that fires in the same paint frame as its surrounding content.
 
@@ -88,16 +123,79 @@ benchmark(
 );
 ```
 
-This produces a `paint:my-component` metric alongside the automatic `paint:default`.
+This produces a `bench:paint#my-component` sub-series alongside the automatic `bench:paint`.
 
 `waitForElementTiming` accepts an optional `timeout` in milliseconds (default: 5000). Pass `0` or `Infinity` to rely on the test timeout instead.
 
+### Custom metrics
+
+Record your own measurements — a timing, a count, anything measured inside or outside React — from a plain `it()` loop or from inside a `benchmark()`. There are two primitives:
+
+- `ScalarMetric` — a continuous value (timings, sizes). Aggregated as mean ± standard deviation with IQR outlier removal, and compared against a baseline with a relative noise band.
+- `DiscreteMetric` — a count of events. Compared as an exact integer (any change is significant) and formatted as a whole number.
+
+Both record values with `record(value)`. `ScalarMetric` additionally offers `time()`/`timeEnd()` — a `console.time`-style shortcut that records the elapsed milliseconds for you.
+
+```tsx
+import { it } from 'vitest';
+import { ScalarMetric, DiscreteMetric } from '@mui/internal-benchmark';
+
+const duration = new ScalarMetric({
+  name: 'work_duration',
+  format: { style: 'unit', unit: 'millisecond' }, // Intl.NumberFormatOptions
+  alarm: { direction: 'lowerIsBetter', warn: 0.1, error: 0.25 }, // warn >10%, error >25%
+});
+
+const clicks = new DiscreteMetric({ name: 'button_clicks' });
+
+it('measures work', () => {
+  for (let i = 0; i < 100; i += 1) {
+    duration.time();
+    runWork();
+    duration.timeEnd(); // records the elapsed milliseconds
+
+    clicks.record(countClicks()); // a discrete count per run
+  }
+});
+```
+
+A metric is declared once (typically at module scope) and reused across tests and iterations. `record()` attaches the value to whichever test is running, so the same instance works in any `it()`.
+
+You can also `record()` or `time()` from inside a `benchmark()` render function or interaction callback. Values recorded during warmup iterations are excluded automatically, just like renders and `bench:paint`, so a metric recorded once per iteration yields exactly `runs` samples.
+
+#### Metric configuration
+
+- `name` — the metric's report key (**required**).
+- `format` — an [`Intl.NumberFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/API/Intl/NumberFormat/NumberFormat) object used to display the value.
+- `alarm` — opts the metric into regression flagging. Omit it and the metric is informational (its diff is shown but never flagged). Holds:
+  - `direction` — `'lowerIsBetter'` (default) or `'higherIsBetter'`.
+  - `warn` — softer band; a regression past it is flagged as a warning.
+  - `error` — harder band; a regression past it is flagged as an error. Defaults to the dashboard's global noise band only when both `warn` and `error` are omitted; with only `warn` set there is no error band (warning-only).
+  - Bands are relative fractions for scalar metrics (`0.1` = 10%) and absolute count deltas for discrete metrics (`1`, `2`). Either band is optional.
+
+Alarms are evaluated against the baseline when the PR comment is generated, not during the local `vitest run` — a regression never fails the test suite locally. In the PR comment, `error`-band regressions surface as failures and `warn`-band regressions as warnings.
+
+#### Sub-series
+
+Pass `record(value, { id })` to split one metric into labeled sub-series, reported as `name#id`. For `ScalarMetric.time()`/`timeEnd()`, pass a label that maps to the same `id`:
+
+```tsx
+const phase = new ScalarMetric({ name: 'render_phase' });
+
+phase.time('header');
+renderHeader();
+phase.timeEnd('header'); // -> render_phase#header
+```
+
+Custom metrics are aggregated in the browser and only the resulting stats cross to the runner, so the amount of data is independent of how many values you record.
+
 ### Options
 
 ```tsx
 benchmark('name', renderFn, interaction, {
   runs: 20, // measurement iterations (default: 20)
   warmupRuns: 10, // warmup iterations before measuring (default: 10)
+  reactRecordingPaused: false, // start with React render/paint recording paused (default: false)
   afterEach: () => {
     /* cleanup between iterations */
   },
@@ -148,5 +246,7 @@ The feature is opt-in — without `BENCHMARK_BASELINE_PATH` (or the `baselinePat
 
 - `benchmark` — define a benchmark test case
 - `ElementTiming` — invisible marker component for paint timing (renders a `<span>` tracked by the Element Timing API)
+- `ScalarMetric` — record a continuous custom measurement (with a `console.time`-style timing helper)
+- `DiscreteMetric` — record a discrete custom count
 - `createBenchmarkVitestConfig` — create a Vitest config with browser benchmarking defaults
 - `BenchmarkReporter` — Vitest reporter that collects and outputs benchmark results

package/ScalarMetric.d.mts

@@ -0,0 +1,23 @@
+import { Metric } from "./Metric.mjs";
+import type { MetricKind } from "./types.mjs";
+/**
+ * A continuous measurement (timings, sizes, …). Samples are aggregated with mean ± standard
+ * deviation and IQR outlier removal, and compared against a baseline with a relative noise band.
+ *
+ * It offers a `console.time`-style timing helper:
+ *
+ * ```ts
+ * const metric = new ScalarMetric({ name: 'render', format: { style: 'unit', unit: 'millisecond' } });
+ * metric.time();
+ * doWork();
+ * metric.timeEnd(); // records the elapsed milliseconds
+ * ```
+ */
+export declare class ScalarMetric extends Metric {
+  readonly kind: MetricKind;
+  private readonly pending;
+  /** Starts a timer. Pass a `label` to time a sub-series; it maps to `record`'s `id`. */
+  time(label?: string): void;
+  /** Stops the timer started by `time(label)` and records the elapsed milliseconds. */
+  timeEnd(label?: string): void;
+}

package/ScalarMetric.mjs

@@ -0,0 +1,42 @@
+import { Metric } from "./Metric.mjs";
+/**
+ * A continuous measurement (timings, sizes, …). Samples are aggregated with mean ± standard
+ * deviation and IQR outlier removal, and compared against a baseline with a relative noise band.
+ *
+ * It offers a `console.time`-style timing helper:
+ *
+ * ```ts
+ * const metric = new ScalarMetric({ name: 'render', format: { style: 'unit', unit: 'millisecond' } });
+ * metric.time();
+ * doWork();
+ * metric.timeEnd(); // records the elapsed milliseconds
+ * ```
+ */
+export class ScalarMetric extends Metric {
+  kind = 'scalar';
+  pending = new Map();
+
+  /** Starts a timer. Pass a `label` to time a sub-series; it maps to `record`'s `id`. */
+  time(label) {
+    const key = label ?? '';
+    if (this.pending.has(key)) {
+      throw new Error(`${this.name}.time(${label ? `"${label}"` : ''}) was called while a timer is already running for that label.`);
+    }
+    this.pending.set(key, performance.now());
+  }
+
+  /** Stops the timer started by `time(label)` and records the elapsed milliseconds. */
+  timeEnd(label) {
+    // Capture the end time first so the map lookup/delete below isn't part of the measurement.
+    const end = performance.now();
+    const key = label ?? '';
+    const start = this.pending.get(key);
+    if (start === undefined) {
+      throw new Error(`${this.name}.timeEnd(${label ? `"${label}"` : ''}) was called without a matching time().`);
+    }
+    this.pending.delete(key);
+    this.record(end - start, label !== undefined ? {
+      id: label
+    } : undefined);
+  }
+}

package/ciReport.d.mts

@@ -58,6 +58,21 @@ declare const benchmarkReportSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
     outliers: z.ZodNumber;
   }, z.core.$strip>>;
 }, z.core.$strip>>;
+declare const metricDefinitionSchema: z.ZodObject<{
+  kind: z.ZodEnum<{
+    discrete: "discrete";
+    scalar: "scalar";
+  }>;
+  format: z.ZodOptional<z.ZodCustom<Intl.NumberFormatOptions, Intl.NumberFormatOptions>>;
+  alarm: z.ZodOptional<z.ZodObject<{
+    direction: z.ZodOptional<z.ZodEnum<{
+      higherIsBetter: "higherIsBetter";
+      lowerIsBetter: "lowerIsBetter";
+    }>>;
+    warn: z.ZodOptional<z.ZodNumber>;
+    error: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
 declare const benchmarkBaseUploadSchema: z.ZodObject<{
   version: z.ZodLiteral<number>;
   timestamp: z.ZodNumber;
@@ -67,6 +82,21 @@ declare const benchmarkBaseUploadSchema: z.ZodObject<{
   prNumber: z.ZodOptional<z.ZodNumber>;
   branch: z.ZodString;
   report: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+  metricDefinitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+    kind: z.ZodEnum<{
+      discrete: "discrete";
+      scalar: "scalar";
+    }>;
+    format: z.ZodOptional<z.ZodCustom<Intl.NumberFormatOptions, Intl.NumberFormatOptions>>;
+    alarm: z.ZodOptional<z.ZodObject<{
+      direction: z.ZodOptional<z.ZodEnum<{
+        higherIsBetter: "higherIsBetter";
+        lowerIsBetter: "lowerIsBetter";
+      }>>;
+      warn: z.ZodOptional<z.ZodNumber>;
+      error: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>>;
 }, z.core.$strip>;
 export declare const benchmarkUploadSchema: z.ZodObject<{
   version: z.ZodLiteral<number>;
@@ -77,6 +107,21 @@ export declare const benchmarkUploadSchema: z.ZodObject<{
   prNumber: z.ZodOptional<z.ZodNumber>;
   branch: z.ZodString;
   report: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+  metricDefinitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+    kind: z.ZodEnum<{
+      discrete: "discrete";
+      scalar: "scalar";
+    }>;
+    format: z.ZodOptional<z.ZodCustom<Intl.NumberFormatOptions, Intl.NumberFormatOptions>>;
+    alarm: z.ZodOptional<z.ZodObject<{
+      direction: z.ZodOptional<z.ZodEnum<{
+        higherIsBetter: "higherIsBetter";
+        lowerIsBetter: "lowerIsBetter";
+      }>>;
+      warn: z.ZodOptional<z.ZodNumber>;
+      error: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>>;
   base: z.ZodOptional<z.ZodObject<{
     version: z.ZodLiteral<number>;
     timestamp: z.ZodNumber;
@@ -86,10 +131,26 @@ export declare const benchmarkUploadSchema: z.ZodObject<{
     prNumber: z.ZodOptional<z.ZodNumber>;
     branch: z.ZodString;
     report: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    metricDefinitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+      kind: z.ZodEnum<{
+        discrete: "discrete";
+        scalar: "scalar";
+      }>;
+      format: z.ZodOptional<z.ZodCustom<Intl.NumberFormatOptions, Intl.NumberFormatOptions>>;
+      alarm: z.ZodOptional<z.ZodObject<{
+        direction: z.ZodOptional<z.ZodEnum<{
+          higherIsBetter: "higherIsBetter";
+          lowerIsBetter: "lowerIsBetter";
+        }>>;
+        warn: z.ZodOptional<z.ZodNumber>;
+        error: z.ZodOptional<z.ZodNumber>;
+      }, z.core.$strip>>;
+    }, z.core.$strip>>>;
   }, z.core.$strip>>;
 }, z.core.$strip>;
 export type RenderStats = z.infer<typeof renderStatsSchema>;
 export type MetricStats = z.infer<typeof metricStatsSchema>;
+export type BenchmarkMetricDefinition = z.infer<typeof metricDefinitionSchema>;
 export type BenchmarkReportEntry = z.infer<typeof benchmarkReportEntrySchema>;
 export type BenchmarkReport = z.infer<typeof benchmarkReportSchema>;
 export type BenchmarkBaseUpload = z.infer<typeof benchmarkBaseUploadSchema>;

package/ciReport.mjs

@@ -45,7 +45,20 @@ const benchmarkReportEntrySchema = z.object({
   metrics: z.record(z.string(), metricStatsSchema)
 });
 const benchmarkReportSchema = z.record(z.string(), benchmarkReportEntrySchema);
-const benchmarkBaseUploadSchema = ciReportUploadSchema('benchmark', 1, benchmarkReportSchema);
+const metricDefinitionSchema = z.object({
+  kind: z.enum(['scalar', 'discrete']),
+  format: z.custom().optional(),
+  alarm: z.object({
+    direction: z.enum(['lowerIsBetter', 'higherIsBetter']).optional(),
+    warn: z.number().min(0).optional(),
+    error: z.number().min(0).optional()
+  }).optional()
+});
+const benchmarkBaseUploadSchema = ciReportUploadSchema('benchmark', 1, benchmarkReportSchema).extend({
+  // Per-metric config for custom metrics, hoisted to the top level (keyed by metric name) so
+  // it is stored once rather than duplicated in every report entry. Optional and additive.
+  metricDefinitions: z.record(z.string(), metricDefinitionSchema).optional()
+});
 export const benchmarkUploadSchema = benchmarkBaseUploadSchema.extend({
   base: benchmarkBaseUploadSchema.optional()
 });

package/index.d.mts

@@ -1,8 +1,13 @@
 import * as React from 'react';
 import type { InteractionContext } from "./types.mjs";
+import { ScalarMetric } from "./ScalarMetric.mjs";
 import "./taskMetaAugmentation.mjs";
-export type { RenderEvent, BenchmarkMetric, IterationData, InteractionContext } from "./types.mjs";
+export type { RenderEvent, IterationData, InteractionContext } from "./types.mjs";
+export type { MetricKind, MetricDirection, MetricAlarm, MetricConfig, MetricDefinition } from "./types.mjs";
 export { ElementTiming } from "./ElementTiming.mjs";
+export { Metric, type MetricRecordOptions } from "./Metric.mjs";
+export { ScalarMetric };
+export { DiscreteMetric } from "./DiscreteMetric.mjs";
 declare global {
   interface Window {
     gc?: () => void;
@@ -12,5 +17,11 @@ interface BenchmarkOptions {
   runs?: number;
   warmupRuns?: number;
   afterEach?: () => Promise<void> | void;
+  /**
+   * Start each iteration with React render/paint recording paused. The interaction callback then
+   * calls `resumeReactRecording()` at the point it cares about — useful to exclude the mount and
+   * measure only the renders/paint of a later interaction. Defaults to `false` (mount recorded).
+   */
+  reactRecordingPaused?: boolean;
 }
 export declare function benchmark(name: string, renderFn: () => React.ReactElement, interactionOrOptions?: ((ctx: InteractionContext) => Promise<void> | void) | BenchmarkOptions, maybeOptions?: BenchmarkOptions): void;

package/index.mjs

@@ -11,22 +11,34 @@ import { expect, it } from 'vitest';
 import * as ReactDOMClient from 'react-dom/client'; // aliased to react-dom/profiling by Vite
 import * as ReactDOM from 'react-dom';
 import { ElementTiming } from "./ElementTiming.mjs";
+import { ScalarMetric } from "./ScalarMetric.mjs";
+import { metricsGate } from "./metricsGate.mjs";
+import { createReactRecordingControls } from "./reactRecording.mjs";
 // Import for TaskMeta augmentation side effect
 import "./taskMetaAugmentation.mjs";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 export { ElementTiming } from "./ElementTiming.mjs";
+export { Metric } from "./Metric.mjs";
+export { ScalarMetric };
+export { DiscreteMetric } from "./DiscreteMetric.mjs";
 function BenchProfiler({
   captures,
+  recording,
   children
 }) {
   const onRender = React.useCallback((id, phase, actualDuration, _baseDuration, startTime) => {
-    captures.push({
-      id,
-      phase,
-      actualDuration,
-      startTime
-    });
-  }, [captures]);
+    // Skip renders captured while React recording is paused (e.g. the mount when the benchmark
+    // starts paused, or a span the interaction explicitly excludes).
+    if (recording.active) {
+      captures.push({
+        id,
+        phase,
+        actualDuration,
+        startTime
+      });
+      recording.markRendered();
+    }
+  }, [captures, recording]);
   return /*#__PURE__*/_jsxs(React.Profiler, {
     id: "bench",
     onRender: onRender,
@@ -64,14 +76,40 @@ export function benchmark(name, renderFn, interactionOrOptions, maybeOptions) {
     const warmupRuns = options?.warmupRuns ?? 10;
     const totalRuns = warmupRuns + runs;
     const iterations = [];
+
+    // Paint timings are recorded as one harness-owned `bench:paint` metric: the default sentinel
+    // is the base series (`bench:paint`) and named `elementtiming` markers are sub-series
+    // (`bench:paint#grid-header`, …), all sharing a single definition. A default alarm keeps a
+    // >20% paint regression flagged, matching the previous behavior.
+    const paint = new ScalarMetric({
+      name: 'bench:paint',
+      format: {
+        style: 'unit',
+        unit: 'millisecond',
+        maximumFractionDigits: 2
+      },
+      alarm: {
+        error: 0.2
+      }
+    });
     const hasElementTiming = supportsElementTiming();
     if (typeof window.gc !== 'function') {
       console.warn('window.gc is not available. Run with --js-flags=--expose-gc for consistent GC between iterations.');
     }
     let renderError = null;
+    // Set if any iteration had a recording window that was active yet captured no renders.
+    let sawEmptyActiveWindow = false;
     for (let i = 0; i < totalRuns; i += 1) {
       const isWarmup = i < warmupRuns;
 
+      // Custom metrics recorded inside the benchmark honor warmup exclusion through the gate, the
+      // same way renders and `bench:paint` are excluded during warmup.
+      metricsGate.setRecordingEnabled(task, !isWarmup);
+
+      // Per-iteration switch for the harness's React render/paint recording. Starts paused when
+      // `reactRecordingPaused` is set; the interaction callback drives it from there.
+      const recording = createReactRecordingControls(!(options?.reactRecordingPaused ?? false));
+
       // Drain event loop from previous unmount, then double GC for thorough cleanup
       // eslint-disable-next-line no-await-in-loop
       await settle();
@@ -136,6 +174,7 @@ export function benchmark(name, renderFn, interactionOrOptions, maybeOptions) {
       ReactDOM.flushSync(() => {
         root.render(/*#__PURE__*/_jsx(BenchProfiler, {
           captures: captures,
+          recording: recording,
           children: renderFn()
         }));
       });
@@ -148,24 +187,39 @@ export function benchmark(name, renderFn, interactionOrOptions, maybeOptions) {
       if (interaction) {
         // eslint-disable-next-line no-await-in-loop
         await interaction({
-          waitForElementTiming
+          waitForElementTiming,
+          pauseReactRecording: recording.pauseReactRecording,
+          resumeReactRecording: recording.resumeReactRecording
         });
       }
 
       // Wait for the bench sentinel paint entry (relies on test timeout)
       // eslint-disable-next-line no-await-in-loop
       await waitForElementTiming('default', 0);
+
+      // Close the final window and remember if any active window measured no renders.
+      recording.finalizeWindow();
+      if (recording.hadEmptyActiveWindow) {
+        sawEmptyActiveWindow = true;
+      }
       elementObserver?.disconnect();
       root.unmount();
       container.remove();
       if (!isWarmup) {
-        const metrics = elementEntries.map(entry => ({
-          name: `paint:${entry.identifier}`,
-          value: entry.renderTime - iterationStart
-        }));
+        for (const entry of elementEntries) {
+          // Skip paints that happened while recording was paused. Attribute by the paint's
+          // `renderTime`, not by when the observer callback fired (which can lag the paint).
+          if (!recording.activeAt(entry.renderTime)) {
+            continue;
+          }
+          // The default sentinel is the base series; named markers become sub-series.
+          const id = entry.identifier === 'default' ? undefined : entry.identifier;
+          paint.record(entry.renderTime - iterationStart, id !== undefined ? {
+            id
+          } : undefined);
+        }
         iterations.push({
-          renders: captures,
-          metrics
+          renders: captures
         });
       }
       if (options?.afterEach) {
@@ -179,8 +233,9 @@ export function benchmark(name, renderFn, interactionOrOptions, maybeOptions) {
       throw renderError;
     }
 
-    // Validate that at least one render was recorded
-    expect(iterations[0].renders.length, 'No renders were recorded during benchmark').toBeGreaterThan(0);
+    // Every active recording window must capture at least one render. Windows where recording was
+    // never running (e.g. a fully-paused, metric-only benchmark) are not checked.
+    expect(sawEmptyActiveWindow, 'React recording was active but captured no renders. If you only measure imperative DOM ' + 'updates or custom metrics, keep recording paused (reactRecordingPaused) instead of resuming.').toBe(false);
 
     // Validate all iterations produced the same render events (count + order).
     // This runs after meta is set so the reporter can still display results on failure.

package/metricsGate.d.mts

@@ -0,0 +1,7 @@
+import type { RunnerTestCase } from 'vitest';
+export declare const metricsGate: {
+  /** Whether custom-metric recording is currently enabled for `test`. Defaults to `true`. */
+  isRecordingEnabled(test: RunnerTestCase): boolean;
+  /** Enable or disable custom-metric recording for `test`. */
+  setRecordingEnabled(test: RunnerTestCase, enabled: boolean): void;
+};

package/metricsGate.mjs

@@ -0,0 +1,21 @@
+// Internal — not exported from the package, not user-facing. The `benchmark()` harness toggles
+// recording per test (off during warmup iterations) and `Metric.record()` consults it, so custom
+// metrics recorded inside a benchmark honor the same warmup exclusion as renders and `bench:paint`.
+//
+// Storage tracks the *disabled* tests so absence means enabled: a test with no entry — e.g. a
+// standalone `it()` loop that never goes through the harness — records normally by default.
+const disabled = new WeakSet();
+export const metricsGate = {
+  /** Whether custom-metric recording is currently enabled for `test`. Defaults to `true`. */
+  isRecordingEnabled(test) {
+    return !disabled.has(test);
+  },
+  /** Enable or disable custom-metric recording for `test`. */
+  setRecordingEnabled(test, enabled) {
+    if (enabled) {
+      disabled.delete(test);
+    } else {
+      disabled.add(test);
+    }
+  }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-benchmark",
-  "version": "0.0.3-canary.5",
+  "version": "0.0.3-canary.7",
   "author": "MUI Team",
   "description": "Benchmark utilities for MUI projects. Internal package.",
   "repository": {
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.29.2",
-    "@vitejs/plugin-react": "^6.0.1",
+    "@vitejs/plugin-react": "^6.0.2",
     "env-ci": "^11.2.0",
     "execa": "^9.6.1",
     "zod": "^4.4.3"
@@ -68,5 +68,5 @@
       }
     }
   },
-  "gitSha": "8b0badde3f4948db33af81129bf69b51a619aa3a"
+  "gitSha": "0763444eee05140fa86809f0a4330c1550c9c3c6"
 }

package/reactRecording.d.mts

@@ -0,0 +1,30 @@
+export interface ReactRecordingControls {
+  /** Whether React render/paint recording is active right now — the synchronous gate for renders. */
+  readonly active: boolean;
+  /** Whether any active recording window closed without capturing a render. */
+  readonly hadEmptyActiveWindow: boolean;
+  /**
+   * Whether recording was active at `time` (a `performance.now()` timestamp). Paint entries are
+   * observed asynchronously, so they are attributed by their `renderTime` rather than by the
+   * recording state at the moment the observer callback happens to fire.
+   */
+  activeAt(time: number): boolean;
+  /** Note that a render was captured in the current window. Called by the harness from `onRender`. */
+  markRendered(): void;
+  /** Close the final window at the end of the iteration (validates it if recording is still active). */
+  finalizeWindow(): void;
+  /** Pause React render/paint recording. Throws if recording is already paused. */
+  pauseReactRecording(): void;
+  /** Resume React render/paint recording. Throws if recording is already active. */
+  resumeReactRecording(): void;
+}
+/**
+ * Creates the per-iteration switch that turns the harness's React render/paint recording on and
+ * off. The interaction callback drives it via `pauseReactRecording`/`resumeReactRecording`; the
+ * strict state machine (each throws when called in the wrong state) catches unbalanced pairs early.
+ *
+ * It also tracks whether each *active* window captured at least one render, so the harness can flag
+ * a window that was recording but measured nothing — while leaving fully-paused (metric-only)
+ * benchmarks alone.
+ */
+export declare function createReactRecordingControls(initiallyActive: boolean): ReactRecordingControls;

package/reactRecording.mjs

@@ -0,0 +1,76 @@
+/**
+ * Creates the per-iteration switch that turns the harness's React render/paint recording on and
+ * off. The interaction callback drives it via `pauseReactRecording`/`resumeReactRecording`; the
+ * strict state machine (each throws when called in the wrong state) catches unbalanced pairs early.
+ *
+ * It also tracks whether each *active* window captured at least one render, so the harness can flag
+ * a window that was recording but measured nothing — while leaving fully-paused (metric-only)
+ * benchmarks alone.
+ */
+export function createReactRecordingControls(initiallyActive) {
+  let active = initiallyActive;
+  let currentWindowHasRender = false;
+  let emptyActiveWindow = false;
+  // Transitions in chronological order. The implicit state before the first toggle is
+  // `initiallyActive`; `activeAt` replays this to attribute a paint to its render time.
+  const transitions = [];
+
+  // Flag the window being closed if it was recording yet captured nothing.
+  function closeWindowIfActive() {
+    if (active && !currentWindowHasRender) {
+      emptyActiveWindow = true;
+    }
+  }
+  return {
+    get active() {
+      return active;
+    },
+    get hadEmptyActiveWindow() {
+      return emptyActiveWindow;
+    },
+    activeAt(time) {
+      let result = initiallyActive;
+      for (const transition of transitions) {
+        if (transition.time > time) {
+          break;
+        }
+        result = transition.active;
+      }
+      return result;
+    },
+    markRendered() {
+      currentWindowHasRender = true;
+    },
+    finalizeWindow() {
+      closeWindowIfActive();
+    },
+    pauseReactRecording() {
+      // Stamp first — before the guard and bookkeeping — so the closing window ends as early as
+      // possible and excludes pause's own overhead. In the throw path it is simply discarded.
+      const now = performance.now();
+      if (!active) {
+        throw new Error('pauseReactRecording() called but React recording is already paused.');
+      }
+      closeWindowIfActive();
+      active = false;
+      transitions.push({
+        time: now,
+        active: false
+      });
+    },
+    resumeReactRecording() {
+      if (active) {
+        throw new Error('resumeReactRecording() called but React recording is already active.');
+      }
+      active = true;
+      currentWindowHasRender = false;
+      // Stamp last — after the bookkeeping — so the new window starts as late as possible and
+      // excludes resume's own overhead.
+      const now = performance.now();
+      transitions.push({
+        time: now,
+        active: true
+      });
+    }
+  };
+}

package/reporter.d.mts

@@ -10,11 +10,13 @@ export interface BenchmarkReporterOptions {
 }
 declare class BenchmarkReporter implements Reporter {
   private benchmarks;
+  private metricDefinitions;
   private outputPath;
   private upload;
   private baselinePath;
   private hasFailures;
   constructor(options?: BenchmarkReporterOptions);
+  onTestRunStart(): void;
   onTestCaseResult(testCase: TestCase): void;
   onTestRunEnd(): Promise<void>;
 }

package/reporter.mjs

@@ -1,46 +1,33 @@
 import * as path from 'node:path';
 import * as fs from 'node:fs/promises';
 import { benchmarkUploadSchema, getCiMetadata } from "./ciReport.mjs";
-import { calculateMean, calculateStdDev, quantile, isOutlier } from "./stats.mjs";
+import { calculateMean, aggregateSamples } from "./stats.mjs";
 import { dim, red, green, yellow, cyan, printTable, fileUrl } from "./format.mjs";
 import { uploadCiReport } from "./upload.mjs";
 import { syncPrComment } from "./syncPrComment.mjs";
 // Import for TaskMeta augmentation side effect
 import "./taskMetaAugmentation.mjs";
-const byNumeric = (a, b) => a - b;
 function getEventKey(event) {
   return `${event.id}:${event.phase}`;
 }
-function aggregateMetrics(iterations) {
-  // Collect all metric names across iterations
-  const metricValues = new Map();
-  for (const iteration of iterations) {
-    for (const metric of iteration.metrics) {
-      let values = metricValues.get(metric.name);
-      if (!values) {
-        values = [];
-        metricValues.set(metric.name, values);
-      }
-      values.push(metric.value);
-    }
+
+/** Order-insensitive deep equality, treating a missing key and an `undefined` value as equal. */
+function deepEqual(first, second) {
+  if (first === second) {
+    return true;
   }
-  const result = {};
-  for (const [name, values] of metricValues) {
-    // Apply IQR filtering
-    const sorted = [...values].sort(byNumeric);
-    const q1 = quantile(sorted, 0.25);
-    const q3 = quantile(sorted, 0.75);
-    const filtered = values.filter(d => !isOutlier(d, q1, q3));
-    const used = filtered.length > 0 ? filtered : values;
-    const mean = calculateMean(used);
-    const stdDev = calculateStdDev(used, mean);
-    result[name] = {
-      mean,
-      stdDev,
-      outliers: values.length - used.length
-    };
+  if (typeof first !== 'object' || first === null || typeof second !== 'object' || second === null) {
+    return false;
   }
-  return result;
+  const firstRecord = first;
+  const secondRecord = second;
+  const keys = new Set([...Object.keys(firstRecord), ...Object.keys(secondRecord)]);
+  for (const key of keys) {
+    if (!deepEqual(firstRecord[key], secondRecord[key])) {
+      return false;
+    }
+  }
+  return true;
 }
 function generateReportFromIterations(iterations) {
   if (iterations.length === 0) {
@@ -69,13 +56,11 @@ function generateReportFromIterations(iterations) {
   const renderStats = [];
   for (let index = 0; index < expectedLength; index += 1) {
     const durations = iterations.map(iteration => iteration.renders[index].actualDuration);
-    const sorted = [...durations].sort(byNumeric);
-    const q1 = quantile(sorted, 0.25);
-    const q3 = quantile(sorted, 0.75);
-    const filtered = durations.filter(d => !isOutlier(d, q1, q3));
-    const used = filtered.length > 0 ? filtered : durations;
-    const iqrMean = calculateMean(used);
-    const iqrStdDev = calculateStdDev(used, iqrMean);
+    const {
+      mean: iqrMean,
+      stdDev: iqrStdDev,
+      outliers
+    } = aggregateSamples(durations);
     const coefficientOfVariation = iqrMean > 0 ? iqrStdDev / iqrMean : 0;
     if (iqrMean > 1 && coefficientOfVariation > 0.1) {
       const event = firstIteration.renders[index];
@@ -85,7 +70,7 @@ function generateReportFromIterations(iterations) {
       event: firstIteration.renders[index],
       iqrMean,
       iqrStdDev,
-      outliers: durations.length - used.length
+      outliers
     });
   }
 
@@ -119,8 +104,8 @@ function generateReportFromIterations(iterations) {
     totalDuration += iqrMean;
   }
 
-  // Aggregate metrics
-  const metrics = aggregateMetrics(iterations);
+  // Custom + paint metrics are merged separately from `task.meta.benchmarkMetrics`.
+  const metrics = {};
   return {
     iterations: iterationCount,
     totalDuration,
@@ -167,21 +152,71 @@ function printDurationMatrix(name, report, footer) {
     width: 4
   }], rows, footer, name);
 }
-function printMetricsTable(name, metrics, iterationCount) {
+
+/** Strips a `#sub-series` suffix to recover the metric name used to look up its definition. */
+function baseMetricName(key) {
+  const hashIndex = key.indexOf('#');
+  return hashIndex === -1 ? key : key.slice(0, hashIndex);
+}
+function formatMetricValue(value, definition) {
+  if (definition?.format) {
+    return new Intl.NumberFormat(undefined, definition.format).format(value);
+  }
+  return value.toFixed(2);
+}
+
+/**
+ * Merges aggregated custom metrics (already stats, not raw samples) into a report entry, keyed
+ * `name` or `name#id` for sub-series, and collects each metric's config into the shared
+ * top-level definitions. For a metric-only test, derives the iteration count from the samples.
+ */
+function mergeCustomMetrics(report, customMetrics, definitions) {
+  let maxCount = 0;
+  for (const [metricName, metric] of Object.entries(customMetrics)) {
+    for (const [seriesId, stats] of Object.entries(metric.series)) {
+      const key = seriesId === '' ? metricName : `${metricName}#${seriesId}`;
+      report.metrics[key] = {
+        mean: stats.mean,
+        stdDev: stats.stdDev,
+        outliers: stats.outliers
+      };
+      maxCount = Math.max(maxCount, stats.count);
+    }
+    const definition = {
+      kind: metric.kind,
+      format: metric.config.format,
+      alarm: metric.config.alarm
+    };
+    // A metric name maps to one definition. Reusing it across benchmarks is fine when the config
+    // matches (e.g. the harness `bench:paint`), but conflicting config would silently apply
+    // last-write-wins to every entry — reject it instead.
+    const existing = definitions[metricName];
+    if (existing && !deepEqual(existing, definition)) {
+      throw new Error(`Benchmark metric "${metricName}" is defined with conflicting configuration across ` + `benchmarks. A metric name must map to a single kind, format, and alarm.`);
+    }
+    definitions[metricName] = definition;
+  }
+  if (report.iterations === 0) {
+    report.iterations = maxCount;
+  }
+}
+function printMetricsTable(name, metrics, iterationCount, definitions) {
   const entries = Object.entries(metrics);
   if (entries.length === 0) {
     return;
   }
   const rows = entries.map(([metricName, stats]) => {
-    const iqrStr = `${stats.mean.toFixed(2)}±${stats.stdDev.toFixed(2)}`;
+    const definition = definitions[baseMetricName(metricName)];
+    const iqrStr = `${formatMetricValue(stats.mean, definition)}±${formatMetricValue(stats.stdDev, definition)}`;
     const cv = stats.mean > 0 ? stats.stdDev / stats.mean * 100 : 0;
-    return [metricName.slice(0, LABEL_WIDTH).padStart(LABEL_WIDTH), cyan(iqrStr.padStart(STAT_WIDTH)), colorCV(cv), stats.outliers > 0 ? yellow(String(stats.outliers).padStart(4)) : dim('0'.padStart(4))];
+    const label = definition?.alarm ? `${metricName} ⚠` : metricName;
+    return [label.slice(0, LABEL_WIDTH).padStart(LABEL_WIDTH), cyan(iqrStr.padStart(STAT_WIDTH)), colorCV(cv), stats.outliers > 0 ? yellow(String(stats.outliers).padStart(4)) : dim('0'.padStart(4))];
   });
   printTable([{
     header: 'Metric',
     width: LABEL_WIDTH
   }, {
-    header: 'Mean±σ (ms)',
+    header: 'Mean±σ',
     width: STAT_WIDTH
   }, {
     header: 'Var%',
@@ -204,28 +239,47 @@ async function loadBaselineReport(baselinePath) {
 }
 class BenchmarkReporter {
   benchmarks = {};
+  metricDefinitions = {};
   hasFailures = false;
   constructor(options) {
     this.outputPath = options?.outputPath ?? process.env.BENCHMARK_OUTPUT_PATH ?? path.resolve(process.cwd(), 'benchmarks', 'results.json');
     this.upload = options?.upload ?? process.env.BENCHMARK_UPLOAD === 'true';
     this.baselinePath = options?.baselinePath ?? process.env.BENCHMARK_BASELINE_PATH;
   }
+
+  // Reset accumulated state at the start of every run so watch-mode re-runs start clean (the
+  // reporter instance is reused across runs). Otherwise stale benchmarks/definitions linger — and
+  // an edited metric config would conflict with its own previous-run definition.
+  onTestRunStart() {
+    this.benchmarks = {};
+    this.metricDefinitions = {};
+    this.hasFailures = false;
+  }
   onTestCaseResult(testCase) {
     if (testCase.result().state === 'failed') {
       this.hasFailures = true;
     }
     const meta = testCase.meta();
     const iterations = meta.benchmarkIterations;
-    if (!iterations) {
+    const customMetrics = meta.benchmarkMetrics;
+    if (!iterations && !customMetrics) {
       console.warn(yellow(`  No iterations recorded for: ${testCase.fullName}`));
       return;
     }
     const name = meta.benchmarkName ?? testCase.fullName;
-    const report = generateReportFromIterations(iterations);
+    const report = iterations ? generateReportFromIterations(iterations) : {
+      iterations: 0,
+      totalDuration: 0,
+      renders: [],
+      metrics: {}
+    };
+    if (customMetrics) {
+      mergeCustomMetrics(report, customMetrics, this.metricDefinitions);
+    }
     this.benchmarks[name] = report;
     const summary = dim('Total: ') + green(`${report.totalDuration.toFixed(2)}ms`) + dim(` (${report.renders.length} renders, ${report.iterations} iterations)`);
     printDurationMatrix(`${name} — React`, report, summary);
-    printMetricsTable(name, report.metrics, report.iterations);
+    printMetricsTable(name, report.metrics, report.iterations, this.metricDefinitions);
   }
   async onTestRunEnd() {
     const count = Object.keys(this.benchmarks).length;
@@ -237,11 +291,15 @@ class BenchmarkReporter {
       console.log(`  ${name}: ${result.totalDuration.toFixed(2)}ms ${dim(`(${result.renders.length} renders, ${result.iterations} iterations)`)}`);
     }
     const baseline = this.baselinePath ? await loadBaselineReport(this.baselinePath) : undefined;
+    const hasMetricDefinitions = Object.keys(this.metricDefinitions).length > 0;
     const results = {
       version: 1,
       reportType: 'benchmark',
       ...(await getCiMetadata()),
       report: this.benchmarks,
+      ...(hasMetricDefinitions ? {
+        metricDefinitions: this.metricDefinitions
+      } : {}),
       ...(baseline ? {
         base: baseline
       } : {})

package/stats.d.mts

@@ -7,4 +7,14 @@ export declare function quantile(sorted: number[], q: number): number;
  *
  * See https://en.wikipedia.org/wiki/Interquartile_range#Outliers
  */
-export declare function isOutlier(value: number, q1: number, q3: number): boolean;
+export declare function isOutlier(value: number, q1: number, q3: number): boolean;
+/**
+ * Aggregates a series of samples into a mean, standard deviation, and outlier count using
+ * IQR-based outlier removal. Falls back to the raw values when filtering would remove
+ * everything. This is the shared aggregation core for custom metrics.
+ */
+export declare function aggregateSamples(values: number[]): {
+  mean: number;
+  stdDev: number;
+  outliers: number;
+};

package/stats.mjs

@@ -24,4 +24,24 @@ export function quantile(sorted, q) {
 export function isOutlier(value, q1, q3) {
   const iqr = q3 - q1;
   return value < q1 - 1.5 * iqr || value > q3 + 1.5 * iqr;
+}
+
+/**
+ * Aggregates a series of samples into a mean, standard deviation, and outlier count using
+ * IQR-based outlier removal. Falls back to the raw values when filtering would remove
+ * everything. This is the shared aggregation core for custom metrics.
+ */
+export function aggregateSamples(values) {
+  const sorted = values.toSorted((first, second) => first - second);
+  const q1 = quantile(sorted, 0.25);
+  const q3 = quantile(sorted, 0.75);
+  const filtered = values.filter(value => !isOutlier(value, q1, q3));
+  const used = filtered.length > 0 ? filtered : values;
+  const mean = calculateMean(used);
+  const stdDev = calculateStdDev(used, mean);
+  return {
+    mean,
+    stdDev,
+    outliers: values.length - used.length
+  };
 }

package/taskMetaAugmentation.d.mts

@@ -1,7 +1,9 @@
-import type { IterationData } from "./types.mjs";
+import type { IterationData, MetricReport } from "./types.mjs";
 declare module 'vitest' {
   interface TaskMeta {
     benchmarkName?: string;
     benchmarkIterations?: IterationData[];
+    /** Custom metrics recorded via `ScalarMetric`/`DiscreteMetric`, keyed by metric name. */
+    benchmarkMetrics?: Record<string, MetricReport>;
   }
 }

package/types.d.mts

@@ -13,15 +13,8 @@ export interface RenderEvent {
   /** Start time in milliseconds (from performance.now()) */
   startTime: number;
 }
-export interface BenchmarkMetric {
-  /** Metric name, e.g. "paint:bench", "paint:grid-header" */
-  name: string;
-  /** Measured value in ms */
-  value: number;
-}
 export interface IterationData {
   renders: RenderEvent[];
-  metrics: BenchmarkMetric[];
 }
 export interface InteractionContext {
   /**
@@ -30,4 +23,69 @@ export interface InteractionContext {
    * @param timeout - Timeout in ms. Default: 5000. Pass 0 or Infinity to rely on the test timeout.
    */
   waitForElementTiming: (identifier: string, timeout?: number) => Promise<void>;
+  /**
+   * Pause recording of the harness's React render/paint measurements. Custom metrics keep
+   * recording. Throws if recording is already paused.
+   */
+  pauseReactRecording: () => void;
+  /**
+   * Resume recording of the harness's React render/paint measurements. Throws if recording is
+   * already active.
+   */
+  resumeReactRecording: () => void;
+}
+/**
+ * Whether a custom metric measures a continuous value or a discrete count.
+ * - `scalar` — continuous measurements (timings, sizes); compared with a relative noise band.
+ * - `discrete` — counts/events; compared as exact integers.
+ */
+export type MetricKind = 'scalar' | 'discrete';
+/** Which direction of change counts as a regression for a metric in alarm mode. */
+export type MetricDirection = 'lowerIsBetter' | 'higherIsBetter';
+export interface MetricAlarm {
+  /** Defaults to `lowerIsBetter`. */
+  direction?: MetricDirection;
+  /**
+   * Softer band: a regression past `warn` (but within `error`) is flagged as a warning.
+   * Scalar metrics: a relative fraction (`0.1` = 10%). Discrete metrics: an absolute count delta.
+   */
+  warn?: number;
+  /**
+   * Harder band: a regression past `error` is flagged as an error (the alarm). When **both**
+   * `warn` and `error` are omitted, `error` defaults to the dashboard's global noise band; with
+   * only `warn` set there is no error band (warning-only).
+   * Scalar metrics: a relative fraction (`0.25` = 25%). Discrete metrics: an absolute count delta.
+   */
+  error?: number;
+}
+export interface MetricConfig {
+  name: string;
+  /** Display formatting applied by the reporter and dashboard via `Intl.NumberFormat`. */
+  format?: Intl.NumberFormatOptions;
+  /**
+   * Regression judgment. Its presence opts the metric into alarming; when omitted the metric
+   * is informational (the diff is shown but never flagged).
+   */
+  alarm?: MetricAlarm;
+}
+/** Aggregated stats for a single metric sub-series, as they cross the browser→runner boundary. */
+export interface MetricSampleStats {
+  mean: number;
+  stdDev: number;
+  outliers: number;
+  /** Number of recorded samples (used to derive iteration counts; stripped from the report). */
+  count: number;
+}
+/** A custom metric's aggregated data attached to `task.meta`, keyed by metric name. */
+export interface MetricReport {
+  kind: MetricKind;
+  config: MetricConfig;
+  /** Aggregated stats keyed by sub-series id (`''` is the base series). */
+  series: Record<string, MetricSampleStats>;
+}
+/** Per-metric configuration hoisted to the top level of the report (keyed by metric name). */
+export interface MetricDefinition {
+  kind: MetricKind;
+  format?: Intl.NumberFormatOptions;
+  alarm?: MetricAlarm;
 }