@mui/internal-benchmark 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Versions
+
+## 2.0.8
+
+Test release
+
+## 2.0.7
+
+Test release
+
+## 2.0.6
+
+Changelog start

package/ElementTiming.d.mts

@@ -0,0 +1,5 @@
+export declare function ElementTiming({
+  name
+}: {
+  name: string;
+}): import("react/jsx-runtime").JSX.Element;

package/ElementTiming.mjs

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import { jsx as _jsx } from "react/jsx-runtime";
+export function ElementTiming({
+  name
+}) {
+  return /*#__PURE__*/_jsx("span", {
+    elementtiming: name,
+    style: {
+      position: 'fixed',
+      top: 0,
+      left: 0,
+      opacity: 0.01,
+      pointerEvents: 'none',
+      fontSize: 1
+    },
+    children: "\xA0"
+  });
+}

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Material-UI SAS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# Benchmark
+
+A React component render benchmarking tool built on Vitest and Playwright. Runs benchmarks in a real browser using React's profiling build to capture accurate render durations.
+
+## Features
+
+- Measures React component render durations using `React.Profiler`
+- Captures paint metrics via the [Element Timing API](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceElementTiming)
+- Runs in a real Chromium browser via Playwright
+- Uses React's profiling build for accurate production-like measurements
+- IQR-based outlier removal for stable results
+- Configurable warmup and measurement runs
+- JSON results output
+
+## Usage
+
+### Setup
+
+Create a `vitest.config.ts`:
+
+```ts
+import { createBenchmarkVitestConfig } from '@mui/internal-benchmark/vitest';
+
+export default createBenchmarkVitestConfig();
+```
+
+### Writing benchmarks
+
+Create `*.bench.tsx` files:
+
+```tsx
+import * as React from 'react';
+import { benchmark } from '@mui/internal-benchmark';
+
+function MyComponent() {
+  return (
+    <div>
+      {Array.from({ length: 100 }, (_, i) => (
+        <span key={i}>{i}</span>
+      ))}
+    </div>
+  );
+}
+
+benchmark('MyComponent mount', () => <MyComponent />);
+```
+
+The second argument is a render function (not an element) — it's called on each iteration to produce a fresh React element.
+
+### Interactions
+
+To benchmark re-renders, pass an interaction callback:
+
+```tsx
+benchmark(
+  'Counter click',
+  () => <Counter />,
+  async () => {
+    document.querySelector('button')?.click();
+  },
+);
+```
+
+### 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.
+
+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.
+
+```tsx
+import { benchmark, ElementTiming } from '@mui/internal-benchmark';
+
+function MyComponent() {
+  return (
+    <div>
+      <ElementTiming name="my-component" />
+      {/* ... */}
+    </div>
+  );
+}
+
+benchmark(
+  'MyComponent mount',
+  () => <MyComponent />,
+  async ({ waitForElementTiming }) => {
+    await waitForElementTiming('my-component');
+  },
+);
+```
+
+This produces a `paint:my-component` metric alongside the automatic `paint:default`.
+
+`waitForElementTiming` accepts an optional `timeout` in milliseconds (default: 5000). Pass `0` or `Infinity` to rely on the test timeout instead.
+
+### Options
+
+```tsx
+benchmark('name', renderFn, interaction, {
+  runs: 20, // measurement iterations (default: 20)
+  warmupRuns: 10, // warmup iterations before measuring (default: 10)
+  afterEach: () => {
+    /* cleanup between iterations */
+  },
+});
+```
+
+### Running
+
+```bash
+vitest run
+```
+
+### Configuration
+
+`createBenchmarkVitestConfig` accepts:
+
+- `outputPath` — path for JSON results (default: `benchmarks/results.json`)
+- `launchArgs` — additional browser launch arguments
+
+To override standard Vitest options (e.g. `include`, `testTimeout`, `headless`), use `mergeConfig`:
+
+```ts
+import { mergeConfig } from 'vitest/config';
+import { createBenchmarkVitestConfig } from '@mui/internal-benchmark/vitest';
+
+export default mergeConfig(createBenchmarkVitestConfig(), {
+  test: {
+    include: ['**/*.perf.tsx'],
+  },
+});
+```
+
+## API
+
+- `benchmark` — define a benchmark test case
+- `ElementTiming` — invisible marker component for paint timing (renders a `<span>` tracked by the Element Timing API)
+- `createBenchmarkVitestConfig` — create a Vitest config with browser benchmarking defaults
+- `BenchmarkReporter` — Vitest reporter that collects and outputs benchmark results

package/ciReport.d.mts

@@ -0,0 +1,83 @@
+import { z } from 'zod/v4';
+declare const renderStatsSchema: z.ZodObject<{
+  id: z.ZodString;
+  phase: z.ZodEnum<{
+    mount: "mount";
+    "nested-update": "nested-update";
+    update: "update";
+  }>;
+  startTime: z.ZodNumber;
+  actualDuration: z.ZodNumber;
+  stdDev: z.ZodNumber;
+  outliers: z.ZodNumber;
+}, z.core.$strip>;
+declare const metricStatsSchema: z.ZodObject<{
+  mean: z.ZodNumber;
+  stdDev: z.ZodNumber;
+  outliers: z.ZodNumber;
+}, z.core.$strip>;
+declare const benchmarkReportEntrySchema: z.ZodObject<{
+  iterations: z.ZodNumber;
+  totalDuration: z.ZodNumber;
+  renders: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    phase: z.ZodEnum<{
+      mount: "mount";
+      "nested-update": "nested-update";
+      update: "update";
+    }>;
+    startTime: z.ZodNumber;
+    actualDuration: z.ZodNumber;
+    stdDev: z.ZodNumber;
+    outliers: z.ZodNumber;
+  }, z.core.$strip>>;
+  metrics: z.ZodRecord<z.ZodString, z.ZodObject<{
+    mean: z.ZodNumber;
+    stdDev: z.ZodNumber;
+    outliers: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const benchmarkReportSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+  iterations: z.ZodNumber;
+  totalDuration: z.ZodNumber;
+  renders: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    phase: z.ZodEnum<{
+      mount: "mount";
+      "nested-update": "nested-update";
+      update: "update";
+    }>;
+    startTime: z.ZodNumber;
+    actualDuration: z.ZodNumber;
+    stdDev: z.ZodNumber;
+    outliers: z.ZodNumber;
+  }, z.core.$strip>>;
+  metrics: z.ZodRecord<z.ZodString, z.ZodObject<{
+    mean: z.ZodNumber;
+    stdDev: z.ZodNumber;
+    outliers: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>>;
+export declare const benchmarkUploadSchema: 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>>;
+}, z.core.$strip>;
+export type RenderStats = z.infer<typeof renderStatsSchema>;
+export type MetricStats = z.infer<typeof metricStatsSchema>;
+export type BenchmarkReportEntry = z.infer<typeof benchmarkReportEntrySchema>;
+export type BenchmarkReport = z.infer<typeof benchmarkReportSchema>;
+export type BenchmarkUpload = z.infer<typeof benchmarkUploadSchema>;
+export declare function getCiMetadata(): Promise<{
+  timestamp: number;
+  repo: string;
+  branch: string;
+  prNumber: number | undefined;
+  commitSha: string;
+}>;
+export {};

package/ciReport.mjs

@@ -0,0 +1,61 @@
+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;
+  }
+}
+
+/**
+ * Creates a CI report upload schema for a specific report type.
+ * Common fields (commitSha, repo, branch, prNumber) are shared across all report types.
+ */
+function ciReportUploadSchema(type, version, reportSchema) {
+  return z.object({
+    version: z.literal(version),
+    timestamp: z.number(),
+    commitSha: z.string().regex(/^[0-9a-f]{40}$/, 'Must be a 40-character hex string'),
+    repo: z.string().includes('/', 'Must be in owner/repo format'),
+    reportType: z.literal(type),
+    prNumber: z.number().int().positive().optional(),
+    branch: z.string(),
+    report: reportSchema
+  });
+}
+const renderStatsSchema = z.object({
+  id: z.string(),
+  phase: z.enum(['mount', 'update', 'nested-update']),
+  startTime: z.number(),
+  actualDuration: z.number(),
+  stdDev: z.number(),
+  outliers: z.number()
+});
+const metricStatsSchema = z.object({
+  mean: z.number(),
+  stdDev: z.number(),
+  outliers: z.number()
+});
+const benchmarkReportEntrySchema = z.object({
+  iterations: z.number(),
+  totalDuration: z.number(),
+  renders: z.array(renderStatsSchema),
+  metrics: z.record(z.string(), metricStatsSchema)
+});
+const benchmarkReportSchema = z.record(z.string(), benchmarkReportEntrySchema);
+export const benchmarkUploadSchema = ciReportUploadSchema('benchmark', 1, benchmarkReportSchema);
+export async function getCiMetadata() {
+  const ciInfo = envCi();
+  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()) ?? ''
+  };
+}

package/format.d.mts

@@ -0,0 +1,12 @@
+export declare const dim: (s: string) => string;
+export declare const red: (s: string) => string;
+export declare const green: (s: string) => string;
+export declare const yellow: (s: string) => string;
+export declare const cyan: (s: string) => string;
+export declare function fileUrl(filePath: string): string;
+interface Column {
+  header: string;
+  width: number;
+}
+export declare function printTable(columns: Column[], rows: string[][], footer?: string, title?: string): void;
+export {};

package/format.mjs

@@ -0,0 +1,75 @@
+import { pathToFileURL } from 'node:url';
+import { styleText } from 'node:util';
+export const dim = s => styleText('dim', s);
+export const red = s => styleText('red', s);
+export const green = s => styleText('green', s);
+export const yellow = s => styleText('yellow', s);
+export const cyan = s => styleText('cyan', s);
+export function fileUrl(filePath) {
+  return pathToFileURL(filePath).href;
+}
+function truncate(str, maxLength) {
+  if (str.length <= maxLength) {
+    return str;
+  }
+  return `${str.slice(0, maxLength - 1)}…`;
+}
+export function printTable(columns, rows, footer, title) {
+  const colWidths = columns.map(col => col.width);
+  const totalInner = colWidths.reduce((sum, w) => sum + w + 2, 0) + colWidths.length - 1;
+  if (title) {
+    const titleTop = dim(`┌${'─'.repeat(totalInner)}┐`);
+    const titleContent = ` ${truncate(title, totalInner - 2)}`;
+    const titlePadding = totalInner - titleContent.length;
+    const titleLine = dim('│') + titleContent + ' '.repeat(Math.max(0, titlePadding)) + dim('│');
+    const titleSep = dim(`├${colWidths.map(w => '─'.repeat(w + 2)).join('┬')}┤`);
+
+    // eslint-disable-next-line no-console
+    console.log(titleTop);
+    // eslint-disable-next-line no-console
+    console.log(titleLine);
+    // eslint-disable-next-line no-console
+    console.log(titleSep);
+  } else {
+    const topBorder = dim(`┌${colWidths.map(w => '─'.repeat(w + 2)).join('┬')}┐`);
+    // eslint-disable-next-line no-console
+    console.log(topBorder);
+  }
+  const headerSep = dim(`├${colWidths.map(w => '─'.repeat(w + 2)).join('┼')}┤`);
+  const headerCells = columns.map(col => ` ${col.header.padStart(col.width)} `);
+  const headerLine = dim('│') + headerCells.join(dim('│')) + dim('│');
+
+  // eslint-disable-next-line no-console
+  console.log(headerLine);
+  // eslint-disable-next-line no-console
+  console.log(headerSep);
+  for (const row of rows) {
+    const cells = row.map((cell, i) => ` ${cell.padStart(colWidths[i])} `);
+    // eslint-disable-next-line no-console
+    console.log(dim('│') + cells.join(dim('│')) + dim('│'));
+  }
+  if (footer) {
+    const footerSep = dim(`├${colWidths.map(w => '─'.repeat(w + 2)).join('┴')}┤`);
+    const footerContent = ` ${footer}`;
+    const padding = totalInner - stripAnsi(footerContent).length;
+    const footerLine = dim('│') + footerContent + ' '.repeat(Math.max(0, padding)) + dim('│');
+    const bottomBorder = dim(`└${'─'.repeat(totalInner)}┘`);
+
+    // eslint-disable-next-line no-console
+    console.log(footerSep);
+    // eslint-disable-next-line no-console
+    console.log(footerLine);
+    // eslint-disable-next-line no-console
+    console.log(bottomBorder);
+  } else {
+    const bottomBorder = dim(`└${colWidths.map(w => '─'.repeat(w + 2)).join('┴')}┘`);
+    // eslint-disable-next-line no-console
+    console.log(bottomBorder);
+  }
+}
+
+// Strip ANSI escape codes to measure visible string length
+function stripAnsi(str) {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[0-9;]*m/g, '');
+}

package/index.d.mts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import type { InteractionContext } from "./types.mjs";
+import "./taskMetaAugmentation.mjs";
+export type { RenderEvent, BenchmarkMetric, IterationData, InteractionContext } from "./types.mjs";
+export { ElementTiming } from "./ElementTiming.mjs";
+declare global {
+  interface Window {
+    gc?: () => void;
+  }
+}
+interface BenchmarkOptions {
+  runs?: number;
+  warmupRuns?: number;
+  afterEach?: () => Promise<void> | void;
+}
+export declare function benchmark(name: string, renderFn: () => React.ReactElement, interactionOrOptions?: ((ctx: InteractionContext) => Promise<void> | void) | BenchmarkOptions, maybeOptions?: BenchmarkOptions): void;

package/index.mjs

@@ -0,0 +1,196 @@
+/**
+ * @mui/internal-benchmark v0.0.1
+ *
+ * @license undefined
+ * This source code is licensed under the undefined license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+var _ElementTiming;
+import * as React from 'react';
+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 for TaskMeta augmentation side effect
+import "./taskMetaAugmentation.mjs";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export { ElementTiming } from "./ElementTiming.mjs";
+function BenchProfiler({
+  captures,
+  children
+}) {
+  const onRender = React.useCallback((id, phase, actualDuration, _baseDuration, startTime) => {
+    captures.push({
+      id,
+      phase,
+      actualDuration,
+      startTime
+    });
+  }, [captures]);
+  return /*#__PURE__*/_jsxs(React.Profiler, {
+    id: "bench",
+    onRender: onRender,
+    children: [children, _ElementTiming || (_ElementTiming = /*#__PURE__*/_jsx(ElementTiming, {
+      name: "default"
+    }))]
+  });
+}
+
+// Double GC: the first pass collects garbage, the second catches weak refs
+// and prevent leaking into the next iteration.
+function forceGC() {
+  if (typeof window.gc === 'function') {
+    window.gc();
+    window.gc();
+  }
+}
+// Flush pending microtasks and React cleanup effects (e.g. from a previous unmount)
+// so they don't interfere with the next iteration's timing.
+function settle() {
+  return new Promise(resolve => {
+    setTimeout(resolve, 0);
+  });
+}
+function supportsElementTiming() {
+  return PerformanceObserver.supportedEntryTypes.includes('element');
+}
+export function benchmark(name, renderFn, interactionOrOptions, maybeOptions) {
+  const interaction = typeof interactionOrOptions === 'function' ? interactionOrOptions : undefined;
+  const options = typeof interactionOrOptions === 'object' ? interactionOrOptions : maybeOptions;
+  it(name, async ({
+    task
+  }) => {
+    const runs = options?.runs ?? 20;
+    const warmupRuns = options?.warmupRuns ?? 10;
+    const totalRuns = warmupRuns + runs;
+    const iterations = [];
+    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;
+    for (let i = 0; i < totalRuns; i += 1) {
+      const isWarmup = i < warmupRuns;
+
+      // Drain event loop from previous unmount, then double GC for thorough cleanup
+      // eslint-disable-next-line no-await-in-loop
+      await settle();
+      forceGC();
+      const captures = [];
+      const elementEntries = [];
+      const elementResolvers = new Map();
+
+      // Set up Element Timing observer
+      let elementObserver = null;
+      if (hasElementTiming) {
+        elementObserver = new PerformanceObserver(list => {
+          for (const entry of list.getEntries()) {
+            elementEntries.push(entry);
+            const resolver = elementResolvers.get(entry.identifier);
+            if (resolver) {
+              elementResolvers.delete(entry.identifier);
+              resolver();
+            }
+          }
+        });
+        elementObserver.observe({
+          type: 'element',
+          buffered: false
+        });
+      }
+      const waitForElementTiming = (identifier, timeout) => {
+        if (!hasElementTiming) {
+          console.warn(`waitForElementTiming("${identifier}"): Element Timing API is not supported. ` + 'Paint metrics will not be collected.');
+          return Promise.resolve();
+        }
+        if (elementEntries.some(entry => entry.identifier === identifier)) {
+          return Promise.resolve();
+        }
+        const {
+          promise,
+          resolve,
+          reject
+        } = Promise.withResolvers();
+        const timeoutMs = timeout ?? 5000;
+        const timer = timeoutMs > 0 && timeoutMs < Infinity ? setTimeout(() => {
+          elementResolvers.delete(identifier);
+          reject(new Error(`waitForElementTiming("${identifier}"): timed out after ${timeoutMs}ms. ` + 'Ensure the element has an `elementtiming` attribute and is visible in the viewport.'));
+        }, timeoutMs) : undefined;
+        elementResolvers.set(identifier, () => {
+          if (timer) {
+            clearTimeout(timer);
+          }
+          resolve();
+        });
+        return promise;
+      };
+      const iterationStart = performance.now();
+      const container = document.createElement('div');
+      document.body.appendChild(container);
+      const root = ReactDOMClient.createRoot(container, {
+        // eslint-disable-next-line @typescript-eslint/no-loop-func
+        onUncaughtError: error => {
+          renderError = error;
+        }
+      });
+      ReactDOM.flushSync(() => {
+        root.render(/*#__PURE__*/_jsx(BenchProfiler, {
+          captures: captures,
+          children: renderFn()
+        }));
+      });
+      if (renderError) {
+        elementObserver?.disconnect();
+        root.unmount();
+        container.remove();
+        break;
+      }
+      if (interaction) {
+        // eslint-disable-next-line no-await-in-loop
+        await interaction({
+          waitForElementTiming
+        });
+      }
+
+      // Wait for the bench sentinel paint entry (relies on test timeout)
+      // eslint-disable-next-line no-await-in-loop
+      await waitForElementTiming('default', 0);
+      elementObserver?.disconnect();
+      root.unmount();
+      container.remove();
+      if (!isWarmup) {
+        const metrics = elementEntries.map(entry => ({
+          name: `paint:${entry.identifier}`,
+          value: entry.renderTime - iterationStart
+        }));
+        iterations.push({
+          renders: captures,
+          metrics
+        });
+      }
+      if (options?.afterEach) {
+        // eslint-disable-next-line no-await-in-loop
+        await options.afterEach();
+      }
+    }
+    task.meta.benchmarkIterations = iterations;
+    task.meta.benchmarkName = name;
+    if (renderError) {
+      throw renderError;
+    }
+
+    // Validate that at least one render was recorded
+    expect(iterations[0].renders.length, 'No renders were recorded during benchmark').toBeGreaterThan(0);
+
+    // 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.
+    if (iterations.length > 1) {
+      const getEventKey = event => `${event.id}:${event.phase}`;
+      const expectedKeys = iterations[0].renders.map(getEventKey);
+      for (let i = 1; i < iterations.length; i += 1) {
+        const iterationKeys = iterations[i].renders.map(getEventKey);
+        expect(iterationKeys, `Iteration ${i} render events differ from iteration 0`).toEqual(expectedKeys);
+      }
+    }
+  });
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@mui/internal-benchmark",
+  "version": "0.0.1",
+  "author": "MUI Team",
+  "description": "Benchmark utilities for MUI projects. Internal package.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mui/mui-public.git",
+    "directory": "packages/benchmark"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.29.2",
+    "@vitejs/plugin-react": "^6.0.1",
+    "env-ci": "^11.2.0",
+    "execa": "^9.6.1",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@vitest/browser-playwright": ">=4.1",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "vitest": ">=4.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./index.d.mts",
+        "default": "./index.mjs"
+      },
+      "default": {
+        "types": "./index.d.mts",
+        "default": "./index.mjs"
+      }
+    },
+    "./ciReport": {
+      "import": {
+        "types": "./ciReport.d.mts",
+        "default": "./ciReport.mjs"
+      },
+      "default": {
+        "types": "./ciReport.d.mts",
+        "default": "./ciReport.mjs"
+      }
+    },
+    "./reporter": {
+      "import": {
+        "types": "./reporter.d.mts",
+        "default": "./reporter.mjs"
+      },
+      "default": {
+        "types": "./reporter.d.mts",
+        "default": "./reporter.mjs"
+      }
+    },
+    "./vitest": {
+      "import": {
+        "types": "./vitest.d.mts",
+        "default": "./vitest.mjs"
+      },
+      "default": {
+        "types": "./vitest.d.mts",
+        "default": "./vitest.mjs"
+      }
+    }
+  }
+}

package/reporter.d.mts

@@ -0,0 +1,20 @@
+import type { Reporter, TestCase } from 'vitest/node';
+import type { IterationData } from "./types.mjs";
+import type { BenchmarkReportEntry } from "./ciReport.mjs";
+import "./taskMetaAugmentation.mjs";
+declare function generateReportFromIterations(iterations: IterationData[]): BenchmarkReportEntry;
+export interface BenchmarkReporterOptions {
+  outputPath?: string;
+  upload?: boolean;
+}
+declare class BenchmarkReporter implements Reporter {
+  private benchmarks;
+  private outputPath;
+  private upload;
+  private hasFailures;
+  constructor(options?: BenchmarkReporterOptions);
+  onTestCaseResult(testCase: TestCase): void;
+  onTestRunEnd(): Promise<void>;
+}
+export { BenchmarkReporter, generateReportFromIterations };
+export default BenchmarkReporter;

package/reporter.mjs

@@ -0,0 +1,251 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import { getCiMetadata } from "./ciReport.mjs";
+import { calculateMean, calculateStdDev, quantile, isOutlier } from "./stats.mjs";
+import { dim, red, green, yellow, cyan, printTable, fileUrl } from "./format.mjs";
+import { uploadCiReport } from "./upload.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);
+    }
+  }
+  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
+    };
+  }
+  return result;
+}
+function generateReportFromIterations(iterations) {
+  if (iterations.length === 0) {
+    return {
+      iterations: 0,
+      totalDuration: 0,
+      renders: [],
+      metrics: {}
+    };
+  }
+  const iterationCount = iterations.length;
+  const firstIteration = iterations[0];
+  const expectedLength = firstIteration.renders.length;
+
+  // Skip report if iterations have inconsistent event counts (the test already failed)
+  if (iterations.some(iter => iter.renders.length !== expectedLength)) {
+    return {
+      iterations: iterationCount,
+      totalDuration: 0,
+      renders: [],
+      metrics: {}
+    };
+  }
+
+  // Per-render stats (IQR-filtered)
+  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 coefficientOfVariation = iqrMean > 0 ? iqrStdDev / iqrMean : 0;
+    if (iqrMean > 1 && coefficientOfVariation > 0.1) {
+      const event = firstIteration.renders[index];
+      console.warn(`High coefficient of variation (${(coefficientOfVariation * 100).toFixed(1)}%) for render #${index} event "${getEventKey(event)}". ` + `Mean: ${iqrMean.toFixed(2)}ms, StdDev: ${iqrStdDev.toFixed(2)}ms. Results may be unreliable.`);
+    }
+    renderStats.push({
+      event: firstIteration.renders[index],
+      iqrMean,
+      iqrStdDev,
+      outliers: durations.length - used.length
+    });
+  }
+
+  // Calculate mean gaps between consecutive renders, then derive start times
+  const meanGaps = [0]; // no gap before first render
+  for (let index = 1; index < expectedLength; index += 1) {
+    const gaps = iterations.map(iteration => {
+      const prevEnd = iteration.renders[index - 1].startTime + iteration.renders[index - 1].actualDuration;
+      return iteration.renders[index].startTime - prevEnd;
+    });
+    meanGaps.push(calculateMean(gaps));
+  }
+  const renders = [];
+  let totalDuration = 0;
+  for (let index = 0; index < expectedLength; index += 1) {
+    const {
+      event,
+      iqrMean,
+      iqrStdDev,
+      outliers
+    } = renderStats[index];
+    const startTime = index === 0 ? 0 : renders[index - 1].startTime + renders[index - 1].actualDuration + meanGaps[index];
+    renders.push({
+      id: event.id,
+      phase: event.phase,
+      startTime,
+      actualDuration: iqrMean,
+      stdDev: iqrStdDev,
+      outliers
+    });
+    totalDuration += iqrMean;
+  }
+
+  // Aggregate metrics
+  const metrics = aggregateMetrics(iterations);
+  return {
+    iterations: iterationCount,
+    totalDuration,
+    renders,
+    metrics
+  };
+}
+const LABEL_WIDTH = 28;
+const STAT_WIDTH = 16;
+const CV_WIDTH = 8;
+function colorCV(cv) {
+  const str = `${cv.toFixed(1)}%`.padStart(CV_WIDTH);
+  if (cv > 10) {
+    return red(str);
+  }
+  if (cv > 5) {
+    return yellow(str);
+  }
+  return dim(str);
+}
+function printDurationMatrix(name, report, footer) {
+  if (report.renders.length === 0) {
+    return;
+  }
+  const rows = [];
+  for (let r = 0; r < report.renders.length; r += 1) {
+    const render = report.renders[r];
+    const label = `#${r} ${render.id}:${render.phase}`;
+    const iqrStr = `${render.actualDuration.toFixed(2)}±${render.stdDev.toFixed(2)}`;
+    const cv = render.actualDuration > 0 ? render.stdDev / render.actualDuration * 100 : 0;
+    rows.push([label.slice(0, LABEL_WIDTH).padStart(LABEL_WIDTH), cyan(iqrStr.padStart(STAT_WIDTH)), colorCV(cv), render.outliers > 0 ? yellow(String(render.outliers).padStart(4)) : dim('0'.padStart(4))]);
+  }
+  printTable([{
+    header: 'Render',
+    width: LABEL_WIDTH
+  }, {
+    header: 'Mean±σ (ms)',
+    width: STAT_WIDTH
+  }, {
+    header: 'Var%',
+    width: CV_WIDTH
+  }, {
+    header: 'Out',
+    width: 4
+  }], rows, footer, name);
+}
+function printMetricsTable(name, metrics, iterationCount) {
+  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 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))];
+  });
+  printTable([{
+    header: 'Metric',
+    width: LABEL_WIDTH
+  }, {
+    header: 'Mean±σ (ms)',
+    width: STAT_WIDTH
+  }, {
+    header: 'Var%',
+    width: CV_WIDTH
+  }, {
+    header: 'Out',
+    width: 4
+  }], rows, dim(`${iterationCount} iterations`), `${name} — Metrics`);
+}
+class BenchmarkReporter {
+  benchmarks = {};
+  hasFailures = false;
+  constructor(options) {
+    this.outputPath = options?.outputPath ?? path.resolve(process.cwd(), 'benchmarks', 'results.json');
+    this.upload = options?.upload ?? process.env.BENCHMARK_UPLOAD === 'true';
+  }
+  onTestCaseResult(testCase) {
+    if (testCase.result().state === 'failed') {
+      this.hasFailures = true;
+    }
+    const meta = testCase.meta();
+    const iterations = meta.benchmarkIterations;
+    if (!iterations) {
+      console.warn(yellow(`  No iterations recorded for: ${testCase.fullName}`));
+      return;
+    }
+    const name = meta.benchmarkName ?? testCase.fullName;
+    const report = generateReportFromIterations(iterations);
+    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);
+  }
+  async onTestRunEnd() {
+    const count = Object.keys(this.benchmarks).length;
+
+    // eslint-disable-next-line no-console
+    console.log(`\n${cyan('Benchmark Results')} ${dim(`(${count} benchmark${count === 1 ? '' : 's'})`)}`);
+    for (const [name, result] of Object.entries(this.benchmarks)) {
+      // eslint-disable-next-line no-console
+      console.log(`  ${name}: ${result.totalDuration.toFixed(2)}ms ${dim(`(${result.renders.length} renders, ${result.iterations} iterations)`)}`);
+    }
+    const results = {
+      version: 1,
+      reportType: 'benchmark',
+      ...(await getCiMetadata()),
+      report: this.benchmarks
+    };
+    const outputDir = path.dirname(this.outputPath);
+    await fs.mkdir(outputDir, {
+      recursive: true
+    });
+    await fs.writeFile(this.outputPath, JSON.stringify(results, null, 2));
+
+    // eslint-disable-next-line no-console
+    console.log(dim(`\nResults saved to ${fileUrl(this.outputPath)}`));
+    if (this.upload) {
+      if (this.hasFailures) {
+        // eslint-disable-next-line no-console
+        console.log(yellow('\nSkipping upload: some test cases failed'));
+      } else {
+        await uploadCiReport(results);
+      }
+    }
+  }
+}
+export { BenchmarkReporter, generateReportFromIterations };
+export default BenchmarkReporter;

package/stats.d.mts

@@ -0,0 +1,10 @@
+export declare function calculateMean(values: number[]): number;
+export declare function calculateStdDev(values: number[], mean: number): number;
+export declare function quantile(sorted: number[], q: number): number;
+/**
+ * Determines whether a value is a statistical outlier using the IQR method.
+ * Values below Q1 - 1.5*IQR or above Q3 + 1.5*IQR are considered outliers.
+ *
+ * See https://en.wikipedia.org/wiki/Interquartile_range#Outliers
+ */
+export declare function isOutlier(value: number, q1: number, q3: number): boolean;

package/stats.mjs

@@ -0,0 +1,27 @@
+export function calculateMean(values) {
+  return values.reduce((sum, v) => sum + v, 0) / values.length;
+}
+export function calculateStdDev(values, mean) {
+  const squaredDiffs = values.map(v => (v - mean) ** 2);
+  return Math.sqrt(squaredDiffs.reduce((sum, v) => sum + v, 0) / values.length);
+}
+export function quantile(sorted, q) {
+  const pos = (sorted.length - 1) * q;
+  const base = Math.floor(pos);
+  const rest = pos - base;
+  if (sorted[base + 1] !== undefined) {
+    return sorted[base] + rest * (sorted[base + 1] - sorted[base]);
+  }
+  return sorted[base];
+}
+
+/**
+ * Determines whether a value is a statistical outlier using the IQR method.
+ * Values below Q1 - 1.5*IQR or above Q3 + 1.5*IQR are considered outliers.
+ *
+ * See https://en.wikipedia.org/wiki/Interquartile_range#Outliers
+ */
+export function isOutlier(value, q1, q3) {
+  const iqr = q3 - q1;
+  return value < q1 - 1.5 * iqr || value > q3 + 1.5 * iqr;
+}

package/taskMetaAugmentation.d.mts

@@ -0,0 +1,7 @@
+import type { IterationData } from "./types.mjs";
+declare module 'vitest' {
+  interface TaskMeta {
+    benchmarkName?: string;
+    benchmarkIterations?: IterationData[];
+  }
+}

package/taskMetaAugmentation.mjs

@@ -0,0 +1 @@
+export {};

package/types.d.mts

@@ -0,0 +1,33 @@
+export interface RenderEvent {
+  id: string;
+  /**
+   * The React Profiler phase that triggered the render.
+   * - `mount` — first render of the component
+   * - `update` — re-render caused by state, props, or context change
+   * - `nested-update` — re-render caused by a state update inside useLayoutEffect or flushSync
+   *
+   * See https://react.dev/reference/react/Profiler#onrender-callback
+   */
+  phase: 'mount' | 'update' | 'nested-update';
+  actualDuration: number;
+  /** 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 {
+  /**
+   * Wait for an element with the given `elementtiming` identifier to be painted.
+   * @param identifier - The `elementtiming` attribute value to wait for.
+   * @param timeout - Timeout in ms. Default: 5000. Pass 0 or Infinity to rely on the test timeout.
+   */
+  waitForElementTiming: (identifier: string, timeout?: number) => Promise<void>;
+}

package/types.mjs

@@ -0,0 +1 @@
+export {};

package/upload.d.mts

@@ -0,0 +1,5 @@
+import type { BenchmarkUpload } from "./ciReport.mjs";
+declare function uploadCiReport(report: BenchmarkUpload, options?: {
+  apiUrl?: string;
+}): Promise<void>;
+export { uploadCiReport };

package/upload.mjs

@@ -0,0 +1,34 @@
+import { benchmarkUploadSchema } from "./ciReport.mjs";
+async function uploadCiReport(report, options) {
+  benchmarkUploadSchema.parse(report);
+  const apiUrl = options?.apiUrl ?? process.env.CI_REPORT_API_URL ?? 'https://code-infra-dashboard.onrender.com';
+  const url = new URL('/api/ci-reports/upload', apiUrl);
+  const oidcToken = process.env.CIRCLE_OIDC_TOKEN_V2;
+  if (!oidcToken) {
+    throw new Error('CIRCLE_OIDC_TOKEN_V2 environment variable is required for uploads');
+  }
+
+  // eslint-disable-next-line no-console
+  console.log('Upload request body:', JSON.stringify({
+    ...report,
+    report: '...'
+  }, null, 2));
+  // eslint-disable-next-line no-console
+  console.log(`Uploading benchmark to ${url.href}`);
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${oidcToken}`
+    },
+    body: JSON.stringify(report)
+  });
+  const responseText = await response.text();
+  if (!response.ok) {
+    throw new Error(`Upload failed (${response.status}): ${responseText}`);
+  }
+  const result = JSON.parse(responseText);
+  // eslint-disable-next-line no-console
+  console.log(`Benchmark results uploaded successfully. S3 key: ${result.key}`);
+}
+export { uploadCiReport };

package/vitest.d.mts

@@ -0,0 +1,12 @@
+import { ViteUserConfig } from 'vitest/config';
+export interface CreateBenchmarkVitestConfigOptions {
+  /**
+   * Path to save benchmark results JSON file. If not provided, results will not be saved to disk.
+   */
+  outputPath?: string;
+  /**
+   * Additional Chromium launch arguments.
+   */
+  launchArgs?: string[];
+}
+export declare function createBenchmarkVitestConfig(options?: CreateBenchmarkVitestConfigOptions): ViteUserConfig;

package/vitest.mjs

@@ -0,0 +1,51 @@
+import react from '@vitejs/plugin-react';
+import { playwright } from '@vitest/browser-playwright';
+export function createBenchmarkVitestConfig(options) {
+  const {
+    outputPath,
+    launchArgs = []
+  } = options ?? {};
+  return {
+    plugins: [react()],
+    define: {
+      'process.env.NODE_ENV': '"production"'
+    },
+    resolve: {
+      dedupe: ['react', 'react-dom'],
+      alias: [{
+        find: 'react-dom/client',
+        replacement: 'react-dom/profiling'
+      }]
+    },
+    test: {
+      browser: {
+        enabled: true,
+        headless: true,
+        screenshotFailures: false,
+        instances: [{
+          browser: 'chromium',
+          testTimeout: 120_000
+        }],
+        provider: playwright({
+          launchOptions: {
+            args: [
+            // V8 flags for deterministic JS execution
+            '--js-flags=--expose-gc,--predictable,--no-opt,--predictable-gc-schedule,--no-concurrent-sweeping,--hash-seed=1,--random-seed=1,--max-old-space-size=4096',
+            // Chromium flags to reduce renderer/compositor noise
+            '--disable-background-timer-throttling', '--disable-backgrounding-occluded-windows', '--disable-renderer-backgrounding', '--disable-background-networking',
+            // Reduces environmental noise by disabling field trials,
+            // for more consistent profiling results.
+            '--enable-benchmarking',
+            // Forces software rendering instead of GPU, which is more deterministic.
+            '--disable-gpu', ...launchArgs]
+          }
+        })
+      },
+      fileParallelism: false,
+      reporters: ['default', ['@mui/internal-benchmark/reporter', {
+        outputPath
+      }]],
+      include: ['**/*.bench.tsx']
+    }
+  };
+}