benchforge 0.1.2 → 0.1.4

package/README.md

@@ -151,18 +151,17 @@ The `--profile` flag executes exactly one iteration with no warmup, making it id
 Results are displayed in a formatted table:
 
 ```
-╔═════════════════╤═══════════════════════════════════════════╤═══════╤═════════╗
-║                 │                   time                    │       │         ║
-║ name            │ mean  Δ% CI                    p50   p99  │ conv% │ runs    ║
-╟─────────────────┼───────────────────────────────────────────┼───────┼─────────╢
-║ quicksort       │ 0.17  +5.5% [+4.7%, +6.2%]     0.15  0.63 │ 100%  │ 1,134   ║
-║ insertion sort  │ 0.24  +25.9% [+25.3%, +27.4%]  0.18  0.36 │ 100%  │ 807     ║
-║ --> native sort │ 0.16                           0.15  0.41 │ 100%  │ 1,210   ║
-╚═════════════════╧═══════════════════════════════════════════╧═══════╧═════════╝
+╔═════════════════╤═══════════════════════════════════════════╤═════════╗
+║                 │                   time                    │         ║
+║ name            │ mean  Δ% CI                    p50   p99  │ runs    ║
+╟─────────────────┼───────────────────────────────────────────┼─────────╢
+║ quicksort       │ 0.17  +5.5% [+4.7%, +6.2%]     0.15  0.63 │ 1,134   ║
+║ insertion sort  │ 0.24  +25.9% [+25.3%, +27.4%]  0.18  0.36 │ 807     ║
+║ --> native sort │ 0.16                           0.15  0.41 │ 1,210   ║
+╚═════════════════╧═══════════════════════════════════════════╧═════════╝
 ```
 
 - **Δ% CI**: Percentage difference from baseline with bootstrap confidence interval
-- **conv%**: Convergence percentage (100% = stable measurements)
 
 ### HTML
 
@@ -284,136 +283,23 @@ V8's sampling profiler uses Poisson-distributed sampling. When an allocation occ
 - Node.js 22.6+ (for native TypeScript support)
 - Use `--expose-gc --allow-natives-syntax` flags for garbage collection monitoring and V8 native functions
 
-## Adaptive Mode
+## Adaptive Mode (Experimental)
 
-Adaptive mode automatically adjusts the number of benchmark iterations until measurements stabilize, providing statistically significant results without excessive runtime.
+Adaptive mode (`--adaptive`) automatically adjusts iteration count until measurements stabilize. The algorithm is still being tuned — use `--help` for available options.
 
-### Using Adaptive Mode
+## Interpreting Results
 
-```bash
-# Enable adaptive benchmarking with default settings
-simple-cli.ts --adaptive
-
-# Customize time limits
-simple-cli.ts --adaptive --time 60 --min-time 5
-
-# Combine with other options
-simple-cli.ts --adaptive --filter "quicksort"
-```
-
-### CLI Options for Adaptive Mode
-
-- `--adaptive` - Enable adaptive sampling mode
-- `--min-time <seconds>` - Minimum time before convergence can stop (default: 1s)
-- `--convergence <percent>` - Confidence threshold 0-100 (default: 95)
-- `--time <seconds>` - Maximum time limit (default: 20s in adaptive mode)
-
-### How It Works
-
-1. **Initial Sampling**: Collects initial batch of ~100 samples (includes warmup)
-2. **Window Comparison**: Compares recent samples against previous window
-3. **Stability Detection**: Checks median drift and outlier impact between windows
-4. **Convergence**: Stops when both metrics are stable (<5% drift) or reaches threshold
-
-Progress is shown during execution:
-```
-◊ quicksort: 75% confident (2.1s)
-```
-
-### Output with Adaptive Mode
-
-```
-╔═════════════════╤═════════════════════════════════════════════╤═══════╤═════════╤══════╗
-║                 │                    time                     │       │         │      ║
-║ name            │ median  Δ% CI                    mean  p99  │ conv% │ runs    │ time ║
-╟─────────────────┼─────────────────────────────────────────────┼───────┼─────────┼──────╢
-║ quicksort       │ 0.17    +17.3% [+15.4%, +20.0%]  0.20  0.65 │ 100%  │ 526     │ 0.0s ║
-║ insertion sort  │ 0.18    +24.2% [+23.9%, +24.6%]  0.19  0.36 │ 100%  │ 529     │ 0.0s ║
-║ --> native sort │ 0.15                             0.15  0.25 │ 100%  │ 647     │ 0.0s ║
-╚═════════════════╧═════════════════════════════════════════════╧═══════╧═════════╧══════╝
-```
-
-- **conv%**: Convergence percentage (100% = stable measurements)
-- **time**: Total sampling duration for that benchmark
-
-## Statistical Considerations: Mean vs Median
-
-### When to Use Mean with Confidence Intervals
-
-**Best for:**
-- **Normally distributed data** - When benchmark times follow a bell curve
-- **Statistical comparison** - Comparing performance between implementations
-- **Throughput analysis** - Understanding average system performance
-- **Resource planning** - Estimating typical resource usage
-
-**Advantages:**
-- Provides confidence intervals for statistical significance
-- Captures the full distribution including outliers
-- Better for detecting small but consistent performance differences
-- Standard in academic performance research
-
-**Example use cases:**
-- Comparing algorithm implementations
-- Measuring API response times under normal load
-- Evaluating compiler optimizations
-- Benchmarking pure computational functions
-
-### When to Use Median (p50)
-
-**Best for:**
-- **Skewed distributions** - When outliers are common
-- **Latency-sensitive applications** - Where typical user experience matters
-- **Noisy environments** - Systems with unpredictable interference
-- **Service Level Agreements** - "50% of requests complete within X ms"
-
-**Advantages:**
-- Robust to outliers and system noise
-- Better represents "typical" performance
-- More stable in virtualized/cloud environments
-- Less affected by GC pauses and OS scheduling
-
-**Example use cases:**
-- Web server response times
-- Database query performance
-- UI responsiveness metrics
-- Real-time system benchmarks
-
-### Interpreting Results
-
-#### Baseline Comparison (Δ% CI)
+### Baseline Comparison (Δ% CI)
 ```
 0.17  +5.5% [+4.7%, +6.2%]
 ```
-This shows the benchmark is 5.5% slower than baseline, with a bootstrap confidence interval of [+4.7%, +6.2%]. Use this for comparing implementations.
+The benchmark is 5.5% slower than baseline, with a bootstrap confidence interval of [+4.7%, +6.2%].
 
-#### Percentiles
+### Percentiles
 ```
 p50: 0.15ms, p99: 0.27ms
 ```
-This shows that 50% of runs completed in ≤0.15ms and 99% in ≤0.27ms. Use this when you care about consistency and tail latencies.
-
-### Practical Guidelines
-
-1. **Use adaptive mode when:**
-   - You want automatic convergence detection
-   - Benchmarks have varying execution times
-   - You need stable measurements without guessing iteration counts
-
-2. **Use fixed iterations when:**
-   - Comparing across runs/machines (reproducibility)
-   - You know roughly how many samples you need
-   - Running in CI pipelines with time constraints
-
-3. **Interpreting conv%:**
-   - 100% = measurements are stable
-   - <100% = still converging or high variance
-   - Red color indicates low confidence
-
-### Statistical Notes
-
-- **Bootstrap CI**: Baseline comparison uses permutation testing with bootstrap confidence intervals
-- **Window Stability**: Adaptive mode compares sliding windows for median drift and outlier impact
-- **Independence**: Assumes benchmark iterations are independent (use `--worker` flag for better isolation)
+50% of runs completed in ≤0.15ms and 99% in ≤0.27ms. Use percentiles when you care about consistency and tail latencies.
 
 ## Understanding GC Time Measurements
 

package/dist/{BenchRunner-BLfGX2wQ.d.mts → BenchRunner-CSKN9zPy.d.mts}

@@ -222,4 +222,4 @@ interface RunnerOptions {
 }
 //#endregion
 export { MeasuredResults as a, BenchmarkSpec as i, BenchGroup as n, HeapProfile as o, BenchSuite as r, RunnerOptions as t };
-//# sourceMappingURL=BenchRunner-BLfGX2wQ.d.mts.map
+//# sourceMappingURL=BenchRunner-CSKN9zPy.d.mts.map

package/dist/BrowserHeapSampler-DQwmmuDu.mjs

@@ -0,0 +1,187 @@
+import { t as aggregateGcStats } from "./GcStats-ByEovUi1.mjs";
+import { chromium } from "playwright";
+
+//#region src/browser/BrowserGcStats.ts
+/** Parse CDP trace events (MinorGC/MajorGC) into GcEvent[] */
+function parseGcTraceEvents(traceEvents) {
+	return traceEvents.flatMap((e) => {
+		if (e.ph !== "X") return [];
+		const type = gcType(e.name);
+		if (!type) return [];
+		const durUs = e.dur ?? 0;
+		const heapBefore = e.args?.usedHeapSizeBefore ?? 0;
+		const heapAfter = e.args?.usedHeapSizeAfter ?? 0;
+		return [{
+			type,
+			pauseMs: durUs / 1e3,
+			collected: Math.max(0, heapBefore - heapAfter)
+		}];
+	});
+}
+function gcType(name) {
+	if (name === "MinorGC") return "scavenge";
+	if (name === "MajorGC") return "mark-compact";
+}
+/** Parse CDP trace events and aggregate into GcStats */
+function browserGcStats(traceEvents) {
+	return aggregateGcStats(parseGcTraceEvents(traceEvents));
+}
+
+//#endregion
+//#region src/browser/BrowserHeapSampler.ts
+/** Run browser benchmark, auto-detecting page API mode.
+*  Bench function (window.__bench): CLI controls iteration and timing.
+*  Lap mode (__start/__lap/__done): page controls the measured region. */
+async function profileBrowser(params) {
+	const { url, headless = true, chromeArgs, timeout = 60 } = params;
+	const { gcStats: collectGc } = params;
+	const { samplingInterval = 32768 } = params.heapOptions ?? {};
+	const browser = await chromium.launch({
+		headless,
+		args: chromeArgs
+	});
+	try {
+		const page = await browser.newPage();
+		page.setDefaultTimeout(timeout * 1e3);
+		const cdp = await page.context().newCDPSession(page);
+		const pageErrors = [];
+		page.on("pageerror", (err) => pageErrors.push(err.message));
+		const traceEvents = collectGc ? await startGcTracing(cdp) : [];
+		const lapMode = await setupLapMode(page, cdp, params, samplingInterval, timeout, pageErrors);
+		await page.goto(url, { waitUntil: "load" });
+		const hasBench = await page.evaluate(() => typeof globalThis.__bench === "function");
+		let result;
+		if (hasBench) {
+			lapMode.cancel();
+			lapMode.promise.catch(() => {});
+			result = await runBenchLoop(page, cdp, params, samplingInterval);
+		} else {
+			result = await lapMode.promise;
+			lapMode.cancel();
+		}
+		if (collectGc) result = {
+			...result,
+			gcStats: await collectTracing(cdp, traceEvents)
+		};
+		return result;
+	} finally {
+		await browser.close();
+	}
+}
+/** Inject __start/__lap as in-page functions, expose __done for results collection.
+*  __start/__lap are pure in-page (zero CDP overhead). First __start() triggers
+*  instrument start. __done() stops instruments and collects timing data. */
+async function setupLapMode(page, cdp, params, samplingInterval, timeout, pageErrors) {
+	const { heapSample } = params;
+	const { promise, resolve, reject } = Promise.withResolvers();
+	let instrumentsStarted = false;
+	await page.exposeFunction("__benchInstrumentStart", async () => {
+		if (instrumentsStarted) return;
+		instrumentsStarted = true;
+		if (heapSample) await cdp.send("HeapProfiler.startSampling", heapSamplingParams(samplingInterval));
+	});
+	await page.exposeFunction("__benchCollect", async (samples, wallTimeMs) => {
+		let heapProfile;
+		if (heapSample && instrumentsStarted) heapProfile = (await cdp.send("HeapProfiler.stopSampling")).profile;
+		resolve({
+			samples,
+			heapProfile,
+			wallTimeMs
+		});
+	});
+	await page.addInitScript(injectLapFunctions);
+	const timer = setTimeout(() => {
+		const lines = [`Timed out after ${timeout}s`];
+		if (pageErrors.length) lines.push("Page JS errors:", ...pageErrors.map((e) => `  ${e}`));
+		else lines.push("Page did not call __done() or define window.__bench");
+		reject(new Error(lines.join("\n")));
+	}, timeout * 1e3);
+	return {
+		promise,
+		cancel: () => clearTimeout(timer)
+	};
+}
+/** In-page timing functions injected via addInitScript (zero CDP overhead).
+*  __start/__lap collect timestamps, __done delegates to exposed __benchCollect. */
+function injectLapFunctions() {
+	const g = globalThis;
+	g.__benchSamples = [];
+	g.__benchLastTime = 0;
+	g.__benchFirstStart = 0;
+	g.__start = () => {
+		const now = performance.now();
+		g.__benchLastTime = now;
+		if (!g.__benchFirstStart) {
+			g.__benchFirstStart = now;
+			return g.__benchInstrumentStart();
+		}
+	};
+	g.__lap = () => {
+		const now = performance.now();
+		g.__benchSamples.push(now - g.__benchLastTime);
+		g.__benchLastTime = now;
+	};
+	g.__done = () => {
+		const wall = g.__benchFirstStart ? performance.now() - g.__benchFirstStart : 0;
+		return g.__benchCollect(g.__benchSamples.slice(), wall);
+	};
+}
+function heapSamplingParams(samplingInterval) {
+	return {
+		samplingInterval,
+		includeObjectsCollectedByMajorGC: true,
+		includeObjectsCollectedByMinorGC: true
+	};
+}
+/** Start CDP GC tracing, returns the event collector array. */
+async function startGcTracing(cdp) {
+	const events = [];
+	cdp.on("Tracing.dataCollected", ({ value }) => {
+		for (const e of value) events.push(e);
+	});
+	await cdp.send("Tracing.start", { traceConfig: { includedCategories: ["v8", "v8.gc"] } });
+	return events;
+}
+/** Bench function mode: run window.__bench in a timed iteration loop. */
+async function runBenchLoop(page, cdp, params, samplingInterval) {
+	const { heapSample } = params;
+	const maxTime = params.maxTime ?? 642;
+	const maxIter = params.maxIterations ?? Number.MAX_SAFE_INTEGER;
+	if (heapSample) await cdp.send("HeapProfiler.startSampling", heapSamplingParams(samplingInterval));
+	const { samples, totalMs } = await page.evaluate(async ({ maxTime, maxIter }) => {
+		const bench = globalThis.__bench;
+		const samples = [];
+		const startAll = performance.now();
+		const deadline = startAll + maxTime;
+		for (let i = 0; i < maxIter && performance.now() < deadline; i++) {
+			const t0 = performance.now();
+			await bench();
+			samples.push(performance.now() - t0);
+		}
+		return {
+			samples,
+			totalMs: performance.now() - startAll
+		};
+	}, {
+		maxTime,
+		maxIter
+	});
+	let heapProfile;
+	if (heapSample) heapProfile = (await cdp.send("HeapProfiler.stopSampling")).profile;
+	return {
+		samples,
+		heapProfile,
+		wallTimeMs: totalMs
+	};
+}
+/** Stop CDP tracing and parse GC events into GcStats. */
+async function collectTracing(cdp, traceEvents) {
+	const complete = new Promise((resolve) => cdp.once("Tracing.tracingComplete", () => resolve()));
+	await cdp.send("Tracing.end");
+	await complete;
+	return browserGcStats(traceEvents);
+}
+
+//#endregion
+export { profileBrowser, profileBrowser as profileBrowserHeap };
+//# sourceMappingURL=BrowserHeapSampler-DQwmmuDu.mjs.map

package/dist/BrowserHeapSampler-DQwmmuDu.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserHeapSampler-DQwmmuDu.mjs","names":[],"sources":["../src/browser/BrowserGcStats.ts","../src/browser/BrowserHeapSampler.ts"],"sourcesContent":["import {\n  aggregateGcStats,\n  type GcEvent,\n  type GcStats,\n} from \"../runners/GcStats.ts\";\n\n/** CDP trace event from Tracing.dataCollected */\nexport interface TraceEvent {\n  cat: string;\n  name: string;\n  ph: string;\n  dur?: number; // microseconds\n  args?: Record<string, any>;\n}\n\n/** Parse CDP trace events (MinorGC/MajorGC) into GcEvent[] */\nexport function parseGcTraceEvents(traceEvents: TraceEvent[]): GcEvent[] {\n  return traceEvents.flatMap(e => {\n    if (e.ph !== \"X\") return [];\n    const type = gcType(e.name);\n    if (!type) return [];\n    const durUs = e.dur ?? 0;\n    const heapBefore: number = e.args?.usedHeapSizeBefore ?? 0;\n    const heapAfter: number = e.args?.usedHeapSizeAfter ?? 0;\n    return [\n      {\n        type,\n        pauseMs: durUs / 1000,\n        collected: Math.max(0, heapBefore - heapAfter),\n      },\n    ];\n  });\n}\n\nfunction gcType(name: string): GcEvent[\"type\"] | undefined {\n  if (name === \"MinorGC\") return \"scavenge\";\n  if (name === \"MajorGC\") return \"mark-compact\";\n  return undefined;\n}\n\n/** Parse CDP trace events and aggregate into GcStats */\nexport function browserGcStats(traceEvents: TraceEvent[]): GcStats {\n  return aggregateGcStats(parseGcTraceEvents(traceEvents));\n}\n","import { type CDPSession, chromium, type Page } from \"playwright\";\nimport type {\n  HeapProfile,\n  HeapSampleOptions,\n} from \"../heap-sample/HeapSampler.ts\";\nimport type { GcStats } from \"../runners/GcStats.ts\";\nimport { browserGcStats, type TraceEvent } from \"./BrowserGcStats.ts\";\n\nexport interface BrowserProfileParams {\n  url: string;\n  heapSample?: boolean;\n  heapOptions?: HeapSampleOptions;\n  gcStats?: boolean;\n  headless?: boolean;\n  chromeArgs?: string[];\n  timeout?: number; // seconds\n  maxTime?: number; // ms, bench function iteration time limit\n  maxIterations?: number; // exact iteration count (bench function mode)\n}\n\nexport interface BrowserProfileResult {\n  heapProfile?: HeapProfile;\n  gcStats?: GcStats;\n  /** Wall-clock ms (lap mode: first start to done, bench function: total loop) */\n  wallTimeMs?: number;\n  /** Per-iteration timing samples (ms) from bench function or lap mode */\n  samples?: number[];\n}\n\ninterface LapModeHandle {\n  promise: Promise<BrowserProfileResult>;\n  cancel: () => void;\n}\n\n/** Run browser benchmark, auto-detecting page API mode.\n *  Bench function (window.__bench): CLI controls iteration and timing.\n *  Lap mode (__start/__lap/__done): page controls the measured region. */\nexport async function profileBrowser(\n  params: BrowserProfileParams,\n): Promise<BrowserProfileResult> {\n  const { url, headless = true, chromeArgs, timeout = 60 } = params;\n  const { gcStats: collectGc } = params;\n  const { samplingInterval = 32768 } = params.heapOptions ?? {};\n\n  const browser = await chromium.launch({ headless, args: chromeArgs });\n  try {\n    const page = await browser.newPage();\n    page.setDefaultTimeout(timeout * 1000);\n    const cdp = await page.context().newCDPSession(page);\n\n    const pageErrors: string[] = [];\n    page.on(\"pageerror\", err => pageErrors.push(err.message));\n\n    const traceEvents = collectGc ? await startGcTracing(cdp) : [];\n    const lapMode = await setupLapMode(\n      page,\n      cdp,\n      params,\n      samplingInterval,\n      timeout,\n      pageErrors,\n    );\n\n    await page.goto(url, { waitUntil: \"load\" });\n    const hasBench = await page.evaluate(\n      () => typeof (globalThis as any).__bench === \"function\",\n    );\n\n    let result: BrowserProfileResult;\n    if (hasBench) {\n      lapMode.cancel();\n      lapMode.promise.catch(() => {}); // suppress unused rejection\n      result = await runBenchLoop(page, cdp, params, samplingInterval);\n    } else {\n      result = await lapMode.promise;\n      lapMode.cancel();\n    }\n\n    if (collectGc) {\n      result = { ...result, gcStats: await collectTracing(cdp, traceEvents) };\n    }\n    return result;\n  } finally {\n    await browser.close();\n  }\n}\n\n/** Inject __start/__lap as in-page functions, expose __done for results collection.\n *  __start/__lap are pure in-page (zero CDP overhead). First __start() triggers\n *  instrument start. __done() stops instruments and collects timing data. */\nasync function setupLapMode(\n  page: Page,\n  cdp: CDPSession,\n  params: BrowserProfileParams,\n  samplingInterval: number,\n  timeout: number,\n  pageErrors: string[],\n): Promise<LapModeHandle> {\n  const { heapSample } = params;\n  const { promise, resolve, reject } =\n    Promise.withResolvers<BrowserProfileResult>();\n  let instrumentsStarted = false;\n\n  await page.exposeFunction(\"__benchInstrumentStart\", async () => {\n    if (instrumentsStarted) return;\n    instrumentsStarted = true;\n    if (heapSample) {\n      await cdp.send(\n        \"HeapProfiler.startSampling\",\n        heapSamplingParams(samplingInterval),\n      );\n    }\n  });\n\n  await page.exposeFunction(\n    \"__benchCollect\",\n    async (samples: number[], wallTimeMs: number) => {\n      let heapProfile: HeapProfile | undefined;\n      if (heapSample && instrumentsStarted) {\n        const result = await cdp.send(\"HeapProfiler.stopSampling\");\n        heapProfile = result.profile as unknown as HeapProfile;\n      }\n      resolve({ samples, heapProfile, wallTimeMs });\n    },\n  );\n\n  await page.addInitScript(injectLapFunctions);\n\n  const timer = setTimeout(() => {\n    const lines = [`Timed out after ${timeout}s`];\n    if (pageErrors.length) {\n      lines.push(\"Page JS errors:\", ...pageErrors.map(e => `  ${e}`));\n    } else {\n      lines.push(\"Page did not call __done() or define window.__bench\");\n    }\n    reject(new Error(lines.join(\"\\n\")));\n  }, timeout * 1000);\n\n  return { promise, cancel: () => clearTimeout(timer) };\n}\n\n/** In-page timing functions injected via addInitScript (zero CDP overhead).\n *  __start/__lap collect timestamps, __done delegates to exposed __benchCollect. */\nfunction injectLapFunctions(): void {\n  const g = globalThis as any;\n  g.__benchSamples = [];\n  g.__benchLastTime = 0;\n  g.__benchFirstStart = 0;\n\n  g.__start = () => {\n    const now = performance.now();\n    g.__benchLastTime = now;\n    if (!g.__benchFirstStart) {\n      g.__benchFirstStart = now;\n      return g.__benchInstrumentStart();\n    }\n  };\n\n  g.__lap = () => {\n    const now = performance.now();\n    g.__benchSamples.push(now - g.__benchLastTime);\n    g.__benchLastTime = now;\n  };\n\n  g.__done = () => {\n    const wall = g.__benchFirstStart\n      ? performance.now() - g.__benchFirstStart\n      : 0;\n    return g.__benchCollect(g.__benchSamples.slice(), wall);\n  };\n}\n\nfunction heapSamplingParams(samplingInterval: number) {\n  return {\n    samplingInterval,\n    includeObjectsCollectedByMajorGC: true,\n    includeObjectsCollectedByMinorGC: true,\n  };\n}\n\n/** Start CDP GC tracing, returns the event collector array. */\nasync function startGcTracing(cdp: CDPSession): Promise<TraceEvent[]> {\n  const events: TraceEvent[] = [];\n  cdp.on(\"Tracing.dataCollected\", ({ value }) => {\n    for (const e of value) events.push(e as unknown as TraceEvent);\n  });\n  await cdp.send(\"Tracing.start\", {\n    traceConfig: { includedCategories: [\"v8\", \"v8.gc\"] },\n  });\n  return events;\n}\n\n/** Bench function mode: run window.__bench in a timed iteration loop. */\nasync function runBenchLoop(\n  page: Page,\n  cdp: CDPSession,\n  params: BrowserProfileParams,\n  samplingInterval: number,\n): Promise<BrowserProfileResult> {\n  const { heapSample } = params;\n  const maxTime = params.maxTime ?? 642;\n  const maxIter = params.maxIterations ?? Number.MAX_SAFE_INTEGER;\n\n  if (heapSample) {\n    await cdp.send(\n      \"HeapProfiler.startSampling\",\n      heapSamplingParams(samplingInterval),\n    );\n  }\n\n  const { samples, totalMs } = await page.evaluate(\n    async ({ maxTime, maxIter }) => {\n      const bench = (globalThis as any).__bench;\n      const samples: number[] = [];\n      const startAll = performance.now();\n      const deadline = startAll + maxTime;\n      for (let i = 0; i < maxIter && performance.now() < deadline; i++) {\n        const t0 = performance.now();\n        await bench();\n        samples.push(performance.now() - t0);\n      }\n      return { samples, totalMs: performance.now() - startAll };\n    },\n    { maxTime, maxIter },\n  );\n\n  let heapProfile: HeapProfile | undefined;\n  if (heapSample) {\n    const result = await cdp.send(\"HeapProfiler.stopSampling\");\n    heapProfile = result.profile as unknown as HeapProfile;\n  }\n\n  return { samples, heapProfile, wallTimeMs: totalMs };\n}\n\n/** Stop CDP tracing and parse GC events into GcStats. */\nasync function collectTracing(\n  cdp: CDPSession,\n  traceEvents: TraceEvent[],\n): Promise<GcStats> {\n  const complete = new Promise<void>(resolve =>\n    cdp.once(\"Tracing.tracingComplete\", () => resolve()),\n  );\n  await cdp.send(\"Tracing.end\");\n  await complete;\n  return browserGcStats(traceEvents);\n}\n\nexport { profileBrowser as profileBrowserHeap };\n"],"mappings":"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"}

package/dist/GcStats-ByEovUi1.mjs

@@ -0,0 +1,77 @@
+//#region src/runners/GcStats.ts
+/** Parse a single --trace-gc-nvp stderr line */
+function parseGcLine(line) {
+	if (!line.includes("pause=")) return void 0;
+	const fields = parseNvpFields(line);
+	if (!fields.gc) return void 0;
+	const int = (k) => Number.parseInt(fields[k] || "0", 10);
+	const type = parseGcType(fields.gc);
+	const pauseMs = Number.parseFloat(fields.pause || "0");
+	const allocated = int("allocated");
+	const promoted = int("promoted");
+	const survived = int("new_space_survived") || int("survived");
+	const startSize = int("start_object_size");
+	const endSize = int("end_object_size");
+	const collected = startSize > endSize ? startSize - endSize : 0;
+	if (Number.isNaN(pauseMs)) return void 0;
+	return {
+		type,
+		pauseMs,
+		allocated,
+		collected,
+		promoted,
+		survived
+	};
+}
+/** Parse name=value pairs from trace-gc-nvp line */
+function parseNvpFields(line) {
+	const fields = {};
+	const matches = line.matchAll(/(\w+)=([^\s,]+)/g);
+	for (const [, key, value] of matches) fields[key] = value;
+	return fields;
+}
+/** Map V8 gc type codes to our types */
+function parseGcType(gcField) {
+	if (gcField === "s" || gcField === "scavenge") return "scavenge";
+	if (gcField === "mc" || gcField === "ms" || gcField === "mark-compact") return "mark-compact";
+	if (gcField === "mmc" || gcField === "minor-mc" || gcField === "minor-ms") return "minor-ms";
+	return "unknown";
+}
+/** Aggregate GC events into summary stats */
+function aggregateGcStats(events) {
+	let scavenges = 0;
+	let markCompacts = 0;
+	let gcPauseTime = 0;
+	let totalCollected = 0;
+	let hasNodeFields = false;
+	let totalAllocated = 0;
+	let totalPromoted = 0;
+	let totalSurvived = 0;
+	for (const e of events) {
+		if (e.type === "scavenge" || e.type === "minor-ms") scavenges++;
+		else if (e.type === "mark-compact") markCompacts++;
+		gcPauseTime += e.pauseMs;
+		totalCollected += e.collected;
+		if (e.allocated != null) {
+			hasNodeFields = true;
+			totalAllocated += e.allocated;
+			totalPromoted += e.promoted ?? 0;
+			totalSurvived += e.survived ?? 0;
+		}
+	}
+	return {
+		scavenges,
+		markCompacts,
+		totalCollected,
+		gcPauseTime,
+		...hasNodeFields && {
+			totalAllocated,
+			totalPromoted,
+			totalSurvived
+		}
+	};
+}
+
+//#endregion
+export { parseGcLine as n, aggregateGcStats as t };
+//# sourceMappingURL=GcStats-ByEovUi1.mjs.map

package/dist/GcStats-ByEovUi1.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"GcStats-ByEovUi1.mjs","names":[],"sources":["../src/runners/GcStats.ts"],"sourcesContent":["/** GC statistics aggregated from V8 trace events.\n *  Node (--trace-gc-nvp) provides all fields.\n *  Browser (CDP Tracing) provides counts, collected, and pause only. */\nexport interface GcStats {\n  scavenges: number;\n  markCompacts: number;\n  totalCollected: number; // bytes freed\n  gcPauseTime: number; // total pause time (ms)\n  totalAllocated?: number; // bytes allocated (Node only)\n  totalPromoted?: number; // bytes promoted to old gen (Node only)\n  totalSurvived?: number; // bytes survived in young gen (Node only)\n}\n\n/** Single GC event. Node provides all fields; browser provides type, pauseMs, collected. */\nexport interface GcEvent {\n  type: \"scavenge\" | \"mark-compact\" | \"minor-ms\" | \"unknown\";\n  pauseMs: number;\n  collected: number;\n  allocated?: number; // Node only\n  promoted?: number; // Node only\n  survived?: number; // Node only\n}\n\n/** Parse a single --trace-gc-nvp stderr line */\nexport function parseGcLine(line: string): GcEvent | undefined {\n  // V8 format: [pid:addr:gen] N ms: pause=X gc=s ... allocated=N promoted=N ...\n  if (!line.includes(\"pause=\")) return undefined;\n\n  const fields = parseNvpFields(line);\n  if (!fields.gc) return undefined;\n\n  const int = (k: string) => Number.parseInt(fields[k] || \"0\", 10);\n  const type = parseGcType(fields.gc);\n  const pauseMs = Number.parseFloat(fields.pause || \"0\");\n  const allocated = int(\"allocated\");\n  const promoted = int(\"promoted\");\n  // V8 uses \"new_space_survived\" not \"survived\"\n  const survived = int(\"new_space_survived\") || int(\"survived\");\n  // Calculate collected from start/end object size if available\n  const startSize = int(\"start_object_size\");\n  const endSize = int(\"end_object_size\");\n  const collected = startSize > endSize ? startSize - endSize : 0;\n\n  if (Number.isNaN(pauseMs)) return undefined;\n\n  return { type, pauseMs, allocated, collected, promoted, survived };\n}\n\n/** Parse name=value pairs from trace-gc-nvp line */\nfunction parseNvpFields(line: string): Record<string, string> {\n  const fields: Record<string, string> = {};\n  // Format: \"key=value, key=value, ...\" or \"key=value key=value\"\n  const matches = line.matchAll(/(\\w+)=([^\\s,]+)/g);\n  for (const [, key, value] of matches) {\n    fields[key] = value;\n  }\n  return fields;\n}\n\n/** Map V8 gc type codes to our types */\nfunction parseGcType(gcField: string): GcEvent[\"type\"] {\n  // V8 uses: s=scavenge, mc=mark-compact, mmc=minor-mc (young gen mark-compact)\n  if (gcField === \"s\" || gcField === \"scavenge\") return \"scavenge\";\n  if (gcField === \"mc\" || gcField === \"ms\" || gcField === \"mark-compact\")\n    return \"mark-compact\";\n  if (gcField === \"mmc\" || gcField === \"minor-mc\" || gcField === \"minor-ms\")\n    return \"minor-ms\";\n  return \"unknown\";\n}\n\n/** Aggregate GC events into summary stats */\nexport function aggregateGcStats(events: GcEvent[]): GcStats {\n  let scavenges = 0;\n  let markCompacts = 0;\n  let gcPauseTime = 0;\n  let totalCollected = 0;\n  let hasNodeFields = false;\n  let totalAllocated = 0;\n  let totalPromoted = 0;\n  let totalSurvived = 0;\n\n  for (const e of events) {\n    if (e.type === \"scavenge\" || e.type === \"minor-ms\") scavenges++;\n    else if (e.type === \"mark-compact\") markCompacts++;\n    gcPauseTime += e.pauseMs;\n    totalCollected += e.collected;\n    if (e.allocated != null) {\n      hasNodeFields = true;\n      totalAllocated += e.allocated;\n      totalPromoted += e.promoted ?? 0;\n      totalSurvived += e.survived ?? 0;\n    }\n  }\n\n  return {\n    scavenges,\n    markCompacts,\n    totalCollected,\n    gcPauseTime,\n    ...(hasNodeFields && { totalAllocated, totalPromoted, totalSurvived }),\n  };\n}\n\n/** @return GcStats with all counters zeroed */\nexport function emptyGcStats(): GcStats {\n  return { scavenges: 0, markCompacts: 0, totalCollected: 0, gcPauseTime: 0 };\n}\n"],"mappings":";;AAwBA,SAAgB,YAAY,MAAmC;AAE7D,KAAI,CAAC,KAAK,SAAS,SAAS,CAAE,QAAO;CAErC,MAAM,SAAS,eAAe,KAAK;AACnC,KAAI,CAAC,OAAO,GAAI,QAAO;CAEvB,MAAM,OAAO,MAAc,OAAO,SAAS,OAAO,MAAM,KAAK,GAAG;CAChE,MAAM,OAAO,YAAY,OAAO,GAAG;CACnC,MAAM,UAAU,OAAO,WAAW,OAAO,SAAS,IAAI;CACtD,MAAM,YAAY,IAAI,YAAY;CAClC,MAAM,WAAW,IAAI,WAAW;CAEhC,MAAM,WAAW,IAAI,qBAAqB,IAAI,IAAI,WAAW;CAE7D,MAAM,YAAY,IAAI,oBAAoB;CAC1C,MAAM,UAAU,IAAI,kBAAkB;CACtC,MAAM,YAAY,YAAY,UAAU,YAAY,UAAU;AAE9D,KAAI,OAAO,MAAM,QAAQ,CAAE,QAAO;AAElC,QAAO;EAAE;EAAM;EAAS;EAAW;EAAW;EAAU;EAAU;;;AAIpE,SAAS,eAAe,MAAsC;CAC5D,MAAM,SAAiC,EAAE;CAEzC,MAAM,UAAU,KAAK,SAAS,mBAAmB;AACjD,MAAK,MAAM,GAAG,KAAK,UAAU,QAC3B,QAAO,OAAO;AAEhB,QAAO;;;AAIT,SAAS,YAAY,SAAkC;AAErD,KAAI,YAAY,OAAO,YAAY,WAAY,QAAO;AACtD,KAAI,YAAY,QAAQ,YAAY,QAAQ,YAAY,eACtD,QAAO;AACT,KAAI,YAAY,SAAS,YAAY,cAAc,YAAY,WAC7D,QAAO;AACT,QAAO;;;AAIT,SAAgB,iBAAiB,QAA4B;CAC3D,IAAI,YAAY;CAChB,IAAI,eAAe;CACnB,IAAI,cAAc;CAClB,IAAI,iBAAiB;CACrB,IAAI,gBAAgB;CACpB,IAAI,iBAAiB;CACrB,IAAI,gBAAgB;CACpB,IAAI,gBAAgB;AAEpB,MAAK,MAAM,KAAK,QAAQ;AACtB,MAAI,EAAE,SAAS,cAAc,EAAE,SAAS,WAAY;WAC3C,EAAE,SAAS,eAAgB;AACpC,iBAAe,EAAE;AACjB,oBAAkB,EAAE;AACpB,MAAI,EAAE,aAAa,MAAM;AACvB,mBAAgB;AAChB,qBAAkB,EAAE;AACpB,oBAAiB,EAAE,YAAY;AAC/B,oBAAiB,EAAE,YAAY;;;AAInC,QAAO;EACL;EACA;EACA;EACA;EACA,GAAI,iBAAiB;GAAE;GAAgB;GAAe;GAAe;EACtE"}

package/dist/{HeapSampler-BX3de22o.mjs → HeapSampler-B8dtKHn1.mjs}

@@ -51,4 +51,4 @@ async function stopSampling(session) {
 
 //#endregion
 export { withHeapSampling };
-//# sourceMappingURL=HeapSampler-BX3de22o.mjs.map
+//# sourceMappingURL=HeapSampler-B8dtKHn1.mjs.map

package/dist/{HeapSampler-BX3de22o.mjs.map → HeapSampler-B8dtKHn1.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"HeapSampler-BX3de22o.mjs","names":[],"sources":["../src/heap-sample/HeapSampler.ts"],"sourcesContent":["import { Session } from \"node:inspector/promises\";\n\nexport interface HeapSampleOptions {\n  samplingInterval?: number; // bytes between samples, default 32768\n  stackDepth?: number; // max stack frames, default 64\n  includeMinorGC?: boolean; // keep objects collected by minor GC, default true\n  includeMajorGC?: boolean; // keep objects collected by major GC, default true\n}\n\nexport interface ProfileNode {\n  callFrame: {\n    functionName: string;\n    url: string;\n    lineNumber: number;\n    columnNumber?: number;\n  };\n  selfSize: number;\n  children?: ProfileNode[];\n}\n\nexport interface HeapProfile {\n  head: ProfileNode;\n  samples?: number[]; // sample IDs (length = number of samples taken)\n}\n\nconst defaultOptions: Required<HeapSampleOptions> = {\n  samplingInterval: 32768,\n  stackDepth: 64,\n  includeMinorGC: true,\n  includeMajorGC: true,\n};\n\n/** Run a function while sampling heap allocations, return profile */\nexport async function withHeapSampling<T>(\n  options: HeapSampleOptions,\n  fn: () => Promise<T> | T,\n): Promise<{ result: T; profile: HeapProfile }> {\n  const opts = { ...defaultOptions, ...options };\n  const session = new Session();\n  session.connect();\n\n  try {\n    await startSampling(session, opts);\n    const result = await fn();\n    const profile = await stopSampling(session);\n    return { result, profile };\n  } finally {\n    session.disconnect();\n  }\n}\n\n/** Start heap sampling, falling back if include-collected params aren't supported */\nasync function startSampling(\n  session: Session,\n  opts: Required<HeapSampleOptions>,\n): Promise<void> {\n  const { samplingInterval, stackDepth } = opts;\n  const base = { samplingInterval, stackDepth };\n  const params = {\n    ...base,\n    includeObjectsCollectedByMinorGC: opts.includeMinorGC,\n    includeObjectsCollectedByMajorGC: opts.includeMajorGC,\n  };\n\n  try {\n    await session.post(\"HeapProfiler.startSampling\", params);\n  } catch {\n    console.warn(\n      \"HeapProfiler: include-collected params not supported, falling back\",\n    );\n    await session.post(\"HeapProfiler.startSampling\", base);\n  }\n}\n\nasync function stopSampling(session: Session): Promise<HeapProfile> {\n  const { profile } = await session.post(\"HeapProfiler.stopSampling\");\n  return profile as HeapProfile;\n}\n"],"mappings":";;;AAyBA,MAAM,iBAA8C;CAClD,kBAAkB;CAClB,YAAY;CACZ,gBAAgB;CAChB,gBAAgB;CACjB;;AAGD,eAAsB,iBACpB,SACA,IAC8C;CAC9C,MAAM,OAAO;EAAE,GAAG;EAAgB,GAAG;EAAS;CAC9C,MAAM,UAAU,IAAI,SAAS;AAC7B,SAAQ,SAAS;AAEjB,KAAI;AACF,QAAM,cAAc,SAAS,KAAK;AAGlC,SAAO;GAAE,QAFM,MAAM,IAAI;GAER,SADD,MAAM,aAAa,QAAQ;GACjB;WAClB;AACR,UAAQ,YAAY;;;;AAKxB,eAAe,cACb,SACA,MACe;CACf,MAAM,EAAE,kBAAkB,eAAe;CACzC,MAAM,OAAO;EAAE;EAAkB;EAAY;CAC7C,MAAM,SAAS;EACb,GAAG;EACH,kCAAkC,KAAK;EACvC,kCAAkC,KAAK;EACxC;AAED,KAAI;AACF,QAAM,QAAQ,KAAK,8BAA8B,OAAO;SAClD;AACN,UAAQ,KACN,qEACD;AACD,QAAM,QAAQ,KAAK,8BAA8B,KAAK;;;AAI1D,eAAe,aAAa,SAAwC;CAClE,MAAM,EAAE,YAAY,MAAM,QAAQ,KAAK,4BAA4B;AACnE,QAAO"}
+{"version":3,"file":"HeapSampler-B8dtKHn1.mjs","names":[],"sources":["../src/heap-sample/HeapSampler.ts"],"sourcesContent":["import { Session } from \"node:inspector/promises\";\n\nexport interface HeapSampleOptions {\n  samplingInterval?: number; // bytes between samples, default 32768\n  stackDepth?: number; // max stack frames, default 64\n  includeMinorGC?: boolean; // keep objects collected by minor GC, default true\n  includeMajorGC?: boolean; // keep objects collected by major GC, default true\n}\n\nexport interface ProfileNode {\n  callFrame: {\n    functionName: string;\n    url: string;\n    lineNumber: number;\n    columnNumber?: number;\n  };\n  selfSize: number;\n  children?: ProfileNode[];\n}\n\nexport interface HeapProfile {\n  head: ProfileNode;\n  samples?: number[]; // sample IDs (length = number of samples taken)\n}\n\nconst defaultOptions: Required<HeapSampleOptions> = {\n  samplingInterval: 32768,\n  stackDepth: 64,\n  includeMinorGC: true,\n  includeMajorGC: true,\n};\n\n/** Run a function while sampling heap allocations, return profile */\nexport async function withHeapSampling<T>(\n  options: HeapSampleOptions,\n  fn: () => Promise<T> | T,\n): Promise<{ result: T; profile: HeapProfile }> {\n  const opts = { ...defaultOptions, ...options };\n  const session = new Session();\n  session.connect();\n\n  try {\n    await startSampling(session, opts);\n    const result = await fn();\n    const profile = await stopSampling(session);\n    return { result, profile };\n  } finally {\n    session.disconnect();\n  }\n}\n\n/** Start heap sampling, falling back if include-collected params aren't supported */\nasync function startSampling(\n  session: Session,\n  opts: Required<HeapSampleOptions>,\n): Promise<void> {\n  const { samplingInterval, stackDepth } = opts;\n  const base = { samplingInterval, stackDepth };\n  const params = {\n    ...base,\n    includeObjectsCollectedByMinorGC: opts.includeMinorGC,\n    includeObjectsCollectedByMajorGC: opts.includeMajorGC,\n  };\n\n  try {\n    await session.post(\"HeapProfiler.startSampling\", params);\n  } catch {\n    console.warn(\n      \"HeapProfiler: include-collected params not supported, falling back\",\n    );\n    await session.post(\"HeapProfiler.startSampling\", base);\n  }\n}\n\nasync function stopSampling(session: Session): Promise<HeapProfile> {\n  const { profile } = await session.post(\"HeapProfiler.stopSampling\");\n  return profile as HeapProfile;\n}\n"],"mappings":";;;AAyBA,MAAM,iBAA8C;CAClD,kBAAkB;CAClB,YAAY;CACZ,gBAAgB;CAChB,gBAAgB;CACjB;;AAGD,eAAsB,iBACpB,SACA,IAC8C;CAC9C,MAAM,OAAO;EAAE,GAAG;EAAgB,GAAG;EAAS;CAC9C,MAAM,UAAU,IAAI,SAAS;AAC7B,SAAQ,SAAS;AAEjB,KAAI;AACF,QAAM,cAAc,SAAS,KAAK;AAGlC,SAAO;GAAE,QAFM,MAAM,IAAI;GAER,SADD,MAAM,aAAa,QAAQ;GACjB;WAClB;AACR,UAAQ,YAAY;;;;AAKxB,eAAe,cACb,SACA,MACe;CACf,MAAM,EAAE,kBAAkB,eAAe;CACzC,MAAM,OAAO;EAAE;EAAkB;EAAY;CAC7C,MAAM,SAAS;EACb,GAAG;EACH,kCAAkC,KAAK;EACvC,kCAAkC,KAAK;EACxC;AAED,KAAI;AACF,QAAM,QAAQ,KAAK,8BAA8B,OAAO;SAClD;AACN,UAAQ,KACN,qEACD;AACD,QAAM,QAAQ,KAAK,8BAA8B,KAAK;;;AAI1D,eAAe,aAAa,SAAwC;CAClE,MAAM,EAAE,YAAY,MAAM,QAAQ,KAAK,4BAA4B;AACnE,QAAO"}