@progen-labs/spectra 0.1.3 → 0.2.0

package/server/recorder.js

@@ -18,6 +18,7 @@ import { attachChrome, launchChrome } from './chrome.js';
 import { FRONTEND_ROOT, REPORTS_DIR, SOURCE_ROOTS, FRAMEWORK } from './config.js';
 import { SourceIndex } from './analysis/locate.js';
 import { gitInfo } from './git.js';
+import { REPORT_SCHEMA_VERSION } from '../shared/result.js';
 import { buildSignInUrl, looksSignedOut } from './signin.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -417,7 +418,7 @@ export class PerfSession extends EventEmitter {
           .toISOString()
           .replace(/[-:]/g, '')
           .replace(/\..+/, '') + `-${rec.mode}`;
-      const report = await buildReport({
+      const built = await buildReport({
         events,
         probe,
         metrics: { before: rec.metricsBefore, after: metricsAfter, dom },
@@ -438,6 +439,8 @@ export class PerfSession extends EventEmitter {
           navUrl: this.navigation?.url ?? '',
         },
       });
+      // versioned so editors, CI and agents can tell which format they read
+      const report = { schemaVersion: REPORT_SCHEMA_VERSION, ...built };
       this.lastTrace = { id: report.id, text: traceText };
       report.pageView = pageView
         ? { ...pageView.layout, hasImage: true }

package/server/reports-cli.js

@@ -0,0 +1,31 @@
+/**
+ * spectra reports [--json] [--limit n] — the saved reports, newest first, so
+ * their ids can be passed to `spectra compare` or opened in the dashboard.
+ */
+import { listReports } from './recorder.js';
+import { REPORTS_DIR } from './config.js';
+import { intOption, parseArgs } from './args.js';
+import { EXIT, SPECTRA_VERSION, exitAfterFlush, writeResult } from './output.js';
+import { buildReportsResult } from '../shared/result.js';
+
+const { opt, flag } = parseArgs(process.argv.slice(2));
+let limit;
+try {
+  limit = intOption(opt('limit'), 'limit', { max: 10_000, fallback: 20 });
+} catch (err) {
+  console.error(`spectra: ${err.message}`);
+  process.exit(EXIT.ERROR);
+}
+
+const reports = listReports().slice(0, limit);
+if (flag('json')) {
+  writeResult(buildReportsResult({ reports, dir: REPORTS_DIR, spectraVersion: SPECTRA_VERSION }), { json: true });
+} else if (!reports.length) {
+  console.log(`No reports yet in ${REPORTS_DIR}. Create one with: spectra performance --quick`);
+} else {
+  console.log(`${'Report id'.padEnd(26)}${'Mode'.padEnd(7)}${'Findings'.padStart(9)}${'Critical'.padStart(10)}  URL`);
+  for (const r of reports)
+    console.log(`${r.id.padEnd(26)}${String(r.mode).padEnd(7)}${String(r.findings).padStart(9)}${String(r.critical).padStart(10)}  ${r.url}`);
+  console.log(`\n${reports.length} shown · ${REPORTS_DIR}`);
+}
+exitAfterFlush(EXIT.OK);

package/server/test-result.js

@@ -0,0 +1,226 @@
+// Named test-*.js (not *.test.js): the repo's jest testRegex covers tools/.
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+import {
+  BUDGET_KEYS,
+  REPORT_SCHEMA_VERSION,
+  RESULT_SCHEMA_VERSION,
+  SUMMARY_METRICS,
+  briefFinding,
+  buildCompareResult,
+  buildEvaluationResult,
+  buildProfileResult,
+  checkBudgets,
+  isRegression,
+  representativeRun,
+  summarize,
+  summarizeRuns,
+  validateBudgets,
+} from '../shared/result.js';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const readSchema = name => JSON.parse(fs.readFileSync(path.join(ROOT, 'schema', name), 'utf8'));
+
+const finding = (over = {}) => ({
+  id: 'slow-component-Row-src/Row.jsx',
+  severity: 'critical',
+  category: 'React',
+  title: 'Row is slow to render',
+  detail: 'src/Row.jsx:3.',
+  impactMs: 1442.94,
+  file: 'src/Row.jsx',
+  fix: 'Memoise it.',
+  culprits: [{ fn: 'Row', file: 'src/Row.jsx', line: 3, lineKind: 'exact', abs: '/p/src/Row.jsx', ms: 1442.94, note: 'slow render' }],
+  ...over,
+});
+
+/** A report with just enough in it for summaries, budgets and compare. */
+function report(id, { tbt = 0, lcp = 100, scripting = 1000, findings = [finding()] } = {}) {
+  return {
+    schemaVersion: REPORT_SCHEMA_VERSION,
+    id,
+    createdAt: '2026-10-17T10:00:00.000Z',
+    meta: { url: 'http://localhost:5188/', title: 'Demo', mode: 'load', durationMs: 4000, cpuThrottle: 1, attribution: 'sourcemap', git: null, label: '' },
+    vitals: { tbtMs: tbt, lcpMs: lcp, fcpMs: lcp, cls: 0.0015, inpMs: null, ttfbMs: 2.4, longTaskCount: 0, maxLongTaskMs: 0 },
+    totals: { activeMs: scripting + 100, scriptingMs: scripting, layoutMs: 10, styleMs: 10, paintMs: 5, gcMs: 5, compileMs: 5, layoutCount: 4, styleRecalcCount: 4, forcedLayoutCount: 0, forcedStyleCount: 0, forcedMs: 0 },
+    memory: { domNodes: 800, listeners: 20, heapUsedMb: 9.4, heapGrowthMb: 0 },
+    network: { count: 10, totalEncoded: 2048 * 1024 },
+    react: { detected: true, hasTimings: true, version: '18.3.1', components: [], commits: { count: 60, totalMs: 100, maxMs: 10 } },
+    files: [],
+    findings,
+  };
+}
+
+test('summarize reads the headline numbers, rounded, with null where unmeasured', () => {
+  const s = summarize(report('a', { tbt: 212.96 }));
+  assert.equal(s.tbtMs, 213);
+  assert.equal(s.cls, 0.002);
+  assert.equal(s.inpMs, null);
+  assert.equal(s.transferKb, 2048);
+  assert.equal(s.criticalFindings, 1);
+  assert.deepEqual(Object.keys(s), SUMMARY_METRICS.map(m => m.key));
+});
+
+test('several runs reduce to medians with a min / max spread; the typical run supplies the findings', () => {
+  const runs = [report('r1', { scripting: 900 }), report('r2', { scripting: 1000 }), report('r3', { scripting: 2000 })];
+  const { summary, spread } = summarizeRuns(runs);
+  assert.equal(summary.runs, 3);
+  assert.equal(summary.scriptingMs, 1000);
+  assert.deepEqual(spread.scriptingMs, { min: 900, max: 2000 });
+  assert.equal(representativeRun(runs).id, 'r2');
+  // one run: no spread to speak of
+  assert.deepEqual(summarizeRuns([runs[0]]).spread, {});
+});
+
+test('briefFinding keeps what a reader acts on', () => {
+  const b = briefFinding(finding());
+  assert.equal(b.impactMs, 1442.9);
+  assert.equal(b.line, 3);
+  assert.equal(b.culprits[0].abs, '/p/src/Row.jsx');
+  assert.equal(b.fix, 'Memoise it.');
+});
+
+test('budgets: unknown keys and bad limits are rejected, unmeasured metrics are skipped', () => {
+  assert.equal(validateBudgets({ tbt: 200 }).ok, false);
+  assert.match(validateBudgets({ tbt: 200 }).error, /Unknown budget "tbt"/);
+  assert.equal(validateBudgets({ tbtMs: -1 }).ok, false);
+  assert.equal(validateBudgets(undefined).ok, true);
+  const res = checkBudgets({ tbtMs: 200, inpMs: 100, criticalFindings: 0 }, [{ name: 'median', summary: summarize(report('a', { tbt: 250 })) }]);
+  assert.equal(res.ok, false);
+  assert.equal(res.failed, 2);
+  assert.deepEqual(res.checks.map(c => c.status), ['fail', 'skipped', 'fail']);
+  assert.equal(checkBudgets({}, []), null);
+});
+
+test('profile result: versioned envelope, per-run summaries, findings marked with how many runs saw them', () => {
+  const runs = [report('r1'), report('r2', { findings: [] }), report('r3')];
+  const result = buildProfileResult({ reports: runs, fileOf: id => `/reports/${id}.json`, target: 'demo', spectraVersion: '9.9.9', budgets: { tbtMs: 200 } });
+  assert.equal(result.schemaVersion, RESULT_SCHEMA_VERSION);
+  assert.equal(result.kind, 'profile');
+  assert.equal(result.runs[1].file, '/reports/r2.json');
+  assert.equal(result.findings[0].seenIn, 2);
+  assert.equal(result.budgets.ok, true);
+});
+
+test('evaluation result: one summary per journey, budgets name the journey that broke them', () => {
+  const reports = { base: report('base'), p1: report('p1', { tbt: 400 }) };
+  const evaluation = {
+    url: 'http://localhost:5188/',
+    target: 'demo',
+    discovered: 3,
+    skippedDestructive: [],
+    baseline: { id: 'base', title: 'Initial page load', kind: 'load', ok: true },
+    paths: [{ id: 'p1', title: 'Click "Long task"', kind: 'interaction', ok: true }],
+  };
+  const result = buildEvaluationResult({ evaluation, readReport: id => reports[id], budgets: { tbtMs: 200 } });
+  assert.equal(result.journeys.length, 2);
+  assert.equal(result.passed, 1);
+  const failed = result.budgets.checks.filter(c => c.status === 'fail');
+  assert.deepEqual(failed.map(c => c.where), ['Click "Long task"']);
+});
+
+test('compare result wraps the shared comparison and flags regressions', () => {
+  const slow = [report('b1', { scripting: 1500 }), report('b2', { scripting: 1520 })];
+  const fast = [report('a1', { scripting: 90, findings: [] }), report('a2', { scripting: 95, findings: [] })];
+  const better = buildCompareResult({ before: slow, after: fast });
+  assert.equal(better.kind, 'compare');
+  assert.equal(better.comparison.verdict, 'improved');
+  assert.equal(better.comparison.findings.resolved.length, 1);
+  assert.equal(isRegression(better), false);
+  assert.equal(isRegression(buildCompareResult({ before: fast, after: slow })), true);
+});
+
+test('the published schemas list exactly the metrics and budgets the code produces', () => {
+  const result = readSchema('result.schema.json');
+  assert.deepEqual(Object.keys(result.$defs.summary.properties), SUMMARY_METRICS.map(m => m.key));
+  assert.equal(result.properties.schemaVersion.const, RESULT_SCHEMA_VERSION);
+  const config = readSchema('config.schema.json');
+  assert.deepEqual(Object.keys(config.properties.budgets.properties), BUDGET_KEYS);
+  // every key the schema requires is present in what the builders return
+  const profile = buildProfileResult({ reports: [report('r1')], budgets: {} });
+  for (const key of [...result.required, ...result.$defs.profile.required]) assert.ok(key in profile, `profile result lacks ${key}`);
+  const finding0 = profile.findings[0];
+  for (const key of result.$defs.finding.required) assert.ok(key in finding0, `finding lacks ${key}`);
+});
+
+// ------------------------------------------------------------------ CLI (no Chrome needed)
+
+function workspace() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'spectra-cli-'));
+  const reports = path.join(dir, '.spectra', 'reports');
+  fs.mkdirSync(reports, { recursive: true });
+  const save = r => fs.writeFileSync(path.join(reports, `${r.id}.json`), JSON.stringify(r));
+  save(report('20261017T100000-load', { scripting: 1500 }));
+  save(report('20261017T100010-load', { scripting: 1510 }));
+  save(report('20261017T100100-load', { scripting: 90, findings: [] }));
+  save(report('20261017T100110-load', { scripting: 92, findings: [] }));
+  return { dir, reports };
+}
+
+const run = (script, args, ws) =>
+  spawnSync(process.execPath, [path.join(ROOT, script), ...args], {
+    cwd: ws.dir,
+    encoding: 'utf8',
+    env: { ...process.env, PERF_FRONTEND_DIR: ws.dir, PERF_REPORTS_DIR: ws.reports },
+  });
+
+test('cli: compare by ids prints a verdict, emits JSON, and exits 2 on a regression when asked', () => {
+  const ws = workspace();
+  const before = '20261017T100000-load,20261017T100010-load';
+  const after = '20261017T100100-load,20261017T100110-load';
+  const ok = run('bin/spectra.js', ['compare', before, after, '--json'], ws);
+  assert.equal(ok.status, 0, ok.stderr);
+  const result = JSON.parse(ok.stdout);
+  assert.equal(result.comparison.verdict, 'improved');
+  assert.match(ok.stderr, /Spectra compare — IMPROVED/);
+
+  const worse = run('bin/spectra.js', ['compare', after, before, '--fail-on-regression'], ws);
+  assert.equal(worse.status, 2);
+  assert.match(worse.stdout, /REGRESSED/);
+  fs.rmSync(ws.dir, { recursive: true, force: true });
+});
+
+test('cli: a saved profile result works as a compare side, from any directory', () => {
+  const ws = workspace();
+  const profile = buildProfileResult({
+    reports: ['20261017T100000-load', '20261017T100010-load'].map(id => JSON.parse(fs.readFileSync(path.join(ws.reports, `${id}.json`), 'utf8'))),
+    fileOf: id => path.join(ws.reports, `${id}.json`),
+  });
+  fs.writeFileSync(path.join(ws.dir, 'before.json'), JSON.stringify(profile));
+  const res = run('bin/spectra.js', ['compare', 'before.json', '20261017T100100-load', '--out', 'cmp.json'], ws);
+  assert.equal(res.status, 0, res.stderr);
+  const written = JSON.parse(fs.readFileSync(path.join(ws.dir, 'cmp.json'), 'utf8'));
+  assert.equal(written.comparison.before.runs.length, 2);
+  fs.rmSync(ws.dir, { recursive: true, force: true });
+});
+
+test('cli: reports lists newest first; bad input fails fast with exit 1 and no browser', () => {
+  const ws = workspace();
+  const list = run('bin/spectra.js', ['reports', '--json'], ws);
+  assert.equal(list.status, 0, list.stderr);
+  const parsed = JSON.parse(list.stdout);
+  assert.equal(parsed.kind, 'reports');
+  assert.equal(parsed.reports[0].id, '20261017T100110-load');
+
+  const missing = run('bin/spectra.js', ['compare', 'nope', '20261017T100100-load'], ws);
+  assert.equal(missing.status, 1);
+  assert.match(missing.stderr, /no report "nope"/);
+
+  fs.writeFileSync(path.join(ws.dir, 'spectra.config.json'), JSON.stringify({ budgets: { tbt: 200 } }));
+  const badConfig = run('server/cli.js', ['--url', 'http://localhost:9/', '--mode', 'load'], ws);
+  assert.equal(badConfig.status, 1);
+  assert.match(badConfig.stderr, /Unknown budget "tbt"/);
+
+  const runsOnSuite = run('bin/spectra.js', ['performance', '--runs', '3', '--url', 'http://localhost:9/'], ws);
+  assert.equal(runsOnSuite.status, 1);
+  assert.match(runsOnSuite.stderr, /--runs works with single-page profiles/);
+
+  const quickLive = run('bin/spectra.js', ['performance', '--quick', '--mode', 'live', '--url', 'http://localhost:9/'], ws);
+  assert.equal(quickLive.status, 1);
+  fs.rmSync(ws.dir, { recursive: true, force: true });
+});

package/shared/compare.js

@@ -84,6 +84,7 @@ export function formatValue(unit, v) {
   if (!finite(v)) return '–';
   switch (unit) {
     case 'ms':
+      if (v === 0) return '0 ms';
       if (v >= 1000) return `${(v / 1000).toFixed(2)} s`;
       if (v >= 100) return `${Math.round(v)} ms`;
       if (v >= 1) return `${v.toFixed(1)} ms`;

package/shared/result.js

@@ -0,0 +1,291 @@
+/**
+ * The machine-readable side of Spectra: what `--json` prints, what `--out`
+ * writes, and what editor / CI / AI integrations consume.
+ *
+ * Pure functions, no I/O. A "result" is a small, versioned envelope that
+ * points at the full reports on disk instead of embedding them:
+ *
+ *   kind 'profile'     one or more page-load / live recordings of one page,
+ *                      reduced to a median summary plus the findings
+ *   kind 'evaluation'  the golden-path suite: one summary per journey
+ *   kind 'compare'     before vs after, judged against run-to-run noise
+ *
+ * Every summary metric is "lower is better", which is what budgets assume.
+ */
+import { compareSides, findingKey, median } from './compare.js';
+
+/** Bumped on breaking changes to the saved report format. */
+export const REPORT_SCHEMA_VERSION = 1;
+/** Bumped on breaking changes to the result envelopes below. */
+export const RESULT_SCHEMA_VERSION = 1;
+
+const finite = v => typeof v === 'number' && Number.isFinite(v);
+const round = (v, d = 1) => (finite(v) ? Math.round(v * 10 ** d) / 10 ** d : null);
+
+// ------------------------------------------------------------------ summaries
+
+/**
+ * The headline numbers budgets and summaries are built from. `get` reads a
+ * full report; every entry is lower-is-better.
+ */
+export const SUMMARY_METRICS = [
+  { key: 'tbtMs', label: 'Total blocking time', unit: 'ms', get: r => r.vitals?.tbtMs },
+  { key: 'lcpMs', label: 'Largest contentful paint', unit: 'ms', get: r => r.vitals?.lcpMs },
+  { key: 'fcpMs', label: 'First contentful paint', unit: 'ms', get: r => r.vitals?.fcpMs },
+  { key: 'cls', label: 'Cumulative layout shift', unit: 'score', digits: 3, get: r => r.vitals?.cls },
+  { key: 'inpMs', label: 'Interaction to next paint', unit: 'ms', get: r => r.vitals?.inpMs },
+  { key: 'ttfbMs', label: 'Time to first byte', unit: 'ms', get: r => r.vitals?.ttfbMs },
+  { key: 'longTaskCount', label: 'Long tasks', unit: 'count', get: r => r.vitals?.longTaskCount },
+  { key: 'maxLongTaskMs', label: 'Longest task', unit: 'ms', get: r => r.vitals?.maxLongTaskMs },
+  { key: 'scriptingMs', label: 'Scripting time', unit: 'ms', get: r => r.totals?.scriptingMs },
+  { key: 'forcedLayoutCount', label: 'Forced layouts', unit: 'count', get: r => r.totals?.forcedLayoutCount },
+  { key: 'domNodes', label: 'DOM nodes', unit: 'count', get: r => r.memory?.domNodes },
+  { key: 'heapUsedMb', label: 'JS heap used', unit: 'MB', get: r => r.memory?.heapUsedMb },
+  {
+    key: 'transferKb',
+    label: 'Transferred',
+    unit: 'KB',
+    get: r => (finite(r.network?.totalEncoded) ? r.network.totalEncoded / 1024 : null),
+  },
+  {
+    key: 'criticalFindings',
+    label: 'Critical findings',
+    unit: 'count',
+    get: r => (Array.isArray(r.findings) ? r.findings.filter(f => f.severity === 'critical').length : null),
+  },
+  {
+    key: 'findingCount',
+    label: 'Findings',
+    unit: 'count',
+    get: r => (Array.isArray(r.findings) ? r.findings.length : null),
+  },
+];
+
+const metricDef = key => SUMMARY_METRICS.find(m => m.key === key);
+const valueOf = (def, r) => {
+  const v = def.get(r);
+  return finite(v) ? v : null;
+};
+
+/** Headline numbers of one report; null where the recording has no value. */
+export function summarize(report) {
+  const out = {};
+  for (const def of SUMMARY_METRICS) out[def.key] = round(valueOf(def, report), def.digits ?? 1);
+  return out;
+}
+
+/**
+ * Median of each headline number across runs, plus the min / max spread
+ * (only when there is more than one run, so the spread means something).
+ */
+export function summarizeRuns(reports) {
+  const summary = { runs: reports.length };
+  const spread = {};
+  for (const def of SUMMARY_METRICS) {
+    const values = reports.map(r => valueOf(def, r)).filter(finite);
+    summary[def.key] = values.length ? round(median(values), def.digits ?? 1) : null;
+    if (reports.length > 1 && values.length > 1) {
+      spread[def.key] = {
+        min: round(Math.min(...values), def.digits ?? 1),
+        max: round(Math.max(...values), def.digits ?? 1),
+      };
+    }
+  }
+  return { summary, spread };
+}
+
+/**
+ * The run that best stands for the set: closest to the median on main-thread
+ * cost. Its findings are the ones reported, so they match the summary.
+ */
+export function representativeRun(reports) {
+  if (reports.length <= 2) return reports[reports.length - 1] || null;
+  const keys = ['tbtMs', 'scriptingMs', 'lcpMs'];
+  const medians = Object.fromEntries(
+    keys.map(k => [k, median(reports.map(r => valueOf(metricDef(k), r)).filter(finite))]),
+  );
+  let best = null;
+  let bestScore = Infinity;
+  for (const r of reports) {
+    let score = 0;
+    for (const k of keys) {
+      const v = valueOf(metricDef(k), r);
+      const m = medians[k];
+      if (finite(v) && finite(m)) score += Math.abs(v - m) / Math.max(Math.abs(m), 1);
+    }
+    if (score < bestScore) {
+      best = r;
+      bestScore = score;
+    }
+  }
+  return best;
+}
+
+/** A finding trimmed to what a reader (or an agent) acts on. */
+export function briefFinding(f) {
+  const top = (f.culprits || [])[0];
+  return {
+    id: f.id,
+    severity: f.severity,
+    category: f.category,
+    title: f.title,
+    detail: f.detail || '',
+    impactMs: round(f.impactMs || 0),
+    file: f.file || top?.file || null,
+    line: top?.line ?? null,
+    fix: f.fix || '',
+    culprits: (f.culprits || []).slice(0, 5).map(c => ({
+      fn: c.fn,
+      file: c.file || null,
+      line: c.line ?? null,
+      lineKind: c.lineKind || null,
+      abs: c.abs || null,
+      ms: round(c.ms),
+      note: c.note || '',
+    })),
+  };
+}
+
+// ------------------------------------------------------------------ budgets
+
+export const BUDGET_KEYS = SUMMARY_METRICS.map(m => m.key);
+
+/**
+ * Validates a `budgets` object from spectra.config.json.
+ * @returns {{ok: true, budgets: object} | {ok: false, error: string}}
+ */
+export function validateBudgets(budgets) {
+  if (budgets == null) return { ok: true, budgets: {} };
+  if (typeof budgets !== 'object' || Array.isArray(budgets))
+    return { ok: false, error: '"budgets" must be an object such as { "tbtMs": 200 }.' };
+  for (const [key, limit] of Object.entries(budgets)) {
+    if (!BUDGET_KEYS.includes(key))
+      return { ok: false, error: `Unknown budget "${key}". Known budgets: ${BUDGET_KEYS.join(', ')}.` };
+    if (!finite(limit) || limit < 0)
+      return { ok: false, error: `Budget "${key}" must be a number ≥ 0 (got ${JSON.stringify(limit)}).` };
+  }
+  return { ok: true, budgets };
+}
+
+/**
+ * Checks budgets (upper limits) against one or more measured summaries, e.g.
+ * the median of a profile, or every journey of an evaluation. A metric the
+ * recording did not measure is reported as skipped, never as a failure.
+ * @param {object} budgets           { tbtMs: 200, ... } (already validated)
+ * @param {{name: string, summary: object}[]} items
+ */
+export function checkBudgets(budgets, items) {
+  const entries = Object.entries(budgets || {});
+  if (!entries.length) return null;
+  const checks = [];
+  for (const [key, limit] of entries) {
+    const def = metricDef(key);
+    for (const item of items) {
+      const value = item.summary?.[key];
+      checks.push({
+        key,
+        label: def.label,
+        unit: def.unit,
+        limit,
+        value: finite(value) ? value : null,
+        where: item.name,
+        status: !finite(value) ? 'skipped' : value <= limit ? 'pass' : 'fail',
+      });
+    }
+  }
+  const failed = checks.filter(c => c.status === 'fail');
+  return { ok: failed.length === 0, failed: failed.length, checks };
+}
+
+// ------------------------------------------------------------------ envelopes
+
+const envelope = (kind, spectraVersion) => ({
+  schemaVersion: RESULT_SCHEMA_VERSION,
+  kind,
+  spectraVersion: spectraVersion || null,
+  createdAt: new Date().toISOString(),
+});
+
+/**
+ * @param {object} o
+ * @param {object[]} o.reports        full reports, in run order
+ * @param {(id: string) => string} o.fileOf   where each report is saved
+ */
+export function buildProfileResult({ reports, fileOf, target, spectraVersion, budgets }) {
+  const first = reports[0];
+  const { summary, spread } = summarizeRuns(reports);
+  const rep = representativeRun(reports);
+  const keysPerRun = reports.map(r => new Set((r.findings || []).map(findingKey)));
+  const findings = (rep?.findings || []).map(f => {
+    const brief = briefFinding(f);
+    if (reports.length > 1) brief.seenIn = keysPerRun.filter(s => s.has(findingKey(f))).length;
+    return brief;
+  });
+  return {
+    ...envelope('profile', spectraVersion),
+    target: target || null,
+    url: first?.meta?.url || null,
+    mode: first?.meta?.mode || null,
+    cpuThrottle: first?.meta?.cpuThrottle || 1,
+    git: first?.meta?.git || null,
+    runs: reports.map(r => ({ id: r.id, file: fileOf ? fileOf(r.id) : null, summary: summarize(r) })),
+    representativeRunId: rep?.id || null,
+    summary,
+    spread,
+    findings,
+    budgets: checkBudgets(budgets, [{ name: 'median', summary }]),
+  };
+}
+
+/**
+ * @param {object} o
+ * @param {object} o.evaluation   the object runEvaluation() returns
+ * @param {(id: string) => object|null} o.readReport
+ */
+export function buildEvaluationResult({ evaluation, readReport, fileOf, file, spectraVersion, budgets }) {
+  const journey = j => {
+    const report = j.id ? readReport(j.id) : null;
+    return {
+      title: j.title,
+      kind: j.kind,
+      ok: j.ok,
+      error: j.error || null,
+      reportId: j.id || null,
+      reportFile: j.id && fileOf ? fileOf(j.id) : null,
+      summary: report ? summarize(report) : null,
+      findings: report ? (report.findings || []).slice(0, 5).map(briefFinding) : [],
+    };
+  };
+  const journeys = [journey(evaluation.baseline), ...evaluation.paths.map(journey)];
+  return {
+    ...envelope('evaluation', spectraVersion),
+    target: evaluation.target || null,
+    url: evaluation.url,
+    file: file || null,
+    discovered: evaluation.discovered,
+    skippedDestructive: evaluation.skippedDestructive || [],
+    passed: evaluation.paths.filter(p => p.ok).length,
+    total: evaluation.paths.length,
+    journeys,
+    budgets: checkBudgets(
+      budgets,
+      journeys.filter(j => j.summary).map(j => ({ name: j.title, summary: j.summary })),
+    ),
+  };
+}
+
+/** Before vs after; the comparison itself is shared/compare.js (COMPARE_VERSION). */
+export function buildCompareResult({ before, after, spectraVersion }) {
+  const comparison = compareSides({ runs: before }, { runs: after });
+  if (!comparison) return null;
+  return { ...envelope('compare', spectraVersion), comparison };
+}
+
+/** The saved reports, newest first (rows from recorder.listReports()). */
+export function buildReportsResult({ reports, dir, spectraVersion }) {
+  return { ...envelope('reports', spectraVersion), dir: dir || null, reports };
+}
+
+/** A compare counts as a regression when any key metric got worse. */
+export const isRegression = result =>
+  ['regressed', 'mixed'].includes(result?.comparison?.verdict);

package/src/styles.css

@@ -656,14 +656,23 @@ label.switch {
 }
 .main-tabs {
   align-items: center;
+  flex-wrap: wrap;
+  row-gap: 0.4rem;
+  overflow-x: visible;
   padding: 0.5rem 0.9rem;
   border-bottom: 1px solid var(--border);
 }
+/* Wrap rather than scroll: a scrolled-away tab (Compare commits, on a laptop
+   screen) is a tab nobody finds, since overlay scrollbars stay hidden. */
 .main-tabs .tab-list {
   display: flex;
+  flex-wrap: wrap;
   gap: 0.2rem;
   min-width: 0;
-  overflow-x: auto;
+}
+.main-tabs label.switch {
+  white-space: nowrap;
+  margin-left: auto;
 }
 .tabs button {
   background: transparent;
@@ -1188,7 +1197,8 @@ tr.detail td {
 }
 .task-cols {
   display: grid;
-  grid-template-columns: 1fr 1fr;
+  /* minmax(0, …): a long file path must not push its column out of the card */
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
   gap: 1rem;
 }
 .task-cols h4 {
@@ -1198,17 +1208,24 @@ tr.detail td {
   letter-spacing: 0.04em;
   color: var(--text-2);
 }
-.row {
+.row,
+button.link.row {
   display: flex;
   justify-content: space-between;
   gap: 0.6rem;
   width: 100%;
+  text-align: left;
 }
 .row span {
+  min-width: 0;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
+.row b {
+  flex: none;
+  white-space: nowrap;
+}
 
 /* ---- source view ---- */
 .code-scroll {