benchforge 0.1.11 → 0.2.4

package/dist/index.d.mts

@@ -1,248 +1,68 @@
-import { a as MeasuredResults, i as BenchmarkSpec, n as BenchGroup, o as HeapProfile, r as BenchSuite, t as RunnerOptions } from "./BenchRunner-BzyUfiyB.mjs";
-import { Alignment } from "table";
+import { a as MeasuredResults, c as HeapProfile, i as BenchmarkSpec, n as BenchGroup, o as PausePoint, r as BenchSuite, t as RunnerOptions } from "./BenchRunner-DglX1NOn.mjs";
 import { Argv, InferredOptionTypes } from "yargs";
-import * as node_http0 from "node:http";
+import { Alignment } from "table";
 
-//#region src/BenchMatrix.d.ts
-/** Stateless variant - called each iteration with case data */
-type VariantFn<T = unknown> = (caseData: T) => void;
-/** Stateful variant - setup once, run many */
-interface StatefulVariant<T = unknown, S = unknown> {
-  setup: (caseData: T) => S | Promise<S>;
-  run: (state: S) => void;
-}
-/** A variant is either a plain function or a stateful setup+run pair */
-type Variant<T = unknown, S = unknown> = VariantFn<T> | StatefulVariant<T, S>;
-/** Variant with any state type - used in BenchMatrix to allow mixed variants */
-type AnyVariant<T = unknown> = VariantFn<T> | StatefulVariant<T, any>;
-/** Result from casesModule.loadCase() */
-interface LoadedCase<T = unknown> {
-  data: T;
-  metadata?: Record<string, unknown>;
-}
-interface MatrixDefaults {
-  warmup?: number;
-  maxTime?: number;
-  iterations?: number;
-}
-/** Bench matrix configuration */
-interface BenchMatrix<T = unknown> {
-  name: string;
-  variantDir?: string;
-  variants?: Record<string, AnyVariant<T>>;
-  cases?: string[];
-  casesModule?: string;
-  baselineDir?: string;
-  baselineVariant?: string;
-  defaults?: MatrixDefaults;
-}
-/** Collection of matrices */
-interface MatrixSuite {
-  name: string;
-  matrices: BenchMatrix<any>[];
-}
-/** Results for a single variant across all cases */
-interface VariantResult {
-  id: string;
-  cases: CaseResult[];
-}
-/** Results for a single (variant, case) pair */
-interface CaseResult {
-  caseId: string;
-  measured: MeasuredResults;
-  metadata?: Record<string, unknown>;
-  baseline?: MeasuredResults;
-  deltaPercent?: number;
-}
-/** Results from running a matrix */
-interface MatrixResults {
-  name: string;
-  variants: VariantResult[];
-}
-/** Options for runMatrix */
-interface RunMatrixOptions {
-  iterations?: number;
-  maxTime?: number;
-  warmup?: number;
-  useWorker?: boolean;
-  filteredCases?: string[];
-  filteredVariants?: string[];
-  collect?: boolean;
-  cpuCounters?: boolean;
-  traceOpt?: boolean;
-  noSettle?: boolean;
-  pauseFirst?: number;
-  pauseInterval?: number;
-  pauseDuration?: number;
-  gcStats?: boolean;
-  heapSample?: boolean;
-  heapInterval?: number;
-  heapDepth?: number;
-}
-/** @return true if variant is a StatefulVariant (has setup + run) */
-declare function isStatefulVariant<T, S>(v: Variant<T, S>): v is StatefulVariant<T, S>;
-/** Run a BenchMatrix with inline variants or variantDir */
-declare function runMatrix<T>(matrix: BenchMatrix<T>, options?: RunMatrixOptions): Promise<MatrixResults>;
-//#endregion
-//#region src/table-util/TableReport.d.ts
-type AnyColumn<T> = Column<T> | DiffColumn<T>;
-/** Column with optional formatter */
-interface Column<T> extends ColumnFormat<T> {
-  formatter?: (value: unknown) => string | null;
-  diffKey?: undefined;
-}
-/** Comparison column against baseline */
-interface DiffColumn<T> extends ColumnFormat<T> {
-  diffFormatter?: (value: unknown, baseline: unknown) => string | null;
-  formatter?: undefined;
-  /** Key for comparison value against baseline */
-  diffKey: keyof T;
-}
-interface ColumnFormat<T> {
-  key: keyof T;
-  title: string;
-  alignment?: Alignment;
-  width?: number;
-}
-/** Build formatted table with column groups and baselines */
-//#endregion
-//#region src/BenchmarkReport.d.ts
-/** Benchmark results with optional baseline for comparison */
-interface ReportGroup {
-  name: string;
-  reports: BenchmarkReport[];
-  baseline?: BenchmarkReport;
-}
-/** Results from a single benchmark run */
-interface BenchmarkReport {
-  name: string;
-  measuredResults: MeasuredResults;
-  metadata?: UnknownRecord;
-}
-interface ReportColumnGroup<T> {
-  groupTitle?: string;
-  columns: ReportColumn<T>[];
-}
-type ReportColumn<T> = AnyColumn<T> & {
-  /** Add diff column after this column when baseline exists */comparable?: boolean; /** Set true for throughput metrics where higher values are better (e.g., lines/sec) */
-  higherIsBetter?: boolean;
-};
-/** Maps benchmark results to table columns */
-interface ResultsMapper<T extends Record<string, any> = Record<string, any>> {
-  extract(results: MeasuredResults, metadata?: UnknownRecord): T;
-  columns(): ReportColumnGroup<T>[];
-}
-type UnknownRecord = Record<string, unknown>;
-/** @return formatted table report with optional baseline comparisons */
-declare function reportResults<S extends ReadonlyArray<ResultsMapper<any>>>(groups: ReportGroup[], sections: S): string;
-//#endregion
 //#region src/cli/CliArgs.d.ts
 type Configure<T> = (yargs: Argv) => Argv<T>;
-/** CLI args type inferred from cliOptions, plus optional file positional */
+/** CLI args type inferred from cliOptions, plus optional file positional. */
 type DefaultCliArgs = InferredOptionTypes<typeof cliOptions> & {
   file?: string;
 };
 declare const cliOptions: {
-  readonly time: {
+  readonly duration: {
     readonly type: "number";
-    readonly default: 0.642;
     readonly requiresArg: true;
-    readonly describe: "test duration in seconds";
+    readonly describe: "duration per batch in seconds (default: 0.642)";
   };
-  readonly cpu: {
-    readonly type: "boolean";
-    readonly default: false;
-    readonly describe: "CPU counter measurements (requires root)";
-  };
-  readonly collect: {
-    readonly type: "boolean";
-    readonly default: false;
-    readonly describe: "force GC after each iteration";
-  };
-  readonly "gc-stats": {
-    readonly type: "boolean";
-    readonly default: false;
-    readonly describe: "collect GC statistics (Node: --trace-gc-nvp, browser: CDP tracing)";
+  readonly iterations: {
+    readonly type: "number";
+    readonly requiresArg: true;
+    readonly describe: "iterations per batch (page loads for page-load mode, inner loop for bench)";
   };
-  readonly profile: {
-    readonly type: "boolean";
-    readonly default: false;
-    readonly describe: "run once for profiling";
+  readonly warmup: {
+    readonly type: "number";
+    readonly default: 0;
+    readonly describe: "warmup iterations before measurement";
   };
   readonly filter: {
     readonly type: "string";
     readonly requiresArg: true;
-    readonly describe: "filter benchmarks by regex or substring";
+    readonly describe: "filter by name/regex. Matrix: case/variant, case/, /variant";
   };
   readonly all: {
     readonly type: "boolean";
     readonly default: false;
     readonly describe: "run all cases (ignore defaultCases)";
   };
+  readonly list: {
+    readonly type: "boolean";
+    readonly default: false;
+    readonly describe: "list available benchmarks (or matrix cases/variants)";
+  };
   readonly worker: {
     readonly type: "boolean";
     readonly default: true;
     readonly describe: "run in worker process for isolation (default: true)";
   };
-  readonly adaptive: {
-    readonly type: "boolean";
-    readonly default: false;
-    readonly describe: "adaptive sampling (experimental)";
-  };
-  readonly "min-time": {
+  readonly batches: {
     readonly type: "number";
     readonly default: 1;
-    readonly describe: "minimum time before adaptive convergence can stop";
-  };
-  readonly convergence: {
-    readonly type: "number";
-    readonly default: 95;
-    readonly describe: "adaptive confidence threshold (0-100)";
-  };
-  readonly warmup: {
-    readonly type: "number";
-    readonly default: 0;
-    readonly describe: "warmup iterations before measurement";
-  };
-  readonly html: {
-    readonly type: "boolean";
-    readonly default: false;
-    readonly describe: "generate HTML report and open in browser";
-  };
-  readonly "export-html": {
-    readonly type: "string";
-    readonly requiresArg: true;
-    readonly describe: "export HTML report to specified file";
-  };
-  readonly json: {
-    readonly type: "string";
-    readonly requiresArg: true;
-    readonly describe: "export benchmark data to JSON file";
-  };
-  readonly "export-perfetto": {
-    readonly type: "string";
-    readonly requiresArg: true;
-    readonly describe: "export Perfetto trace file (view at ui.perfetto.dev)";
+    readonly describe: "divide time into N batches, alternating baseline/current order";
   };
-  readonly speedscope: {
+  readonly "warmup-batch": {
     readonly type: "boolean";
     readonly default: false;
-    readonly describe: "open heap profile in speedscope (via npx)";
-  };
-  readonly "export-speedscope": {
-    readonly type: "string";
-    readonly requiresArg: true;
-    readonly describe: "export heap profile as speedscope JSON";
+    readonly describe: "include first batch in results (normally dropped to avoid OS cache warmup)";
   };
-  readonly "trace-opt": {
-    readonly type: "boolean";
-    readonly default: false;
-    readonly describe: "trace V8 optimization tiers (requires --allow-natives-syntax)";
+  readonly "equiv-margin": {
+    readonly type: "number";
+    readonly default: 2;
+    readonly describe: "equivalence margin % for baseline comparison (0 to disable)";
   };
-  readonly "skip-settle": {
+  readonly "no-batch-trim": {
     readonly type: "boolean";
     readonly default: false;
-    readonly describe: "skip post-warmup settle time (see V8 optimization cold start)";
+    readonly describe: "disable Tukey trimming of outlier batches";
   };
   readonly "pause-first": {
     readonly type: "number";
@@ -258,71 +78,180 @@ declare const cliOptions: {
     readonly default: 100;
     readonly describe: "pause duration in ms for V8 optimization";
   };
-  readonly batches: {
+  readonly "gc-stats": {
+    readonly type: "boolean";
+    readonly default: false;
+    readonly describe: "collect GC statistics (Node: --trace-gc-nvp, browser: CDP tracing)";
+  };
+  readonly "gc-force": {
+    readonly type: "boolean";
+    readonly default: false;
+    readonly describe: "force GC after each iteration";
+  };
+  readonly adaptive: {
+    readonly type: "boolean";
+    readonly default: false;
+    readonly describe: "adaptive sampling (experimental)";
+  };
+  readonly "min-time": {
     readonly type: "number";
     readonly default: 1;
-    readonly describe: "divide time into N batches, alternating baseline/current order";
+    readonly describe: "minimum time before adaptive convergence can stop";
   };
-  readonly iterations: {
+  readonly convergence: {
     readonly type: "number";
-    readonly requiresArg: true;
-    readonly describe: "exact number of iterations (overrides --time)";
+    readonly default: 95;
+    readonly describe: "adaptive confidence threshold (0-100)";
   };
-  readonly "heap-sample": {
+  readonly alloc: {
     readonly type: "boolean";
     readonly default: false;
-    readonly describe: "heap sampling allocation attribution (includes garbage)";
+    readonly describe: "allocation sampling attribution (includes garbage)";
   };
-  readonly "heap-interval": {
+  readonly "alloc-interval": {
     readonly type: "number";
     readonly default: 32768;
-    readonly describe: "heap sampling interval in bytes";
+    readonly describe: "allocation sampling interval in bytes";
   };
-  readonly "heap-depth": {
+  readonly "alloc-depth": {
     readonly type: "number";
     readonly default: 64;
-    readonly describe: "heap sampling stack depth";
+    readonly describe: "allocation sampling stack depth";
   };
-  readonly "heap-rows": {
+  readonly "alloc-rows": {
     readonly type: "number";
     readonly default: 20;
     readonly describe: "top allocation sites to show";
   };
-  readonly "heap-stack": {
+  readonly "alloc-stack": {
     readonly type: "number";
     readonly default: 3;
     readonly describe: "call stack depth to display";
   };
-  readonly "heap-verbose": {
+  readonly "alloc-verbose": {
     readonly type: "boolean";
     readonly default: false;
     readonly describe: "verbose output with file:// paths and line numbers";
   };
-  readonly "heap-raw": {
+  readonly "alloc-raw": {
     readonly type: "boolean";
     readonly default: false;
-    readonly describe: "dump every raw heap sample (ordinal, size, stack)";
+    readonly describe: "dump every raw allocation sample (ordinal, size, stack)";
   };
-  readonly "heap-user-only": {
+  readonly "alloc-user-only": {
     readonly type: "boolean";
     readonly default: false;
     readonly describe: "filter to user code only (hide node internals)";
   };
+  readonly profile: {
+    readonly type: "boolean";
+    readonly default: false;
+    readonly alias: "time-sample";
+    readonly describe: "V8 CPU time sampling profiler";
+  };
+  readonly "profile-interval": {
+    readonly type: "number";
+    readonly default: 1000;
+    readonly alias: "time-interval";
+    readonly describe: "CPU sampling interval in microseconds";
+  };
+  readonly "call-counts": {
+    readonly type: "boolean";
+    readonly default: false;
+    readonly describe: "collect per-function execution counts via V8 precise coverage";
+  };
+  readonly stats: {
+    readonly type: "string";
+    readonly default: "mean,p50,p99";
+    readonly describe: "timing columns: mean|median|min|max|p<N> (e.g. mean,p70,p99)";
+  };
+  readonly view: {
+    readonly type: "boolean";
+    readonly default: false;
+    readonly alias: "html";
+    readonly describe: "open viewer in browser";
+  };
+  readonly "view-serve": {
+    readonly type: "boolean";
+    readonly default: false;
+    readonly describe: "start viewer server without opening browser (reload an existing tab)";
+  };
+  readonly "export-perfetto": {
+    readonly type: "string";
+    readonly requiresArg: true;
+    readonly describe: "export Perfetto trace file (view at ui.perfetto.dev)";
+  };
+  readonly "export-profile": {
+    readonly type: "string";
+    readonly requiresArg: true;
+    readonly alias: "export-time";
+    readonly describe: "export CPU profile as .cpuprofile (V8/Chrome DevTools format)";
+  };
+  readonly archive: {
+    readonly type: "string";
+    readonly describe: "archive profile + sources to .benchforge file";
+  };
+  readonly editor: {
+    readonly type: "string";
+    readonly default: "vscode";
+    readonly describe: "editor for source links: vscode, cursor, or custom://scheme";
+  };
+  readonly inspect: {
+    readonly type: "boolean";
+    readonly default: false;
+    readonly describe: "run once for external profiler attach";
+  };
+  readonly "trace-opt": {
+    readonly type: "boolean";
+    readonly default: false;
+    readonly describe: "trace V8 optimization tiers (requires --allow-natives-syntax)";
+  };
+  readonly "pause-warmup": {
+    readonly type: "number";
+    readonly default: 0;
+    readonly requiresArg: true;
+    readonly describe: "post-warmup settle time in ms for V8 background compilation (0 to skip)";
+  };
   readonly url: {
     readonly type: "string";
     readonly requiresArg: true;
     readonly describe: "page URL for browser profiling (enables browser mode)";
   };
+  readonly "page-load": {
+    readonly type: "boolean";
+    readonly default: false;
+    readonly describe: "passive page-load profiling (no __bench needed)";
+  };
+  readonly "wait-for": {
+    readonly type: "string";
+    readonly requiresArg: true;
+    readonly describe: "page-load completion: CSS selector, JS expression, 'load', or 'domcontentloaded'";
+  };
   readonly headless: {
     readonly type: "boolean";
-    readonly default: true;
-    readonly describe: "run browser in headless mode";
+    readonly default: false;
+    readonly describe: "run browser in headless mode (default: headed)";
   };
   readonly timeout: {
     readonly type: "number";
     readonly default: 60;
     readonly describe: "browser page timeout in seconds";
   };
+  readonly chrome: {
+    readonly type: "string";
+    readonly requiresArg: true;
+    readonly describe: "Chrome binary path (default: auto-detect or CHROME_PATH)";
+  };
+  readonly "chrome-profile": {
+    readonly type: "string";
+    readonly requiresArg: true;
+    readonly describe: "Chrome user profile directory (default: temp profile)";
+  };
+  readonly "baseline-url": {
+    readonly type: "string";
+    readonly requiresArg: true;
+    readonly describe: "baseline URL for A/B comparison (fresh tab per batch)";
+  };
   readonly "chrome-args": {
     readonly type: "string";
     readonly array: true;
@@ -330,103 +259,131 @@ declare const cliOptions: {
     readonly describe: "extra Chromium flags";
   };
 };
-/** @return yargs with standard benchmark options */
-declare function defaultCliArgs(yargsInstance: Argv): Argv<DefaultCliArgs>;
-/** @return parsed command line arguments */
+/** Parse command line arguments with optional custom yargs configuration. */
 declare function parseCliArgs<T = DefaultCliArgs>(args: string[], configure?: Configure<T>): T;
+/** Configure yargs for browser benchmarking with url as a required positional. */
+declare function browserCliArgs(yargsInstance: Argv): Argv<DefaultCliArgs>;
+/** Configure yargs with standard benchmark options and file positional. */
+declare function defaultCliArgs(yargsInstance: Argv): Argv<DefaultCliArgs>;
 //#endregion
-//#region src/html/Types.d.ts
-/** Data passed to the HTML report generator */
-interface ReportData {
-  groups: GroupData[];
-  metadata: {
-    timestamp: string;
-    bencherVersion: string;
-    cliArgs?: Record<string, unknown>;
-    gcTrackingEnabled?: boolean;
-    currentVersion?: GitVersion;
-    baselineVersion?: GitVersion;
-  };
-}
-interface GroupData {
-  name: string;
-  baseline?: BenchmarkData;
-  benchmarks: BenchmarkData[];
-}
-interface BenchmarkData {
-  name: string;
-  samples: number[];
-  warmupSamples?: number[];
-  allocationSamples?: number[];
-  heapSamples?: number[];
-  gcEvents?: GcEvent[];
-  optSamples?: number[];
-  pausePoints?: PausePoint[];
-  stats: {
-    min: number;
-    max: number;
-    avg: number;
-    p50: number;
-    p75: number;
-    p99: number;
-    p999: number;
-  };
-  heapSize?: {
-    min: number;
-    max: number;
-    avg: number;
-  };
-  sectionStats?: FormattedStat[];
-  comparisonCI?: DifferenceCI;
-}
-interface FormattedStat {
-  label: string;
-  value: string;
-  groupTitle?: string;
-}
-interface GcEvent {
-  offset: number;
-  duration: number;
-}
-interface PausePoint {
-  sampleIndex: number;
-  durationMs: number;
-}
-interface GitVersion {
-  hash: string;
-  date: string;
-  dirty?: boolean;
-}
-type CIDirection = "faster" | "slower" | "uncertain";
+//#region src/stats/StatisticalUtils.d.ts
+/** Whether CI was computed from block-level or sample-level resampling */
+type CILevel = "block" | "sample";
+/** Stat descriptor for multi-bootstrap: known stat kinds enable zero-alloc inner loops */
+type StatKind = "mean" | "min" | "max" | {
+  percentile: number;
+};
+type CIDirection = "faster" | "slower" | "uncertain" | "equivalent";
+/** Binned histogram for efficient transfer to browser */
 interface HistogramBin {
+  /** Bin center value */
   x: number;
   count: number;
 }
+/**
+* Bootstrap confidence interval for percentage difference between two sample medians.
+* Used for baseline comparisons: negative percent means current is faster.
+*/
 interface DifferenceCI {
+  /** Observed percentage difference (current - baseline) / baseline */
   percent: number;
+  /** Confidence interval [lower, upper] in percent */
   ci: [number, number];
+  /** Whether the CI excludes zero: "faster", "slower", or "uncertain" */
   direction: CIDirection;
+  /** Bootstrap distribution histogram for visualization */
   histogram?: HistogramBin[];
+  /** Label for the CI plot title (e.g. "mean Δ%") */
+  label?: string;
+  /** Blocks trimmed per side [baseline, current] via Tukey fences */
+  trimmed?: [number, number];
+  /** Block-level (between-run) or sample-level (within-run) resampling */
+  ciLevel?: CILevel;
+  /** false when batch count is too low for reliable CI */
+  ciReliable?: boolean;
+  /** Original sample count before subsampling (set only when cap applied) */
+  subsampled?: number;
+}
+declare const maxBootstrapInput = 1e4;
+/** Compute a statistic from samples by kind */
+declare function computeStat(samples: number[], kind: StatKind): number;
+/** @return true if the stat kind supports bootstrap CI (min/max don't) */
+declare function isBootstrappable(kind: StatKind): boolean;
+/** @return mean of values */
+declare function average(values: number[]): number;
+/** @return median (50th percentile) of values */
+declare function median(values: number[]): number;
+/** @return value at percentile p (0-1), using O(N) quickselect */
+declare function percentile(values: number[], p: number): number;
+//#endregion
+//#region src/report/text/TableReport.d.ts
+type AnyColumn<T> = Column<T> | DiffColumn<T>;
+/** Table column with a value formatter (non-diff). */
+interface Column<T> extends ColumnFormat<T> {
+  formatter?: (value: unknown) => string | null;
+  diffKey?: undefined;
 }
-interface HtmlReportOptions {
-  openBrowser: boolean;
-  outputPath?: string;
+interface DiffColumn<T> extends ColumnFormat<T> {
+  diffFormatter?: (value: unknown, baseline: unknown) => string | null;
+  formatter?: undefined;
+  diffKey: keyof T;
 }
-interface HtmlReportResult {
-  reportDir: string;
-  server?: node_http0.Server;
-  closeServer?: () => void;
+interface ColumnFormat<T> {
+  key: keyof T;
+  title: string;
+  alignment?: Alignment;
+  width?: number;
 }
+/** Build formatted table with column groups and baseline diffs. */
 //#endregion
-//#region src/html/HtmlReport.d.ts
-/** Generate HTML report from prepared data and optionally open in browser */
-declare function generateHtmlReport(data: ReportData, options: HtmlReportOptions): Promise<HtmlReportResult>;
-//#endregion
-//#region src/html/HtmlTemplate.d.ts
-/** Format ISO date as local time with UTC: "Jan 9, 2026, 3:45 PM (2026-01-09T23:45:00Z)" */
-declare function formatDateWithTimezone(isoDate: string): string;
+//#region src/report/BenchmarkReport.d.ts
+/** Options that affect baseline comparison statistics */
+interface ComparisonOptions {
+  /** Equivalence margin in percent (0 to disable) */
+  equivMargin?: number;
+  /** Disable Tukey trimming of outlier batches */
+  noBatchTrim?: boolean;
+}
+/** Benchmark results with optional baseline for comparison */
+interface ReportGroup {
+  name: string;
+  reports: BenchmarkReport[];
+  baseline?: BenchmarkReport;
+}
+/** Results from a single benchmark run */
+interface BenchmarkReport {
+  name: string;
+  measuredResults: MeasuredResults;
+  metadata?: UnknownRecord;
+}
+/** A titled group of related columns (one per report section) */
+interface ReportSection {
+  title: string;
+  columns: ReportColumn[];
+}
+/** A table column with optional comparison behavior */
+type ReportColumn = AnyColumn<Record<string, unknown>> & {
+  /** Add diff column after this column when baseline exists */comparable?: boolean; /** Set true for throughput metrics where higher values are better (e.g., lines/sec) */
+  higherIsBetter?: boolean; /** Stat descriptor: framework computes value from samples via computeStat */
+  statKind?: StatKind; /** Accessor for non-sample data (e.g., run count, metadata fields) */
+  value?: (results: MeasuredResults, metadata?: UnknownRecord) => unknown; /** Convert a timing-domain value to display domain (e.g., ms to lines/sec) */
+  toDisplay?: (timingValue: number, metadata?: Record<string, unknown>) => number;
+};
+type UnknownRecord = Record<string, unknown>;
+/** Compute column values for a section from results + metadata.
+*  statKind columns: computeStat(samples, kind), then toDisplay.
+*  value columns: call the accessor directly. */
+declare function computeColumnValues(section: ReportSection, results: MeasuredResults, metadata?: UnknownRecord): UnknownRecord;
+/** True if any result in the groups has the specified field with a defined value */
+declare function hasField(groups: ReportGroup[], field: keyof MeasuredResults): boolean;
 //#endregion
-//#region src/GitUtils.d.ts
+//#region src/report/GitUtils.d.ts
+/** Git commit hash, date, and dirty status for version tracking */
+interface GitVersion {
+  hash: string;
+  date: string;
+  dirty?: boolean;
+}
 /** Get current git version info. For dirty repos, uses most recent modified file date. */
 declare function getCurrentGitVersion(): GitVersion | undefined;
 /** Read baseline version from .baseline-version file */
@@ -434,184 +391,243 @@ declare function getBaselineVersion(baselineDir?: string): GitVersion | undefine
 /** Format git version for display: "abc1234 (Jan 9, 2026, 3:45 PM)" or "abc1234*" if dirty */
 declare function formatGitVersion(version: GitVersion): string;
 //#endregion
-//#region src/heap-sample/HeapSampleReport.d.ts
-interface CallFrame {
-  fn: string;
+//#region src/cli/CliExport.d.ts
+/** Options for exporting benchmark results to various formats */
+interface ExportOptions {
+  results: ReportGroup[];
+  args: DefaultCliArgs;
+  sections?: ReportSection[];
+  currentVersion?: GitVersion;
+  baselineVersion?: GitVersion;
+}
+/** Export options for matrix benchmarks (results/args supplied by the matrix pipeline). */
+interface MatrixExportOptions {
+  sections?: ReportSection[];
+  currentVersion?: GitVersion;
+  baselineVersion?: GitVersion;
+}
+/** Export reports (JSON, Perfetto, archive, viewer) based on CLI args. */
+declare function exportReports(options: ExportOptions): Promise<void>;
+//#endregion
+//#region src/matrix/CaseLoader.d.ts
+/** Module exporting case IDs and an optional loader for case data */
+interface CasesModule<T = unknown> {
+  cases: string[];
+  /** Subset of cases for quick runs */
+  defaultCases?: string[];
+  /** Subset of variants for quick runs */
+  defaultVariants?: string[];
+  loadCase?: (id: string) => LoadedCase<T> | Promise<LoadedCase<T>>;
+}
+/** Import and validate a cases module, which must export a `cases` array */
+declare function loadCasesModule<T = unknown>(moduleUrl: string): Promise<CasesModule<T>>;
+/** Load case data from a CasesModule, or use the caseId as data if no module */
+declare function loadCaseData<T>(casesModule: CasesModule<T> | undefined, caseId: string): Promise<LoadedCase<T>>;
+//#endregion
+//#region src/matrix/BenchMatrix.d.ts
+/** Stateless variant - called each iteration with case data */
+type VariantFn<T = unknown> = (caseData: T) => void;
+/** Stateful variant - setup once, run many */
+interface StatefulVariant<T = unknown, S = unknown> {
+  setup: (caseData: T) => S | Promise<S>;
+  run: (state: S) => void;
+}
+/** A variant is either a plain function or a stateful setup+run pair */
+type Variant<T = unknown, S = unknown> = VariantFn<T> | StatefulVariant<T, S>;
+/** Variant with any state type, allowing mixed variants in a matrix */
+type AnyVariant<T = unknown> = VariantFn<T> | StatefulVariant<T, any>;
+/** Case data and optional metadata returned by a cases module */
+interface LoadedCase<T = unknown> {
+  data: T;
+  metadata?: Record<string, unknown>;
+}
+/** Default runner settings applied to all matrix benchmarks */
+interface MatrixDefaults {
+  warmup?: number;
+  maxTime?: number;
+  iterations?: number;
+}
+/** Configuration for a cases x variants benchmark matrix */
+interface BenchMatrix<T = unknown> {
+  name: string;
+  variantDir?: string;
+  variants?: Record<string, AnyVariant<T>>;
+  cases?: string[];
+  casesModule?: string;
+  baselineDir?: string;
+  baselineVariant?: string;
+  defaults?: MatrixDefaults;
+}
+/** Named collection of benchmark matrices */
+interface MatrixSuite {
+  name: string;
+  matrices: BenchMatrix<any>[];
+}
+/** Results for a single variant across all cases */
+interface VariantResult {
+  id: string;
+  cases: CaseResult[];
+}
+/** Results for a single (variant, case) pair */
+interface CaseResult {
+  caseId: string;
+  measured: MeasuredResults;
+  metadata?: Record<string, unknown>;
+  baseline?: MeasuredResults;
+  deltaPercent?: number;
+}
+/** Aggregated results from running a benchmark matrix */
+interface MatrixResults {
+  name: string;
+  variants: VariantResult[];
+}
+/** Options for {@link runMatrix} */
+interface RunMatrixOptions {
+  /** Maximum iterations per benchmark */
+  iterations?: number;
+  /** Maximum time in ms per benchmark */
+  maxTime?: number;
+  /** Number of warmup iterations before measurement */
+  warmup?: number;
+  /** Use worker process isolation (default: true for variantDir) */
+  useWorker?: boolean;
+  /** Number of interleaved batches for baseline comparison */
+  batches?: number;
+  /** Include first batch in results (normally dropped for OS cache warmup) */
+  warmupBatch?: boolean;
+  /** Run only these cases (from --filter) */
+  filteredCases?: string[];
+  /** Run only these variants (from --filter) */
+  filteredVariants?: string[];
+  /** Force garbage collection between iterations */
+  gcForce?: boolean;
+  /** Track V8 optimization/deoptimization events */
+  traceOpt?: boolean;
+  /** Pause duration in ms before warmup begins */
+  pauseWarmup?: number;
+  /** Pause duration in ms before first measurement */
+  pauseFirst?: number;
+  /** Pause every N iterations during measurement */
+  pauseInterval?: number;
+  /** Duration of each pause in ms */
+  pauseDuration?: number;
+  /** Collect GC statistics via --trace-gc-nvp */
+  gcStats?: boolean;
+  /** Enable heap allocation profiling */
+  alloc?: boolean;
+  /** Heap sampling interval in bytes */
+  allocInterval?: number;
+  /** Maximum stack depth for allocation traces */
+  allocDepth?: number;
+  /** Enable CPU time profiling */
+  profile?: boolean;
+  /** CPU profiling sample interval in microseconds */
+  profileInterval?: number;
+  /** Track function call counts via V8 coverage */
+  callCounts?: boolean;
+}
+/** Run a BenchMatrix with inline variants or variantDir */
+declare function runMatrix<T>(matrix: BenchMatrix<T>, options?: RunMatrixOptions): Promise<MatrixResults>;
+/** Type guard for StatefulVariant */
+declare function isStatefulVariant<T, S>(v: Variant<T, S>): v is StatefulVariant<T, S>;
+//#endregion
+//#region src/profiling/node/ResolvedProfile.d.ts
+/** A call frame with display-ready 1-indexed source positions */
+interface ResolvedFrame {
+  /** Function name, "(anonymous)" when empty */
+  name: string;
+  /** Script URL or file path, "" when unknown */
   url: string;
+  /** 1-indexed line number */
   line: number;
+  /** 1-indexed column number (undefined when unknown) */
   col?: number;
 }
-type UserCodeFilter = (site: CallFrame) => boolean;
+//#endregion
+//#region src/profiling/node/HeapSampleReport.d.ts
+/** Predicate that returns true for user code (vs. runtime internals) */
+type UserCodeFilter = (site: ResolvedFrame) => boolean;
+/** Options for {@link formatHeapReport} */
 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;
 }
 //#endregion
+//#region src/cli/CliOptions.d.ts
+/** Convert CLI args to matrix runner options. */
+declare function cliToMatrixOptions(args: DefaultCliArgs): RunMatrixOptions;
+//#endregion
 //#region src/matrix/MatrixReport.d.ts
-/** Custom column definition for extra computed metrics */
-interface ExtraColumn {
-  key: string;
-  title: string;
-  groupTitle?: string;
-  extract: (caseResult: CaseResult) => unknown;
-  formatter?: (value: unknown) => string;
-}
-/** Options for matrix report generation */
+/** Options for {@link reportMatrixResults} */
 interface MatrixReportOptions {
-  extraColumns?: ExtraColumn[];
-  sections?: ResultsMapper[];
+  /** ReportSection sections (default: [timeSection, runsSection]) */
+  sections?: ReportSection[];
+  /** Custom title for the variant column (default: "variant") */
   variantTitle?: string;
+  /** Comparison options (equivalence margin, batch trimming) */
+  comparison?: ComparisonOptions;
 }
-/** GC statistics columns - derived from gcStatsSection for consistency */
-declare const gcStatsColumns: ExtraColumn[];
-/** GC pause time column */
-declare const gcPauseColumn: ExtraColumn;
-/** Heap sampling total bytes column */
-declare const heapTotalColumn: ExtraColumn;
-/** Format matrix results as one table per case */
+/** Format matrix results as text, with one table per case */
 declare function reportMatrixResults(results: MatrixResults, options?: MatrixReportOptions): string;
 //#endregion
-//#region src/cli/RunBenchCLI.d.ts
-interface ExportOptions {
-  results: ReportGroup[];
-  args: DefaultCliArgs;
-  sections?: any[];
-  suiteName?: string;
-  currentVersion?: GitVersion;
-  baselineVersion?: GitVersion;
-}
-interface MatrixExportOptions {
-  sections?: any[];
-  currentVersion?: GitVersion;
-  baselineVersion?: GitVersion;
-}
-/** Parse CLI with custom configuration */
-declare function parseBenchArgs<T = DefaultCliArgs>(configureArgs?: Configure<T>): T & DefaultCliArgs;
-/** Run suite with CLI arguments */
-declare function runBenchmarks(suite: BenchSuite, args: DefaultCliArgs): Promise<ReportGroup[]>;
-/** Generate table with standard sections */
-declare function defaultReport(groups: ReportGroup[], args: DefaultCliArgs): string;
-/** Run benchmarks, display table, and optionally generate HTML report */
-declare function benchExports(suite: BenchSuite, args: DefaultCliArgs): Promise<void>;
-/** Print heap allocation reports for benchmarks with heap profiles */
-declare function printHeapReports(groups: ReportGroup[], options: HeapReportOptions): void;
-/** Run benchmarks and display table. Suite is optional with --url (browser mode). */
-declare function runDefaultBench(suite?: BenchSuite, configureArgs?: Configure<any>): Promise<void>;
-/** Log V8 optimization tier distribution and deoptimizations */
+//#region src/cli/CliReport.d.ts
+/** Options for defaultReport: custom sections replace the CLI-derived defaults. */
+interface DefaultReportOptions {
+  sections?: ReportSection[];
+}
+/** Generate text report table with standard sections based on CLI args. */
+declare function defaultReport(groups: ReportGroup[], args: DefaultCliArgs, opts?: DefaultReportOptions): string;
+/** Log V8 optimization tier distribution and deoptimizations. */
 declare function reportOptStatus(groups: ReportGroup[]): void;
-/** @return true if any result has the specified field with a defined value */
-declare function hasField(results: ReportGroup[], field: keyof MeasuredResults): boolean;
-/** Export reports (HTML, JSON, Perfetto) based on CLI args */
-declare function exportReports(options: ExportOptions): Promise<void>;
-/** Run matrix suite with CLI arguments.
-*  no options ==> defaultCases/defaultVariants, --filter ==> subset of defaults,
-*  --all --filter ==> subset of all, --all ==> all cases/variants */
-declare function runMatrixSuite(suite: MatrixSuite, args: DefaultCliArgs): Promise<MatrixResults[]>;
-/** Convert CLI args to matrix run options */
-declare function cliToMatrixOptions(args: DefaultCliArgs): RunMatrixOptions;
-/** Generate report for matrix results. Uses same sections as regular benchmarks. */
+/** Print heap allocation profiles for each benchmark in the report groups. */
+declare function printHeapReports(groups: ReportGroup[], options: HeapReportOptions): void;
+/** Format matrix benchmark results as text, applying default sections from CLI args. */
 declare function defaultMatrixReport(results: MatrixResults[], reportOptions?: MatrixReportOptions, args?: DefaultCliArgs): string;
-/** Run matrix suite with full CLI handling (parse, run, report, export) */
-declare function runDefaultMatrixBench(suite: MatrixSuite, configureArgs?: Configure<any>, reportOptions?: MatrixReportOptions): Promise<void>;
-/** Convert MatrixResults to ReportGroup[] for export compatibility */
+/** Convert MatrixResults to ReportGroup[] for the standard export pipeline. */
 declare function matrixToReportGroups(results: MatrixResults[]): ReportGroup[];
-/** Run matrix benchmarks, display table, and generate exports */
-declare function matrixBenchExports(suite: MatrixSuite, args: DefaultCliArgs, reportOptions?: MatrixReportOptions, exportOptions?: MatrixExportOptions): Promise<void>;
 //#endregion
-//#region src/export/JsonFormat.d.ts
-/** Complete benchmark data structure for JSON export */
-interface BenchmarkJsonData {
-  meta: {
-    timestamp: string;
-    version: string;
-    args: Record<string, any>;
-    environment: {
-      node: string;
-      platform: string;
-      arch?: string;
-    };
-  };
-  suites: BenchmarkSuite[];
-}
-interface BenchmarkSuite {
-  name: string;
-  groups: BenchmarkGroup[];
-}
-interface BenchmarkGroup {
-  name: string;
-  baseline?: BenchmarkResult;
-  benchmarks: BenchmarkResult[];
-}
-interface BenchmarkResult {
-  name: string;
-  status: "completed" | "running" | "failed";
-  /** Raw execution time samples in milliseconds */
-  samples: number[];
-  /** Statistical summaries */
-  time: {
-    min: number;
-    max: number;
-    mean: number;
-    p50: number;
-    p75: number;
-    p99: number;
-    p999: number;
-  };
-  /** Optional performance metrics */
-  heapSize?: {
-    min: number;
-    max: number;
-    mean: number;
-  };
-  gcTime?: {
-    min: number;
-    max: number;
-    mean: number;
-  };
-  cpu?: {
-    instructions?: number;
-    cycles?: number;
-    cacheMisses?: number;
-    branchMisses?: number;
-  };
-  /** Execution metadata */
-  execution: {
-    iterations: number;
-    totalTime: number;
-    warmupRuns?: number;
-  };
-  /** Adaptive mode results */
-  adaptive?: {
-    confidenceInterval: {
-      lower: number;
-      upper: number;
-      margin: number;
-      marginPercent: number;
-      confidence: number;
-    };
-    converged: boolean;
-    stopReason: "threshold_met" | "max_time" | "max_iterations";
-  };
-  /** Error information */
-  error?: {
-    message: string;
-    type: string;
-    stackTrace?: string;
-  };
-}
+//#region src/cli/RunBenchCLI.d.ts
+/** Options for running a BenchSuite: custom sections replace the CLI-derived defaults. */
+interface BenchExportsOptions {
+  sections?: ReportSection[];
+}
+/** Top-level CLI dispatch: route to view, analyze, or default bench runner. */
+declare function dispatchCli(): Promise<void>;
+/** Run benchmarks and display results. Suite is optional with --url (browser mode). */
+declare function runDefaultBench(suite?: BenchSuite, configureArgs?: Configure<any>, argv?: string[], opts?: BenchExportsOptions): Promise<void>;
+/** Parse CLI args with optional custom yargs configuration. */
+declare function parseBenchArgs<T = DefaultCliArgs>(configureArgs?: Configure<T>, argv?: string[]): T & DefaultCliArgs;
+/** Run a BenchSuite and print results with standard reporting. */
+declare function benchExports(suite: BenchSuite, args: DefaultCliArgs, opts?: BenchExportsOptions): Promise<void>;
+/** Run matrix suite with full CLI handling (parse, run, report, export). */
+declare function runDefaultMatrixBench(suite: MatrixSuite, configureArgs?: Configure<any>, reportOptions?: MatrixReportOptions): Promise<void>;
+/** Run a matrix suite, print results, and handle exports. */
+declare function matrixBenchExports(suite: MatrixSuite, args: DefaultCliArgs, reportOptions?: MatrixReportOptions, exportOptions?: MatrixExportOptions): Promise<void>;
+/** Run matrix suite with CLI arguments. --filter narrows defaults, --all --filter narrows all. */
+declare function runMatrixSuite(suite: MatrixSuite, args: DefaultCliArgs): Promise<MatrixResults[]>;
 //#endregion
-//#region src/export/PerfettoExport.d.ts
-/** Export benchmark results to Perfetto-compatible trace file */
-declare function exportPerfettoTrace(groups: ReportGroup[], outputPath: string, args: DefaultCliArgs): void;
+//#region src/cli/SuiteRunner.d.ts
+/** Run a benchmark suite with CLI arguments. */
+declare function runBenchmarks(suite: BenchSuite, args: DefaultCliArgs): Promise<ReportGroup[]>;
 //#endregion
-//#region src/export/SpeedscopeExport.d.ts
+//#region src/export/SpeedscopeTypes.d.ts
+/** Shared speedscope file format types and frame interning utilities. */
 /** speedscope file format (https://www.speedscope.app/file-format-schema.json) */
 interface SpeedscopeFile {
   $schema: "https://www.speedscope.app/file-format-schema.json";
@@ -622,13 +638,17 @@ interface SpeedscopeFile {
   name?: string;
   exporter?: string;
 }
+/** A single call frame with optional source location */
 interface SpeedscopeFrame {
   name: string;
   file?: string;
   line?: number;
   col?: number;
 }
-interface SpeedscopeProfile {
+/** Union of heap and time profile shapes (unit differs) */
+type SpeedscopeProfile = SpeedscopeHeapProfile | SpeedscopeTimeProfile;
+/** Heap allocation profile weighted by bytes */
+interface SpeedscopeHeapProfile {
   type: "sampled";
   name: string;
   unit: "bytes";
@@ -637,39 +657,185 @@ interface SpeedscopeProfile {
   samples: number[][];
   weights: number[];
 }
-/** Export heap profiles from benchmark results to speedscope JSON format.
-*  Creates one speedscope profile per benchmark that has a heapProfile.
-*  @returns resolved output path, or undefined if no profiles were found */
+/** CPU time profile weighted by microseconds */
+interface SpeedscopeTimeProfile {
+  type: "sampled";
+  name: string;
+  unit: "microseconds";
+  startValue: number;
+  endValue: number;
+  samples: number[][];
+  weights: number[];
+}
+//#endregion
+//#region src/export/AllocExport.d.ts
+/** Export heap profiles to speedscope JSON. Returns output path, or undefined if no profiles. */
 declare function exportSpeedscope(groups: ReportGroup[], outputPath: string): string | undefined;
-/** Export to a temp file and open in speedscope via npx */
-declare function exportAndLaunchSpeedscope(groups: ReportGroup[]): void;
-/** Launch speedscope viewer on a file via npx */
-declare function launchSpeedscope(filePath: string): void;
-/** Convert a single HeapProfile to speedscope format (for standalone use) */
+/** Convert a single HeapProfile to speedscope format. */
 declare function heapProfileToSpeedscope(name: string, profile: HeapProfile): SpeedscopeFile;
+/** Build SpeedscopeFile from report groups. Returns undefined if no profiles found. */
+declare function buildSpeedscopeFile(groups: ReportGroup[]): SpeedscopeFile | undefined;
 //#endregion
-//#region src/HtmlDataPrep.d.ts
-interface PrepareHtmlOptions {
-  cliArgs?: Record<string, unknown>;
-  sections?: ResultsMapper[];
-  currentVersion?: GitVersion;
-  baselineVersion?: GitVersion;
+//#region src/viewer/ReportData.d.ts
+/** Top-level data structure for the HTML benchmark report. */
+interface ReportData {
+  groups: BenchmarkGroup[];
+  metadata: {
+    timestamp: string;
+    bencherVersion: string;
+    cliArgs?: Record<string, unknown>;
+    cliDefaults?: Record<string, unknown>;
+    gcTrackingEnabled?: boolean;
+    currentVersion?: GitVersion;
+    baselineVersion?: GitVersion;
+    environment?: {
+      node: string;
+      platform: string;
+      arch: string;
+    };
+  };
+}
+/** A named group of benchmarks, optionally compared against a baseline. */
+interface BenchmarkGroup {
+  name: string;
+  baseline?: BenchmarkEntry;
+  benchmarks: BenchmarkEntry[];
+  warnings?: string[];
+}
+/** One benchmark's raw data, statistics, and optional comparison results. */
+interface BenchmarkEntry {
+  name: string;
+  samples: number[];
+  warmupSamples?: number[];
+  allocationSamples?: number[];
+  heapSamples?: number[];
+  gcEvents?: GcEvent[];
+  optSamples?: number[];
+  pausePoints?: PausePoint[];
+  batchOffsets?: number[];
+  stats: BenchmarkStats;
+  heapSize?: {
+    min: number;
+    max: number;
+    avg: number;
+  };
+  totalTime?: number;
+  sections?: ViewerSection[];
+  coverageSummary?: CoverageSummary;
+  heapSummary?: HeapSummary;
+  comparisonCI?: DifferenceCI;
+}
+/** Summary percentile statistics for a benchmark's samples. */
+interface BenchmarkStats {
+  min: number;
+  max: number;
+  avg: number;
+  p50: number;
+  p75: number;
+  p99: number;
+  p999: number;
+  cv?: number;
+  mad?: number;
+  outlierRate?: number;
+}
+/** A section of related stats for the viewer (e.g., "Lines / Sec", "GC"). */
+interface ViewerSection {
+  title: string;
+  tabLink?: string;
+  rows: ViewerRow[];
+}
+/** A stat row with per-run values and optional comparison CI. */
+interface ViewerRow {
+  label: string;
+  entries: ViewerEntry[];
+  comparisonCI?: DifferenceCI;
+  shared?: boolean;
+  /** First comparable row with a statKind in the section. */
+  primary?: boolean;
+}
+/** A single run's value for a stat. */
+interface ViewerEntry {
+  runName: string;
+  value: string;
+  bootstrapCI?: BootstrapCIData;
+}
+/** Bootstrap CI data for inline visualization. */
+interface BootstrapCIData {
+  estimate: number;
+  ci: [number, number];
+  histogram: HistogramBin[];
+  /** Formatted CI bounds for display (e.g., ["0.12ms", "0.15ms"]) */
+  ciLabels?: [string, string];
+  /** Block-level (between-run) or sample-level (within-run) resampling */
+  ciLevel?: CILevel;
+  /** false when batch count is too low for reliable CI */
+  ciReliable?: boolean;
+}
+/** Summary of coverage/call-count data. */
+interface CoverageSummary {
+  functionCount: number;
+  totalCalls: number;
+}
+/** Summary of heap allocation profile. */
+interface HeapSummary {
+  totalBytes: number;
+  userBytes: number;
+}
+/** A garbage collection event with timing relative to the benchmark start. */
+interface GcEvent {
+  offset: number;
+  duration: number;
 }
-/** Prepare ReportData from benchmark results for HTML rendering */
-declare function prepareHtmlData(groups: ReportGroup[], options: PrepareHtmlOptions): ReportData;
 //#endregion
-//#region src/matrix/CaseLoader.d.ts
-/** Module that exports case definitions */
-interface CasesModule<T = unknown> {
-  cases: string[];
-  defaultCases?: string[];
-  defaultVariants?: string[];
-  loadCase?: (id: string) => LoadedCase<T> | Promise<LoadedCase<T>>;
+//#region src/export/CoverageExport.d.ts
+/** Per-function execution count at a specific source line. */
+interface LineCoverage {
+  /** 1-indexed line number of the function start */
+  startLine: number;
+  /** Function name (empty string for anonymous top-level) */
+  functionName: string;
+  /** Number of times the function was invoked */
+  count: number;
 }
-/** Load a cases module by URL */
-declare function loadCasesModule<T = unknown>(moduleUrl: string): Promise<CasesModule<T>>;
-/** Load case data from a CasesModule or pass through the caseId */
-declare function loadCaseData<T>(casesModule: CasesModule<T> | undefined, caseId: string): Promise<LoadedCase<T>>;
+//#endregion
+//#region src/export/ArchiveFormat.d.ts
+interface BenchforgeArchive {
+  /** Archive format version. */
+  schema: number;
+  /** Heap allocation profile in Speedscope format. */
+  allocProfile?: SpeedscopeFile;
+  /** CPU time profile in Speedscope format. */
+  timeProfile?: SpeedscopeFile;
+  /** Per-line coverage data keyed by source URL. */
+  coverage?: Record<string, LineCoverage[]>;
+  /** Benchmark report with suite results and statistics. */
+  report?: ReportData;
+  /** Source file contents keyed by file URL. */
+  sources: Record<string, string>;
+  /** Archive creation metadata. */
+  metadata: ArchiveMetadata;
+}
+interface ArchiveMetadata {
+  /** ISO timestamp (colons/periods replaced with dashes for filename safety). */
+  timestamp: string;
+  /** Benchforge package version. */
+  benchforgeVersion: string;
+}
+//#endregion
+//#region src/export/ArchiveExport.d.ts
+interface ArchiveOptions {
+  groups: ReportGroup[];
+  reportData?: ReportData;
+  timeProfileData?: string;
+  coverageData?: string;
+  outputPath?: string;
+}
+/** Build a .benchforge archive file. Returns output path, or undefined if nothing to archive. */
+declare function archiveBenchmark(options: ArchiveOptions): Promise<string | undefined>;
+//#endregion
+//#region src/export/PerfettoExport.d.ts
+/** Export benchmark results to Perfetto-compatible trace file */
+declare function exportPerfettoTrace(groups: ReportGroup[], outputPath: string, args: DefaultCliArgs): void;
 //#endregion
 //#region src/matrix/MatrixFilter.d.ts
 /** Filter for matrix case/variant selection */
@@ -687,84 +853,71 @@ declare function parseMatrixFilter(filter: string): MatrixFilter;
 /** Apply filter to a matrix, merging with existing filters via intersection */
 declare function filterMatrix<T>(matrix: FilteredMatrix<T>, filter?: MatrixFilter): Promise<FilteredMatrix<T>>;
 //#endregion
-//#region src/StandardSections.d.ts
-interface TimeStats {
-  mean?: number;
-  p50?: number;
-  p99?: number;
-}
-interface GcSectionStats {
-  gc?: number;
-}
-interface GcStatsInfo {
-  allocPerIter?: number;
-  collected?: number;
-  scavenges?: number;
-  fullGCs?: number;
-  promoPercent?: number;
-  pausePerIter?: number;
-}
-interface CpuStats {
-  cpuCacheMiss?: number;
-  cpuStall?: number;
-}
-interface RunStats {
-  runs?: number;
-}
-interface AdaptiveStats {
-  median?: number;
-  mean?: number;
-  p99?: number;
-  convergence?: number;
-}
-interface OptStats {
-  tiers?: string;
-  deopt?: number;
-}
-/** Section: mean, p50, p99 timing */
-declare const timeSection: ResultsMapper<TimeStats>;
-/** Section: GC time as fraction of total benchmark time (Node performance hooks) */
-declare const gcSection: ResultsMapper<GcSectionStats>;
-/** Section: detailed GC stats from --trace-gc-nvp (allocation, promotion, pauses) */
-declare const gcStatsSection: ResultsMapper<GcStatsInfo>;
-/** Section: CPU L1 cache miss rate and stall rate (requires @mitata/counters) */
-declare const cpuSection: ResultsMapper<CpuStats>;
-/** Section: number of sample iterations */
-declare const runsSection: ResultsMapper<RunStats>;
-/** Section: total sampling duration in seconds (brackets if >= 30s) */
-declare const totalTimeSection: ResultsMapper<{
-  totalTime?: number;
-}>;
-/** Section: median, mean, p99, and convergence for adaptive mode */
-declare const adaptiveSection: ResultsMapper<AdaptiveStats>;
-/** Section: V8 optimization tier distribution and deopt count */
-declare const optSection: ResultsMapper<OptStats>;
-/** Build generic sections based on CLI flags */
-declare function buildGenericSections(args: {
-  "gc-stats"?: boolean;
-  "heap-sample"?: boolean;
-}): ResultsMapper[];
-//#endregion
-//#region src/StatisticalUtils.d.ts
-/** @return mean of values */
-declare function average(values: number[]): number;
-//#endregion
-//#region src/table-util/ConvergenceFormatters.d.ts
-/** @return convergence percentage with color for low values */
-declare function formatConvergence(v: unknown): string;
-//#endregion
-//#region src/table-util/Formatters.d.ts
-/** Format time in milliseconds, showing very small values with units */
+//#region src/report/Formatters.d.ts
+/** Format time in milliseconds with appropriate units */
 declare function timeMs(ms: unknown): string | null;
 /** Format integer with thousand separators */
 declare function integer(x: unknown): string | null;
-/** Format bytes with appropriate units (B, KB, MB, GB).
-*  Use `space: true` for human-readable console output (`1.5 KB`). */
+/** Format bytes with appropriate units. Use `space: true` for `1.5 KB` style. */
 declare function formatBytes(bytes: unknown, opts?: {
   space?: boolean;
 }): string | null;
 /** @return truncated string with ellipsis if over maxLen */
 declare function truncate(str: string, maxLen?: number): string;
+/** @return convergence percentage with color for low values */
+declare function formatConvergence(v: unknown): string;
+//#endregion
+//#region src/report/GcSections.d.ts
+/** Report section: GC time as fraction of total benchmark time. */
+declare const gcSection: ReportSection;
+/** Report section: detailed GC stats from --trace-gc-nvp. */
+declare const gcStatsSection: ReportSection;
+/** @return GC stats sections if enabled by CLI flags */
+declare function gcSections(args: {
+  "gc-stats"?: boolean;
+}): ReportSection[];
+//#endregion
+//#region src/report/HtmlReport.d.ts
+/** Options for prepareHtmlData: report sections, git versions, and CLI args */
+interface PrepareHtmlOptions extends ComparisonOptions {
+  cliArgs?: Record<string, unknown>;
+  sections?: ReportSection[];
+  currentVersion?: GitVersion;
+  baselineVersion?: GitVersion;
+}
+/** Convert benchmark results into a ReportData payload for the HTML viewer */
+declare function prepareHtmlData(groups: ReportGroup[], options: PrepareHtmlOptions): ReportData;
+//#endregion
+//#region src/report/StandardSections.d.ts
+/** Default timing section: mean, p50, p99. */
+declare const timeSection: ReportSection;
+/** Report section: number of sample iterations. */
+declare const runsSection: ReportSection;
+/** Report section: total sampling duration. */
+declare const totalTimeSection: ReportSection;
+/** Report sections: timing stats and convergence for adaptive mode. */
+declare const adaptiveSections: ReportSection[];
+/** Report section: V8 optimization tier distribution and deopt count. */
+declare const optSection: ReportSection;
+/** Build a time section with user-chosen percentile/stat columns. */
+declare function buildTimeSection(stats?: string): ReportSection;
+/** @return default report sections from CLI flags (GC stats if enabled, plus run count). */
+declare function buildGenericSections(args: {
+  "gc-stats"?: boolean;
+  alloc?: boolean;
+}): ReportSection[];
+//#endregion
+//#region src/report/text/TextReport.d.ts
+/** Options for text report rendering, including baseline comparison settings. */
+interface TextReportOptions extends ComparisonOptions {}
+/** Build a formatted text table from benchmark groups, with baseline diff columns when present. */
+declare function reportResults(groups: ReportGroup[], sections: ReportSection[], options?: TextReportOptions): string;
+//#endregion
+//#region src/viewer/DateFormat.d.ts
+/** Format ISO date as local time with UTC: "Jan 9, 2026, 3:45 PM (2026-01-09T23:45:00Z)" */
+declare function formatDateWithTimezone(isoDate: string): string;
+/** Format relative time: "5m ago", "2h ago", "yesterday", "3 days ago" */
+declare function formatRelativeTime(isoDate: string): string;
 //#endregion
-export { type AnyVariant, type BenchGroup, type BenchMatrix, type BenchSuite, BenchmarkGroup, BenchmarkJsonData, type BenchmarkReport, BenchmarkResult, type BenchmarkSpec, BenchmarkSuite, type CaseResult, type CasesModule, type Configure, type DefaultCliArgs, type ExportOptions, type ExtraColumn, type FilteredMatrix, type GitVersion, type HtmlReportOptions, type LoadedCase, type MatrixDefaults, type MatrixExportOptions, type MatrixFilter, type MatrixReportOptions, type MatrixResults, type MatrixSuite, type MeasuredResults, type PrepareHtmlOptions, type ReportColumnGroup, type ReportData, type ReportGroup, type ResultsMapper, type RunMatrixOptions, type RunnerOptions, type StatefulVariant, type UnknownRecord, type Variant, type VariantFn, type VariantResult, adaptiveSection, average, benchExports, buildGenericSections, cliToMatrixOptions, cpuSection, defaultCliArgs, defaultMatrixReport, defaultReport, exportAndLaunchSpeedscope, exportPerfettoTrace, exportReports, exportSpeedscope, filterMatrix, formatBytes, formatConvergence, formatDateWithTimezone, formatGitVersion, gcPauseColumn, gcSection, gcStatsColumns, gcStatsSection, generateHtmlReport, getBaselineVersion, getCurrentGitVersion, hasField, heapProfileToSpeedscope, heapTotalColumn, integer, isStatefulVariant, launchSpeedscope, loadCaseData, loadCasesModule, matrixBenchExports, matrixToReportGroups, optSection, parseBenchArgs, parseCliArgs, parseMatrixFilter, prepareHtmlData, printHeapReports, reportMatrixResults, reportOptStatus, reportResults, runBenchmarks, runDefaultBench, runDefaultMatrixBench, runMatrix, runMatrixSuite, runsSection, timeMs, timeSection, totalTimeSection, truncate };
+export { type AnyVariant, type ArchiveMetadata, type BenchGroup, type BenchMatrix, type BenchSuite, type BenchforgeArchive, type BenchmarkReport, type BenchmarkSpec, type CaseResult, type CasesModule, type ComparisonOptions, type Configure, type DefaultCliArgs, type ExportOptions, type FilteredMatrix, type GitVersion, type LoadedCase, type MatrixDefaults, type MatrixExportOptions, type MatrixFilter, type MatrixReportOptions, type MatrixResults, type MatrixSuite, type MeasuredResults, type PrepareHtmlOptions, type ReportColumn, type ReportData, type ReportGroup, type ReportSection, type RunMatrixOptions, type RunnerOptions, type StatKind, type StatefulVariant, type UnknownRecord, type Variant, type VariantFn, type VariantResult, adaptiveSections, archiveBenchmark, average, benchExports, browserCliArgs, buildGenericSections, buildSpeedscopeFile, buildTimeSection, cliToMatrixOptions, computeColumnValues, computeStat, defaultCliArgs, defaultMatrixReport, defaultReport, dispatchCli, exportPerfettoTrace, exportReports, exportSpeedscope, filterMatrix, formatBytes, formatConvergence, formatDateWithTimezone, formatGitVersion, formatRelativeTime, gcSection, gcSections, gcStatsSection, getBaselineVersion, getCurrentGitVersion, hasField, heapProfileToSpeedscope, integer, isBootstrappable, isStatefulVariant, loadCaseData, loadCasesModule, matrixBenchExports, matrixToReportGroups, maxBootstrapInput, median, optSection, parseBenchArgs, parseCliArgs, parseMatrixFilter, percentile, prepareHtmlData, printHeapReports, reportMatrixResults, reportOptStatus, reportResults, runBenchmarks, runDefaultBench, runDefaultMatrixBench, runMatrix, runMatrixSuite, runsSection, timeMs, timeSection, totalTimeSection, truncate };
 //# sourceMappingURL=index.d.mts.map