Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

46.6 KB
Raw Blame
#!/usr/bin/env node
/**
 * page-audit.mjs — authenticated, full-site console / error / network / layout audit.
 *
 * Drives a real Chromium across every public and authenticated page (sourced
 * from data/pages.json plus the dynamic agent/dashboard routes), in both a
 * desktop and a mobile viewport, and records everything a human would otherwise
 * hunt for with the dev console open on each page:
 *
 *   • console.error / console.warn output
 *   • uncaught exceptions (pageerror)
 *   • failed network requests (requestfailed)
 *   • HTTP responses with status >= 400
 *   • horizontal overflow / elements escaping the viewport
 *   • interactive controls below the 32px tap-target floor
 *   • missing <title>, missing alt text, empty links/buttons
 *
 * Findings are deduped, grouped per page, scored by severity, and written to
 * reports/page-audit-<timestamp>.{json,md}. A console summary is printed at the
 * end. The harness never mutates the target — it only reads pages.
 *
 * ── Target ──────────────────────────────────────────────────────────────────
 *   BASE_URL=https://three.ws        (default — real APIs, real data)
 *   BASE_URL=http://localhost:3000   (vite/vercel dev)
 *
 * ── Auth (reach dashboard / wallet / profile pages) ──────────────────────────
 * Authentication is a server-set HttpOnly session cookie. Generate a reusable
 * Playwright storageState once, then every run replays it:
 *
 *   AUDIT_EMAIL=you@example.com AUDIT_PASSWORD=••• \
 *     node scripts/page-audit.mjs --login
 *
 * That logs in via POST /api/auth/login against the chosen BASE_URL and saves
 * cookies + localStorage to .auth/audit-state.json (gitignored). Subsequent
 * runs pick it up automatically. Without it, the audit runs anonymously and
 * skips authenticated-only routes.
 *
 * ── Usage ────────────────────────────────────────────────────────────────────
 *   node scripts/page-audit.mjs                 # full audit, all routes
 *   node scripts/page-audit.mjs / /agents /pay  # only these routes
 *   node scripts/page-audit.mjs --login         # (re)create the auth session
 *   node scripts/page-audit.mjs --desktop-only  # skip the mobile viewport
 *   node scripts/page-audit.mjs --mobile-only   # skip the desktop viewport
 *   node scripts/page-audit.mjs --concurrency 6 # parallel pages per viewport
 *   node scripts/page-audit.mjs --strict        # exit 1 if any error-severity finding
 *   node scripts/page-audit.mjs --engine webkit # audit in Safari's engine instead
 */
import { chromium, webkit, firefox, devices } from 'playwright';
import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
import { resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { config as dotenv } from 'dotenv';
import {
	AUTHED_ROUTES,
	isHtmlRoute,
	manifestRoutes,
	seedDynamicRoutes,
} from './lib/audit-routes.mjs';

// The QA credentials live in .env, so `npm run audit:web:login` has to read it:
// without this the script only ever saw an inline-prefixed environment and told
// every caller the credentials were missing while they sat on disk.
// Shell env wins: dotenv never overrides a var that is already set.
dotenv({ path: new URL('../.env', import.meta.url), quiet: true });
dotenv({ path: new URL('../.env.local', import.meta.url), quiet: true });

const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const BASE_URL = (process.env.BASE_URL || 'https://three.ws').replace(/\/$/, '');
const AUTH_STATE = resolve(ROOT, '.auth/audit-state.json');
const IS_LOCAL = /localhost|127\.0\.0\.1/.test(BASE_URL);

// ── CLI parsing ───────────────────────────────────────────────────────────────
const argv = process.argv.slice(2);
const flag = (name) => argv.includes(`--${name}`);
const opt = (name, fallback) => {
	const i = argv.indexOf(`--${name}`);
	return i !== -1 && argv[i + 1] ? argv[i + 1] : fallback;
};
const DO_LOGIN = flag('login');
const DESKTOP_ONLY = flag('desktop-only');
const MOBILE_ONLY = flag('mobile-only');
const STRICT = flag('strict');
const CONCURRENCY = Math.max(1, Number(opt('concurrency', 5)) || 5);

// The sweep's own navigation budget, and the wider one the solo re-check gets.
//
// The solo pass removes the contention THIS run creates, but it cannot remove
// the load every other process on the box creates, and a starved browser misses
// a 25 s navigation on a page that is perfectly healthy. On 2026-09-08, with
// three sweeps and two Playwright suites sharing one machine, /dashboard/avatars
// timed out at 25 s in the sweep AND again in the solo re-check, so it was
// published as the run's only confirmed error. The same route, loaded by itself
// moments later, reached domcontentloaded in 769 ms and logged nothing.
//
// Re-checking a timeout with the budget that produced it just reproduces the
// starvation, so the solo pass navigates with a wider one: a page that loads
// fine given room emits no nav-failed, and the original finding demotes as the
// artifact it was. A genuinely dead route still fails at 60 s and stays an
// error. This only widens the re-check; the sweep itself is unchanged, so a
// slow route is still flagged by the first pass.
const NAV_TIMEOUT_MS = 25000;
const REVERIFY_NAV_TIMEOUT_MS = 60000;

// Which engine renders the sweep. Chromium is the default because it is the
// only browser every machine here already has, but it cannot see a whole class
// of bug on its own: JavaScriptCore and V8 disagree about when a temporal dead
// zone is checked, so a page can render perfectly in Chrome and throw
// "Cannot access uninitialized variable." on every Safari. That is exactly how
// /avatars/:id shipped dead on iOS and macOS while this audit stayed green.
// `--engine webkit` needs `npx playwright install webkit` once.
const ENGINES = { chromium, webkit, firefox };
const ENGINE_NAME = String(opt('engine', 'chromium')).toLowerCase();
const ENGINE = ENGINES[ENGINE_NAME];
if (!ENGINE) {
	console.error(`✗ unknown --engine "${ENGINE_NAME}". Use one of: ${Object.keys(ENGINES).join(', ')}`);
	process.exit(2);
}

// The viewport a route is audited at, and the browser it claims to be. Mobile
// borrows the iPhone 13 descriptor, which already announces real Safari. Bare
// desktop Chromium announces "HeadlessChrome", and third-party embeds behind a
// bot wall answer that with a 403 and X-Frame-Options: SAMEORIGIN: the DEXTools
// chart on /three-token was reported as a refused frame on every sweep while
// every real visitor got the chart. A human audit should see what a human sees,
// so desktop Chromium presents Playwright's stock Desktop Chrome user agent.
function viewportOptions(viewport) {
	if (viewport === 'mobile') return devices['iPhone 13'];
	return {
		viewport: { width: 1440, height: 900 },
		...(ENGINE_NAME === 'chromium' ? { userAgent: devices['Desktop Chrome'].userAgent } : {}),
	};
}
const explicitRoutes = argv.filter((a) => a.startsWith('/'));

// Console output a cross-origin iframe's own scripts emit: an embedded chart or
// widget talking to its own backends (the DEXTools chart on /three-token logs
// its websocket handshake and captcha config from inside its frame). That is the
// embed's business, not a fault in our page, the same reasoning that already
// ignores the DexScreener frame by name. A script our page itself loads from a
// CDN runs in our frame and is still reported: only origins that belong to a
// child frame, and not to the page, are dropped.
function originOf(url) {
	try {
		return new URL(url).origin;
	} catch {
		return null;
	}
}
function fromEmbeddedThirdPartyFrame(page, msg) {
	const src = originOf(msg.location()?.url || '');
	if (!src || src === originOf(page.url())) return false;
	return page.frames().some((f) => f !== page.mainFrame() && originOf(f.url()) === src);
}

// ── Noise filter ────────────────────────────────────────────────────────────
// Third-party chatter that is never our bug, regardless of target. Kept tight
// so we don't accidentally swallow real failures.
const ALWAYS_IGNORE = [
	/chrome-extension:\/\//,
	/favicon\.ico/,
	/google-analytics\.com|googletagmanager\.com|analytics\.google/,
	/doubleclick\.net|facebook\.net|hotjar|sentry\.io|fullstory/,
	/Failed to load resource: net::ERR_BLOCKED_BY_CLIENT/, // ad/track blockers
	// Errors raised inside the embedded DexScreener chart iframe (its own
	// origin fetching its own backends) are theirs, not ours.
	/dexscreener\.com/,
	// Performance advisories emitted by the headless box's software GL stack
	// (ANGLE over SwiftShader), e.g. "[.WebGL-0x…]GL Driver Message (OpenGL,
	// Performance, GL_CLOSE_PATH_NV, High): GPU stall due to ReadPixels". They
	// come from the emulated driver, not from page code, and no visitor on a
	// real GPU ever sees them. Scoped to the Performance category on purpose:
	// a driver message in the Error category is still a real WebGL fault and
	// stays reportable.
	/GL Driver Message \(OpenGL, Performance/,
];
// Failures that only happen because serverless functions / CDNs aren't present
// under a bare local dev server. Applied only when auditing localhost.
const LOCAL_ONLY_IGNORE = [
	/localhost:\d+\/api\//,
	/localhost:\d+\/chat/,
	/esm\.sh/,
	/ajax\.googleapis\.com/,
	/\/node_modules\/vite\/dist\/client\/env\.mjs/,
	// Vite's HMR client dials a websocket at the page's own host. On a plain
	// laptop that connects; inside a Codespace the page is served over a
	// forwarded https origin whose wss upgrade answers 404, so every locally
	// audited page reports the same three errors (the handshake, Vite's own
	// retry log, and the uncaught close) before a single line of page code
	// runs. Hot reload is a dev-server feature that production does not ship,
	// so its failure says nothing about the page.
	/\[vite\] failed to connect to websocket/,
	/WebSocket (connection to '[^']*' failed|closed without opened)/,
	/Unexpected token .+, .<!doctype /,
	/Expected a JavaScript-or-Wasm module script but the server responded with a MIME type of "text\/html"/,
];
const ignorePatterns = IS_LOCAL ? [...ALWAYS_IGNORE, ...LOCAL_ONLY_IGNORE] : ALWAYS_IGNORE;
const shouldIgnore = (text) => ignorePatterns.some((re) => re.test(text || ''));

// ── Route discovery ───────────────────────────────────────────────────────────
// Public pages, the authenticated route list and the dynamic-id seeder all come
// from scripts/lib/audit-routes.mjs, shared with the visual sweep so the two
// can never disagree about what pages exist.
function buildRouteList(dynamic) {
	if (explicitRoutes.length) {
		const skipped = explicitRoutes.filter((r) => !isHtmlRoute(r));
		for (const r of skipped) console.log(`  skipping ${r} (non-HTML endpoint, nothing to audit)`);
		return [...new Set(explicitRoutes.filter(isHtmlRoute))];
	}
	// With a session, the manifest's own auth-gated pages come in too. Asking
	// for the public set alone dropped five of them (/conversions, /agent-screen,
	// /agent-studio, /proof, /autopilot-activity): flagged `auth` in
	// data/pages.json, so the public filter removed them, and absent from
	// AUTHED_ROUTES, which only carries what the manifest deliberately omits.
	// They fell between the two lists and no sweep had ever loaded them.
	const signedIn = existsSync(AUTH_STATE);
	const manifest = manifestRoutes(signedIn ? { access: 'all' } : undefined);
	const authed = signedIn ? AUTHED_ROUTES : [];
	return [...new Set([...manifest, ...authed, ...dynamic])];
}

// ── Login (storageState bootstrap) ────────────────────────────────────────────
async function login() {
	const email = process.env.AUDIT_EMAIL;
	const passwordVal = process.env.AUDIT_PASSWORD;
	if (!email || !passwordVal) {
		console.error(
			'✗ --login needs AUDIT_EMAIL and AUDIT_PASSWORD in the environment.\n' +
				'  Example:\n' +
				'    [email protected] AUDIT_PASSWORD=secret \\\n' +
				`      BASE_URL=${BASE_URL} node scripts/page-audit.mjs --login`,
		);
		process.exit(2);
	}
	const browser = await chromium.launch();
	const ctx = await browser.newContext();
	console.log(`Logging in as ${email} at ${BASE_URL}…`);
	const res = await ctx.request.post(`${BASE_URL}/api/auth/login`, {
		data: { email, password: passwordVal },
		headers: { 'content-type': 'application/json' },
		timeout: 20000,
	});
	if (!res.ok()) {
		const text = await res.text().catch(() => '');
		console.error(`✗ login failed: HTTP ${res.status()} ${text.slice(0, 200)}`);
		await browser.close();
		process.exit(1);
	}
	// Prime the optimistic auth-hint the viewer reads on first paint.
	const page = await ctx.newPage();
	await page.goto(`${BASE_URL}/`, { waitUntil: 'domcontentloaded', timeout: 20000 }).catch(() => {});
	await page.evaluate(() => {
		try {
			localStorage.setItem('3dagent:auth-hint', JSON.stringify({ authed: true, ts: Date.now() }));
		} catch {}
	});
	mkdirSync(dirname(AUTH_STATE), { recursive: true });
	await ctx.storageState({ path: AUTH_STATE });
	await browser.close();
	console.log(`✓ session saved to ${AUTH_STATE.replace(ROOT + '/', '')}`);
}

// ── Click-listener tracking (installed before any page script runs) ───────────
// `el.onclick` is only set by inline onclick= attributes and direct property
// assignment. Everything wired with addEventListener reports onclick === null,
// so a dead-control check built on it both misses real handlers and slanders
// working ones. Patching addEventListener at document start is the only way to
// know from inside the page which elements are genuinely interactive.
function trackClickListeners() {
	const ACTIVATING = new Set(['click', 'pointerdown', 'mousedown', 'mouseup', 'keydown', 'keyup']);
	const wired = new WeakSet();
	// Walk up to (but not including) <body>. A listener on a real container is
	// genuine delegation and makes the anchor live. A listener on
	// body/document/window is not counted: pages routinely attach one for
	// dropdown dismissal or analytics, and honouring those would mark every
	// anchor on the page live and silence the check entirely.
	window.__auditWiredClick = (el) => {
		for (let n = el; n && n !== document.body; n = n.parentElement) {
			if (wired.has(n)) return true;
			if (typeof n.onclick === 'function') return true;
		}
		return false;
	};
	const original = EventTarget.prototype.addEventListener;
	EventTarget.prototype.addEventListener = function (type, listener, options) {
		if (ACTIVATING.has(type) && listener) wired.add(this);
		return original.call(this, type, listener, options);
	};
}

// ── In-page audit (runs in the browser) ───────────────────────────────────────
function inPageAudit() {
	const vw = window.innerWidth;
	const docW = document.documentElement.scrollWidth;
	const findings = [];
	const cls = (el) =>
		(el.className && typeof el.className === 'string' ? el.className : '').trim().slice(0, 60);
	const label = (el) =>
		`${el.tagName.toLowerCase()}${el.id ? '#' + el.id : ''}${cls(el) ? '.' + cls(el).split(/\s+/)[0] : ''}`;

	// Horizontal overflow — elements escaping the viewport that aren't clipped
	// by a scrollable ancestor (marquees / carousels are fine).
	if (docW > vw + 2) {
		for (const el of document.querySelectorAll('body *')) {
			const r = el.getBoundingClientRect();
			if (r.width === 0 || r.height === 0) continue;
			const st = getComputedStyle(el);
			if (st.position === 'fixed') continue;
			if (r.right <= vw + 2 && r.left >= -2) continue;
			let clipped = false;
			for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
				const ox = getComputedStyle(p).overflowX;
				if (ox === 'hidden' || ox === 'clip' || ox === 'auto' || ox === 'scroll') {
					clipped = true;
					break;
				}
			}
			if (clipped) continue;
			findings.push({
				type: 'overflow',
				severity: 'warn',
				detail: `${label(el)} overflows: left=${Math.round(r.left)} right=${Math.round(r.right)} vw=${vw}`,
			});
			if (findings.filter((f) => f.type === 'overflow').length >= 10) break;
		}
	}

	// Tiny tap targets (mobile only — caller decides whether to keep these).
	for (const el of document.querySelectorAll(
		'a[href], button, input, select, textarea, [role="button"]',
	)) {
		const r = el.getBoundingClientRect();
		if (r.width === 0 || r.height === 0) continue;
		const st = getComputedStyle(el);
		if (st.display === 'none' || st.visibility === 'hidden' || st.pointerEvents === 'none') continue;
		if (r.height < 32 || r.width < 24) {
			findings.push({
				type: 'tap-target',
				severity: 'info',
				detail: `${label(el)} is ${Math.round(r.width)}×${Math.round(r.height)}px ("${(el.textContent || '').trim().slice(0, 24)}")`,
			});
			if (findings.filter((f) => f.type === 'tap-target').length >= 8) break;
		}
	}

	// Accessibility / dead-control smells.
	if (!document.title || !document.title.trim()) {
		findings.push({ type: 'a11y', severity: 'warn', detail: 'page has no <title>' });
	}
	let noAlt = 0;
	for (const img of document.querySelectorAll('img')) {
		const r = img.getBoundingClientRect();
		if (r.width < 24 || r.height < 24) continue;
		if (!img.hasAttribute('alt')) noAlt++;
	}
	if (noAlt > 0) {
		findings.push({ type: 'a11y', severity: 'info', detail: `${noAlt} image(s) missing alt text` });
	}
	// A link is dead only if it has no destination AND nothing made it
	// interactive. Placeholder href="#" anchors that JS fills in later are fine
	// once assigned; the ones nobody ever assigns or wires are real dead ends.
	const deadLinks = [];
	const wiredCheck = window.__auditWiredClick;
	for (const a of document.querySelectorAll('a')) {
		const href = a.getAttribute('href');
		const r = a.getBoundingClientRect();
		if (r.width === 0 || r.height === 0) continue;
		if (href !== null && href !== '' && href !== '#' && href !== 'javascript:void(0)') continue;
		if (a.getAttribute('role')) continue;
		if (wiredCheck ? wiredCheck(a) : a.onclick) continue;
		deadLinks.push(
			`${label(a)} ("${(a.textContent || '').trim().slice(0, 32) || 'no text'}") href=${
				href === null ? 'absent' : `"${href}"`
			}`,
		);
		if (deadLinks.length >= 12) break;
	}
	if (deadLinks.length > 0) {
		findings.push({
			type: 'dead-link',
			severity: 'warn',
			detail: `${deadLinks.length} link(s) with no destination and no click handler: ${deadLinks.join('; ')}`,
		});
	}

	// Blank-render detection: the page "loaded" but nothing meaningful painted.
	// A 3D canvas, iframe, or video counts as content; otherwise we require some
	// visible text or a reasonable number of visible elements.
	const visibleText = (document.body?.innerText || '').replace(/\s+/g, ' ').trim();
	const hasMedia = !!document.querySelector('canvas, iframe, video');
	let visibleEls = 0;
	for (const el of document.querySelectorAll('body *')) {
		const r = el.getBoundingClientRect();
		if (r.width > 4 && r.height > 4) visibleEls++;
		if (visibleEls > 12) break;
	}
	if (!hasMedia && visibleText.length < 40 && visibleEls <= 12) {
		findings.push({
			type: 'blank-page',
			severity: 'error',
			detail: `page rendered ~nothing: ${visibleText.length} chars of visible text, ${visibleEls} visible elements, no canvas/iframe/video`,
		});
	}

	// Visible failure text: error banners and raw exception text a user would see.
	const ERROR_TEXT =
		/something went wrong|an error occurred|unexpected error|failed to (load|fetch|initialize)|cannot read propert|is not a function|is not defined|internal server error|\bTypeError\b|\bReferenceError\b/i;
	const seenBanners = new Set();
	for (const el of document.querySelectorAll('body *')) {
		if (el.children.length > 3) continue;
		// Docs and articles legitimately print error strings in code samples.
		if (el.closest('pre, code, script, style, table, article, [data-audit-intentional-error]')) continue;
		const t = (el.innerText || '').trim();
		if (!t || t.length > 400 || !ERROR_TEXT.test(t)) continue;
		const r = el.getBoundingClientRect();
		if (r.width === 0 || r.height === 0) continue;
		const st = getComputedStyle(el);
		if (st.display === 'none' || st.visibility === 'hidden') continue;
		const key = t.slice(0, 120);
		if (seenBanners.has(key)) continue;
		seenBanners.add(key);
		findings.push({ type: 'error-banner', severity: 'error', detail: `visible error text: "${key}"` });
		if (seenBanners.size >= 5) break;
	}

	// Same-origin links, for crawl discovery of routes missing from the manifest.
	const links = new Set();
	for (const a of document.querySelectorAll('a[href]')) {
		try {
			const u = new URL(a.getAttribute('href'), location.href);
			if (u.origin !== location.origin) continue;
			const p = u.pathname.replace(/\/$/, '') || '/';
			links.add(p);
		} catch {}
	}

	return {
		title: document.title,
		hasHorizontalScroll: docW > vw + 2,
		findings,
		links: [...links].slice(0, 400),
	};
}

// ── Per-route audit ───────────────────────────────────────────────────────────
async function auditRoute(ctx, route, viewport, { navTimeoutMs = NAV_TIMEOUT_MS } = {}) {
	const page = await ctx.newPage();
	const findings = [];
	const push = (type, severity, detail) => {
		if (shouldIgnore(detail)) return;
		findings.push({ type, severity, detail: String(detail).slice(0, 300) });
	};

	page.on('console', (m) => {
		const t = m.type();
		if (t !== 'error' && t !== 'warning') return;
		const text = m.text();
		// A blocked or failed resource is reported once, by the requestfailed
		// handler below. Each engine also echoes it to the console in its own
		// words, and counting those again turned one blocked IPFS image into
		// three findings. Chromium's echo is "Failed to load resource"; these
		// are WebKit's.
		if (text.startsWith('Failed to load resource')) return; // cascade, captured below
		if (/^Cancelled load to .+ because it violates the Content Security Policy/.test(text)) return;
		if (/^Cannot load .+ due to access control checks\.$/.test(text)) return;
		if (fromEmbeddedThirdPartyFrame(page, m)) return;
		push(t === 'error' ? 'console-error' : 'console-warn', t === 'error' ? 'error' : 'warn', text);
	});
	page.on('pageerror', (e) => push('exception', 'error', `${e.message}`));
	page.on('requestfailed', (req) => {
		const f = req.failure()?.errorText || '';
		// Same event, two vocabularies: Chromium says net::ERR_ABORTED, WebKit
		// says "Load request cancelled". Both mean the page navigated away or a
		// long-lived stream (SSE, the pump/oracle trade feeds) was closed with
		// the tab, which is the audit's own doing rather than a page fault.
		if (f === 'net::ERR_ABORTED' || /^Load request cancelled$/i.test(f.trim())) return;
		push('request-failed', 'error', `${req.url()} — ${f}`);
	});
	page.on('response', (res) => {
		const s = res.status();
		if (s < 400) return;
		// x402 payment-gated endpoints correctly answer 402 to a non-paying
		// browser; that is the product working, not a defect.
		if (s === 402 && new URL(res.url()).pathname.startsWith('/api/')) {
			push('payment-gated', 'info', `HTTP 402 ${res.url()} (x402 payment required, expected)`);
			return;
		}
		push('http-' + s, s >= 500 ? 'error' : 'warn', `HTTP ${s} ${res.url()}`);
	});

	let navStatus = null;
	try {
		const resp = await page.goto(`${BASE_URL}${route}`, {
			waitUntil: 'networkidle',
			timeout: navTimeoutMs,
		});
		navStatus = resp?.status() ?? null;
	} catch {
		try {
			const resp = await page.goto(`${BASE_URL}${route}`, {
				waitUntil: 'domcontentloaded',
				timeout: navTimeoutMs,
			});
			navStatus = resp?.status() ?? null;
		} catch (e) {
			push('nav-failed', 'error', e.message);
		}
	}
	// Let async boot code settle (3D loads, data fetches, late errors).
	await page.waitForTimeout(2500);

	if (navStatus && navStatus >= 400) {
		push('nav-status', navStatus >= 500 ? 'error' : 'warn', `navigation returned HTTP ${navStatus}`);
	}

	let title = '';
	let links = [];
	try {
		const r = await page.evaluate(inPageAudit);
		title = r.title;
		links = r.links || [];
		for (const f of r.findings) {
			// Tap-target noise is only meaningful on the mobile pass.
			if (f.type === 'tap-target' && viewport !== 'mobile') continue;
			// Content-heavy prose surfaces mention error strings legitimately;
			// keep the signal but do not fail the page on it.
			const sev =
				f.type === 'error-banner' && /^\/(docs|blog|news|changelog|specs)(\/|$)/.test(route)
					? 'info'
					: f.severity;
			push(f.type, sev, f.detail);
		}
	} catch {
		/* page torn down mid-eval */
	}

	// A screenshot for every page with an error-severity finding, so the report
	// shows what a user would have seen.
	let screenshot = null;
	if (findings.some((f) => f.severity === 'error')) {
		try {
			const dir = resolve(ROOT, 'reports/screens');
			mkdirSync(dir, { recursive: true });
			const safe = route.replace(/[^a-z0-9]+/gi, '_').replace(/^_|_$/g, '') || 'root';
			screenshot = `reports/screens/${safe}-${viewport}.png`;
			await page.screenshot({ path: resolve(ROOT, screenshot), fullPage: false });
		} catch {
			screenshot = null;
		}
	}

	await page.close();
	return { route, viewport, title, navStatus, findings, links, screenshot };
}

// ── Crawl discovery ───────────────────────────────────────────────────────────
// Links collected on audited pages that point at same-origin HTML routes we
// were NOT going to visit. These are exactly the pages past audits missed:
// reachable by users, absent from the manifest. Deep dynamic families
// (/u/<id>, /coin/<mint>, ...) are sampled, never exhaustively crawled, and
// anything sampled out is reported rather than silently dropped.
function pickDiscovered(links, known) {
	const candidates = [];
	for (const p of links) {
		if (!p.startsWith('/') || known.has(p)) continue;
		if (!isHtmlRoute(p)) continue;
		if (/^\/(api|assets|cdn|static|models|textures|_)/.test(p)) continue;
		candidates.push(p);
	}
	candidates.sort();
	const perFamily = new Map();
	const audit = [];
	const dropped = [];
	for (const p of candidates) {
		const fam = p.split('/').slice(0, 2).join('/');
		const depth = p.split('/').filter(Boolean).length;
		const cap = depth >= 2 ? 3 : Infinity;
		const n = perFamily.get(fam) || 0;
		if (n >= cap || audit.length >= 150) {
			dropped.push(p);
			continue;
		}
		perFamily.set(fam, n + 1);
		audit.push(p);
	}
	return { audit, dropped };
}

// ── Re-verification ───────────────────────────────────────────────────────────
// The sweep runs CONCURRENCY pages at once, and a WebGL-heavy page audited
// beside four others in one headless (software-GL) browser fails in ways a real
// visitor never sees: GPU contention makes texture uploads fail, and a
// contended page misses a 25 s networkidle it would otherwise hit easily.
// Measured 2026-07-28: 108 of 131 console errors in one report were
// "GLTFLoader: Couldn't load texture blob:…" from avatar pages, alongside
// "Framebuffer is incomplete" and GPU-stall warnings. Re-running those same
// routes one at a time, and even in parallel from a fresh browser, produced
// ZERO. A report where 4 findings in 5 are phantom is a report nobody can act
// on, so every error-severity finding is re-checked SOLO before it is reported:
// findings that reproduce stay errors, findings that do not are demoted to info
// and labelled, never silently dropped.
// `|| 60` here silently rewrote an explicit `--reverify-cap 0` back to 60, so
// the documented way to skip the solo re-check never skipped anything. Fall
// back only when the value is absent or not a number.
const REVERIFY_CAP = (() => {
	const raw = Number(opt('reverify-cap', 60));
	return Number.isFinite(raw) && raw >= 0 ? raw : 60;
})();

// Collapse the volatile parts of a finding so the same defect matches across
// runs: blob/object URLs, uuids, base58 mints, query strings and bare numbers
// all differ per load while naming the same problem.
function fingerprint(f) {
	const detail = String(f.detail || '')
		.replace(/blob:[^\s"']+/g, 'BLOB')
		.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, 'UUID')
		.replace(/\b[1-9A-HJ-NP-Za-km-z]{32,44}\b/g, 'ADDR')
		.replace(/\?[^\s"']*/g, '')
		.replace(/\d+/g, 'N')
		.trim();
	return `${f.type}::${detail}`;
}

async function reverify(browser, results, viewports, authed) {
	// One route may fail on desktop, mobile, or both; re-check each pair once.
	const suspects = [];
	for (const r of results) {
		if (r.findings.some((f) => f.severity === 'error')) suspects.push(r);
	}
	if (!suspects.length) return { checked: 0, demoted: 0, skipped: 0 };

	// The cap is spread evenly across viewports, never spent in arrival order.
	// Desktop runs first, so a flat slice handed all 60 slots to desktop and left
	// every mobile suspect reported-but-unverified: on 2026-08-11 that published
	// 28 unchecked mobile pages as the report's worst offenders while the desktop
	// pages beside them demoted at 4-in-5. Round-robin keeps one slow viewport
	// from starving the other.
	const byViewport = new Map();
	for (const s of suspects) {
		if (!byViewport.has(s.viewport)) byViewport.set(s.viewport, []);
		byViewport.get(s.viewport).push(s);
	}
	const lanes = [...byViewport.values()];
	const budget = [];
	for (let i = 0; budget.length < Math.min(REVERIFY_CAP, suspects.length); i++) {
		for (const lane of lanes) {
			if (i >= lane.length) continue;
			budget.push(lane[i]);
			if (budget.length >= REVERIFY_CAP) break;
		}
	}
	const skipped = suspects.length - budget.length;
	console.log(
		`\n── re-verify: ${budget.length} route/viewport pair(s) with errors, re-checked one at a time ──`,
	);
	if (skipped) {
		console.log(`  (${skipped} beyond --reverify-cap ${REVERIFY_CAP} kept as reported, unverified)`);
	}

	let demoted = 0;
	let checked = 0;
	for (const suspect of budget) {
		const viewport = suspect.viewport;
		if (!viewports.includes(viewport)) continue;
		let ctx;
		try {
			ctx = await browser.newContext({
				...viewportOptions(viewport),
				...(authed ? { storageState: AUTH_STATE } : {}),
				ignoreHTTPSErrors: true,
			});
		} catch (err) {
			// No browser to re-check with. Every remaining suspect keeps the
			// severity the sweep gave it, and the report still gets written.
			console.log(`  ⚠ re-verify stopped: ${err.message.split('\n')[0]}`);
			return { checked, demoted, skipped: skipped + (budget.length - checked), aborted: true };
		}
		let solo;
		try {
			solo = await auditRoute(ctx, suspect.route, viewport, {
				navTimeoutMs: REVERIFY_NAV_TIMEOUT_MS,
			});
		} catch {
			solo = null; // a crashed re-check proves nothing; leave the finding as-is
		}
		try {
			await ctx.close();
		} catch {
			// The context went down with its browser; the session relaunches it.
		}
		if (!solo) continue;
		checked++;

		const reproduced = new Set(solo.findings.map(fingerprint));
		let localDemotions = 0;
		for (const f of suspect.findings) {
			if (f.severity !== 'error') continue;
			if (reproduced.has(fingerprint(f))) {
				f.reproduced = true;
				continue;
			}
			f.severity = 'info';
			f.reproduced = false;
			f.detail = `${f.detail} [not reproduced on a solo re-check: contention artifact]`;
			localDemotions++;
		}
		demoted += localDemotions;
		const left = suspect.findings.filter((f) => f.severity === 'error').length;
		process.stdout.write(
			`  ${left ? '🔴' : '✓ '} ${suspect.route} [${viewport}] ${left} confirmed, ${localDemotions} demoted\n`,
		);
	}
	return { checked, demoted, skipped };
}

// ── Worker pool ───────────────────────────────────────────────────────────────
// A dead browser or a context torn down with it is not a defect in the page
// being audited: every route after it would otherwise be reported as an
// `audit-crash` error against a page nobody ever loaded.
const DEAD_SESSION = /Target (page, context or browser|closed)|browser has been closed|Browser closed|has been closed/i;

async function runPool(pool, routes, viewport, onResult) {
	const queue = [...routes];
	const results = [];
	const worker = async () => {
		while (queue.length) {
			const route = queue.shift();
			let r = null;
			// One retry on a torn-down session, against a rebuilt context. A second
			// failure is reported, so a route that genuinely crashes the renderer
			// still surfaces instead of looping.
			for (let attempt = 0; attempt < 2; attempt++) {
				try {
					r = await auditRoute(await pool.context(), route, viewport);
					break;
				} catch (e) {
					if (attempt === 0 && DEAD_SESSION.test(e.message || '')) {
						await pool.recycle();
						continue;
					}
					r = {
						route,
						viewport,
						title: '',
						navStatus: null,
						findings: [{ type: 'audit-crash', severity: 'error', detail: e.message }],
					};
					break;
				}
			}
			results.push(r);
			onResult(r);
		}
	};
	await Promise.all(Array.from({ length: Math.min(CONCURRENCY, routes.length) }, worker));
	return results;
}

// ── Reporting ─────────────────────────────────────────────────────────────────
function dedupe(findings) {
	const seen = new Map();
	for (const f of findings) {
		const key = `${f.type}::${f.detail}`;
		if (!seen.has(key)) seen.set(key, { ...f, count: 1 });
		else seen.get(key).count++;
	}
	return [...seen.values()];
}

const SEVERITY_RANK = { error: 0, warn: 1, info: 2 };

function writeReport(allResults, meta) {
	mkdirSync(resolve(ROOT, 'reports'), { recursive: true });
	const stamp = new Date().toISOString().replace(/[:.]/g, '-');
	const jsonPath = resolve(ROOT, `reports/page-audit-${stamp}.json`);
	const mdPath = resolve(ROOT, `reports/page-audit-${stamp}.md`);

	// Group by route, merging viewports.
	const byRoute = new Map();
	for (const r of allResults) {
		if (!byRoute.has(r.route)) byRoute.set(r.route, { route: r.route, viewports: {}, findings: [] });
		const entry = byRoute.get(r.route);
		entry.viewports[r.viewport] = { title: r.title, navStatus: r.navStatus };
		if (r.screenshot) entry.screenshot = entry.screenshot || r.screenshot;
		for (const f of r.findings) entry.findings.push({ ...f, viewport: r.viewport });
	}

	const pages = [...byRoute.values()].map((p) => {
		const deduped = dedupe(p.findings).sort(
			(a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity],
		);
		const counts = { error: 0, warn: 0, info: 0 };
		for (const f of deduped) counts[f.severity] += f.count;
		return { ...p, findings: deduped, counts };
	});
	pages.sort((a, b) => b.counts.error - a.counts.error || b.counts.warn - a.counts.warn);

	const totals = pages.reduce(
		(t, p) => ({
			error: t.error + p.counts.error,
			warn: t.warn + p.counts.warn,
			info: t.info + p.counts.info,
		}),
		{ error: 0, warn: 0, info: 0 },
	);

	const report = { meta: { ...meta, generatedAt: stamp, totals }, pages };
	writeFileSync(jsonPath, JSON.stringify(report, null, 2));

	// Markdown
	const lines = [];
	lines.push(`# Page audit — ${meta.baseUrl}`);
	lines.push('');
	lines.push(`- Generated: ${new Date().toISOString()}`);
	lines.push(`- Auth: ${meta.authed ? 'authenticated session' : 'anonymous'}`);
	lines.push(`- Viewports: ${meta.viewports.join(', ')}`);
	lines.push(`- Routes audited: ${pages.length}`);
	lines.push(
		`- **Totals: ${totals.error} error · ${totals.warn} warn · ${totals.info} info**`,
	);
	if (meta.verification?.checked) {
		lines.push(
			`- Every error was re-checked solo: ${meta.verification.checked} route/viewport pair(s) re-run one at a time, ` +
				`${meta.verification.demoted} finding(s) demoted to info as parallel-run contention artifacts` +
				(meta.verification.skipped ? `, ${meta.verification.skipped} left unverified (past --reverify-cap)` : '') +
				'. Errors below reproduced on a page loaded by itself, so they are real.',
		);
	}
	if (meta.verification?.aborted) {
		lines.push(
			'- ⚠ The solo re-check did not finish (the browser session ended). Errors that were not' +
				' re-checked are reported exactly as the parallel sweep saw them, so some may be' +
				' contention artifacts. Re-run those routes with `--concurrency 1` before acting.',
		);
	}
	lines.push('');
	if (meta.discovered?.length) {
		lines.push('## Crawl-discovered routes (linked on the site, missing from data/pages.json)');
		lines.push('');
		lines.push('These were audited this run, but add them to the manifest so every future');
		lines.push('audit, the sitemap, and llms.txt see them:');
		lines.push('');
		for (const d of meta.discovered) lines.push(`- \`${d}\``);
		lines.push('');
	}
	if (meta.droppedDiscoveries?.length) {
		lines.push(
			`*Crawl sampled out ${meta.droppedDiscoveries.length} additional dynamic route(s) (families capped at 3): ${meta.droppedDiscoveries.slice(0, 15).map((d) => `\`${d}\``).join(', ')}${meta.droppedDiscoveries.length > 15 ? ', ...' : ''}*`,
		);
		lines.push('');
	}
	lines.push('## Pages by severity');
	lines.push('');
	lines.push('| Route | err | warn | info |');
	lines.push('| --- | --: | --: | --: |');
	for (const p of pages) {
		if (p.counts.error + p.counts.warn + p.counts.info === 0) continue;
		lines.push(`| \`${p.route}\` | ${p.counts.error} | ${p.counts.warn} | ${p.counts.info} |`);
	}
	const clean = pages.filter((p) => p.counts.error + p.counts.warn + p.counts.info === 0);
	if (clean.length) {
		lines.push('');
		lines.push(`✓ ${clean.length} route(s) clean: ${clean.map((p) => `\`${p.route}\``).join(', ')}`);
	}
	lines.push('');
	lines.push('## Detail');
	for (const p of pages) {
		if (p.counts.error + p.counts.warn + p.counts.info === 0) continue;
		lines.push('');
		lines.push(`### \`${p.route}\``);
		const navs = Object.entries(p.viewports)
			.map(([v, d]) => `${v}: HTTP ${d.navStatus ?? '?'}`)
			.join(' · ');
		lines.push(`*${navs}*`);
		if (p.screenshot) lines.push(`*screenshot: ${p.screenshot}*`);
		lines.push('');
		for (const f of p.findings) {
			const icon = f.severity === 'error' ? '🔴' : f.severity === 'warn' ? '🟡' : '⚪';
			const n = f.count > 1 ? ` ×${f.count}` : '';
			lines.push(`- ${icon} **${f.type}**${n}: ${f.detail}`);
		}
	}
	lines.push('');
	writeFileSync(mdPath, lines.join('\n'));

	return { jsonPath, mdPath, totals, pages };
}

// ── Browser session ───────────────────────────────────────────────────────────
// A full sweep drives hundreds of WebGL pages through one browser process for
// well over an hour, on a box that is often running other agents' builds beside
// it. When that process dies (the kernel reaps it, or a renderer takes the
// browser down with it), every later `newContext` throws
// "Target page, context or browser has been closed" and the run aborts with
// hundreds of already-collected results still in memory and no report on disk.
// The findings were never the problem, so a dead browser is replaced rather
// than allowed to end the sweep.
class BrowserSession {
	constructor() {
		this.browser = null;
		this.relaunches = 0;
	}

	// The sandbox flags are chromium-only; webkit and firefox reject unknown args.
	async #launch() {
		this.browser = await ENGINE.launch(
			ENGINE_NAME === 'chromium' ? { args: ['--no-sandbox', '--disable-dev-shm-usage'] } : {},
		);
		return this.browser;
	}

	async start() {
		return this.#launch();
	}

	// Playwright reports a dead process through isConnected(), but a browser can
	// also die between that check and the call, so the retry covers both.
	async newContext(opts) {
		for (let attempt = 0; ; attempt++) {
			if (!this.browser || !this.browser.isConnected()) {
				this.relaunches++;
				console.log(`  ⚠ browser process gone; relaunching (#${this.relaunches})`);
				await this.#launch();
			}
			try {
				return await this.browser.newContext(opts);
			} catch (err) {
				if (attempt >= 2) throw err;
				try {
					await this.browser.close();
				} catch {
					// Already gone. Nothing to close, and nothing that changes the retry.
				}
				this.browser = null;
			}
		}
	}

	async close() {
		if (!this.browser) return;
		try {
			await this.browser.close();
		} catch {
			// Closing a browser that already died is not a sweep failure.
		}
		this.browser = null;
	}
}

// One shared context per viewport pass, rebuilt on demand. The pool exists so
// the concurrent workers in runPool can agree on a single replacement instead
// of each opening its own after the same crash.
class ContextPool {
	constructor(session, opts, init) {
		this.session = session;
		this.opts = opts;
		this.init = init;
		this.ctx = null;
		this.pending = null;
		this.recycling = null;
	}

	async context() {
		if (this.ctx) return this.ctx;
		if (!this.pending) {
			this.pending = (async () => {
				try {
					const ctx = await this.session.newContext(this.opts);
					if (this.init) await ctx.addInitScript(this.init);
					this.ctx = ctx;
					return ctx;
				} finally {
					// Cleared on failure too: a rejected promise left in `pending`
					// would be handed to every remaining route, turning one bad
					// launch into a sweep of identical phantom crashes.
					this.pending = null;
				}
			})();
		}
		return this.pending;
	}

	// Drop the current context so the next `context()` builds a fresh one. Every
	// worker that hit the same dead session calls this at once, so a recycle
	// already in flight is awaited rather than started again: otherwise the
	// second caller would throw away the replacement the first just built.
	async recycle() {
		if (this.recycling) return this.recycling;
		this.recycling = (async () => {
			const dead = this.ctx;
			this.ctx = null;
			this.pending = null;
			if (dead) {
				try {
					await dead.close();
				} catch {
					// The context died with its browser; there is nothing left to close.
				}
			}
			this.recycling = null;
		})();
		return this.recycling;
	}

	async close() {
		const ctx = this.ctx;
		this.ctx = null;
		if (!ctx) return;
		try {
			await ctx.close();
		} catch {
			// Same as above: a context whose browser is gone needs no teardown.
		}
	}
}

// ── Main ──────────────────────────────────────────────────────────────────────
async function main() {
	if (DO_LOGIN) {
		await login();
		return;
	}

	const authed = existsSync(AUTH_STATE);
	const viewports = MOBILE_ONLY
		? ['mobile']
		: DESKTOP_ONLY
			? ['desktop']
			: ['desktop', 'mobile'];

	console.log(`Page audit → ${BASE_URL}`);
	console.log(`  auth: ${authed ? 'session from ' + AUTH_STATE.replace(ROOT + '/', '') : 'anonymous'}`);
	console.log(`  viewports: ${viewports.join(', ')}  ·  concurrency: ${CONCURRENCY}`);
	console.log(`  engine: ${ENGINE_NAME}`);

	const browser = new BrowserSession();
	await browser.start();
	const seedCtx = await browser.newContext(
		authed ? { storageState: AUTH_STATE } : {},
	);
	const dynamic = explicitRoutes.length ? [] : await seedDynamicRoutes(seedCtx, BASE_URL);
	await seedCtx.close();
	const routes = buildRouteList(dynamic);
	console.log(`  routes: ${routes.length}\n`);

	const allResults = [];
	const knownRoutes = new Set(routes);
	const discovered = [];
	let droppedDiscoveries = [];
	let firstViewport = true;
	for (const viewport of viewports) {
		const ctxOpts = {
			...viewportOptions(viewport),
			...(authed ? { storageState: AUTH_STATE } : {}),
			// Codespaces hostnames aren't in the R2 CORS allowlist; ignore HTTPS errors.
			ignoreHTTPSErrors: true,
		};
		const pool = new ContextPool(browser, ctxOpts, trackClickListeners);
		console.log(`── ${viewport} ──`);
		const onResult = (r) => {
			const e = r.findings.filter((f) => f.severity === 'error').length;
			const w = r.findings.filter((f) => f.severity === 'warn').length;
			const tag = e ? '🔴' : w ? '🟡' : '✓ ';
			process.stdout.write(`  ${tag} ${r.route} (${e}e/${w}w)\n`);
			allResults.push(r);
		};
		await runPool(pool, routes, viewport, onResult);
		// After the first pass, audit every crawl-discovered route the manifest
		// missed. They join `routes` so later viewports cover them too.
		if (firstViewport && !explicitRoutes.length) {
			const linkSet = new Set(allResults.flatMap((r) => r.links || []));
			const picked = pickDiscovered(linkSet, knownRoutes);
			droppedDiscoveries = picked.dropped;
			if (picked.audit.length) {
				console.log(
					`  ── crawl: ${picked.audit.length} linked route(s) missing from the manifest, auditing them too ──`,
				);
				for (const d of picked.audit) {
					routes.push(d);
					knownRoutes.add(d);
					discovered.push(d);
				}
				await runPool(pool, picked.audit, viewport, onResult);
			}
			if (picked.dropped.length) {
				console.log(
					`  ── crawl: ${picked.dropped.length} more discovered route(s) sampled out (dynamic families capped at 3) ──`,
				);
			}
			firstViewport = false;
		}
		await pool.close();
	}

	// Confirm every error against a solo re-check before reporting it.
	let verification = { checked: 0, demoted: 0, skipped: 0 };
	try {
		verification = await reverify(browser, allResults, viewports, authed);
	} catch (err) {
		// Hundreds of collected results are worth more than a perfect re-check.
		// Report what the sweep saw and say the pass did not finish.
		console.log(`  ⚠ re-verify failed: ${err.message.split('\n')[0]}`);
		verification.aborted = true;
	}
	await browser.close();

	const { jsonPath, mdPath, totals, pages } = writeReport(allResults, {
		baseUrl: BASE_URL,
		authed,
		viewports,
		discovered,
		droppedDiscoveries,
		verification,
	});

	console.log('\n── Summary ──');
	console.log(`  ${totals.error} error · ${totals.warn} warn · ${totals.info} info`);
	if (verification.checked) {
		console.log(
			`  (re-verified ${verification.checked} route/viewport pair(s); ${verification.demoted} finding(s) demoted as contention artifacts)`,
		);
	}
	const worst = pages.filter((p) => p.counts.error).slice(0, 10);
	if (worst.length) {
		console.log('  Pages with errors:');
		for (const p of worst) console.log(`    ${p.route}  (${p.counts.error} error)`);
	}
	console.log(`\n  Report: ${mdPath.replace(ROOT + '/', '')}`);
	console.log(`          ${jsonPath.replace(ROOT + '/', '')}`);

	if (STRICT && totals.error > 0) process.exit(1);
}

main().catch((e) => {
	console.error(e);
	process.exit(1);
});