benchforge 0.1.11 → 0.2.4

package/src/viewer/ReportData.ts

@@ -0,0 +1,123 @@
+import type { GitVersion } from "../report/GitUtils.ts";
+import type { PausePoint } from "../runners/MeasuredResults.ts";
+import type {
+  CILevel,
+  DifferenceCI,
+  HistogramBin,
+} from "../stats/StatisticalUtils.ts";
+
+/** Top-level data structure for the HTML benchmark report. */
+export 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. */
+export interface BenchmarkGroup {
+  name: string;
+  baseline?: BenchmarkEntry;
+  benchmarks: BenchmarkEntry[];
+  warnings?: string[];
+}
+
+/** One benchmark's raw data, statistics, and optional comparison results. */
+export 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. */
+export 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"). */
+export interface ViewerSection {
+  title: string;
+  tabLink?: string;
+  rows: ViewerRow[];
+}
+
+/** A stat row with per-run values and optional comparison CI. */
+export 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. */
+export interface ViewerEntry {
+  runName: string;
+  value: string;
+  bootstrapCI?: BootstrapCIData;
+}
+
+/** Bootstrap CI data for inline visualization. */
+export 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. */
+export interface CoverageSummary {
+  functionCount: number;
+  totalCalls: number;
+}
+
+/** Summary of heap allocation profile. */
+export interface HeapSummary {
+  totalBytes: number;
+  userBytes: number;
+}
+
+/** A garbage collection event with timing relative to the benchmark start. */
+export interface GcEvent {
+  offset: number;
+  duration: number;
+}

package/src/viewer/State.ts

@@ -0,0 +1,49 @@
+import { signal } from "@preact/signals";
+import type { DataProvider } from "./Providers.ts";
+import type { ReportData } from "./ReportData.ts";
+
+/** Tracked state for an open source-code tab in the viewer. */
+export interface SourceTabState {
+  id: string;
+  file: string;
+  line: number;
+  col: number;
+  generation: number;
+}
+
+/** User color-scheme preference: follow OS, or force light/dark. */
+export type ThemePreference = "system" | "light" | "dark";
+
+/** Active data source (server or archive). */
+export const provider = signal<DataProvider | null>(null);
+
+/** Parsed report data from the provider. */
+export const reportData = signal<ReportData | null>(null);
+
+/** Currently visible tab id. */
+export const activeTabId = signal("summary");
+
+/** Whether sample data has been loaded for the samples tab. */
+export const samplesLoaded = signal(false);
+
+/** Error info when a `?url=` archive fetch fails. */
+export const urlError = signal<{ url: string; detail: string } | null>(null);
+
+/** Open source-code tabs. */
+export const sourceTabs = signal<SourceTabState[]>([]);
+
+const cookieTheme = document.cookie.match(/(?:^|; )theme=(light|dark)/);
+
+/** User's light/dark theme preference, initialized from cookie. */
+export const themePreference = signal<ThemePreference>(
+  (cookieTheme?.[1] as ThemePreference) ?? "system",
+);
+
+/** Pick the best default tab based on available data. */
+export function defaultTabId(): string {
+  const config = provider.value?.config;
+  if (config?.hasReport) return "summary";
+  if (config?.hasProfile) return "flamechart";
+  if (config?.hasTimeProfile) return "time-flamechart";
+  return "summary";
+}

package/src/viewer/Theme.ts

@@ -0,0 +1,15 @@
+import { type ThemePreference, themePreference } from "./State.ts";
+
+/** Apply a theme preference, persisting to a cookie and updating the document. */
+export function setTheme(pref: ThemePreference): void {
+  themePreference.value = pref;
+  if (pref === "system") {
+    delete document.documentElement.dataset.theme;
+    // biome-ignore lint/suspicious/noDocumentCookie: no alternative API for setting cookies
+    document.cookie = "theme=; max-age=0; path=/; SameSite=Lax";
+  } else {
+    document.documentElement.dataset.theme = pref;
+    // biome-ignore lint/suspicious/noDocumentCookie: no alternative API for setting cookies
+    document.cookie = `theme=${pref}; max-age=31536000; path=/; SameSite=Lax`;
+  }
+}

package/src/viewer/components/App.tsx

@@ -0,0 +1,73 @@
+import { useEffect, useState } from "preact/hooks";
+import type { DataProvider } from "../Providers.ts";
+import {
+  type ArchiveData,
+  ArchiveProvider,
+  ServerProvider,
+} from "../Providers.ts";
+import {
+  activeTabId,
+  defaultTabId,
+  provider,
+  reportData,
+  samplesLoaded,
+  sourceTabs,
+  urlError,
+} from "../State.ts";
+import { DropZone } from "./DropZone.tsx";
+import { Shell } from "./Shell.tsx";
+
+/** Reset viewer state and activate the appropriate default tab for the provider. */
+export function initViewer(p: DataProvider): void {
+  provider.value = p;
+  reportData.value = null;
+  samplesLoaded.value = false;
+  urlError.value = null;
+  sourceTabs.value = [];
+  activeTabId.value = defaultTabId();
+}
+
+export function App() {
+  const [resolved, setResolved] = useState(false);
+
+  useEffect(() => {
+    resolve().then(() => setResolved(true));
+  }, []);
+
+  if (provider.value) return <Shell />;
+  if (resolved) return <DropZone />;
+  return null;
+}
+
+/** Try archive URL param, preloaded data, then dev server -- first match wins. */
+async function resolve(): Promise<void> {
+  const archiveUrl = new URLSearchParams(window.location.search).get("url");
+  if (archiveUrl) {
+    try {
+      const resp = await fetch(archiveUrl);
+      if (resp.ok) {
+        initViewer(new ArchiveProvider((await resp.json()) as ArchiveData));
+        return;
+      }
+      urlError.value = { url: archiveUrl, detail: `(${resp.status})` };
+    } catch {
+      urlError.value = {
+        url: archiveUrl,
+        detail: "(Perhaps CORS or network error?)",
+      };
+    }
+  }
+
+  const preloaded = (window as unknown as Record<string, unknown>)
+    .__benchforgeArchive as ArchiveData | undefined;
+  if (preloaded) {
+    initViewer(new ArchiveProvider(preloaded));
+    return;
+  }
+
+  try {
+    initViewer(await ServerProvider.create());
+  } catch {
+    // No server available
+  }
+}

package/src/viewer/components/DropZone.tsx

@@ -0,0 +1,71 @@
+import { useRef, useState } from "preact/hooks";
+import { type ArchiveData, ArchiveProvider } from "../Providers.ts";
+import { urlError } from "../State.ts";
+import { initViewer } from "./App.tsx";
+
+/** Landing page for loading `.benchforge` archive files via drag-drop or file picker. */
+export function DropZone() {
+  const [dragOver, setDragOver] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  /** Parse an archive JSON file and initialize the viewer with its data. */
+  async function loadFile(file: File): Promise<void> {
+    try {
+      const text = await file.text();
+      const archive = JSON.parse(text) as ArchiveData;
+      initViewer(new ArchiveProvider(archive));
+    } catch (err) {
+      console.error("Failed to load archive:", err);
+      setError(String(err));
+    }
+  }
+
+  return (
+    <div
+      class={`drop-zone${dragOver ? " drag-over" : ""}`}
+      onDragOver={e => {
+        e.preventDefault();
+        setDragOver(true);
+      }}
+      onDragLeave={() => setDragOver(false)}
+      onDrop={async e => {
+        e.preventDefault();
+        setDragOver(false);
+        const file = e.dataTransfer?.files[0];
+        if (file) loadFile(file);
+      }}
+    >
+      <div class="drop-zone-content">
+        <h2>Benchforge Viewer</h2>
+        <p>
+          Drop a <code>.benchforge</code> file here to view results
+        </p>
+        <div class="drop-zone-divider">or</div>
+        <label class="drop-zone-browse">
+          Browse files
+          <input
+            ref={inputRef}
+            type="file"
+            accept=".benchforge"
+            hidden
+            onChange={() => {
+              const file = inputRef.current?.files?.[0];
+              if (file) loadFile(file);
+            }}
+          />
+        </label>
+        {urlError.value && (
+          <p class="drop-zone-error">
+            Failed to load archive from <b>{urlError.value.url}</b>.{" "}
+            {urlError.value.detail}
+            <p>Download the file and drop it here instead.</p>
+          </p>
+        )}
+        {error && (
+          <p class="drop-zone-error">Failed to load file: {error}</p>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/viewer/components/LazyPlot.ts

@@ -0,0 +1,33 @@
+import type { RefObject } from "preact";
+import { useEffect, useRef } from "preact/hooks";
+
+/**
+ * Lazy-import a plot module and mount the resulting element into a div ref.
+ * Defers the ~hundreds-of-KB `@observablehq/plot` + `d3` bundle until the
+ * Samples tab is actually opened, keeping the initial viewer load small.
+ */
+export function useLazyPlot(
+  render: () => Promise<Element | null | undefined>,
+  deps: unknown[],
+  errorLabel?: string,
+): RefObject<HTMLDivElement> {
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    render()
+      .then(el => {
+        if (!ref.current || !el) return;
+        ref.current.innerHTML = "";
+        ref.current.appendChild(el);
+      })
+      .catch(err => {
+        console.error(`${errorLabel ?? "Plot"} failed:`, err);
+        if (ref.current) {
+          const div = document.createElement("div");
+          div.className = "loading";
+          div.textContent = String(err.message ?? err);
+          ref.current.replaceChildren(div);
+        }
+      });
+  }, deps);
+  return ref;
+}

package/src/viewer/components/SamplesPanel.tsx

@@ -0,0 +1,214 @@
+import { useMemo, useState } from "preact/hooks";
+import type { BenchmarkGroup, ReportData } from "../ReportData.ts";
+import {
+  batchCount,
+  filterToBatch,
+  type FlattenedData,
+  flattenSamples,
+  type PreparedBenchmark,
+  prepareBenchmarks,
+} from "../plots/RenderPlots.ts";
+import type { SeriesVisibility } from "../plots/SampleTimeSeries.ts";
+import { reportData, samplesLoaded } from "../State.ts";
+import { useLazyPlot } from "./LazyPlot.ts";
+
+/** True when at least one benchmark group has multiple samples (enough to plot). */
+export function hasSufficientSamples(data: ReportData): boolean {
+  return data.groups.some(groupHasSamples);
+}
+
+/** True when any benchmark or baseline in the group has multiple samples. */
+function groupHasSamples(group: BenchmarkGroup): boolean {
+  const multiSample = (b: { samples: unknown[] }) => b.samples.length > 1;
+  return group.benchmarks.some(multiSample) || (!!group.baseline && multiSample(group.baseline));
+}
+
+/** Time-series and histogram plots for each benchmark group. Lazy-loaded on first tab activation. */
+export function SamplesPanel() {
+  const data = reportData.value;
+  if (!samplesLoaded.value || !data) return null;
+
+  return (
+    <>
+      {data.groups.map((group, i) => (
+        <SamplesGroup key={i} group={group} index={i} />
+      ))}
+    </>
+  );
+}
+
+/** Renders time-series and histogram plots for one benchmark group, with batch stepping and series toggles. */
+function SamplesGroup({ group, index }: { group: BenchmarkGroup; index: number }) {
+  const hasSamples = groupHasSamples(group);
+  const benchmarks = useMemo(() => prepareBenchmarks(group), [group]);
+  const flat = useMemo(
+    () => hasSamples ? flattenSamples(benchmarks) : null,
+    [benchmarks, hasSamples],
+  );
+  const numBatches = hasSamples ? batchCount(benchmarks) : 0;
+
+  // batch === 0 means "All", 1..numBatches means specific batch
+  const [batch, setBatch] = useState(0);
+  const activeBatch = batch > numBatches ? 0 : batch;
+
+  const viewFlat = useMemo(
+    () => flat && activeBatch > 0 ? filterToBatch(flat, benchmarks, activeBatch - 1) : flat,
+    [flat, benchmarks, activeBatch],
+  );
+
+  const [visibility, setVisibility] = useState<SeriesVisibility>({
+    baseline: true,
+    heap: true,
+    baselineHeap: false,
+    rejected: true,
+  });
+
+  if (!group.benchmarks?.length) return null;
+  if (!hasSamples || !flat || !viewFlat) return (
+    <div>
+      <div class="group-header">
+        <h2>{group.name}</h2>
+      </div>
+      <p class="single-sample-notice">
+        Single sample collected &mdash; plots require multiple samples.
+      </p>
+    </div>
+  );
+
+  const hasBaseline = !!group.baseline;
+  const hasHeap = flat.heapSeries.length > 0, hasBaselineHeap = flat.baselineHeapSeries.length > 0;
+  const hasRejected = flat.timeSeries.some(d => d.isRejected);
+  const totalPoints = viewFlat.timeSeries.length, sampled = totalPoints > 1000;
+
+  const toggle = (key: keyof SeriesVisibility) =>
+    setVisibility(v => ({ ...v, [key]: !v[key] }));
+
+  return (
+    <div>
+      <div class="group-header">
+        <h2>{group.name}</h2>
+      </div>
+      <div class="plot-grid">
+        <div class="plot-container">
+          <div class="plot-title">Time per Iteration</div>
+          <div class="plot-description">
+            {sampled
+              ? `Sampled from ${totalPoints.toLocaleString()} iterations (showing ~1,000)`
+              : "Execution time for each iteration in collection order"}
+          </div>
+          <div class="plot-controls">
+            <SeriesToggles
+              hasBaseline={hasBaseline}
+              hasHeap={hasHeap}
+              hasBaselineHeap={hasBaselineHeap}
+              hasRejected={hasRejected}
+              visibility={visibility}
+              onToggle={toggle}
+            />
+            {numBatches > 1 && (
+              <BatchStepper batch={activeBatch} total={numBatches} onChange={setBatch} />
+            )}
+          </div>
+          <TimeSeriesPlot
+            benchmarks={benchmarks}
+            flat={viewFlat}
+            index={index}
+            visibility={visibility}
+          />
+        </div>
+        <div class="plot-container">
+          <div class="plot-title">Time Distribution</div>
+          <div class="plot-description">
+            Frequency distribution of execution times
+          </div>
+          <HistogramPlot benchmarks={benchmarks} flat={viewFlat} index={index} />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+interface ToggleProps {
+  hasBaseline: boolean;
+  hasHeap: boolean;
+  hasBaselineHeap: boolean;
+  hasRejected: boolean;
+  visibility: SeriesVisibility;
+  onToggle: (key: keyof SeriesVisibility) => void;
+}
+
+/** Pill button that toggles a boolean state with active/inactive styling. */
+function TogglePill(
+  { label, active, onClick }: { label: string; active: boolean; onClick: () => void },
+) {
+  return (
+    <button class={`toggle-pill${active ? " active" : ""}`} onClick={onClick}>
+      {label}
+    </button>
+  );
+}
+
+/** Visibility toggles for optional series (baseline, heap, rejected). */
+function SeriesToggles(props: ToggleProps) {
+  const { hasBaseline, hasHeap, hasBaselineHeap, hasRejected, visibility, onToggle } = props;
+  if (!hasBaseline && !hasHeap && !hasRejected) return null;
+  return (
+    <div class="series-toggles">
+      {hasBaseline && <TogglePill label="baseline" active={visibility.baseline} onClick={() => onToggle("baseline")} />}
+      {hasHeap && <TogglePill label="heap" active={visibility.heap} onClick={() => onToggle("heap")} />}
+      {hasBaselineHeap && <TogglePill label="heap (baseline)" active={visibility.baselineHeap} onClick={() => onToggle("baselineHeap")} />}
+      {hasRejected && <TogglePill label="rejected" active={visibility.rejected} onClick={() => onToggle("rejected")} />}
+    </div>
+  );
+}
+
+/** Prev/next stepper for cycling through batches or showing all. */
+function BatchStepper({ batch, total, onChange }: {
+  batch: number; total: number; onChange: (batch: number) => void;
+}) {
+  const prev = () => onChange(batch <= 0 ? total : batch - 1);
+  const next = () => onChange(batch >= total ? 0 : batch + 1);
+  const label = batch === 0 ? "All" : `Batch ${batch} of ${total}`;
+  return (
+    <div class="batch-stepper">
+      <button class="batch-btn" onClick={prev}>&lsaquo;</button>
+      <span class="batch-label">{label}</span>
+      <button class="batch-btn" onClick={next}>&rsaquo;</button>
+    </div>
+  );
+}
+
+interface PlotProps { benchmarks: PreparedBenchmark[]; flat: FlattenedData; index: number }
+interface TimeSeriesPlotProps extends PlotProps { visibility: SeriesVisibility }
+
+/** Lazy-imports and renders a time-series chart for one benchmark group. */
+function TimeSeriesPlot({ flat, index, visibility }: TimeSeriesPlotProps) {
+  const ref = useLazyPlot(async () => {
+    if (flat.timeSeries.length === 0) return null;
+    const { createSampleTimeSeries } = await import("../plots/SampleTimeSeries.ts");
+    const { timeSeries, allGcEvents, allPausePoints, heapSeries, baselineHeapSeries } = flat;
+    return createSampleTimeSeries(
+      timeSeries, allGcEvents, allPausePoints, heapSeries, baselineHeapSeries, visibility,
+    );
+  }, [flat, visibility], "Time series plot");
+  return (
+    <div id={`sample-timeseries-${index}`} class="plot-area" ref={ref}>
+      <div class="loading">Loading time series...</div>
+    </div>
+  );
+}
+
+/** Lazy-imports and renders a histogram with KDE for one benchmark group. */
+function HistogramPlot({ benchmarks, flat, index }: PlotProps) {
+  const names = benchmarks.map(b => b.name);
+  const ref = useLazyPlot(async () => {
+    if (flat.allSamples.length === 0) return null;
+    const { createHistogramKde } = await import("../plots/HistogramKde.ts");
+    return createHistogramKde(flat.allSamples, names);
+  }, [flat, benchmarks], "Histogram plot");
+  return (
+    <div id={`histogram-${index}`} class="plot-area" ref={ref}>
+      <div class="loading">Loading histogram...</div>
+    </div>
+  );
+}

package/src/viewer/components/Shell.tsx

@@ -0,0 +1,26 @@
+import { useEffect } from "preact/hooks";
+import { provider, sourceTabs } from "../State.ts";
+import { openSourceTab } from "./SourcePanel.tsx";
+import { TabBar } from "./TabBar.tsx";
+import { TabContent } from "./TabContent.tsx";
+
+/** Root viewer shell: listens for `open-source` messages, renders tab bar and content. */
+export function Shell() {
+  useEffect(() => {
+    function onMessage(ev: MessageEvent): void {
+      if (ev.data?.type === "open-source") {
+        const { file, line, col } = ev.data;
+        if (file) openSourceTab(file, line, col);
+      }
+    }
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, []);
+
+  return (
+    <>
+      <TabBar />
+      <TabContent />
+    </>
+  );
+}