@monoes/monobrowse 1.0.12 → 1.0.14

package/src/report/render-trend.ts

@@ -0,0 +1,225 @@
+/**
+ * Report sections for the trend (RIG-13) and the run-to-run diff (RIG-10).
+ *
+ * Kept separate from render.ts purely for size. Same rules apply: no external
+ * resources, so the sparklines are hand-written inline SVG rather than a
+ * charting library, and the diff image is a `data:` URI.
+ *
+ * The design goal for the trend is legibility at a glance — the point of the
+ * feature is catching decay nobody noticed, which only works if the reader
+ * sees it without going looking.
+ */
+
+import { formatTrendDelta, formatTrendValue } from './trend.js';
+import type { RunDiff, StructureDiff, StructureNode, TrendReport, TrendSeries } from './types.js';
+import { escapeHtml } from './util.js';
+
+/** Rows shown per diff category before the tail is summarised. */
+const MAX_DIFF_ROWS = 20;
+
+export const TREND_STYLES = `
+.headlines{background:var(--warn-bg);border:1px solid var(--warn);color:var(--warn);
+  border-radius:10px;padding:12px 16px;margin:0 0 16px}
+.headlines p{margin:0 0 6px;font-size:14px}
+.headlines p:last-child{margin-bottom:0}
+.spark{display:block}
+.spark .line{fill:none;stroke:var(--muted);stroke-width:1.5}
+.spark .dot{fill:var(--ink)}
+.dir{font-weight:600}
+.dir.regressed{color:var(--fail)}
+.dir.improved{color:var(--pass)}
+.dir.flat,.dir.new{color:var(--muted)}
+.verdictstrip{display:flex;flex-wrap:wrap;gap:4px;margin:0 0 16px;padding:0;list-style:none}
+.verdictstrip li{width:13px;height:13px;border-radius:3px;background:var(--pass)}
+.verdictstrip li.fail{background:var(--fail)}
+.difftag{display:inline-block;margin:0 8px 8px 0;padding:4px 10px;border-radius:999px;
+  font-size:12px;background:var(--panel);border:1px solid var(--line)}
+.difftag b{font-variant-numeric:tabular-nums}
+`.trim();
+
+// ---------------------------------------------------------------------------
+// Trend
+// ---------------------------------------------------------------------------
+
+/**
+ * A sparkline as inline SVG. Flat series are drawn down the middle rather
+ * than at y=0, which is what a naive min/max scale does when every value is
+ * identical and it reads as a cliff.
+ */
+function sparkline(series: TrendSeries): string {
+  const values = series.points.map((p) => p.value).filter((v): v is number => v !== null);
+  if (values.length < 2) return '<span style="color:var(--muted)">—</span>';
+
+  const width = 120;
+  const height = 24;
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const span = max - min;
+  const x = (i: number) => (i / (values.length - 1)) * (width - 4) + 2;
+  const y = (v: number) =>
+    span === 0 ? height / 2 : height - 2 - ((v - min) / span) * (height - 4);
+
+  const points = values.map((v, i) => `${x(i).toFixed(1)},${y(v).toFixed(1)}`).join(' ');
+  const lastX = x(values.length - 1).toFixed(1);
+  const lastY = y(values[values.length - 1]).toFixed(1);
+  const label = `${series.label} over ${values.length} runs, ${formatTrendValue(series.unit, min)} to ${formatTrendValue(series.unit, max)}`;
+  return `<svg class="spark" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-label="${escapeHtml(label)}">
+    <polyline class="line" points="${points}"/>
+    <circle class="dot" cx="${lastX}" cy="${lastY}" r="2.5"/>
+  </svg>`;
+}
+
+const DIRECTION_WORD: Record<TrendSeries['direction'], string> = {
+  regressed: 'worse',
+  improved: 'better',
+  flat: 'steady',
+  new: 'first',
+};
+
+export function renderTrend(trend: TrendReport | undefined): string {
+  if (!trend) return '';
+  if (trend.runs === 0) {
+    return `<h2>Trend</h2><p class="empty">First recorded run for this URL — from the next run on, this section compares against it.</p>`;
+  }
+
+  const headlines = trend.headlines.length
+    ? `<div class="headlines">${trend.headlines.map((h) => `<p>${escapeHtml(h)}</p>`).join('')}</div>`
+    : '';
+
+  const strip = `<ul class="verdictstrip" aria-label="Verdict per run, oldest first">${trend.verdictHistory
+    .map(
+      (v) =>
+        `<li class="${v.verdict}" title="${escapeHtml(`${v.capturedAt}: ${v.verdict}`)}"></li>`,
+    )
+    .join('')}</ul>`;
+
+  // A series nobody has ever measured is noise, not an absent trend.
+  const rows = trend.series
+    .filter((s) => s.points.some((p) => p.value !== null))
+    .map(
+      (s) => `<tr>
+        <td><b>${escapeHtml(s.label)}</b></td>
+        <td class="num mono">${escapeHtml(formatTrendValue(s.unit, s.previous))}</td>
+        <td class="num mono">${escapeHtml(formatTrendValue(s.unit, s.current))}</td>
+        <td class="num mono"><span class="dir ${s.direction}">${escapeHtml(formatTrendDelta(s.unit, s.deltaFromPrevious))}</span></td>
+        <td class="num mono">${escapeHtml(formatTrendDelta(s.unit, s.deltaFromOldest))}</td>
+        <td><span class="dir ${s.direction}">${DIRECTION_WORD[s.direction]}</span></td>
+        <td>${sparkline(s)}</td>
+      </tr>`,
+    )
+    .join('');
+
+  return `<h2>Trend — this run against the previous ${trend.runs}</h2>
+${headlines}
+${strip}
+<table><thead><tr>
+  <th>Metric</th><th>Last run</th><th>This run</th><th>vs last</th>
+  <th>vs ${trend.runs} runs ago</th><th>Direction</th><th>History</th>
+</tr></thead><tbody>${rows}</tbody></table>
+<p class="note">Window starts ${escapeHtml(trend.windowFrom ?? 'unknown')}. Every metric here is lower-is-better, so a positive delta is a regression.</p>`;
+}
+
+// ---------------------------------------------------------------------------
+// Diff
+// ---------------------------------------------------------------------------
+
+function nodeRows(nodes: StructureNode[], kind: string): string {
+  const shown = nodes.slice(0, MAX_DIFF_ROWS);
+  const rows = shown
+    .map(
+      (n) => `<tr>
+      <td>${escapeHtml(kind)}</td>
+      <td>${escapeHtml(n.role)}</td>
+      <td>${n.name ? escapeHtml(n.name) : '<span style="color:var(--muted)">(no accessible name)</span>'}</td>
+      <td class="wrap mono">${escapeHtml(n.path)}</td>
+    </tr>`,
+    )
+    .join('');
+  const rest = nodes.length - shown.length;
+  return rest > 0
+    ? `${rows}<tr><td colspan="4" style="color:var(--muted)">…and ${rest} more ${escapeHtml(kind)}</td></tr>`
+    : rows;
+}
+
+function renderStructure(diff: StructureDiff): string {
+  const tags = [
+    `<span class="difftag"><b>${diff.gained.length}</b> gained</span>`,
+    `<span class="difftag"><b>${diff.lost.length}</b> lost</span>`,
+    `<span class="difftag"><b>${diff.renamed.length}</b> renamed</span>`,
+    `<span class="difftag"><b>${diff.moved.length}</b> moved</span>`,
+    `<span class="difftag"><b>${diff.unchanged}</b> unchanged</span>`,
+  ].join('');
+
+  if (diff.changed === 0 && diff.moved.length === 0) {
+    return `${tags}<p class="empty">The accessibility tree is identical to the previous run.</p>`;
+  }
+
+  const renamedRows = diff.renamed
+    .slice(0, MAX_DIFF_ROWS)
+    .map(
+      (r) => `<tr>
+      <td>renamed</td>
+      <td>${escapeHtml(r.role)}</td>
+      <td>${escapeHtml(r.from ?? '(none)')} → <b>${escapeHtml(r.to ?? '(none)')}</b></td>
+      <td class="wrap mono">${escapeHtml(r.path)}</td>
+    </tr>`,
+    )
+    .join('');
+
+  const body = `${nodeRows(diff.gained, 'gained')}${nodeRows(diff.lost, 'lost')}${renamedRows}`;
+  return `${tags}
+<table><thead><tr><th>Change</th><th>Role</th><th>Accessible name</th><th>Path</th></tr></thead>
+<tbody>${body}</tbody></table>
+<p class="note">Compared on the accessibility tree, not the DOM: a restyled class name is invisible here, while a control losing its label is not. Elements that only moved are counted but not listed.</p>`;
+}
+
+function renderPixels(diff: NonNullable<RunDiff['pixels']>): string {
+  if (!diff.comparable)
+    return `<p class="empty">${escapeHtml(diff.note ?? 'Pixel diff unavailable.')}</p>`;
+
+  const pct =
+    diff.changedPercent === 0
+      ? '0'
+      : diff.changedPercent < 0.01
+        ? '<0.01'
+        : diff.changedPercent.toFixed(2);
+  const size = diff.sizeChanged
+    ? `<span class="difftag">size <b>${diff.previousSize?.width}×${diff.previousSize?.height}</b> → <b>${diff.currentSize?.width}×${diff.currentSize?.height}</b></span>`
+    : '';
+  const tags = `<span class="difftag"><b>${pct}%</b> of pixels changed</span>
+    <span class="difftag"><b>${diff.changedPixels.toLocaleString('en-US')}</b> of ${diff.totalPixels.toLocaleString('en-US')} pixels</span>${size}`;
+
+  if (!diff.diffDataUrl) {
+    return `${tags}<p class="empty">The screenshots are pixel-identical.</p>`;
+  }
+  const scaled = diff.scale
+    ? ` Shown at 1/${diff.scale} scale; a change smaller than one output pixel is still marked.`
+    : '';
+  return `${tags}
+<figure>
+  <figcaption>Changed pixels in magenta, over this run's screenshot.${escapeHtml(scaled)}</figcaption>
+  <img alt="Pixel differences against the previous run" src="${escapeHtml(diff.diffDataUrl)}">
+</figure>
+<p class="note">Per-channel tolerance is applied before counting, so anti-aliasing and font-hinting jitter do not register as change.</p>`;
+}
+
+export function renderDiff(diff: RunDiff | undefined): string {
+  if (!diff) return '';
+  const notes = diff.notes.length
+    ? `<p class="note">${diff.notes.map((n) => escapeHtml(n)).join(' ')}</p>`
+    : '';
+  const structure = diff.structure
+    ? `<h3 style="font-size:13px;color:var(--muted);margin:20px 0 8px">Structure</h3>${renderStructure(diff.structure)}`
+    : '';
+  const pixels = diff.pixels
+    ? `<h3 style="font-size:13px;color:var(--muted);margin:24px 0 8px">Pixels</h3>${renderPixels(diff.pixels)}`
+    : '';
+  if (!structure && !pixels) {
+    return `<h2>Changes since the previous run</h2>${notes || '<p class="empty">Nothing could be compared against the previous run.</p>'}`;
+  }
+  return `<h2>Changes since the previous run</h2>
+<p class="note">Compared against the run of ${escapeHtml(diff.previousCapturedAt)}.</p>
+${structure}
+${pixels}
+${notes}`;
+}

package/src/report/render.ts

@@ -0,0 +1,314 @@
+/**
+ * Renders a Report as ONE self-contained HTML file: CSS inline, screenshots
+ * as `data:` URIs, no fonts, no CDN, no network access of any kind at view
+ * time. That is not a stylistic preference — it is what lets monomind's
+ * document pipeline ingest the file as an ordinary document, so test history
+ * becomes searchable, and what lets the report be mailed or archived and
+ * still render years later.
+ *
+ * Reading order matches how you triage: verdict, errors, failed requests,
+ * vitals, accessibility, screenshots.
+ */
+
+import { budgetLabel } from './budget.js';
+import type { FlakeReport } from './flake.js';
+import { EVIDENCE_STYLES, renderEvidence, renderFlake } from './render-evidence.js';
+import { renderDiff, renderTrend, TREND_STYLES } from './render-trend.js';
+import type { A11yFinding, Report, RequestEntry, Screenshot } from './types.js';
+import { escapeHtml } from './util.js';
+
+export { escapeHtml };
+
+function ms(value?: number): string {
+  return value === undefined || !Number.isFinite(value) ? 'not measured' : `${Math.round(value)}ms`;
+}
+
+function vitalRating(metric: string, v?: number): 'good' | 'mixed' | 'poor' | 'none' {
+  if (v === undefined || !Number.isFinite(v)) return 'none';
+  const scale: Record<string, [number, number]> = {
+    lcp: [2500, 4000],
+    fcp: [1800, 3000],
+    cls: [0.1, 0.25],
+    inp: [200, 500],
+    ttfb: [800, 1800],
+  };
+  const bounds = scale[metric];
+  if (!bounds) return 'none';
+  return v <= bounds[0] ? 'good' : v <= bounds[1] ? 'mixed' : 'poor';
+}
+
+const STYLES = `
+:root{
+  --bg:#fbfbfd; --panel:#fff; --ink:#15171c; --muted:#5d6470; --line:#e3e6ec;
+  --pass:#0f7b4f; --pass-bg:#e7f6ee; --fail:#b3261e; --fail-bg:#fdeceb;
+  --warn:#8a5a00; --warn-bg:#fff5e0; --code:#f3f4f7;
+}
+@media (prefers-color-scheme: dark){
+  :root{
+    --bg:#101317; --panel:#171b21; --ink:#e7eaf0; --muted:#98a1b0; --line:#262c35;
+    --pass:#57d69c; --pass-bg:#11291f; --fail:#ff9a92; --fail-bg:#2c1614;
+    --warn:#f0c168; --warn-bg:#2b2113; --code:#1d222a;
+  }
+}
+*{box-sizing:border-box}
+body{margin:0;padding:32px 16px 72px;background:var(--bg);color:var(--ink);
+  font:15px/1.55 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;}
+main{max-width:940px;margin:0 auto}
+h1{font-size:22px;margin:0 0 4px;letter-spacing:-.01em}
+h2{font-size:15px;text-transform:uppercase;letter-spacing:.08em;color:var(--muted);
+  margin:36px 0 12px;font-weight:600}
+a{color:inherit}
+.sub{color:var(--muted);font-size:13px;margin:0 0 24px;word-break:break-all}
+.verdict{border-radius:12px;padding:18px 20px;margin-bottom:8px;border:1px solid transparent}
+.verdict.pass{background:var(--pass-bg);border-color:var(--pass);color:var(--pass)}
+.verdict.fail{background:var(--fail-bg);border-color:var(--fail);color:var(--fail)}
+.verdict .tag{font-size:26px;font-weight:700;letter-spacing:.02em}
+.verdict .line{color:var(--ink);margin-top:6px;font-size:14px}
+.stats{display:flex;flex-wrap:wrap;gap:8px;margin:16px 0 0;padding:0;list-style:none}
+.stats li{background:var(--panel);border:1px solid var(--line);border-radius:8px;
+  padding:8px 12px;font-size:13px;color:var(--muted)}
+.stats li b{display:block;font-size:18px;color:var(--ink)}
+.stats li.bad b{color:var(--fail)}
+table{width:100%;border-collapse:collapse;background:var(--panel);
+  border:1px solid var(--line);border-radius:10px;overflow:hidden;font-size:13px}
+th,td{text-align:left;padding:9px 12px;border-bottom:1px solid var(--line);vertical-align:top}
+th{color:var(--muted);font-weight:600;white-space:nowrap}
+tr:last-child td{border-bottom:none}
+td.num{text-align:right;white-space:nowrap;font-variant-numeric:tabular-nums}
+.wrap{word-break:break-all}
+code,.mono{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px}
+code{background:var(--code);padding:1px 5px;border-radius:4px}
+.pill{display:inline-block;padding:1px 7px;border-radius:999px;font-size:11px;
+  font-weight:600;text-transform:uppercase;letter-spacing:.04em}
+.pill.error{background:var(--fail-bg);color:var(--fail)}
+.pill.warning{background:var(--warn-bg);color:var(--warn)}
+.pill.good{background:var(--pass-bg);color:var(--pass)}
+.pill.mixed{background:var(--warn-bg);color:var(--warn)}
+.pill.poor{background:var(--fail-bg);color:var(--fail)}
+.pill.none{background:var(--code);color:var(--muted)}
+.empty{color:var(--muted);font-size:13px;background:var(--panel);border:1px solid var(--line);
+  border-radius:10px;padding:12px}
+.note{color:var(--muted);font-size:12px;margin-top:8px}
+figure{margin:0 0 20px}
+figcaption{color:var(--muted);font-size:12px;margin-bottom:6px}
+img{max-width:100%;height:auto;display:block;border:1px solid var(--line);border-radius:10px}
+footer{margin-top:40px;color:var(--muted);font-size:12px;border-top:1px solid var(--line);
+  padding-top:12px}
+@media (max-width:640px){body{padding:20px 12px 48px}th,td{padding:8px}}
+`.trim();
+
+function emptyBlock(text: string): string {
+  return `<p class="empty">${escapeHtml(text)}</p>`;
+}
+
+function renderVerdict(report: Report): string {
+  const pass = report.verdict === 'pass';
+  const headline = pass
+    ? 'All budgets met.'
+    : `${report.failures.length} budget ${report.failures.length === 1 ? 'failure' : 'failures'}.`;
+  const rows = report.failures
+    .map(
+      (f) => `<tr>
+        <td>${escapeHtml(budgetLabel(f.budget))}</td>
+        <td class="num mono">${escapeHtml(f.expected)}</td>
+        <td class="num mono">${escapeHtml(f.actual)}</td>
+        <td class="wrap">${escapeHtml(f.detail ?? '')}</td>
+      </tr>`,
+    )
+    .join('');
+
+  const table = report.failures.length
+    ? `<table><thead><tr><th>Budget</th><th>Expected</th><th>Actual</th><th>Evidence</th></tr></thead>
+       <tbody>${rows}</tbody></table>`
+    : '';
+
+  const unmeasured = report.unmeasured.length
+    ? `<p class="note">Not measured on this run: ${escapeHtml(report.unmeasured.join(', '))} — the page never reported the metric, so its budget was neither met nor breached.</p>`
+    : '';
+
+  return `<section class="verdict ${pass ? 'pass' : 'fail'}">
+    <div class="tag">${pass ? 'PASS' : 'FAIL'}</div>
+    <div class="line">${escapeHtml(headline)}</div>
+  </section>
+  ${table}
+  ${unmeasured}`;
+}
+
+function renderStats(report: Report): string {
+  const c = report.counts;
+  const item = (label: string, value: number, bad: boolean) =>
+    `<li class="${bad ? 'bad' : ''}"><b>${value}</b>${escapeHtml(label)}</li>`;
+  return `<ul class="stats">
+    ${item('console errors', c.consoleErrors, c.consoleErrors > 0)}
+    ${item('page errors', c.pageErrors, c.pageErrors > 0)}
+    ${item('failed requests', c.failedRequests, c.failedRequests > 0)}
+    ${item('requests', c.requests, false)}
+    ${item('a11y errors', c.a11yErrors, c.a11yErrors > 0)}
+    ${item('a11y warnings', c.a11yWarnings, false)}
+  </ul>`;
+}
+
+function renderErrors(report: Report): string {
+  const rows: string[] = [];
+  for (const e of report.pageErrors) {
+    const where = e.url ? `${e.url}${e.lineNumber !== undefined ? `:${e.lineNumber}` : ''}` : '';
+    rows.push(`<tr>
+      <td><span class="pill error">uncaught</span></td>
+      <td class="wrap">${escapeHtml(e.text)}</td>
+      <td class="wrap mono">${escapeHtml(where)}</td>
+    </tr>`);
+  }
+  for (const m of report.console) {
+    if (m.type !== 'error' && m.type !== 'warn' && m.type !== 'warning') continue;
+    const pill = m.type === 'error' ? 'error' : 'warning';
+    const where = m.url ? `${m.url}${m.lineNumber !== undefined ? `:${m.lineNumber}` : ''}` : '';
+    rows.push(`<tr>
+      <td><span class="pill ${pill}">console.${escapeHtml(m.type)}</span></td>
+      <td class="wrap">${escapeHtml(m.text)}</td>
+      <td class="wrap mono">${escapeHtml(where)}</td>
+    </tr>`);
+  }
+  if (!rows.length) return emptyBlock('No console errors, warnings or uncaught exceptions.');
+  return `<table><thead><tr><th>Kind</th><th>Message</th><th>Source</th></tr></thead>
+    <tbody>${rows.join('')}</tbody></table>`;
+}
+
+function renderRequests(requests: RequestEntry[]): string {
+  const failed = requests.filter((r) => r.failed);
+  if (!failed.length) return emptyBlock('Every request returned a successful response.');
+  const rows = failed
+    .map(
+      (r) => `<tr>
+      <td class="mono">${escapeHtml(r.status ?? '—')}</td>
+      <td class="mono">${escapeHtml(r.method)}</td>
+      <td class="wrap mono">${escapeHtml(r.url)}</td>
+      <td class="wrap">${escapeHtml(r.errorText ?? '')}</td>
+    </tr>`,
+    )
+    .join('');
+  return `<table><thead><tr><th>Status</th><th>Method</th><th>URL</th><th>Error</th></tr></thead>
+    <tbody>${rows}</tbody></table>`;
+}
+
+function renderVitals(report: Report): string {
+  const v = report.vitals;
+  const defs: Array<[string, string, string]> = [
+    ['lcp', 'LCP', 'Largest Contentful Paint'],
+    ['fcp', 'FCP', 'First Contentful Paint'],
+    ['cls', 'CLS', 'Cumulative Layout Shift'],
+    ['inp', 'INP', 'Interaction to Next Paint'],
+    ['ttfb', 'TTFB', 'Time to First Byte'],
+  ];
+  const rows = defs
+    .map(([key, short, long]) => {
+      const raw = v[key as keyof typeof v] as number | undefined;
+      const rating = vitalRating(key, raw);
+      const shown = key === 'cls' ? (raw === undefined ? 'not measured' : raw.toFixed(3)) : ms(raw);
+      return `<tr>
+        <td><b>${short}</b> <span style="color:var(--muted)">${escapeHtml(long)}</span></td>
+        <td class="num mono">${escapeHtml(shown)}</td>
+        <td><span class="pill ${rating}">${rating === 'none' ? 'n/a' : rating}</span></td>
+      </tr>`;
+    })
+    .join('');
+  const load = `<tr><td>Load event</td><td class="num mono">${escapeHtml(ms(v.loadTime))}</td><td></td></tr>
+    <tr><td>DOM interactive</td><td class="num mono">${escapeHtml(ms(v.domInteractive))}</td><td></td></tr>
+    <tr><td>Resources</td><td class="num mono">${escapeHtml(v.resources ?? '—')}</td><td></td></tr>`;
+  return `<table><thead><tr><th>Metric</th><th>Value</th><th>Rating</th></tr></thead>
+    <tbody>${rows}${load}</tbody></table>`;
+}
+
+function renderA11y(findings: A11yFinding[]): string {
+  const disclaimer =
+    '<p class="note">Colour contrast is not evaluated: it cannot be derived from the accessibility tree, and guessing it would be worse than omitting it.</p>';
+  if (!findings.length) {
+    return `${emptyBlock('No accessibility findings from the AX tree.')}${disclaimer}`;
+  }
+  const order = { error: 0, warning: 1 } as const;
+  const rows = [...findings]
+    .sort((a, b) => order[a.impact] - order[b.impact])
+    .map(
+      (f) => `<tr>
+      <td><span class="pill ${f.impact}">${escapeHtml(f.impact)}</span></td>
+      <td class="mono">${escapeHtml(f.rule)}</td>
+      <td>${escapeHtml(f.role)}</td>
+      <td>${f.name ? escapeHtml(f.name) : '<span style="color:var(--muted)">(no accessible name)</span>'}</td>
+      <td class="wrap mono">${escapeHtml(f.locator)}</td>
+      <td class="wrap">${escapeHtml(f.detail)}</td>
+    </tr>`,
+    )
+    .join('');
+  return `<table><thead><tr><th>Impact</th><th>Rule</th><th>Role</th><th>Name</th><th>Locator</th><th>Detail</th></tr></thead>
+    <tbody>${rows}</tbody></table>${disclaimer}`;
+}
+
+function renderScreenshots(shots: Screenshot[]): string {
+  if (!shots.length) return emptyBlock('No screenshot was captured.');
+  return shots
+    .map(
+      (s) => `<figure>
+      <figcaption>${escapeHtml(s.label)} — ${s.width}×${s.height}</figcaption>
+      <img alt="${escapeHtml(`${s.label} screenshot`)}" src="${escapeHtml(s.dataUrl)}">
+    </figure>`,
+    )
+    .join('');
+}
+
+export interface RenderOptions {
+  /** Present when the report came from `--repeat` (RIG-14). */
+  flake?: FlakeReport;
+}
+
+export function renderHtml(report: Report, options: RenderOptions = {}): string {
+  const title = report.title || report.finalUrl || report.url;
+  const notes = report.notes.length
+    ? `<h2>Run notes</h2><ul class="empty">${report.notes.map((n) => `<li>${escapeHtml(n)}</li>`).join('')}</ul>`
+    : '';
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light dark">
+<title>${escapeHtml(`Page report — ${title}`)}</title>
+<style>${STYLES}
+${TREND_STYLES}
+${EVIDENCE_STYLES}</style>
+</head>
+<body>
+<main>
+<h1>${escapeHtml(title)}</h1>
+<p class="sub">${escapeHtml(report.finalUrl || report.url)} · captured ${escapeHtml(report.capturedAt)} · ${Math.round(report.durationMs)}ms</p>
+
+${renderVerdict(report)}
+${renderFlake(options.flake)}
+${renderStats(report)}
+
+${renderTrend(report.trend)}
+${renderDiff(report.diff)}
+
+<h2>Errors</h2>
+${renderErrors(report)}
+
+${renderEvidence(report.evidence)}
+
+<h2>Failed requests</h2>
+${renderRequests(report.requests)}
+
+<h2>Web vitals</h2>
+${renderVitals(report)}
+
+<h2>Accessibility</h2>
+${renderA11y(report.a11y)}
+
+<h2>Screenshots</h2>
+${renderScreenshots(report.screenshots)}
+
+${notes}
+<footer>Generated by monobrowse report — self-contained, no external resources.</footer>
+</main>
+</body>
+</html>
+`;
+}

package/src/report/run-diff.ts

@@ -0,0 +1,63 @@
+/**
+ * Assembles the run-to-run diff (RIG-10) from what the previous run left in
+ * the history directory: its structural signature (in the JSON record) and
+ * its screenshot (the sibling PNG).
+ *
+ * Every missing piece degrades into a note rather than an absent section, so
+ * a reader can tell "nothing changed" apart from "we could not check".
+ */
+
+import { type HistoryRun, loadRunScreenshot } from './history.js';
+import { type PixelDiffOptions, pixelDiff } from './pixel-diff.js';
+import { pngFromDataUrl } from './png.js';
+import { diffStructure } from './structure.js';
+import type { Report, RunDiff } from './types.js';
+
+export interface BuildRunDiffOptions {
+  pixels?: PixelDiffOptions;
+  /** Set false to skip the pixel half entirely. */
+  comparePixels?: boolean;
+}
+
+export async function buildRunDiff(
+  dir: string,
+  previous: HistoryRun | undefined,
+  current: Report,
+  options: BuildRunDiffOptions = {},
+): Promise<RunDiff | undefined> {
+  if (!previous) return undefined;
+
+  const notes: string[] = [];
+  const diff: RunDiff = {
+    previousRunId: previous.id,
+    previousCapturedAt: previous.capturedAt,
+    notes,
+  };
+
+  if (previous.structure?.length && current.structure?.length) {
+    diff.structure = diffStructure(previous.structure, current.structure);
+  } else if (!current.structure?.length) {
+    notes.push('No accessibility tree this run — structural diff skipped.');
+  } else {
+    notes.push('The previous run stored no structural signature — nothing to diff against.');
+  }
+
+  if (options.comparePixels !== false) {
+    const currentShot =
+      current.screenshots.find((s) => s.label === 'page') ?? current.screenshots[0];
+    const previousPng = await loadRunScreenshot(dir, previous);
+    if (!previousPng) {
+      notes.push('The previous run archived no screenshot — pixel diff skipped.');
+    } else if (!currentShot?.dataUrl) {
+      notes.push('No screenshot this run — pixel diff skipped.');
+    } else {
+      try {
+        diff.pixels = pixelDiff(previousPng, pngFromDataUrl(currentShot.dataUrl), options.pixels);
+      } catch (err) {
+        notes.push(`Pixel diff failed: ${(err as Error).message}`);
+      }
+    }
+  }
+
+  return diff;
+}