Redesign the compare report as a single-page triage UI

Replace the flat per-comparison report pages with one static
reports/index.html that embeds every result as JSON (window.REGLANCE)
and renders three views client-side from the location hash, with no
framework and no network access:

- Overview: results grouped by page, changed-only by default, diff
  thumbnails, +added/-removed HTML counts, search, and full keyboard
  triage (worst-first queue).
- Comparison: swipe, side-by-side, onion skin, diff overlay, and blink
  modes.
- HTML diff: unified diff with line numbers, hunk headers, and collapsed
  unchanged regions.

Generator changes:
- report.mjs: buildHtmlDiff() emits changed-line counts and unified-diff
  hunk JSON (replacing the boolean Yes/No signal); generateReport()
  groups per-slug results into one entry per page and writes the single
  page with run metadata (compared/baseline timestamps, duration).
- compare.mjs: compareSlug() returns HTML add/del/hunks inline and no
  longer writes per-result report or html-diff files; compare() gathers
  run metadata and builds the single report.

Templates: new index.html shell plus assets/reglance.css (the "Quiet"
direction, auto light/dark) and assets/app.js (vanilla renderer). Remove
the old report.html, index.html table, diff-viewer.html, html-diff.html,
and their stylesheets/script.

Tests and docs updated; eslint ignores the design handoff prototypes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jeremyfelt

CLAUDE.md

@@ -34,8 +34,10 @@ The package is a thin CLI over a set of focused modules:
   `context.route()` and fulfills repeats locally instead of hitting the origin.
 - `src/compare.mjs` — pixelmatch comparison + HTML diffing. Exports
   `compare(config, options)`; opens the generated report via `file://`.
-- `src/report.mjs` — All HTML/report generation and asset copying, driven by the
-  templates in `templates/`.
+- `src/report.mjs` — Assembles the report data and writes the single-page
+  report. `buildHtmlDiff` turns two HTML snapshots into changed-line counts and
+  unified-diff hunk JSON; `generateReport` groups the per-slug results into one
+  entry per page and embeds them as `window.REGLANCE` in `templates/index.html`.
 
 Command modules take the normalized `config` object and an `options` object;
 they never read `process.argv` or the config file themselves.
@@ -50,27 +52,32 @@ config works across developers who each run against their own local domain.
 
 All artifacts are written under the configured output directory (`.reglance` by
 default), which gets a generated `.gitignore` so nothing is committed to the host
-project. Subdirectories: `captures/`, `controls/`, `compares/`, `reports/`,
-`assets/`, and `image-cache/` when the image cache is enabled.
+project. Subdirectories: `captures/`, `controls/`, `compares/` (diff PNGs only),
+`reports/`, `assets/`, and `image-cache/` when the image cache is enabled.
 
 ## Templates
 
 `templates/` ships with the package (listed in `package.json` `files`):
 
-- `report.html` — Per-comparison visual report with a before/after slider.
-- `index.html` — Report index with filtering, sorting, and a diff modal.
-- `diff-viewer.html` — Diff modal markup/JS injected into the index.
-- `html-diff.html` — HTML diff report for a single comparison.
-- `assets/` — `style.css`, `index-style.css`, `script.js`, copied into the
-  output directory at compare time.
+- `index.html` — The single-page report shell. Two placeholders: `{title}` (the
+  escaped site name) and `{data}` (the script-safe `window.REGLANCE` JSON blob),
+  both replaced via `String.replaceAll`.
+- `assets/reglance.css` — The report stylesheet (the "Quiet" design direction:
+  system font stack, indigo accent, auto light/dark via `light-dark()`).
+- `assets/app.js` — Vanilla (no framework, no network) renderer. Reads
+  `window.REGLANCE`, routes on the location hash, and renders the overview,
+  comparison (five modes), and HTML-diff views with full keyboard triage.
 
-Placeholders use `{name}` style tokens replaced via `String.replaceAll`.
+The design source lives in `design_handoff_reglance_report/` — React/Babel
+prototypes kept for reference only (ignored by eslint); production is the
+vanilla code above.
 
 ## File naming
 
-Captures, controls, diffs, and reports are named `{pathKey}-{viewport}` (e.g.
-`home-desktop`). There is no project prefix; each project has its own output
-directory.
+Captures, controls, and diffs are named `{pathKey}-{viewport}` (e.g.
+`home-desktop`; diffs add a `-diff` suffix). There is no project prefix; each
+project has its own output directory. The report itself is a single
+`reports/index.html`.
 
 ## Development Notes
 

README.md

@@ -155,11 +155,18 @@ guards against silently baselining bad data:
 .reglance/
 	captures/   Latest screenshots + HTML snapshots
 	controls/   Baseline screenshots + HTML (+ manifest.json)
-	compares/   Diff images and HTML diffs
+	compares/   Diff images
 	reports/    The report — open reports/index.html
+	assets/     Report stylesheet + script
 	image-cache/ Cached image responses (only with imageCache enabled)
 ```
 
+The report is a single `reports/index.html` that embeds every result as JSON
+and renders three views client-side from the URL hash — a triage overview
+(grouped by page, changed-only by default, keyboard-navigable), a comparison
+view (swipe, side-by-side, onion skin, diff overlay, blink), and a unified HTML
+diff. It opens straight from disk with no network access.
+
 ## Development
 
 ```bash

eslint.config.mjs

@@ -1,6 +1,11 @@
 import config from '@happyprime/eslint-config';
 
 export default [
+	{
+		// Design handoff bundle: React/Babel/JSX prototypes kept for reference,
+		// not production code. The real report lives in templates/ and src/.
+		ignores: ['design_handoff_reglance_report/**'],
+	},
 	...config,
 	{
 		// reglance is a CLI: console.log/warn ARE its user-facing output, so

src/compare.mjs

@@ -9,12 +9,7 @@ import { diffLines } from 'diff';
 import open from 'open';
 import { filterTargets } from './config.mjs';
 import { readManifest, detectStaleControls } from './manifest.mjs';
-import {
-	copyAssets,
-	generateHtmlDiff,
-	generateIndex,
-	generateReport,
-} from './report.mjs';
+import { copyAssets, buildHtmlDiff, generateReport } from './report.mjs';
 
 // Skip the inline HTML line-diff above this snapshot size; line-diffing a
 // multi-MB (often minified) document is slow and produces no useful result.
@@ -85,13 +80,6 @@ export function compareSlug(config, target, viewport) {
 	let img1 = PNG.sync.read(fs.readFileSync(controlImage));
 	let img2 = PNG.sync.read(fs.readFileSync(captureImage));
 
-	// Remember each image's natural size before padding so the report can
-	// declare width/height and reserve the box (no layout shift on decode).
-	const controlWidth = img1.width;
-	const controlHeight = img1.height;
-	const captureWidth = img2.width;
-	const captureHeight = img2.height;
-
 	// Pad both onto a common canvas so width changes (a real layout
 	// regression) surface as a large diff instead of dropping the slug from
 	// the report. Height was already handled this way; width is too now.
@@ -116,10 +104,11 @@ export function compareSlug(config, target, viewport) {
 	const totalPixels = maxWidth * maxHeight;
 	const diffPercentage = (numDiffPixels / totalPixels) * 100;
 
-	// Compare the captured HTML snapshots when both exist.
+	// Compare the captured HTML snapshots when both exist, emitting changed-line
+	// counts and unified-diff hunks the report renders client-side.
 	const controlHtml = path.join(dirs.controlsHtml, `${slug}.html`);
 	const captureHtml = path.join(dirs.capturesHtml, `${slug}.html`);
-	let htmlResult = { hasChanges: false, html: '' };
+	let htmlResult = { add: 0, del: 0, hunks: [], note: '' };
 	if (fs.existsSync(controlHtml) && fs.existsSync(captureHtml)) {
 		// Guard pathological inputs: a multi-MB (often minified) document can
 		// grind through the line diff for no useful result.
@@ -129,43 +118,37 @@ export function compareSlug(config, target, viewport) {
 
 		if (tooBig) {
 			htmlResult = {
-				hasChanges: false,
-				html: `<!doctype html><meta charset="utf-8"><title>${slug}</title><p>HTML snapshot too large to diff inline (over ${Math.round(HTML_DIFF_MAX_BYTES / 1024 / 1024)}MB). Compare the captured HTML files directly.</p>`,
+				add: 0,
+				del: 0,
+				hunks: [],
+				note: `HTML snapshot too large to diff inline (over ${Math.round(HTML_DIFF_MAX_BYTES / 1024 / 1024)}MB). Compare the captured HTML files directly.`,
 			};
 		} else {
-			htmlResult = generateHtmlDiff(
-				fs.readFileSync(controlHtml, 'utf8'),
-				fs.readFileSync(captureHtml, 'utf8'),
-				{ name: config.name, urlKey: target.key, viewport },
-				diffLines
-			);
+			htmlResult = {
+				...buildHtmlDiff(
+					fs.readFileSync(controlHtml, 'utf8'),
+					fs.readFileSync(captureHtml, 'utf8'),
+					diffLines
+				),
+				note: '',
+			};
 		}
 	}
 
-	const htmlDiffPath = path.join(dirs.compares, `${slug}-html-diff.html`);
-	writeArtifact(htmlDiffPath, htmlResult.html);
-
-	const report = {
+	return {
 		url: target.url,
 		urlKey: target.key,
+		path: target.path,
 		viewport,
 		controlImage,
 		captureImage,
 		diffImage,
 		diffPercentage,
-		htmlDiffPath,
-		htmlHasChanges: htmlResult.hasChanges,
-		controlWidth,
-		controlHeight,
-		captureWidth,
-		captureHeight,
-		diffWidth: maxWidth,
-		diffHeight: maxHeight,
+		htmlAdd: htmlResult.add,
+		htmlDel: htmlResult.del,
+		htmlHunks: htmlResult.hunks,
+		htmlNote: htmlResult.note,
 	};
-
-	report.reportPath = generateReport(config, report);
-
-	return report;
 }
 
 /**
@@ -262,6 +245,81 @@ async function runComparisons(config, jobs, concurrency) {
 	return reports;
 }
 
+/**
+ * Format a timestamp for the report, e.g. "Jun 12, 2026 · 10:41 AM".
+ *
+ * @param {number|string|Date|null} value A Date, epoch ms, or ISO string.
+ * @returns {string} The formatted timestamp, or an empty string when absent.
+ */
+function formatTimestamp(value) {
+	if (!value) {
+		return '';
+	}
+	const date = new Date(value);
+	if (Number.isNaN(date.getTime())) {
+		return '';
+	}
+	const day = date.toLocaleDateString('en-US', {
+		month: 'short',
+		day: 'numeric',
+		year: 'numeric',
+	});
+	const time = date.toLocaleTimeString('en-US', {
+		hour: 'numeric',
+		minute: '2-digit',
+	});
+	return `${day} · ${time}`;
+}
+
+/**
+ * Format a run duration in milliseconds as a compact string, e.g. "48s".
+ *
+ * @param {number} ms The elapsed milliseconds.
+ * @returns {string} The formatted duration.
+ */
+function formatDuration(ms) {
+	const seconds = Math.max(0, Math.round(ms / 1000));
+	if (seconds < 60) {
+		return `${seconds}s`;
+	}
+	const minutes = Math.floor(seconds / 60);
+	const rest = seconds % 60;
+	return rest ? `${minutes}m ${rest}s` : `${minutes}m`;
+}
+
+/**
+ * Derive the run metadata shown in the report header.
+ *
+ * The capture timestamp comes from the newest compared capture's modified
+ * time; the baseline timestamp from the controls manifest. Both are best
+ * effort — an empty string just hides that line in the report.
+ *
+ * @param {object} config   The normalized config.
+ * @param {Array}  reports  The comparison results.
+ * @param {number} duration The compare run's elapsed milliseconds.
+ * @returns {{ comparedAt: string, baselineAt: string, duration: string }} The metadata.
+ */
+function buildRunMeta(config, reports, duration) {
+	let newestCapture = 0;
+	for (const report of reports) {
+		try {
+			const { mtimeMs } = fs.statSync(report.captureImage);
+			if (mtimeMs > newestCapture) {
+				newestCapture = mtimeMs;
+			}
+		} catch {
+			// A missing capture (already warned about elsewhere) just doesn't
+			// contribute to the timestamp.
+		}
+	}
+
+	return {
+		comparedAt: formatTimestamp(newestCapture || null),
+		baselineAt: formatTimestamp(readManifest(config.dirs).updatedAt),
+		duration: formatDuration(duration),
+	};
+}
+
 /**
  * Compare every captured target against its control and build the report.
  *
@@ -276,6 +334,7 @@ export async function compare(config, options = {}) {
 	const { open: openReport = true } = options;
 	const concurrency =
 		options.concurrency ?? Math.max(1, availableParallelism() - 1);
+	const startedAt = Date.now();
 
 	fs.mkdirSync(dirs.compares, { recursive: true });
 	fs.mkdirSync(dirs.reports, { recursive: true });
@@ -299,7 +358,8 @@ export async function compare(config, options = {}) {
 		return;
 	}
 
-	const indexPath = generateIndex(config, reports);
+	const meta = buildRunMeta(config, reports, Date.now() - startedAt);
+	const indexPath = generateReport(config, reports, meta);
 	const reportUrl = pathToFileURL(indexPath).href;
 
 	console.log(`\n✅ Comparison complete (${reports.length} comparisons)`);