fix: visuals reference matching overhaul and better workflow

web/visual/check.ts

@@ -40,7 +40,8 @@ const contentTypes: Record<string, string> = {
 }
 
 const settleMs = 400
-const diffThreshold = 48
+const diffThreshold = 24
+const maxDiffPercent = 0.5
 
 function slug(text: string) {
 	return text
@@ -302,11 +303,18 @@ async function captureApp(
 		await route.fulfill(fulfilment(mock))
 	})
 	const page = await context.newPage()
-	if (setup.now) {
+	if (setup.paused) {
+		const time = setup.now ? new Date(setup.now) : new Date()
+		await page.clock.install({ time })
+		await page.clock.pauseAt(time)
+	} else if (setup.now) {
 		await page.clock.setFixedTime(new Date(setup.now))
 	}
 	await page.goto(`${origin}${setup.path}`)
 	await Promise.race([page.waitForLoadState('networkidle'), page.waitForTimeout(2000)])
+	await page.waitForFunction(
+		() => (document.querySelector('#app')?.textContent ?? '').trim().length > 0,
+	)
 	await setup.steps?.(page)
 	await page.evaluate(() => document.fonts.ready)
 	await page.waitForTimeout(settleMs)
@@ -386,8 +394,9 @@ async function main() {
 
 	const design = await serveDesign()
 	const app = await serveApp()
-	const browser = await chromium.launch()
+	const browser = await chromium.launch({ args: ['--disable-lcd-text'] })
 	const lines: string[] = []
+	let failures = 0
 
 	try {
 		for (const viewport of args.viewports) {
@@ -402,8 +411,9 @@ async function main() {
 
 					const setup = setups[state]
 					if (!setup) {
+						failures++
 						lines.push(
-							`${state} · ${viewport} · ${theme}: design only, no setup in web/visual/states.ts → ${relative(repoRoot, designPath)}`,
+							`FAIL ${state} · ${viewport} · ${theme}: no setup in web/visual/states.ts → ${relative(repoRoot, designPath)}`,
 						)
 						continue
 					}
@@ -419,14 +429,25 @@ async function main() {
 						appPath,
 					)
 					const result = await diff(browser, designPath, appPath, diffPath)
-					const warnings = [
+					const percent = result.ratio * 100
+					const budget = setup.exception?.maxPercent ?? maxDiffPercent
+					const problems = [
+						...(percent > budget
+							? [`${percent.toFixed(2)}% exceeds ${budget}% budget`]
+							: []),
 						...(result.sizes.split(' vs ')[0] !== result.sizes.split(' vs ')[1]
 							? [`size mismatch ${result.sizes}`]
 							: []),
 						...unmocked.map((key) => `unmocked ${key}`),
 					]
+					if (problems.length) {
+						failures++
+					}
+					const exception = setup.exception
+						? ` [exception ${setup.exception.maxPercent}% approved by ${setup.exception.approvedBy}: ${setup.exception.reason}]`
+						: ''
 					lines.push(
-						`${state} · ${viewport} · ${theme}: ${(result.ratio * 100).toFixed(1)}% pixels differ → ${relative(repoRoot, directory)}${warnings.length ? ` (${warnings.join('; ')})` : ''}`,
+						`${problems.length ? 'FAIL' : 'PASS'} ${state} · ${viewport} · ${theme}: ${percent.toFixed(2)}% pixels differ → ${relative(repoRoot, directory)}${problems.length ? ` (${problems.join('; ')})` : ''}${exception}`,
 					)
 				}
 				await board.context().close()
@@ -438,14 +459,22 @@ async function main() {
 		design.close()
 	}
 
+	const verdict = failures
+		? `FAIL: ${failures} of ${lines.length} captures failed (budget ${maxDiffPercent}% per capture)`
+		: `PASS: all ${lines.length} captures within budget (${maxDiffPercent}% unless an approved exception is listed)`
 	const report = [
 		`# Visual check: ${screen.name}`,
 		`Board: ${screen.board}, group "${screen.group}"`,
 		'',
+		verdict,
+		'',
 		...lines.map((line) => `- ${line}`),
 	].join('\n')
 	await writeFile(join(outRoot, screen.name, 'report.md'), `${report}\n`)
 	console.log(report)
+	if (failures) {
+		process.exitCode = 1
+	}
 }
 
 await main()