benchforge 0.1.11 → 0.2.4

package/src/profiling/browser/ChromeLauncher.ts

@@ -0,0 +1,158 @@
+import { type ChildProcess, execFileSync, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** Handle for a running Chrome instance. */
+export interface ChromeInstance {
+  port: number;
+  process: ChildProcess;
+  close(): Promise<void>;
+}
+
+/** Flags to suppress background services irrelevant to benchmarking. */
+const quietFlags = [
+  "--disable-background-networking",
+  "--disable-client-side-phishing-detection",
+  "--disable-component-update",
+  "--disable-field-trial-config",
+  "--disable-sync",
+  "--disable-breakpad",
+  "--noerrdialogs",
+  "--disable-features=OptimizationHints,Translate,MediaRouter,DialMediaRouteProvider",
+  "--disable-extensions",
+  "--disable-component-extensions-with-background-pages",
+  "--disable-default-apps",
+  "--metrics-recording-only",
+  "--no-service-autorun",
+  "--password-store=basic",
+  "--use-mock-keychain",
+];
+
+/** Stderr patterns to suppress (irrelevant to benchmarking). */
+const chromeNoise =
+  /SharedImageManager|skia_output_device_buffer_queue|task_policy_set/;
+
+/** Launch Chrome with remote debugging and return instance handle. */
+export async function launchChrome(opts: {
+  headless?: boolean;
+  chromePath?: string;
+  chromeProfile?: string;
+  args?: string[];
+}): Promise<ChromeInstance> {
+  const { headless = false, chromeProfile, chromePath, args = [] } = opts;
+  const chrome = chromePath || process.env.CHROME_PATH || findChrome();
+
+  const tmpDir = chromeProfile
+    ? undefined
+    : await mkdtemp(join(tmpdir(), "benchforge-"));
+  const userDataDir = chromeProfile ?? tmpDir!;
+
+  const flags = [
+    "--remote-debugging-port=0",
+    `--user-data-dir=${userDataDir}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    ...quietFlags,
+    ...(headless ? ["--headless=new"] : []),
+    ...args,
+  ];
+
+  const proc = spawn(chrome, flags, { stdio: ["pipe", "pipe", "pipe"] });
+  const wsUrlPromise = parseWsUrl(proc);
+  pipeChromeOutput(proc);
+  const wsUrl = await wsUrlPromise;
+  const port = Number(new URL(wsUrl).port);
+
+  return {
+    port,
+    process: proc,
+    async close() {
+      proc.kill();
+      await new Promise<void>(r => proc.on("exit", () => r()));
+      if (tmpDir)
+        await rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+    },
+  };
+}
+
+/** Create a new browser tab and return its CDP WebSocket URL and target ID. */
+export async function createTab(
+  port: number,
+): Promise<{ wsUrl: string; targetId: string }> {
+  const url = `http://127.0.0.1:${port}/json/new`;
+  const resp = await fetch(url, { method: "PUT" });
+  const text = await resp.text();
+  try {
+    const json = JSON.parse(text);
+    return { wsUrl: json.webSocketDebuggerUrl, targetId: json.id };
+  } catch {
+    const msg = `Chrome /json/new returned non-JSON: ${text.slice(0, 200)}`;
+    throw new Error(msg);
+  }
+}
+
+/** Close a browser tab by target ID. */
+export async function closeTab(port: number, targetId: string): Promise<void> {
+  const url = `http://127.0.0.1:${port}/json/close/${targetId}`;
+  await fetch(url).catch(() => {});
+}
+
+/** Find Chrome/Chromium on the system. */
+function findChrome(): string {
+  if (process.platform === "darwin") {
+    const path = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+    if (existsSync(path)) return path;
+  }
+  if (process.platform === "win32") {
+    for (const env of ["ProgramFiles", "ProgramFiles(x86)"] as const) {
+      const base = process.env[env];
+      if (!base) continue;
+      const p = join(base, "Google", "Chrome", "Application", "chrome.exe");
+      if (existsSync(p)) return p;
+    }
+  }
+  for (const name of ["google-chrome", "chromium-browser", "chromium"]) {
+    try {
+      return execFileSync("which", [name], { encoding: "utf8" }).trim();
+    } catch {}
+  }
+  throw new Error(
+    "Chrome not found. Install Chrome or set CHROME_PATH, or use --chrome <path>.",
+  );
+}
+
+/** Parse the DevTools WebSocket URL from Chrome's stderr. */
+function parseWsUrl(proc: ChildProcess): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const wsPattern = /DevTools listening on (ws:\/\/\S+)/;
+    const onData = (chunk: Buffer) => {
+      const match = chunk.toString().match(wsPattern);
+      if (match) {
+        proc.stderr?.off("data", onData);
+        resolve(match[1]);
+      }
+    };
+    proc.stderr?.on("data", onData);
+    proc.on("error", reject);
+    proc.on("exit", code =>
+      reject(new Error(`Chrome exited (code ${code}) before DevTools ready`)),
+    );
+  });
+}
+
+/** Forward Chrome stdout/stderr to terminal, filtering known noise. */
+function pipeChromeOutput(proc: ChildProcess): void {
+  const forward = (stream: NodeJS.ReadableStream | null) =>
+    stream?.on("data", (chunk: Buffer) => {
+      const lines = chunk
+        .toString()
+        .split("\n")
+        .map(l => l.trim())
+        .filter(l => l && !chromeNoise.test(l));
+      for (const line of lines) process.stderr.write(`[chrome] ${line}\n`);
+    });
+  forward(proc.stdout);
+  forward(proc.stderr);
+}

package/src/profiling/browser/ChromeTraceEvent.ts

@@ -0,0 +1,28 @@
+/** Chrome Trace Event format (used by Perfetto and CDP tracing). */
+export interface TraceEvent {
+  /** Event type: M=metadata, C=counter, i=instant, B/E=begin/end, X=complete */
+  ph: string;
+
+  /** Timestamp in microseconds */
+  ts: number;
+
+  /** Process ID */
+  pid?: number;
+
+  /** Thread ID */
+  tid?: number;
+
+  /** Event category */
+  cat?: string;
+
+  name: string;
+
+  /** Arbitrary event arguments */
+  args?: Record<string, unknown>;
+
+  /** Scope for instant events: "t"=thread, "p"=process, "g"=global */
+  s?: string;
+
+  /** Duration for complete events (microseconds) */
+  dur?: number;
+}

package/src/profiling/browser/PageLoadMode.ts

@@ -0,0 +1,61 @@
+import {
+  instrumentOpts,
+  startInstruments,
+  stopInstruments,
+} from "./BrowserCDP.ts";
+import type {
+  BrowserProfileResult,
+  NavTiming,
+  ProfileCtx,
+} from "./BrowserProfiler.ts";
+import type { CdpPage } from "./CdpPage.ts";
+
+/** Run passive page-load profiling: instrument ==> navigate ==> wait ==> collect. */
+export async function runPageLoad(
+  ctx: ProfileCtx,
+): Promise<BrowserProfileResult> {
+  const { page, cdp, params, samplingInterval } = ctx;
+  const opts = instrumentOpts(params, samplingInterval);
+  await startInstruments(cdp, opts);
+
+  // Observe LCP via PerformanceObserver (avoids deprecated getEntriesByType warning)
+  await page.addInitScript(() => {
+    const g = globalThis as any;
+    g.__lcpTime = undefined;
+    new PerformanceObserver(list => {
+      const entries = list.getEntries();
+      if (entries.length) g.__lcpTime = entries.at(-1)!.startTime;
+    }).observe({ type: "largest-contentful-paint" as any, buffered: true });
+  });
+
+  const { url, waitFor } = params;
+
+  const isBuiltinWait = waitFor === "load" || waitFor === "domcontentloaded";
+  const waitUntil = isBuiltinWait ? waitFor : "load";
+  await page.navigate(url, { waitUntil });
+
+  if (waitFor && !isBuiltinWait) {
+    if (/^[#.[]/.test(waitFor)) {
+      await page.waitForSelector(waitFor);
+    } else {
+      await page.waitForFunction(waitFor);
+    }
+  }
+
+  const navTiming = await readNavTiming(page);
+  const collected = await stopInstruments(cdp, opts);
+  return { ...collected, navTiming, wallTimeMs: navTiming.loadEvent };
+}
+
+/** Read navigation timing from the page via Performance API. */
+export async function readNavTiming(page: CdpPage): Promise<NavTiming> {
+  return page.evaluate(() => {
+    const perf = performance as any;
+    const nav = perf.getEntriesByType("navigation")[0] ?? {};
+    return {
+      domContentLoaded: (nav.domContentLoadedEventEnd as number) ?? 0,
+      loadEvent: (nav.loadEventEnd as number) ?? 0,
+      lcp: (globalThis as any).__lcpTime as number | undefined,
+    };
+  });
+}

package/src/profiling/node/CoverageSampler.ts

@@ -0,0 +1,27 @@
+import { Session } from "node:inspector/promises";
+import type { CoverageData, ScriptCoverage } from "./CoverageTypes.ts";
+
+/** Run a function while collecting precise V8 coverage, return execution counts.
+ *  The session passed to `fn` can be shared with TimeSampler to avoid resetting counters. */
+export async function withCoverageProfiling<T>(
+  fn: (session: Session) => Promise<T> | T,
+): Promise<{ result: T; coverage: CoverageData }> {
+  const session = new Session();
+  session.connect();
+
+  try {
+    await session.post("Profiler.enable");
+    await session.post("Profiler.startPreciseCoverage", {
+      callCount: true,
+      detailed: true,
+    });
+    const result = await fn(session);
+    const raw = await session.post("Profiler.takePreciseCoverage");
+    const scripts = raw.result as unknown as ScriptCoverage[];
+    return { result, coverage: { scripts } };
+  } finally {
+    await session.post("Profiler.stopPreciseCoverage");
+    await session.post("Profiler.disable");
+    session.disconnect();
+  }
+}

package/src/profiling/node/CoverageTypes.ts

@@ -0,0 +1,23 @@
+/** Per-function execution counts from V8 Profiler.takePreciseCoverage (Node and CDP). */
+export interface CoverageData {
+  scripts: ScriptCoverage[];
+}
+
+/** Coverage data for a single script (file) */
+export interface ScriptCoverage {
+  url: string;
+  functions: FunctionCoverage[];
+}
+
+/** Coverage data for a single function within a script */
+export interface FunctionCoverage {
+  functionName: string;
+  ranges: CoverageRange[];
+}
+
+/** A byte-offset range within a function with its execution count */
+export interface CoverageRange {
+  startOffset: number;
+  endOffset: number;
+  count: number;
+}

package/src/profiling/node/HeapSampleReport.ts

@@ -0,0 +1,261 @@
+import colors from "../../report/Colors.ts";
+import { formatBytes } from "../../report/Formatters.ts";
+import type { HeapProfile, HeapSample } from "./HeapSampler.ts";
+import {
+  type ResolvedFrame,
+  type ResolvedProfile,
+  resolveProfile,
+} from "./ResolvedProfile.ts";
+
+/** An allocation site with byte totals, call stack, and optional raw samples */
+export interface HeapSite {
+  name: string;
+  url: string;
+  /** 1-indexed */
+  line: number;
+  col?: number;
+  bytes: number;
+  /** Call stack from root to this frame */
+  stack?: ResolvedFrame[];
+  /** Individual allocation samples at this site */
+  samples?: HeapSample[];
+  /** Distinct caller paths with byte weights (populated by {@link aggregateSites}) */
+  callers?: { stack: ResolvedFrame[]; bytes: number }[];
+}
+
+/** Predicate that returns true for user code (vs. runtime internals) */
+export type UserCodeFilter = (site: ResolvedFrame) => boolean;
+
+/** Options for {@link formatHeapReport} */
+export interface HeapReportOptions {
+  /** Max sites to display */
+  topN: number;
+  /** Caller stack frames to show per site (default 3) */
+  stackDepth?: number;
+  /** Multi-line format with file paths (default false) */
+  verbose?: boolean;
+  /** Dump every raw sample */
+  raw?: boolean;
+  /** Filter to user code only, hiding runtime internals */
+  userOnly?: boolean;
+  /** Predicate for user vs internal code (default {@link isNodeUserCode}) */
+  isUserCode?: UserCodeFilter;
+  /** Total bytes across all nodes (before filtering) */
+  totalAll?: number;
+  /** Total bytes for user code only */
+  totalUserCode?: number;
+  /** Number of samples taken */
+  sampleCount?: number;
+}
+
+/** Sum selfSize across all nodes in profile (before any filtering) */
+export function totalProfileBytes(profile: HeapProfile): number {
+  return resolveProfile(profile).totalBytes;
+}
+
+/** Flatten resolved profile into sorted list of allocation sites with call stacks.
+ *  When raw samples are available, attaches them to corresponding sites. */
+export function flattenProfile(resolved: ResolvedProfile): HeapSite[] {
+  const sites: HeapSite[] = [];
+  const nodeIdToSites = new Map<number, HeapSite[]>();
+
+  for (const node of resolved.allocationNodes) {
+    const site: HeapSite = {
+      ...node.frame,
+      bytes: node.selfSize,
+      stack: node.stack,
+    };
+    sites.push(site);
+    const bucket = nodeIdToSites.get(node.nodeId) ?? [];
+    if (!bucket.length) nodeIdToSites.set(node.nodeId, bucket);
+    bucket.push(site);
+  }
+
+  for (const sample of resolved.sortedSamples ?? []) {
+    const matchingSites = nodeIdToSites.get(sample.nodeId);
+    if (!matchingSites) continue;
+    for (const site of matchingSites) {
+      if (!site.samples) site.samples = [];
+      site.samples.push(sample);
+    }
+  }
+
+  return sites.sort((a, b) => b.bytes - a.bytes);
+}
+
+/** Return true if the call frame is user code (excludes node: and internal/ URLs) */
+export function isNodeUserCode(site: ResolvedFrame): boolean {
+  const { url } = site;
+  return (
+    !!url &&
+    !url.startsWith("node:") &&
+    !url.includes("(native)") &&
+    !url.includes("internal/")
+  );
+}
+
+/** Return true if the call frame is user code (excludes chrome-extension:// and devtools:// URLs) */
+export function isBrowserUserCode(site: ResolvedFrame): boolean {
+  const { url } = site;
+  return (
+    !!url &&
+    !url.startsWith("chrome-extension://") &&
+    !url.startsWith("devtools://") &&
+    !url.includes("(native)")
+  );
+}
+
+/** Return only sites matching a user-code predicate (default: {@link isNodeUserCode}) */
+export function filterSites(
+  sites: HeapSite[],
+  isUser: UserCodeFilter = isNodeUserCode,
+): HeapSite[] {
+  return sites.filter(isUser);
+}
+
+/** Aggregate sites by location (combine same file:line:col).
+ *  Tracks distinct caller stacks with byte weights when merging. */
+export function aggregateSites(sites: HeapSite[]): HeapSite[] {
+  const byLocation = new Map<string, HeapSite>();
+
+  for (const site of sites) {
+    // When column is unknown, include name to avoid merging distinct sites
+    const colKey = site.col != null ? `${site.col}` : `?:${site.name}`;
+    const key = `${site.url}:${site.line}:${colKey}`;
+    const existing = byLocation.get(key);
+    if (existing) {
+      existing.bytes += site.bytes;
+      addCaller(existing, site);
+    } else {
+      const callers = site.stack
+        ? [{ stack: site.stack, bytes: site.bytes }]
+        : undefined;
+      byLocation.set(key, { ...site, callers });
+    }
+  }
+
+  for (const site of byLocation.values()) {
+    if (!site.callers || site.callers.length <= 1) continue;
+    site.callers.sort((a, b) => b.bytes - a.bytes);
+    site.stack = site.callers[0].stack;
+  }
+
+  return [...byLocation.values()].sort((a, b) => b.bytes - a.bytes);
+}
+
+/** Format heap report for console output */
+export function formatHeapReport(
+  sites: HeapSite[],
+  options: HeapReportOptions,
+): string {
+  const { topN, stackDepth = 3, verbose = false } = options;
+  const { totalAll, totalUserCode, sampleCount, isUserCode } = options;
+  const isUser = isUserCode ?? isNodeUserCode;
+  const formatSite = verbose ? formatVerboseSite : formatCompactSite;
+  const lines: string[] = [];
+  lines.push(`Heap allocation sites (top ${topN}, garbage included):`);
+
+  for (const site of sites.slice(0, topN)) {
+    formatSite(lines, site, stackDepth, isUser);
+  }
+
+  lines.push("");
+  if (totalAll !== undefined)
+    lines.push(`Total (all):       ${fmtBytes(totalAll)}`);
+  if (totalUserCode !== undefined)
+    lines.push(`Total (user-code): ${fmtBytes(totalUserCode)}`);
+  if (sampleCount !== undefined)
+    lines.push(`Samples: ${sampleCount.toLocaleString()}`);
+
+  return lines.join("\n");
+}
+
+/** Sum bytes across all sites */
+export function totalBytes(sites: HeapSite[]): number {
+  return sites.reduce((sum, s) => sum + s.bytes, 0);
+}
+
+/** Format every raw sample as one line, ordered by ordinal (time).
+ *  Output is tab-separated for easy piping/grep/diff. */
+export function formatRawSamples(resolved: ResolvedProfile): string {
+  const { sortedSamples, nodeMap } = resolved;
+  if (!sortedSamples || sortedSamples.length === 0)
+    return "No raw samples available.";
+
+  const header = "ordinal\tsize\tfunction\tlocation";
+  const rows = sortedSamples.map(s => {
+    const frame = nodeMap.get(s.nodeId)?.frame;
+    const fn = frame?.name || "(unknown)";
+    const url = frame?.url || "";
+    const loc = url ? fmtLoc(url, frame!.line, frame!.col) : "(unknown)";
+    return `${s.ordinal}\t${s.size}\t${fn}\t${loc}`;
+  });
+  return [header, ...rows].join("\n");
+}
+
+/** Add a caller stack to an aggregated site, merging if the same path exists */
+function addCaller(existing: HeapSite, site: HeapSite): void {
+  if (!site.stack) return;
+  existing.callers ??= [];
+  const key = callerKey(site.stack);
+  const match = existing.callers.find(c => callerKey(c.stack) === key);
+  if (match) match.bytes += site.bytes;
+  else existing.callers.push({ stack: site.stack, bytes: site.bytes });
+}
+
+/** Verbose multi-line format with file:// paths and line numbers */
+function formatVerboseSite(
+  lines: string[],
+  site: HeapSite,
+  stackDepth: number,
+  isUser: UserCodeFilter,
+): void {
+  const bytes = fmtBytes(site.bytes).padStart(10);
+  const loc = site.url ? fmtLoc(site.url, site.line, site.col) : "(unknown)";
+  const style = isUser(site) ? (s: string) => s : colors.dim;
+  lines.push(style(`${bytes}  ${site.name}  ${loc}`));
+
+  const userCallers = callerFrames(site, stackDepth).filter(
+    f => f.url && isUser(f),
+  );
+  for (const frame of userCallers) {
+    const loc = fmtLoc(frame.url, frame.line, frame.col);
+    lines.push(style(`            <- ${frame.name}  ${loc}`));
+  }
+}
+
+/** Compact single-line format: `49 MB  fn1 <- fn2 <- fn3` */
+function formatCompactSite(
+  lines: string[],
+  site: HeapSite,
+  stackDepth: number,
+  isUser: UserCodeFilter,
+): void {
+  const bytes = fmtBytes(site.bytes).padStart(10);
+  const callers = callerFrames(site, stackDepth)
+    .filter(f => f.url && isUser(f))
+    .map(f => f.name);
+  const line = `${bytes}  ${[site.name, ...callers].join(" <- ")}`;
+  lines.push(isUser(site) ? line : colors.dim(line));
+}
+
+/** Format bytes with a space separator, falling back to raw bytes */
+function fmtBytes(bytes: number): string {
+  return formatBytes(bytes, { space: true }) ?? `${bytes} B`;
+}
+
+/** Format location, omitting column when unknown */
+function fmtLoc(url: string, line: number, col?: number): string {
+  return col != null ? `${url}:${line}:${col}` : `${url}:${line}`;
+}
+
+/** Serialize a call stack for dedup comparison */
+function callerKey(stack: ResolvedFrame[]): string {
+  return stack.map(f => `${f.url}:${f.line}:${f.col}`).join("|");
+}
+
+/** Get caller frames (parent stack excluding self, reversed, truncated) */
+function callerFrames(site: HeapSite, depth: number): ResolvedFrame[] {
+  if (!site.stack || site.stack.length <= 1) return [];
+  return site.stack.slice(0, -1).reverse().slice(0, depth);
+}

package/src/{heap-sample → profiling/node}/HeapSampler.ts

@@ -103,7 +103,6 @@ async function startSampling(
     includeObjectsCollectedByMinorGC: opts.includeMinorGC,
     includeObjectsCollectedByMajorGC: opts.includeMajorGC,
   };
-
   try {
     await session.post("HeapProfiler.startSampling", params);
   } catch {
@@ -114,8 +113,8 @@ async function startSampling(
   }
 }
 
+/** Stop heap sampling and return the profile, casting past incomplete @types/node typings */
 async function stopSampling(session: Session): Promise<HeapProfile> {
   const { profile } = await session.post("HeapProfiler.stopSampling");
-  // V8 returns id/samples fields not in @types/node's incomplete SamplingHeapProfile
   return profile as unknown as HeapProfile;
 }

package/src/{heap-sample → profiling/node}/ResolvedProfile.ts

@@ -1,4 +1,9 @@
-import type { HeapProfile, HeapSample, ProfileNode } from "./HeapSampler.ts";
+import type {
+  CallFrame,
+  HeapProfile,
+  HeapSample,
+  ProfileNode,
+} from "./HeapSampler.ts";
 
 /** A call frame with display-ready 1-indexed source positions */
 export interface ResolvedFrame {
@@ -48,6 +53,16 @@ export interface ResolvedProfile {
   totalBytes: number;
 }
 
+/** Convert a V8 0-indexed CallFrame to a display-ready 1-indexed ResolvedFrame */
+export function resolveCallFrame(cf: CallFrame): ResolvedFrame {
+  return {
+    name: cf.functionName || "(anonymous)",
+    url: cf.url || "",
+    line: cf.lineNumber + 1,
+    col: cf.columnNumber != null ? cf.columnNumber + 1 : undefined,
+  };
+}
+
 /** Walk a HeapProfile tree once, producing a fully resolved intermediate form */
 export function resolveProfile(profile: HeapProfile): ResolvedProfile {
   const nodes: ResolvedNode[] = [];
@@ -55,13 +70,7 @@ export function resolveProfile(profile: HeapProfile): ResolvedProfile {
   let totalBytes = 0;
 
   function walk(node: ProfileNode, parentStack: ResolvedFrame[]): void {
-    const { functionName, url, lineNumber, columnNumber } = node.callFrame;
-    const frame: ResolvedFrame = {
-      name: functionName || "(anonymous)",
-      url: url || "",
-      line: lineNumber + 1,
-      col: columnNumber != null ? columnNumber + 1 : undefined,
-    };
+    const frame = resolveCallFrame(node.callFrame);
     const stack = [...parentStack, frame];
     const resolved: ResolvedNode = {
       frame,
@@ -72,7 +81,7 @@ export function resolveProfile(profile: HeapProfile): ResolvedProfile {
     nodes.push(resolved);
     nodeMap.set(node.id, resolved);
     totalBytes += node.selfSize;
-    for (const child of node.children || []) walk(child, stack);
+    for (const child of node.children ?? []) walk(child, stack);
   }
 
   walk(profile.head, []);

package/src/profiling/node/TimeSampler.ts

@@ -0,0 +1,57 @@
+import { Session } from "node:inspector/promises";
+import type { CallFrame } from "./HeapSampler.ts";
+
+/** V8 CPU profile node (flat array element, not tree) */
+export interface TimeProfileNode {
+  id: number;
+  callFrame: CallFrame;
+  hitCount?: number;
+  /** Child node IDs */
+  children?: number[];
+}
+
+/** V8 CPU profile returned by Profiler.stop */
+export interface TimeProfile {
+  nodes: TimeProfileNode[];
+  /** Microseconds */
+  startTime: number;
+  /** Microseconds */
+  endTime: number;
+  /** Node IDs sampled at each tick */
+  samples?: number[];
+  /** Microseconds between samples */
+  timeDeltas?: number[];
+}
+
+export interface TimeProfileOptions {
+  /** Sampling interval in microseconds (default 1000 = 1ms) */
+  interval?: number;
+  /** External session to use (shares Profiler domain, caller manages enable/disable) */
+  session?: Session;
+}
+
+/** Run a function while sampling CPU time, return profile */
+export async function withTimeProfiling<T>(
+  options: TimeProfileOptions,
+  fn: () => Promise<T> | T,
+): Promise<{ result: T; profile: TimeProfile }> {
+  const { interval } = options;
+  const ownSession = !options.session;
+  const session = options.session ?? new Session();
+  if (ownSession) session.connect();
+
+  try {
+    if (ownSession) await session.post("Profiler.enable");
+    if (interval)
+      await session.post("Profiler.setSamplingInterval", { interval });
+    await session.post("Profiler.start");
+    const result = await fn();
+    const { profile } = await session.post("Profiler.stop");
+    return { result, profile: profile as unknown as TimeProfile };
+  } finally {
+    if (ownSession) {
+      await session.post("Profiler.disable");
+      session.disconnect();
+    }
+  }
+}