@mui/internal-benchmark 0.0.3-canary.0 → 0.0.3-canary.10

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 */
   },
@@ -110,12 +208,47 @@ benchmark('name', renderFn, interaction, {
 vitest run
 ```
 
+### Profiling in DevTools
+
+To profile a benchmark case by hand with the browser DevTools instead of running the automated measurement loop, enable profile mode. It opens a **headed** Chromium window with DevTools already open, and replaces the measurement loop with an interactive control panel:
+
+```bash
+BENCHMARK_PROFILE=true vitest run -t "MyComponent mount"
+```
+
+Each `benchmark()` case renders a toolbar pinned to the top of the page with **Render**, **Finish**, and (when the case has an interaction) **Run interaction** buttons. The **Render** button toggles between mounting and unmounting (it reads **Unmount** while the component is mounted). The component under test stays unmounted until you click **Render**, so the flow is:
+
+1. Switch to the DevTools **Performance** tab and start recording.
+2. Click **Render** — this mounts the component (the thing you're profiling).
+3. Stop the recording and inspect. Toggle **Unmount** / **Render** to capture more frames, or **Run interaction** to profile a re-render.
+4. Click **Finish** to end the case and move to the next one.
+
+Filter to a single case with Vitest's `-t "<name>"` (or by file) so the window isn't shared across many cases. Profiling shares the same minimal launch args as measurement (V8 optimization and the GPU stay on for both), so the profiler reflects realistic performance; it differs only by running headed — DevTools open, in a full desktop viewport (below) — so its absolute numbers aren't directly comparable to a measurement run.
+
+Both modes render at a 1920x1080 viewport by default (instead of Vitest's phone-sized 414x896). Set `viewport` (or the `BENCHMARK_VIEWPORT` env var) to change it; in profile mode the headed browser window is also sized to match so the full render is visible:
+
+```bash
+BENCHMARK_PROFILE=true BENCHMARK_VIEWPORT=2560x1440 vitest run -t "MyComponent mount"
+```
+
+Profile mode is also settable via the `profile` config option:
+
+```ts
+export default createBenchmarkVitestConfig({
+  profile: true,
+  viewport: { width: 2560, height: 1440 },
+});
+```
+
 ### Configuration
 
 `createBenchmarkVitestConfig` accepts:
 
-- `outputPath` — path for JSON results (default: `benchmarks/results.json`)
+- `outputPath` — path for JSON results (default: `benchmarks/results.json`). Also settable via `BENCHMARK_OUTPUT_PATH`.
+- `baselinePath` — path to a prior results JSON file to inline as the comparison base (see [Baseline comparisons](#baseline-comparisons)). Also settable via `BENCHMARK_BASELINE_PATH`.
 - `launchArgs` — additional browser launch arguments
+- `profile` — run an interactive profiling session in a headed browser with DevTools instead of measuring (see [Profiling in DevTools](#profiling-in-devtools)). Also settable via `BENCHMARK_PROFILE=true`.
+- `viewport` — `{ width, height }` browser viewport (and window size in profile mode), applied to both modes. Defaults to `1920x1080`. Also settable via `BENCHMARK_VIEWPORT` (e.g. `2560x1440`).
 
 To override standard Vitest options (e.g. `include`, `testTimeout`, `headless`), use `mergeConfig`:
 
@@ -130,9 +263,24 @@ export default mergeConfig(createBenchmarkVitestConfig(), {
 });
 ```
 
+### Baseline comparisons
+
+Benchmark runs are noisy across machines. To get a clean comparison in a PR, run the baseline benchmark in the _same_ CI job as the head: the results are inlined into the head upload as a `base` field, and the dashboard / PR comment render the comparison without fetching a separate base artifact from S3.
+
+```bash
+# in a PR CI job
+git worktree add /tmp/base $BASE_SHA
+(cd /tmp/base && pnpm install && BENCHMARK_OUTPUT_PATH=/tmp/base-bench.json pnpm test:bench)
+BENCHMARK_BASELINE_PATH=/tmp/base-bench.json pnpm test:bench   # head run, inlines base
+```
+
+The feature is opt-in — without `BENCHMARK_BASELINE_PATH` (or the `baselinePath` config option), the dashboard falls back to fetching the base from S3 by merge-base SHA as before.
+
 ## API
 
 - `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,46 @@ 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;
+  commitSha: z.ZodString;
+  repo: z.ZodString;
+  reportType: z.ZodLiteral<string>;
+  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>;
   timestamp: z.ZodNumber;
@@ -67,17 +107,59 @@ 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;
+    commitSha: z.ZodString;
+    repo: z.ZodString;
+    reportType: z.ZodLiteral<string>;
+    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>;
 export type BenchmarkUpload = z.infer<typeof benchmarkUploadSchema>;
 export declare function getCiMetadata(): Promise<{
   timestamp: number;
   repo: string;
-  branch: string;
   prNumber: number | undefined;
+  branch: string;
   commitSha: string;
 }>;
 export {};

package/ciReport.mjs

@@ -1,15 +1,12 @@
 import { execa } from 'execa';
 import { z } from 'zod/v4';
 import envCi from 'env-ci';
-async function getCommitSha() {
-  try {
-    const {
-      stdout
-    } = await execa('git', ['rev-parse', 'HEAD']);
-    return stdout.trim();
-  } catch {
-    return null;
-  }
+async function getGitInfo() {
+  const [commit, branch] = await Promise.all([execa('git', ['rev-parse', 'HEAD']), execa('git', ['branch', '--show-current'])]);
+  return {
+    commitSha: commit.stdout,
+    branch: branch.stdout
+  };
 }
 
 /**
@@ -48,14 +45,31 @@ const benchmarkReportEntrySchema = z.object({
   metrics: z.record(z.string(), metricStatsSchema)
 });
 const benchmarkReportSchema = z.record(z.string(), benchmarkReportEntrySchema);
-export const benchmarkUploadSchema = 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()
+});
 export async function getCiMetadata() {
   const ciInfo = envCi();
+  const gitInfo = await getGitInfo();
   return {
     timestamp: Date.now(),
     repo: ciInfo.slug ?? '',
-    branch: ciInfo.isPr ? ciInfo.prBranch ?? '' : ciInfo.branch ?? '',
     prNumber: ciInfo.pr ? Number(ciInfo.pr) : undefined,
-    commitSha: ciInfo.commit ?? (await getCommitSha()) ?? ''
+    branch: gitInfo.branch || process.env.BENCHMARK_BRANCH || (ciInfo.isPr ? ciInfo.prBranch : ciInfo.branch) || '',
+    commitSha: gitInfo.commitSha
   };
 }

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;