benchforge 0.1.11 → 0.2.4

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "benchforge",
-  "version": "0.1.11",
+  "version": "0.2.4",
+  "description": "GC aware benchmarking/profiling, with an interactive viewer. For Node and browser.",
+  "license": "MIT",
+  "keywords": [
+    "benchmark",
+    "performance",
+    "profiling",
+    "bootstrap",
+    "gc",
+    "v8"
+  ],
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mighdoll/benchforge.git"
+  },
+  "homepage": "https://github.com/mighdoll/benchforge#readme",
+  "bugs": {
+    "url": "https://github.com/mighdoll/benchforge/issues"
+  },
   "bin": {
     "benchforge": "dist/bin/benchforge.mjs"
   },
@@ -16,45 +34,52 @@
     }
   },
   "dependencies": {
-    "esbuild": "^0.27.3",
+    "esbuild": "^0.27.4",
     "open": "^11.0.0",
     "picocolors": "^1.1.1",
+    "sirv": "^3.0.2",
     "table": "^6.9.0",
     "yargs": "^18.0.0"
   },
-  "peerDependencies": {
-    "playwright": ">=1.40.0"
-  },
-  "peerDependenciesMeta": {
-    "playwright": {
-      "optional": true
-    }
-  },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.4",
-    "@types/node": "^25.3.0",
+    "@biomejs/biome": "^2.4.9",
+    "@preact/signals": "^2.9.0",
+    "@observablehq/plot": "^0.6.17",
+    "@types/d3": "^7.4.3",
+    "@types/node": "^25.5.0",
     "@types/yargs": "^17.0.35",
-    "@typescript/native-preview": "7.0.0-dev.20260220.1",
+    "@typescript/native-preview": "7.0.0-dev.20260329.1",
+    "d3": "^7.9.0",
     "npm-run-all": "^4.1.5",
-    "playwright": "^1.58.0",
-    "tsdown": "0.20.3",
-    "vite": "^7.3.1",
-    "vitest": "^4.0.18"
+    "preact": "^10.29.0",
+    "playwright": "^1.58.2",
+    "shiki": "^4.0.2",
+    "tsdown": "0.21.7",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.2"
   },
   "scripts": {
-    "build": "tsdown",
-    "build:plots": "tsdown --config tsdown.plots.config.ts",
-    "example:node": "bin/benchforge examples/simple-cli.ts --gc-stats --heap-sample --html",
-    "example:bench": "bin/benchforge --url file://$PWD/examples/browser-bench/index.html --gc-stats --heap-sample --html",
-    "example:heap": "bin/benchforge --url file://$PWD/examples/browser-heap/index.html --heap-sample --gc-stats",
-    "example:lap": "bin/benchforge --url file://$PWD/examples/browser-lap/index.html --gc-stats --heap-sample --html",
+    "build": "tsdown && vite build --config vite.viewer.config.ts",
+    "build:lib": "tsdown",
+    "build:viewer": "vite build --config vite.viewer.config.ts",
+    "deploy:viewer": "run-s build:viewer pages:viewer:deploy",
+    "dev:viewer": "vite --config vite.viewer.config.ts",
+    "example:node": "bin/benchforge examples/simple-cli.ts --gc-stats --alloc --batches 5 --iterations 100 --view",
+    "example:stats": "bin/benchforge examples/simple-cli.ts --stats mean,p50,p95,p99,max --batches 5 --iterations 200 --view",
+    "example:time": "bin/benchforge examples/simple-cli.ts --alloc --time-sample --batches 5 --iterations 100 --view --filter quicksort",
+    "example:bench": "bin/benchforge --url file://$PWD/examples/browser-bench/index.html --gc-stats --headless --alloc --view",
+    "example:counts": "bin/benchforge examples/simple-cli.ts --alloc --time-sample --call-counts --view --iterations 5",
+    "example:heap": "bin/benchforge --url file://$PWD/examples/browser-heap/index.html --gc-stats --headless --view",
+    "example:page-load": "bin/benchforge --url file://$PWD/examples/browser-page-load/index.html --headless --page-load --alloc --time-sample --call-counts --gc-stats --batches 2 --iterations 2 --view",
+    "pages:viewer:deploy": "pnpx wrangler pages deploy --project-name benchforge-viewer dist/viewer",
     "fix": "biome check --fix --unsafe --error-on-warnings",
     "lint": "biome check --error-on-warnings",
     "test": "pnpm --node-options=--expose-gc vitest --hideSkippedTests --exclude '**/*.e2e.test.ts'",
-    "test:e2e": "pnpm --node-options=--expose-gc vitest run '.e2e.'",
+    "test:e2e": "pnpm --node-options=--expose-gc vitest run '.e2e.' --exclude '**/*.static.e2e.*'",
+    "test:static:e2e": "pnpm --node-options=--expose-gc vitest run '.static.e2e.'",
     "test:once": "pnpm --node-options=--expose-gc vitest run --exclude '**/*.e2e.test.ts'",
-    "typecheck": "tsgo",
-    "prepush": "run-s fix typecheck test:once build build:plots",
-    "publish:all": "pnpm publish && pnpm --filter benchforge-browser publish"
+    "typecheck": "tsgo && tsgo -p src/viewer",
+    "prepush": "run-s fix typecheck test:once build test:e2e test:static:e2e",
+    "publish:all": "pnpm publish"
   }
 }

package/src/bin/benchforge.ts

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import { runDefaultBench } from "../index.ts";
+import { dispatchCli } from "../cli/RunBenchCLI.ts";
 
-await runDefaultBench();
+await dispatchCli();

package/src/cli/AnalyzeArchive.ts

@@ -0,0 +1,232 @@
+/** Diagnostic analysis of a .benchforge archive's per-batch statistics. */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import colors from "../report/Colors.ts";
+import { formatSignedPercent, timeMs } from "../report/Formatters.ts";
+import {
+  average,
+  median,
+  percentile,
+  splitByOffsets,
+  tukeyFences,
+} from "../stats/StatisticalUtils.ts";
+import type { BenchmarkEntry, BenchmarkGroup } from "../viewer/ReportData.ts";
+
+const { bold, dim, red, green, yellow } = colors;
+
+const blockFenceMultiplier = 3;
+
+/** Read an archive and print per-batch diagnostic analysis.
+ * (for benchforge debugging/development purposes, not a general user tool)
+ */
+export async function analyzeArchive(filePath: string): Promise<void> {
+  const absPath = resolve(filePath);
+  const content = await readFile(absPath, "utf-8");
+  const { report } = JSON.parse(content);
+  if (!report?.groups?.length) {
+    console.error("No report data found in archive.");
+    return;
+  }
+  const batchCount = report.metadata?.cliArgs?.batches as number | undefined;
+  for (const group of report.groups) {
+    analyzeGroup(group, batchCount);
+  }
+}
+
+/** Print analysis for all benchmarks in a group. */
+function analyzeGroup(group: BenchmarkGroup, batchCount?: number): void {
+  console.log(bold(`\n=== ${group.name} ===\n`));
+
+  const baseline = group.baseline;
+  for (const bench of group.benchmarks) {
+    analyzeBenchmark(bench, baseline, batchCount);
+  }
+}
+
+/** Print per-batch analysis for one benchmark entry. */
+function analyzeBenchmark(
+  bench: BenchmarkEntry,
+  baseline: BenchmarkEntry | undefined,
+  batchCount?: number,
+): void {
+  const bOffsets =
+    bench.batchOffsets ?? inferOffsets(bench.samples, batchCount);
+  const baseOffsets =
+    baseline?.batchOffsets ?? inferOffsets(baseline?.samples, batchCount);
+  if (!bOffsets?.length) {
+    console.log(dim("  No batch data (single batch run)"));
+    return;
+  }
+
+  const batches = splitByOffsets(bench.samples, bOffsets);
+  const baseBatches =
+    baseOffsets && baseline
+      ? splitByOffsets(baseline.samples, baseOffsets)
+      : undefined;
+
+  printBatchHeader(bench, baseline, batches.length);
+  printBatchTable(batches, baseBatches);
+
+  if (baseBatches && baseBatches.length === batches.length) {
+    printOrderEffect(batches, baseBatches);
+    printPairedDeltas(batches, baseBatches);
+    printTrimmedBlocks(batches, baseBatches, bench.name);
+  }
+  console.log();
+}
+
+/** Infer equal-sized batch offsets when batchOffsets isn't in the archive. */
+function inferOffsets(
+  samples: number[] | undefined,
+  batchCount?: number,
+): number[] | undefined {
+  if (!samples?.length || !batchCount || batchCount <= 1) return undefined;
+  const size = Math.floor(samples.length / batchCount);
+  return Array.from({ length: batchCount }, (_, i) => i * size);
+}
+
+/** Print benchmark name with batch/run summary. */
+function printBatchHeader(
+  bench: BenchmarkEntry,
+  baseline: BenchmarkEntry | undefined,
+  nBatches: number,
+): void {
+  const baseRuns = baseline?.samples?.length;
+  const dur = bench.totalTime
+    ? (bench.totalTime / nBatches).toFixed(1) + "s"
+    : "?";
+  const runs = baseRuns
+    ? `${bench.samples.length}+${baseRuns} runs`
+    : `${bench.samples.length} runs`;
+  const info = dim(` (${nBatches} batches, ${runs}, ~${dur}/batch)`);
+  console.log(bold(`  ${bench.name}`) + info);
+}
+
+/** Print per-batch median table for current and baseline. */
+function printBatchTable(
+  benches: number[][],
+  baselines: number[][] | undefined,
+): void {
+  const header = baselines
+    ? `  ${"batch".padEnd(7)} ${"n".padStart(4)}  ${"current".padStart(10)}  ${"baseline".padStart(10)}  ${"delta".padStart(8)}`
+    : `  ${"batch".padEnd(7)} ${"n".padStart(4)}  ${"median".padStart(10)}`;
+  console.log(dim(header));
+
+  for (let i = 0; i < benches.length; i++) {
+    const n = String(benches[i].length).padStart(4);
+    const med = (timeMs(median(benches[i])) ?? "").padStart(10);
+    const idx = String(i).padEnd(7);
+    if (!baselines?.[i]) {
+      console.log(`  ${idx} ${n}  ${med}`);
+      continue;
+    }
+    const baseMed = (timeMs(median(baselines[i])) ?? "").padStart(10);
+    const delta = formatDelta(medianDelta(benches[i], baselines[i])).padStart(
+      8,
+    );
+    const order = i % 2 === 0 ? dim(" B>C") : dim(" C>B");
+    console.log(`  ${idx} ${n}  ${med}  ${baseMed}  ${delta}${order}`);
+  }
+}
+
+/** Analyze order effect: does running second make a difference? */
+function printOrderEffect(benches: number[][], baselines: number[][]): void {
+  // Even batches: baseline runs first (B>C), odd: current runs first (C>B)
+  const deltas = benches.map((b, i) => medianDelta(b, baselines[i]));
+  const baseFirstDeltas = deltas.filter((_, i) => i % 2 === 0);
+  const currFirstDeltas = deltas.filter((_, i) => i % 2 === 1);
+  const baseFirstAvg = baseFirstDeltas.length ? average(baseFirstDeltas) : 0;
+  const currFirstAvg = currFirstDeltas.length ? average(currFirstDeltas) : 0;
+
+  console.log();
+  console.log(bold("  Order effect:"));
+  console.log(
+    `    baseline first (B>C): avg delta ${formatDelta(baseFirstAvg)}` +
+      dim(` (${baseFirstDeltas.length} batches)`),
+  );
+  console.log(
+    `    current first  (C>B): avg delta ${formatDelta(currFirstAvg)}` +
+      dim(` (${currFirstDeltas.length} batches)`),
+  );
+
+  const diff = Math.abs(baseFirstAvg - currFirstAvg);
+  if (diff > 2) {
+    console.log(yellow(`    ==> ${diff.toFixed(1)}% order effect detected`));
+  } else {
+    console.log(dim(`    order effect: ${diff.toFixed(1)}% (small)`));
+  }
+}
+
+/** Print paired batch deltas and their consistency. */
+function printPairedDeltas(benches: number[][], baselines: number[][]): void {
+  const deltas = benches.map((b, i) => medianDelta(b, baselines[i]));
+
+  const positive = deltas.filter(d => d > 0).length;
+  const negative = deltas.filter(d => d < 0).length;
+  const avgDelta = average(deltas);
+  const med = median(deltas);
+  const spread = percentile(deltas, 0.75) - percentile(deltas, 0.25);
+
+  console.log();
+  console.log(bold("  Paired deltas:"));
+  console.log(
+    `    mean: ${formatDelta(avgDelta)}  median: ${formatDelta(med)}  IQR: ${spread.toFixed(1)}%`,
+  );
+  console.log(
+    `    direction: ${positive} slower, ${negative} faster` +
+      dim(` (${deltas.length} batches)`),
+  );
+
+  if (positive > 0 && negative > 0) {
+    console.log(green("    ==> batches disagree on direction"));
+  } else {
+    console.log(
+      red("    ==> all batches agree on direction (systematic bias?)"),
+    );
+  }
+}
+
+/** Show which blocks would be Tukey-trimmed per side. */
+function printTrimmedBlocks(
+  benches: number[][],
+  baselines: number[][],
+  name: string,
+): void {
+  console.log();
+  console.log(bold("  Trimmed blocks:"));
+  const baseMeans = baselines.map(b => average(b));
+  const benchMeans = benches.map(b => average(b));
+  printSideTrim("baseline", baseMeans);
+  printSideTrim(name, benchMeans);
+}
+
+/** Color a percent delta: red if >1%, green if <-1%. */
+function formatDelta(pct: number): string {
+  const str = formatSignedPercent(pct);
+  if (pct > 1) return red(str);
+  if (pct < -1) return green(str);
+  return str;
+}
+
+/** Percent delta between two medians. */
+function medianDelta(samples: number[], baseSamples: number[]): number {
+  const med = median(samples);
+  const baseMed = median(baseSamples);
+  return ((med - baseMed) / baseMed) * 100;
+}
+
+/** Print trimming info for one side using 3x IQR fences. */
+function printSideTrim(label: string, means: number[]): void {
+  const [, hi] = tukeyFences(means, blockFenceMultiplier);
+  const indices = means.map((v, i) => (v > hi ? i : -1)).filter(i => i >= 0);
+  if (indices.length === 0) {
+    console.log(dim(`    ${label}: 0 trimmed`));
+    return;
+  }
+  const vals = indices.map(i => timeMs(means[i]) ?? "?").join(", ");
+  const fence = `hi: ${timeMs(hi)}`;
+  console.log(
+    `    ${label}: ${yellow(`${indices.length} trimmed`)} (${vals})` +
+      dim(`  fence: ${fence}`),
+  );
+}

package/src/cli/BrowserBench.ts

@@ -0,0 +1,322 @@
+import {
+  type BrowserProfileResult,
+  type NavTiming,
+  profileBrowser,
+} from "../profiling/browser/BrowserProfiler.ts";
+import { launchChrome } from "../profiling/browser/ChromeLauncher.ts";
+import { isBrowserUserCode } from "../profiling/node/HeapSampleReport.ts";
+import type { ReportGroup, ReportSection } from "../report/BenchmarkReport.ts";
+import colors from "../report/Colors.ts";
+import {
+  browserGcStatsSection,
+  pageLoadStatsSections,
+} from "../report/GcSections.ts";
+import { buildTimeSection, runsSection } from "../report/StandardSections.ts";
+import { reportResults } from "../report/text/TextReport.ts";
+import type { MeasuredResults } from "../runners/MeasuredResults.ts";
+import {
+  type BatchProgress,
+  mergeGcStats,
+  runBatched,
+} from "../runners/MergeBatches.ts";
+import { computeStats } from "../runners/SampleStats.ts";
+import type { DefaultCliArgs } from "./CliArgs.ts";
+import { exportReports } from "./CliExport.ts";
+import {
+  cliHeapReportOptions,
+  needsAlloc,
+  needsProfile,
+  resolveLimits,
+} from "./CliOptions.ts";
+import { printHeapReports, withStatus } from "./CliReport.ts";
+
+/** State shared between makeTabRunner closures and runBatchedTabs. */
+type TabRunnerState = {
+  lastRaw?: BrowserProfileResult;
+  detectedPageLoad: boolean;
+};
+
+const { yellow } = colors;
+
+/** Run browser profiling via CDP and report with standard pipeline. */
+export async function browserBenchExports(args: DefaultCliArgs): Promise<void> {
+  warnBrowserFlags(args);
+  const params = buildBrowserParams(args);
+  const name = nameFromUrl(args.url!);
+  const baselineUrl = args["baseline-url"];
+
+  const needsBatching =
+    args.batches > 1 ||
+    !!baselineUrl ||
+    (args.iterations ?? 0) > 1 ||
+    params.pageLoad;
+  if (!needsBatching) {
+    const result = await profileBrowser(params);
+    const results = browserResultGroups(name, result);
+
+    printBrowserReport(result, results, args);
+    await exportReports({ results, args });
+    return;
+  }
+
+  const { lastRaw, results } = await runBrowserBatches(params, name, args);
+  printBrowserReport(lastRaw, results, args);
+  await exportReports({ results, args });
+}
+
+/** Warn about Node-only flags ignored in browser mode. */
+function warnBrowserFlags(args: DefaultCliArgs): void {
+  const checks: [boolean, string][] = [
+    [!args.worker, "--no-worker"],
+    [!!args["trace-opt"], "--trace-opt"],
+    [!!args["gc-force"], "--gc-force"],
+    [!!args.adaptive, "--adaptive"],
+  ];
+  const ignored = checks.filter(([active]) => active).map(([, flag]) => flag);
+  if (ignored.length > 0)
+    console.warn(yellow(`Ignored in browser mode: ${ignored.join(", ")}`));
+}
+
+/** Convert CLI args to browser profiler parameters. */
+function buildBrowserParams(args: DefaultCliArgs) {
+  const { maxTime, maxIterations } = resolveLimits(args);
+  const chromeArgs = args["chrome-args"]
+    ?.flatMap(a => a.split(/\s+/))
+    .map(stripQuotes)
+    .filter(Boolean);
+  return {
+    url: args.url!,
+    pageLoad: args["page-load"] || !!args["wait-for"],
+    maxTime,
+    maxIterations,
+    chromeArgs,
+    allocOptions: {
+      samplingInterval: args["alloc-interval"],
+      stackDepth: args["alloc-depth"],
+    },
+    alloc: needsAlloc(args),
+    profile: needsProfile(args),
+    profileInterval: args["profile-interval"],
+    headless: args.headless,
+    chromePath: args.chrome,
+    chromeProfile: args["chrome-profile"],
+    timeout: args.timeout,
+    gcStats: args["gc-stats"],
+    callCounts: args["call-counts"],
+    waitFor: args["wait-for"],
+  };
+}
+
+/** Extract a short name from a URL for report labels. */
+function nameFromUrl(url: string): string {
+  return new URL(url).pathname.split("/").pop() || "browser";
+}
+
+/** Wrap browser profile result as ReportGroup[] for the standard export pipeline. */
+function browserResultGroups(
+  name: string,
+  result: BrowserProfileResult,
+): ReportGroup[] {
+  const measuredResults = toBrowserMeasured(name, result);
+  return [{ name, reports: [{ name, measuredResults }] }];
+}
+
+/** Print text report and optional heap profile for browser results. */
+function printBrowserReport(
+  result: BrowserProfileResult,
+  results: ReportGroup[],
+  args: DefaultCliArgs,
+): void {
+  const mr = results[0]?.reports[0]?.measuredResults;
+  const hasPageLoad = (mr?.navTimings?.length ?? 0) > 0 || !!result.navTiming;
+  const hasIterSamples = !!result.samples?.length;
+  const sections: ReportSection[] = [
+    ...(hasPageLoad ? pageLoadStatsSections : []),
+    ...(hasIterSamples ? [buildTimeSection(args.stats)] : []),
+    ...(result.gcStats ? [browserGcStatsSection] : []),
+    ...(hasPageLoad || hasIterSamples ? [runsSection] : []),
+  ];
+  if (sections.length > 0) {
+    console.log(
+      withStatus("computing report", () => reportResults(results, sections)),
+    );
+  }
+  if (!result.heapProfile) return;
+  printHeapReports(results, {
+    ...cliHeapReportOptions(args),
+    isUserCode: isBrowserUserCode,
+  });
+}
+
+/** Launch Chrome, run batched fresh tabs, merge results. */
+async function runBrowserBatches(
+  params: ReturnType<typeof buildBrowserParams>,
+  name: string,
+  args: DefaultCliArgs,
+): Promise<{ lastRaw: BrowserProfileResult; results: ReportGroup[] }> {
+  const { headless, chrome: chromePath } = args;
+  const chromeProfile = args["chrome-profile"];
+  const chrome = await launchChrome({
+    headless,
+    chromePath,
+    chromeProfile,
+    args: params.chromeArgs,
+  });
+  try {
+    return await runBatchedTabs(params, name, args, chrome);
+  } finally {
+    await chrome.close();
+  }
+}
+
+/** Strip surrounding quotes from a chrome-args token. */
+function stripQuotes(s: string): string {
+  const bare = s.replace(/^(['"])(.*)\1$/s, "$2");
+  return bare.replace(/^(-[^=]+=)(['"])(.*)\2$/s, "$1$3");
+}
+
+/** Convert a browser profile result into a MeasuredResults for the report pipeline. */
+function toBrowserMeasured(
+  name: string,
+  result: BrowserProfileResult,
+): MeasuredResults {
+  const { gcStats, heapProfile, timeProfile, coverage, navTiming, samples } =
+    result;
+  const navTimings = navTiming ? [navTiming] : undefined;
+  const base = {
+    name,
+    gcStats,
+    heapProfile,
+    timeProfile,
+    coverage,
+    navTimings,
+  };
+
+  if (samples?.length) {
+    const totalTime = result.wallTimeMs ? result.wallTimeMs / 1000 : undefined;
+    return { ...base, samples, time: computeStats(samples), totalTime };
+  }
+  const wallTime = result.wallTimeMs ?? 0;
+  return { ...base, samples: [wallTime], time: computeStats([wallTime]) };
+}
+
+/** Execute batched browser tabs within an already-launched Chrome instance. */
+async function runBatchedTabs(
+  params: ReturnType<typeof buildBrowserParams>,
+  name: string,
+  args: DefaultCliArgs,
+  chrome: any,
+): Promise<{ lastRaw: BrowserProfileResult; results: ReportGroup[] }> {
+  const baselineUrl = args["baseline-url"];
+  const { maxTime, maxIterations } = params;
+  const limits = { maxTime, maxIterations };
+  const state: TabRunnerState = { detectedPageLoad: params.pageLoad };
+
+  const warmup = !(args["warmup-batch"] ?? false) && args.batches > 1;
+  const mk = (url: string, label: string) =>
+    makeTabRunner(params, chrome, limits, warmup, state, url, label);
+  const runCurrent = mk(params.url, name);
+  const runBaseline = baselineUrl
+    ? mk(baselineUrl, nameFromUrl(baselineUrl))
+    : undefined;
+
+  const progress = (p: BatchProgress) => {
+    const sec = (p.elapsed / 1000).toFixed(0);
+    const msg = `\r◊ batch ${p.batch + 1}/${p.batches} ${p.label} (${sec}s)   `;
+    process.stderr.write(msg);
+  };
+
+  const {
+    results: [current],
+    baseline,
+  } = await runBatched(
+    [runCurrent],
+    runBaseline,
+    Math.max(args.batches, 2),
+    args["warmup-batch"] ?? false,
+    progress,
+  );
+  process.stderr.write("\r" + " ".repeat(50) + "\r");
+
+  const baseName = baselineUrl ? nameFromUrl(baselineUrl) : undefined;
+  const baselineEntry =
+    baseline && baseName
+      ? { name: baseName, measuredResults: baseline }
+      : undefined;
+  const reports = [{ name, measuredResults: current }];
+  return {
+    lastRaw: state.lastRaw!,
+    results: [{ name, reports, baseline: baselineEntry }],
+  };
+}
+
+/** Create a batch runner closure for a single URL (current or baseline). */
+function makeTabRunner(
+  params: ReturnType<typeof buildBrowserParams>,
+  chrome: any,
+  limits: { maxTime?: number; maxIterations?: number },
+  warmup: boolean,
+  state: TabRunnerState,
+  url: string,
+  label: string,
+): () => Promise<MeasuredResults> {
+  let firstCall = warmup;
+  return async () => {
+    const isWarmup = firstCall;
+    firstCall = false;
+    const p = { ...params, chrome, url };
+    if (state.detectedPageLoad) {
+      const batchLimits = isWarmup ? { maxIterations: 1 } : limits;
+      const result = await runMultiPageLoad(
+        { ...p, pageLoad: true },
+        label,
+        batchLimits,
+      );
+      state.lastRaw ??= {
+        navTiming: result.navTimings?.[0],
+        wallTimeMs: result.time.p50,
+      };
+      return result;
+    }
+    const raw = await profileBrowser(p);
+    state.lastRaw = raw;
+    // Probe: if no iteration samples and navTiming present, it's page-load mode
+    if (!raw.samples?.length && raw.navTiming) state.detectedPageLoad = true;
+    return toBrowserMeasured(label, raw);
+  };
+}
+
+/** Run page loads until duration or iteration limit, collecting wallTimeMs as samples. */
+async function runMultiPageLoad(
+  params: any, // BrowserProfileParams with chrome attached by caller
+  name: string,
+  limits: { maxTime?: number; maxIterations?: number },
+): Promise<MeasuredResults> {
+  const { maxTime, maxIterations } = limits;
+  const raws: BrowserProfileResult[] = [];
+  let accumulated = 0;
+  for (let i = 0; ; i++) {
+    if (maxIterations != null && i >= maxIterations) break;
+    const raw = await profileBrowser(params);
+    raws.push(raw);
+    accumulated += raw.wallTimeMs ?? 0;
+    if (maxTime != null && accumulated >= maxTime) break;
+  }
+
+  const samples = raws.map(r => r.wallTimeMs ?? 0);
+  const navTimings = raws.map(r => r.navTiming).filter(Boolean) as NavTiming[];
+  const { heapProfile, timeProfile, coverage } = raws[raws.length - 1];
+  const totalTime = accumulated / 1000;
+  const gcStats = mergeGcStats(raws);
+  return {
+    name,
+    samples,
+    time: computeStats(samples),
+    totalTime,
+    navTimings: navTimings.length ? navTimings : undefined,
+    gcStats,
+    heapProfile,
+    timeProfile,
+    coverage,
+  };
+}