@stacknyu/pi-glitch-lab 0.0.0-stage → 0.5.0

package/scripts/lib.mjs

@@ -0,0 +1,260 @@
+// Shared helpers for affordance_scan.mjs and journey_runner.mjs
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { createRequire } from "node:module";
+
+export function parseArgs(argv = process.argv.slice(2)) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) continue;
+    const k = a.slice(2);
+    const v = argv[i + 1];
+    if (v === undefined || v.startsWith("--")) out[k] = true;
+    else { out[k] = v; i++; }
+    if (["interact", "allow-writes", "probe-clicks", "all", "paint", "embed", "headed"].includes(k)) {
+      if (![true, "true", "false"].includes(out[k])) throw new Error(`--${k} must be true or false`);
+      out[k] = out[k] === true || out[k] === "true";
+    }
+  }
+  return out;
+}
+
+export async function loadPlaywright() {
+  try { return await import("playwright"); } catch {}
+  try {
+    const root = execSync("npm root -g", { encoding: "utf8" }).trim();
+    const req = createRequire(path.join(root, "noop.js"));
+    return req("playwright");
+  } catch {}
+  console.error("Playwright not found. Install: npm i -D playwright && npx playwright install chromium");
+  process.exit(1);
+}
+
+/** Launch Chromium; falls back to installed Google Chrome if Playwright's browser isn't downloaded. */
+export async function launchBrowser(chromium, args = {}) {
+  const opts = { headless: !args.headed };
+  const channel = args.channel || process.env.GLITCH_LAB_CHANNEL;
+  try {
+    return await chromium.launch(channel ? { ...opts, channel } : opts);
+  } catch (e) {
+    if (!channel) { try { return await chromium.launch({ ...opts, channel: "chrome" }); } catch {} }
+    throw new Error("Could not launch a browser. Run `npx playwright install chromium` in the package folder, or pass --channel chrome. " + String(e.message).split("\n")[0]);
+  }
+}
+
+export function loadConfig(p) {
+  if (!p || !fs.existsSync(p)) {
+    console.error(`Config not found: ${p}. Start from assets/matrix.example.json`);
+    process.exit(1);
+  }
+  return JSON.parse(fs.readFileSync(p, "utf8"));
+}
+
+export const VIEWPORTS = {
+  mobile: { viewport: { width: 390, height: 844 }, isMobile: true, hasTouch: true, deviceScaleFactor: 2 },
+  tablet: { viewport: { width: 820, height: 1180 }, isMobile: true, hasTouch: true },
+  desktop: { viewport: { width: 1440, height: 900 } },
+  android: { viewport: { width: 360, height: 800 }, isMobile: true, hasTouch: true, deviceScaleFactor: 3 },   // typical Indian mid-range Android
+  iphone: { viewport: { width: 390, height: 844 }, isMobile: true, hasTouch: true, deviceScaleFactor: 3 },
+  laptop: { viewport: { width: 1366, height: 768 } },                                                        // common budget laptop / Chromebook
+  "laptop-zoom125": { viewport: { width: 1093, height: 614 }, deviceScaleFactor: 1.25 },                     // 1366×768 at 125% browser zoom
+  "desktop-zoom150": { viewport: { width: 960, height: 600 }, deviceScaleFactor: 1.5 },                      // 1440×900 at 150% browser zoom
+};
+export const NETWORKS = {
+  fast: null,
+  fast3g: { offline: false, downloadThroughput: (1.6 * 1024 * 1024) / 8, uploadThroughput: (750 * 1024) / 8, latency: 150 },
+  slow3g: { offline: false, downloadThroughput: (500 * 1024) / 8, uploadThroughput: (500 * 1024) / 8, latency: 400 },
+};
+
+/**
+ * Resolve cells into full objects with merged settings.
+ * A cell without "partner" (or partner "direct") tests the platform directly, as a root user
+ * with no partner; it uses cfg.platform for name/url.
+ */
+export function resolveCells(cfg, cellArg, all) {
+  const cells = (cfg.cells || []).map((c) => ({ ...c, partner: c.partner || "direct" }));
+  const ids = cells.map((c) => `${c.persona}@${c.partner}`), slugs = cells.map((c) => `${c.persona}__${c.partner}`.replace(/[^a-z0-9_-]+/gi, "_"));
+  if (new Set(ids).size !== ids.length || new Set(slugs).size !== slugs.length) throw new Error("Cell identities/output slugs must be unique");
+  const key = (c) => `${c.persona}@${c.partner}`;
+  const want = cellArg && !String(cellArg).includes("@") ? `${cellArg}@direct` : cellArg;
+  const pick = all ? cells : cells.filter((c) => key(c) === want);
+  if (!pick.length) {
+    console.error(`No cell matches "${cellArg}". Available: ${cells.map(key).join(", ")}`);
+    process.exit(1);
+  }
+  return pick.map((c) => {
+    const screens = c.screens || [];
+    if (new Set(screens.map(slugify)).size !== screens.length) throw new Error("Screen output names collide; split into separate cells/runs");
+    const persona = cfg.personas?.[c.persona] || {};
+    const direct = c.partner === "direct";
+    const partner = direct ? { name: cfg.platform?.name || "", url: cfg.platform?.url, direct: true } : cfg.partners?.[c.partner] || {};
+    const base = (c.baseUrl || partner.url || cfg.platform?.url || cfg.baseUrl || "").replace(/\/$/, "");
+    return {
+      ...c,
+      id: key(c),
+      slug: `${c.persona}__${c.partner}`.replace(/[^a-z0-9_-]+/gi, "_"),
+      persona, partner, base,
+      viewport: c.viewport || persona.viewport || "desktop",
+      network: c.network || persona.network || "fast",
+      locale: c.locale || persona.locale,
+      timezone: c.timezone || persona.timezone,
+      login: c.login || (direct ? cfg.platform?.login : partner.login) || c.login,
+      unsafe: [...(cfg.unsafeWords || []), ...(partner.unsafeWords || [])],
+      mask: [...(cfg.mask || []), ...(c.mask || [])],
+    };
+  });
+}
+
+/** Find an element the way a user would: by visible text/role, label, placeholder, or selector. */
+export function locatorFor(page, spec, cell) {
+  if (typeof spec === "string") {
+    const t = tpl(spec, cell);
+    return page.getByRole("button", { name: t, exact: true })
+      .or(page.getByRole("link", { name: t, exact: true }))
+      .or(page.getByRole("tab", { name: t, exact: true }))
+      .or(page.getByRole("menuitem", { name: t, exact: true }));
+  }
+  if (spec.selector) return page.locator(spec.selector);
+  if (spec.role) return page.getByRole(spec.role, { name: tpl(spec.name, cell), exact: true });
+  if (spec.label) return page.getByLabel(tpl(spec.label, cell), { exact: true });
+  if (spec.placeholder) return page.getByPlaceholder(tpl(spec.placeholder, cell), { exact: true });
+  if (spec.text) return page.getByText(tpl(spec.text, cell), { exact: true });
+  throw new Error("Unknown target " + JSON.stringify(spec));
+}
+
+/** Fill {{partner.name}}, {{persona.name}} etc. */
+export function tpl(str, cell) {
+  if (typeof str !== "string") return str;
+  return str.replace(/\{\{\s*(partner|persona)\.(\w+)\s*\}\}/g, (_, o, k) => {
+    const value = cell[o]?.[k];
+    if (value === undefined || value === null || String(value).trim() === "") throw new Error(`Missing template value: ${o}.${k}`);
+    return value;
+  });
+}
+
+export async function newContext(browser, cell, args = {}) {
+  const opts = { ...(VIEWPORTS[cell.viewport] || VIEWPORTS.desktop), serviceWorkers: "block" };
+  if (cell.locale) opts.locale = cell.locale;
+  if (cell.timezone) opts.timezoneId = cell.timezone;
+  const context = await browser.newContext(opts);
+  context.setDefaultTimeout(10000);
+  context.setDefaultNavigationTimeout(30000);
+  await protectContext(context, cell, args);
+  return context;
+}
+
+export const UNSAFE = /delete|remove|pay|purchase|buy|billing|send|submit|logout|log.out|sign.out|upgrade|subscribe|invite|publish|deactivate|reset/i;
+export function requireInteraction(args, writes = false) {
+  if (args.interact !== true) throw new Error("Interaction requires --interact: authorize a disposable test environment first");
+  if (writes && args["allow-writes"] !== true) throw new Error("This action requires explicit --allow-writes authorization");
+}
+
+export async function protectContext(context, cell, args) {
+  if (args["allow-writes"]) requireInteraction(args);
+  const origins = new Set([new URL(cell.base).origin, ...(cell.allowedOrigins || []).map((u) => new URL(u).origin)]);
+  context._uxArgs = args;
+  context._uxBlocked = [];
+  await context.exposeBinding("__uxHistoryVisit", (_source, url) => { context._uxPageBudget?.urls.add(url); });
+  await context.route("**/*", async (route) => {
+    const req = route.request(), url = new URL(req.url());
+    const write = !["GET", "HEAD", "OPTIONS"].includes(req.method());
+    const budget = context._uxPageBudget;
+    if (req.isNavigationRequest() && budget) {
+      // Never evaluate in a frame paused for navigation: it waits for this route and deadlocks.
+      const prior = req.frame().url();
+      if (prior && prior !== "about:blank") budget.urls.add(prior);
+    }
+    const overBudget = req.isNavigationRequest() && budget && !budget.urls.has(req.url()) && budget.urls.size >= budget.limit;
+    if (overBudget) budget.hit = true;
+    const denied = overBudget || (req.isNavigationRequest() && !origins.has(url.origin)) ||
+      (write && (!args["allow-writes"] || !origins.has(url.origin))) ||
+      (!args["allow-writes"] && UNSAFE.test(url.pathname));
+    if (denied) {
+      context._uxBlocked.push({ method: req.method(), url: url.origin + url.pathname });
+      await route.abort("blockedbyclient");
+    } else if (req.isNavigationRequest() || write) {
+      if (req.isNavigationRequest() && budget) budget.urls.add(req.url());
+      // Route handlers do not re-check a browser redirect chain. Fail closed before following it.
+      try {
+        const response = await route.fetch({ maxRedirects: 0, timeout: 15000 });
+        if (response.status() >= 300 && response.status() < 400 && response.headers().location) {
+          context._uxBlocked.push({ method: req.method(), url: url.origin + url.pathname, reason: "HTTP redirect requires a direct target URL" });
+          await route.abort("blockedbyclient");
+        } else await route.fulfill({ response });
+      } catch (e) {
+        context._uxBlocked.push({ method: req.method(), url: url.origin + url.pathname, reason: e.message });
+        await route.abort("failed").catch(() => {});
+      }
+    } else await route.continue();
+  });
+  await context.routeWebSocket("**/*", (socket) => {
+    const url = new URL(socket.url()), origin = url.origin.replace(/^ws/, "http");
+    if (args["allow-writes"] === true && origins.has(origin)) socket.connectToServer();
+    else { context._uxBlocked.push({ method: "WEBSOCKET", url: origin + url.pathname }); socket.close(); }
+  });
+}
+
+export async function checkTarget(loc, cell, args, automatic = false) {
+  requireInteraction(args);
+  const target = await loc.evaluate((el) => ({ text: [el.textContent, el.getAttribute("aria-label"), el.getAttribute("href")].join(" "),
+    href: el.closest("a[href]")?.href, submit: el.matches('button:not([type]),button[type=submit],input[type=submit],input[type=image]') && !!el.closest("form") }));
+  if (target.href) {
+    const url = new URL(target.href);
+    if (![new URL(cell.base).origin, ...(cell.allowedOrigins || []).map((u) => new URL(u).origin)].includes(url.origin)) throw new Error("Destination origin is not allowed");
+    if (!["http:", "https:"].includes(url.protocol)) throw new Error("Non-web destination skipped");
+  }
+  const unsafe = UNSAFE.test(target.text) || (cell.unsafe || []).some((w) => target.text.toLowerCase().includes(w.toLowerCase()));
+  if ((target.submit || unsafe) && (automatic || !args["allow-writes"])) throw new Error("Potential write/destructive control skipped; use an explicitly authorized journey");
+}
+
+export function freshOutput(dir) {
+  fs.mkdirSync(path.dirname(path.resolve(dir)), { recursive: true });
+  fs.mkdirSync(dir); // never overwrite a prior run or baseline
+}
+
+export function bounded(value, fallback, max) {
+  const n = value === undefined ? fallback : Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > max) throw new Error(`Expected integer between 1 and ${max}`);
+  return n;
+}
+
+export async function throttle(context, page, cell) {
+  const n = NETWORKS[cell.network];
+  if (!n) return;
+  try {
+    const cdp = await context.newCDPSession(page);
+    await cdp.send("Network.enable");
+    await cdp.send("Network.emulateNetworkConditions", n);
+  } catch { /* non-chromium */ }
+}
+
+export async function login(context, cell) {
+  const l = cell.login;
+  if (!l) return;
+  requireInteraction(context._uxArgs || {}, true);
+  if (!l.authenticated && (!l.waitFor || l.waitFor === "/")) throw new Error("Login needs an authenticated selector or a specific waitFor pathname (not /)");
+  const page = await context.newPage();
+  const timeout = bounded(l.timeout, 15000, 30000);
+  await page.goto(cell.base + tpl(l.url, cell), { waitUntil: "domcontentloaded" });
+  for (const [sel, val] of Object.entries(l.fields || {})) {
+    const v = String(val).startsWith("env:") ? process.env[String(val).slice(4)] : String(val);
+    if (!v) throw new Error(`Missing login value for ${sel}`);
+    await page.fill(sel, v);
+  }
+  await page.click(l.submit || "button[type=submit]");
+  if (l.waitFor) await page.waitForURL((u) => u.origin === new URL(cell.base).origin && u.pathname === l.waitFor, { timeout });
+  if (l.authenticated) await page.locator(l.authenticated).waitFor({ state: "visible", timeout });
+  await page.close();
+}
+
+export function attachListeners(page, sink) {
+  page.on("console", (m) => { if (m.type() === "error") sink.console.push(m.text().slice(0, 300)); });
+  page.on("pageerror", (e) => sink.console.push("pageerror: " + e.message.slice(0, 300)));
+  page.on("requestfailed", (r) => sink.failed.push({ url: r.url().slice(0, 200), error: r.failure()?.errorText }));
+  page.on("response", (r) => { if (r.status() >= 400) sink.failed.push({ url: r.url().slice(0, 200), status: r.status() }); });
+}
+
+export const slugify = (s) => (s === "/" ? "home" : String(s).replace(/[^a-z0-9]+/gi, "_").replace(/^_|_$/g, "").slice(0, 60) || "page");
+export const ensureDir = (d) => (fs.mkdirSync(d, { recursive: true }), d);

package/scripts/report.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * report.mjs — one shareable HTML report from Glitch Lab runs, journeys, affordance scans and Claude's findings.
+ *
+ *   node report.mjs <run-dir> [--findings .ux/findings.json] [--out .ux/report/index.html] [--embed] [--title "..."]
+ *
+ * <run-dir> may contain any mix of: glitch lab cells (findings.json + summary.md), journey results
+ * (<cell>/journeys/<id>/result.json) and affordance scans (<cell>/affordance/*_affordance.json).
+ * --embed inlines images (one self-contained file to share).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "./lib.mjs";
+
+const argv = process.argv.slice(2);
+const runDir = path.resolve(argv.find((a) => !a.startsWith("--")) || ".ux");
+const args = parseArgs(argv);
+const out = path.resolve(args.out || path.join(runDir, "report.html"));
+const outDir = path.dirname(out);
+fs.mkdirSync(outDir, { recursive: true });
+const embed = !!args.embed;
+const human = args.findings && fs.existsSync(args.findings) ? JSON.parse(fs.readFileSync(args.findings, "utf8")) : {};
+
+const e = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+const walk = (dir, test, acc = []) => {
+  if (!fs.existsSync(dir)) return acc;
+  for (const n of fs.readdirSync(dir)) {
+    const p = path.join(dir, n); const st = fs.lstatSync(p);
+    if (st.isSymbolicLink()) continue;
+    if (st.isDirectory()) walk(p, test, acc); else if (test(p)) acc.push(p);
+  }
+  return acc.sort();
+};
+const img = (p, cls = "shot") => {
+  if (!p || !fs.existsSync(p)) return "";
+  const src = embed ? `data:image/png;base64,${fs.readFileSync(p).toString("base64")}` : path.relative(outDir, p);
+  return `<a href="${e(src)}" target="_blank" rel="noopener"><img class="${e(cls)}" loading="lazy" src="${e(src)}"></a>`;
+};
+const SEV = { S1: "#b91c1c", S2: "#c2410c", S3: "#a16207", S4: "#4b5563", high: "#b91c1c", medium: "#c2410c", low: "#4b5563" };
+const pill = (t) => `<span class="pill" style="background:${SEV[t] || "#555"}">${e(t)}</span>`;
+
+const P = [];
+P.push(`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'">
+<title>${e(human.title || args.title || "UX & glitch audit")}</title><style>
+:root{--bg:#fafaf9;--fg:#1c1917;--mut:#57534e;--card:#fff;--line:#e7e5e4}
+@media (prefers-color-scheme: dark){:root{--bg:#1c1917;--fg:#f5f5f4;--mut:#a8a29e;--card:#292524;--line:#44403c}}
+body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.55 system-ui,-apple-system,Segoe UI,Roboto,sans-serif}
+main{max-width:1200px;margin:0 auto;padding:28px 20px 80px}h1{margin:0 0 4px;font-size:28px}h2{margin:40px 0 12px;border-bottom:1px solid var(--line);padding-bottom:6px}
+.mut{color:var(--mut)}.card{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:16px;margin:12px 0}
+.pill{display:inline-block;padding:1px 8px;border-radius:99px;color:#fff;font-size:12px;font-weight:600;margin-right:6px;text-transform:uppercase}
+.grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(230px,1fr));gap:12px}
+.shot{width:100%;border:1px solid var(--line);border-radius:6px;background:#fff}.big{max-width:100%;border:1px solid var(--line);border-radius:6px;margin-top:8px;background:#fff}
+table{border-collapse:collapse;width:100%;font-size:14px}td,th{border-bottom:1px solid var(--line);padding:6px 8px;text-align:left;vertical-align:top}
+.wrap{overflow-x:auto}.ok{color:#15803d;font-weight:600}.bad{color:#b91c1c;font-weight:600}blockquote{margin:8px 0;padding:6px 12px;border-left:3px solid var(--line);color:var(--mut);font-style:italic}
+code{font-size:13px}</style></head><body><main>
+<h1>${e(human.title || args.title || "UX & glitch audit")}</h1><div class="mut">${e(human.subtitle || "")} · generated ${new Date().toISOString().slice(0, 10)}</div>`);
+if (human.summary) P.push(`<div class="card">${e(human.summary)}</div>`);
+
+if (human.scorecard?.length) {
+  const icon = { smooth: "✅ Smooth", friction: "⚠️ Friction", blocked: "❌ Blocked" };
+  P.push(`<h2>Persona × journey scorecard</h2><div class="wrap"><table><tr><th>Persona</th><th>Journey</th><th>Result</th><th>Issues</th></tr>`);
+  for (const r of human.scorecard) P.push(`<tr><td>${e(r.cell)}</td><td>${e(r.journey)}</td><td>${icon[r.result] || e(r.result)}</td><td>${e((r.issues || []).join(", "))}</td></tr>`);
+  P.push(`</table></div>`);
+}
+if (human.patterns?.length) {
+  P.push(`<h2>Patterns to fix first</h2>`);
+  for (const p of human.patterns) P.push(`<div class="card"><b>${e(p.title)}</b> <span class="mut">· ${e((p.findings || []).join(", "))}</span><div>${e(p.description)}</div><div><b>Recommendation:</b> ${e(p.recommendation)}</div></div>`);
+}
+if (human.findings?.length) {
+  P.push(`<h2>Findings</h2>`);
+  const order = { S1: 0, S2: 1, S3: 2, S4: 3 };
+  for (const f of [...human.findings].sort((a, b) => (order[a.severity] ?? 9) - (order[b.severity] ?? 9))) {
+    const shots = (f.screenshots || []).map((s) => img(path.isAbsolute(s) ? s : path.join(runDir, s), "big")).join("");
+    P.push(`<div class="card" id="${e(f.id)}">${pill(f.severity || "S3")}<b>${e(f.id)} · ${e(f.title)}</b> <span class="mut">· ${e(f.category)} · ${e((f.cells || []).join(", "))} · ${e(f.screen || "")}</span>
+${f.personaVoice ? `<blockquote>${e(f.personaVoice)}</blockquote>` : ""}<div>${e(f.observation || "")}</div>
+${f.evidence ? `<div><b>Evidence:</b> ${e(f.evidence)}</div>` : ""}<div><b>Recommendation:</b> ${e(f.recommendation || "")}</div>${shots}</div>`);
+  }
+}
+
+// Glitch Lab
+const glitchFiles = walk(runDir, (p) => path.basename(p) === "findings.json" && path.resolve(p) !== path.resolve(args.findings || "") && fs.existsSync(path.join(path.dirname(p), "summary.md")));
+if (glitchFiles.length) {
+  P.push(`<h2>Visual glitches (Glitch Lab)</h2><div class="mut">Detected with frame-by-frame capture, React render tracking, DOM and network sensors, repeated runs on a slowed CPU. Green in repaint frames = area the browser repainted.</div>`);
+  for (const gf of glitchFiles) {
+    const g = JSON.parse(fs.readFileSync(gf, "utf8")); const d = path.dirname(gf);
+    P.push(`<div class="card"><b>${e(g.cell)}</b> <span class="mut">· ${e(g.mode)} · ${g.repeat} runs · CPU ${g.cpu}× · ${e(g.viewport)} · React sensor ${g.meta?.react ? "on" : "off"}</span>`);
+    if (g.meta?.errors?.length) P.push(`<div class="bad">INCOMPLETE: ${e(g.meta.errors.join("; "))}</div>`);
+    for (const f of (g.findings || []).filter((x) => x.level !== "low")) {
+      P.push(`<div style="margin-top:14px">${pill(f.level)}<b>${e(f.id)} · ${e(f.what)}</b> <span class="mut">· ${e(f.seen)}${f.visibleBlink ? " · visible blink" : ""}</span>
+${f.note ? `<div class="mut">${e(f.note)}</div>` : ""}${f.why ? `<div>Why it rendered: <code>${e([].concat(f.why).join(", "))}</code></div>` : ""}
+${f.network?.length ? `<div>Right after: <code>${e(f.network.join("; "))}</code></div>` : ""}<div class="mut">Where: ${e((f.scenarios || []).slice(0, 5).join("; "))}</div>
+${(f.images || []).slice(0, 1).map((i) => img(path.join(d, i), "big")).join("")}${f.paintImage ? img(path.join(d, f.paintImage), "big") : ""}</div>`);
+    }
+    const low = (g.findings || []).filter((x) => x.level === "low").length;
+    if (low) P.push(`<div class="mut" style="margin-top:10px">${low} low-priority item(s) not shown.</div>`);
+    if (g.meta?.paint && fs.existsSync(g.meta.paint)) P.push(`<div class="mut">Paint-flashing video: <code>${e(g.meta.paint)}</code></div>`);
+    P.push(`</div>`);
+  }
+}
+
+// Journeys
+const journeys = walk(runDir, (p) => p.endsWith(`${path.sep}result.json`) && p.includes(`${path.sep}journeys${path.sep}`));
+if (journeys.length) {
+  P.push(`<h2>Journeys</h2>`);
+  for (const rp of journeys) {
+    const r = JSON.parse(fs.readFileSync(rp, "utf8")); const d = path.dirname(rp);
+    P.push(`<div class="card"><b>${e(r.cell)} — ${e(r.title || r.journey)}</b> ${r.passed ? '<span class="ok">PASS</span>' : '<span class="bad">FAIL</span>'} <span class="mut">· ${e(r.viewport)} · ${e(r.network)} · ${((r.totalMs || 0) / 1000).toFixed(1)}s</span>`);
+    if (r.regressions?.length) P.push(`<div class="bad">Regressions: ${e(r.regressions.map((g) => `${g.type} at step ${g.step ?? "-"}${g.error ? ` (${g.error})` : ""}`).join("; "))}</div>`);
+    P.push(`<div class="wrap"><table><tr><th>#</th><th>Step</th><th>Result</th><th>Time</th><th>Notes</th></tr>`);
+    for (const s of r.steps || []) {
+      let note = s.error || "";
+      if (s.response) note = `first output ${s.response.firstOutputMs} ms, complete ${s.response.completeMs} ms`;
+      if (s.visualDiff) note += ` · visual change ${(s.visualDiff.ratio * 100).toFixed(2)}%`;
+      const arg = typeof s.arg === "string" ? s.arg : JSON.stringify(s.arg);
+      P.push(`<tr><td>${s.i}</td><td>${e(s.kind)} ${e(String(arg).slice(0, 90))}</td><td>${s.skipped ? "skipped" : s.ok ? "✅" : "❌"}</td><td>${s.ms ?? ""} ms</td><td>${e(note)}</td></tr>`);
+    }
+    P.push(`</table></div><div class="grid" style="margin-top:10px">`);
+    for (const s of r.steps || []) if (s.shot) P.push(`<div><div class="mut">#${s.i} ${e(s.kind)}</div>${img(path.join(d, s.shot))}</div>`);
+    P.push(`</div></div>`);
+  }
+}
+
+// Affordance
+const scans = walk(runDir, (p) => p.endsWith("_affordance.json"));
+if (scans.length) {
+  P.push(`<h2>Visual affordance scans</h2><div class="mut">Green = real control · Red = looks clickable but isn't · Orange = clickable but doesn't look it · Purple = unlabeled icon · Yellow = small target</div>`);
+  for (const sp of scans) {
+    const s = JSON.parse(fs.readFileSync(sp, "utf8")); const c = s.counts || {};
+    const clicks = s.clicks || []; const dead = clicks.filter((x) => x.result === "no-observable-response"); const slow = clicks.filter((x) => x.slow);
+    P.push(`<div class="card"><b>${e(s.cell)} — ${e(s.screen)}</b> <span class="mut">· ${e(s.viewport)} · load ${s.loadMs} ms · fake ${(c.fake || 0) + (c["fake-icon"] || 0)} · hidden ${c.hidden || 0} · unlabeled ${c.unlabeled || 0} · small ${c.small || 0}${clicks.length ? ` · no observable response ${dead.length}/${clicks.length} · slow ${slow.length}` : ""}</span>
+${img(sp.replace("_affordance.json", "_annotated.png"), "big")}</div>`);
+    if (s.coverage) {
+      const coverage = s.coverage;
+      P.push(`<div class="card"><b>Interaction coverage — ${e(s.screen)}</b><div>${e(coverage.exercised)}/${e(coverage.discovered)} control-state pairs exercised across ${e(coverage.states.length)} states; ${e(coverage.actualClicks)} actual click attempts including ${e(coverage.replays?.length || 0)} replays. ${coverage.limited ? "LIMIT REACHED — incomplete exploration." : "Bounded exploration finished."}</div><div>${e(coverage.limitations)}</div><div>${e(JSON.stringify(coverage.counts))}</div><div class="wrap"><table><tr><th>State/control</th><th>Outcome</th><th>Notes</th><th>Evidence</th></tr>`);
+      for (const action of coverage.actions) P.push(`<tr><td>${e(action.state)} · ${e(action.text || action.selector)}</td><td>${e(action.result)}</td><td>${e(action.reason || action.errors?.join("; ") || "")}</td><td>${[action.before, action.after].filter(Boolean).map((f) => img(path.join(path.dirname(sp), f))).join("")}</td></tr>`);
+      P.push(`</table></div></div>`);
+    } else P.push(`<div class="mut">Observation only; no controls exercised.</div>`);
+    P.push(`<div class="mut">${e(s.limitations)} ${s.scrollTruncated ? "Scroll limit reached." : ""} ${s.horizontalOverflow ? "Horizontal overflow detected." : ""}</div>`);
+  }
+}
+P.push(`</main></body></html>`);
+fs.writeFileSync(out, P.join("\n"));
+console.log(`Wrote ${out}`);

package/scripts/sensors/dom_observer.mjs

@@ -0,0 +1,96 @@
+/** In-page DOM observer: remounts of DOM elements, text flaps, layout shifts, running animations. Installed before app scripts. */
+export function DOM_OBSERVER() {
+  if (window.__gl) return;
+  const G = (window.__gl = { events: [], shifts: [], anim: [] });
+  // hide the blinking text caret so it isn't reported as flicker
+  const hideCaret = () => { const st = document.createElement("style"); st.textContent = "*{caret-color:transparent!important}"; (document.head || document.documentElement).appendChild(st); };
+  if (document.head) hideCaret(); else document.addEventListener("DOMContentLoaded", hideCaret, { once: true });
+  const now = () => Math.round(performance.now());
+  const desc = (el) => {
+    if (!el || !el.tagName) return "?";
+    let s = el.tagName.toLowerCase();
+    if (el.id) s += "#" + el.id;
+    const tid = el.getAttribute("data-testid") || el.getAttribute("aria-label") || el.getAttribute("role");
+    if (tid) s += `[${tid}]`;
+    else if (typeof el.className === "string" && el.className.trim()) s += "." + el.className.trim().split(/\s+/).slice(0, 2).join(".");
+    const t = (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim().slice(0, 50);
+    return t ? `${s} "${t}"` : s;
+  };
+  const sig = (el) => el.tagName + "|" + (typeof el.className === "string" ? el.className : "") + "|" + (el.textContent || "").replace(/\s+/g, " ").trim().slice(0, 60);
+  const rect = (el) => { try { const r = el.getBoundingClientRect(); return { x: Math.round(r.left), y: Math.round(r.top), w: Math.round(r.width), h: Math.round(r.height) }; } catch { return null; } };
+  const removed = []; // {sig, t, desc, rect}
+  const lastRect = new WeakMap();
+  const textHist = new WeakMap();
+  const start = () => {
+    const mo = new MutationObserver((muts) => {
+      const t = now();
+      for (const m of muts) {
+        if (m.type === "childList") {
+          m.removedNodes.forEach((n) => {
+            if (n.nodeType !== 1) return;
+            const r = lastRect.get(n);
+            if (!r || r.w < 40 || r.h < 16) return;
+            removed.push({ sig: sig(n), t, desc: desc(n), rect: r });
+          });
+          m.addedNodes.forEach((n) => {
+            if (n.nodeType !== 1) return;
+            requestAnimationFrame(() => {
+              const r = rect(n); if (!r || r.w < 40 || r.h < 16) return;
+              lastRect.set(n, r);
+              n.querySelectorAll?.("*").forEach((c) => { const cr = rect(c); if (cr && cr.w >= 40 && cr.h >= 16) lastRect.set(c, cr); });
+              const s = sig(n);
+              const hit = removed.findLast?.((x) => x.sig === s && t - x.t < 1500);
+              if (hit) G.events.push({ type: "remount", t, desc: desc(n), rect: r, gapMs: t - hit.t });
+            });
+          });
+        }
+        const el = m.type === "characterData" ? m.target.parentElement : m.target.nodeType === 1 ? m.target : null;
+        if (el && (m.type === "characterData" || m.type === "childList")) {
+          const txt = el.innerText || "";
+          if (txt.length > 300) continue;
+          const h = textHist.get(el) || [];
+          if (!h.length) {
+            // seed with the value before this mutation, so the first change is visible in history
+            let old = null;
+            if (m.type === "characterData") old = m.oldValue;
+            else if ([...m.removedNodes].every((n) => n.nodeType === 3) && [...m.addedNodes].every((n) => n.nodeType === 3) && m.removedNodes.length)
+              old = txt.replace([...m.addedNodes].map((n) => n.textContent).join(""), [...m.removedNodes].map((n) => n.textContent).join(""));
+            if (old !== null && old !== txt) h.push({ v: old.slice(0, 300), t: t - 1 });
+          }
+          const changed = !h.length || h[h.length - 1].v !== txt;
+          if (changed) h.push({ v: txt, t });
+          while (h.length > 6) h.shift();
+          textHist.set(el, h);
+          const n = h.length;
+          if (changed && n >= 3 && h[n - 1].v === h[n - 3].v && h[n - 2].v !== h[n - 1].v && t - h[n - 2].t < 2000 && (h[n - 1].v || h[n - 2].v))
+            G.events.push({ type: "text-flap", t, visibleMs: t - h[n - 2].t, desc: desc(el), rect: rect(el), sequence: [h[n - 3].v, h[n - 2].v, h[n - 1].v].map((s) => s.slice(0, 60)) });
+        }
+      }
+    });
+    mo.observe(document.documentElement, { childList: true, subtree: true, characterData: true, characterDataOldValue: true });
+    // seed rects for existing elements periodically so removals can be sized
+    const seed = () => {
+      document.querySelectorAll("body *").forEach((c) => { const r = rect(c); if (r && r.w >= 40 && r.h >= 16) lastRect.set(c, r); });
+      // remember where intentional animations run (spinners, typing dots, pulses)
+      try {
+        for (const a of document.getAnimations()) {
+          const el = a.effect?.target; if (!el || a.playState !== "running") continue;
+          const r = rect(el); if (!r || !r.w) continue;
+          G.anim.push({ ...r, t: now(), desc: desc(el) });
+          if (G.anim.length > 1000) G.anim.shift();
+        }
+      } catch {}
+    };
+    setInterval(seed, 250);
+    try {
+      new PerformanceObserver((l) => {
+        for (const e of l.getEntries()) {
+          if (e.hadRecentInput) continue;
+          G.shifts.push({ t: Math.round(e.startTime), value: +e.value.toFixed(4),
+            sources: (e.sources || []).map((s) => ({ desc: desc(s.node), from: s.previousRect && { x: s.previousRect.x, y: s.previousRect.y, w: s.previousRect.width, h: s.previousRect.height }, to: s.currentRect && { x: s.currentRect.x, y: s.currentRect.y, w: s.currentRect.width, h: s.currentRect.height } })) });
+        }
+      }).observe({ type: "layout-shift", buffered: true });
+    } catch {}
+  };
+  if (document.documentElement) start(); else document.addEventListener("readystatechange", start, { once: true });
+}