scenescout 1.0.0 → 1.2.0

package/dist/engine/browser.js

@@ -1,18 +1,20 @@
-import { chromium } from "playwright";
+import { chromium, firefox, webkit } from "playwright";
 import fs from "node:fs";
 import path from "node:path";
 import { elementKey, fingerprintState, isNonPageRoute, normalizePath } from "./fingerprint.js";
 import { AUTH_LOSS_PREFIX, MemoryStore } from "./memory.js";
 import { AuthLossTracker } from "./authloss.js";
-import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues } from "./collector.js";
+import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, } from "./collector.js";
 import { OracleMonitor, formatViolations } from "./oracles.js";
 import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js";
 import { formatJourney, measureJourney } from "./journey.js";
+import { defaultEngine, focusAdvanceKey, REMOVE_SHARED_WORKER_SCRIPT, serviceWorkerPolicy, sharedWorkersAllowed } from "../browsers.js";
+import { revealedLines } from "./hover.js";
 import { explainLaunchFailure, isMissingBrowser } from "./launch.js";
 import { ACTION_TIMEOUT_MS, performScroll, probeFocusIndicators, probeOverlays, scrollContainer } from "./probes.js";
 import { BROWSER_MARKER, reapOrphanBrowsers } from "./reaper.js";
 import { planUploadOptions, resolveDiskUpload } from "./uploads.js";
-import { AUTH_FLOW_RE, destructiveRefusal, isDestructive, isDestructiveWire } from "./policy.js";
+import { destructiveRefusal, isDestructive, isDestructiveWire, allowsWrite, isAuthExempt } from "./policy.js";
 import { scanProject } from "../scan.js";
 import { analyzeDesign, DESIGN_COLLECT_SCRIPT } from "./design.js";
 import { acceptMatches, generatedUpload } from "./fixtures.js";
@@ -125,7 +127,8 @@ export class BrowserEngine {
     authLoss = new AuthLossTracker();
     /** UI-label blocking applies only in read-only mode (safe-write enforces at the network layer instead). */
     get readOnly() {
-        return this.mode === "read-only";
+        // observe is read-only and then some: every UI-level refusal applies to it too.
+        return this.mode === "read-only" || this.mode === "observe";
     }
     /** Append to the shared action log, stamped with THIS session so per-session
      *  reads (journey paths) can separate concurrent roles' interleaved actions. */
@@ -134,6 +137,14 @@ export class BrowserEngine {
     }
     /** Requests blocked by the write policy since the last action (timestamped for attribution). */
     blockedRequests = [];
+    /**
+     * WebSockets this session's pages opened. The write policy works on HTTP
+     * requests; frames sent over a socket are not inspected. In observe mode that
+     * is a hole in "nothing leaves the page", so it is said out loud rather than
+     * left for the reader to discover.
+     */
+    openSockets = new Set();
+    socketsWarned = false;
     /** When the current action began — requests recorded before this are late arrivals from a previous action. */
     actionStartedAt = 0;
     /**
@@ -219,6 +230,8 @@ export class BrowserEngine {
     }
     /** Whether the browser window is visible — headed hover results carry a physical-cursor caveat. */
     headed = false;
+    /** The browser this engine launched; reported by attach so a finding can say where it was seen. */
+    engineName = "chromium";
     /** Non-GET requests fired since the last action — surfaces silent state mutation in read-only runs (timestamped for attribution). */
     mutationRequests = [];
     /**
@@ -284,11 +297,15 @@ export class BrowserEngine {
             this.knownRoutes = [];
         }
         try {
-            this.browser = await this.launchWithRecovery(opts.headed ?? false);
+            this.engineName = opts.browser ?? defaultEngine(process.env);
+            this.browser = await this.launchWithRecovery(this.engineName, opts.headed ?? false);
             this.context = await this.browser.newContext({
                 storageState: opts.storageStatePath,
                 viewport: opts.viewport ?? { width: 1280, height: 900 },
+                serviceWorkers: serviceWorkerPolicy(this.engineName),
             });
+            if (!sharedWorkersAllowed(this.mode))
+                await this.context.addInitScript(REMOVE_SHARED_WORKER_SCRIPT);
             this.page = await this.context.newPage();
         }
         catch (err) {
@@ -299,6 +316,13 @@ export class BrowserEngine {
         // Label-based read-only blocking can't catch every mutation (an innocuous
         // "Add to Cart" fires a POST). Track non-GET traffic so actions that
         // changed server state are at least REPORTED in read-only runs.
+        this.openSockets.clear();
+        this.socketsWarned = false;
+        const watchSockets = (p) => void p.on("websocket", (ws) => this.openSockets.add(ws.url().slice(0, 120)));
+        // The first page already exists by now; later ones (popups) arrive as events.
+        if (this.page)
+            watchSockets(this.page);
+        this.context.on("page", watchSockets);
         this.context.on("request", (req) => {
             const type = req.resourceType();
             if (type === "xhr" || type === "fetch")
@@ -321,6 +345,9 @@ export class BrowserEngine {
             // here let a REFUSED destructive POST mark the route as mutated — a form
             // that was never submitted reading as tested, in read-only mode where by
             // definition nothing is.
+            // Same test the route handler uses: in observe only an exempt auth request goes out.
+            if (this.mode === "observe" && !isAuthExempt(this.mode, method, pathnameOf(req.url()), isDestructiveWire(pathnameOf(req.url()), req.postData())))
+                return;
             if (this.readOnly && isDestructiveWire(pathnameOf(req.url()), req.postData()))
                 return;
             const pageUrl = this.page?.url();
@@ -342,10 +369,11 @@ export class BrowserEngine {
                     return route.continue();
                 const url = req.url();
                 const pathname = pathnameOf(url);
-                // Auth/session flows (login, refresh, logout) must work in every mode.
-                if (AUTH_FLOW_RE.test(pathname) && method === "POST")
-                    return route.continue();
                 const destructiveWire = isDestructiveWire(pathname, req.postData());
+                // Auth/session flows must work in every mode — but never a destructive
+                // one, and in observe only the requests a login itself needs.
+                if (isAuthExempt(this.mode, method, pathname, destructiveWire))
+                    return route.continue();
                 let owned = this.isOwnedResource(pathname);
                 // A single UI action commonly fires create-then-immediately-save
                 // (POST gets an id, PUT saves content under it) faster than the
@@ -362,7 +390,7 @@ export class BrowserEngine {
                 }
                 // POST: creation/RPC passes unless it smells destructive and isn't ours.
                 // PUT/PATCH/DELETE: only in safe-write, only on our own resources.
-                const allow = method === "POST" ? !destructiveWire || owned : this.mode === "safe-write" && owned;
+                const allow = allowsWrite(this.mode, method, destructiveWire, owned);
                 if (allow) {
                     // Ownership tracking (safe-write): register the creation-tracking
                     // task BEFORE the POST goes out. Registering from a context
@@ -441,6 +469,8 @@ export class BrowserEngine {
                 `Continuing now tests a logged-out app.`
             : "";
         return (`Attached to ${this.page.url()} (mode=${this.mode}` +
+            `${this.engineName === "chromium" ? "" : `, browser=${this.engineName}, service workers blocked because their requests cannot be intercepted here`}` +
+            `${focusAdvanceKey(this.engineName, process.platform) === "Tab" ? "" : `, keyboard: Tab stops only at text fields in this browser — press Alt+Tab to reach buttons and links`}` +
             `${opts.storageStatePath ? `, auth=${opts.storageStatePath}` : ""}). ` +
             `Memory: ${this.memory.dir}.${this.memory.loadWarning ? ` WARNING: ${this.memory.loadWarning}` : ""}` +
             `${this.memory.legacyDirNote ? ` ${this.memory.legacyDirNote}` : ""}` +
@@ -668,6 +698,7 @@ export class BrowserEngine {
         const geometry = geometryIssues(elements, page.viewportSize() ?? { width: 1280, height: 900 });
         geometry.push(...(await probeOverlays(page)));
         const hiddenFileInputs = await this.hiddenFileInputs(page);
+        const brokenImages = brokenImageIssues((await page.evaluate(BROKEN_IMAGES_SCRIPT).catch(() => null)) ?? { images: [], total: 0 }, url);
         const cov = memory.coverage();
         const unvisited = this.unvisitedKnownRoutes();
         const title = await page.title();
@@ -677,10 +708,12 @@ export class BrowserEngine {
             `\n` +
             body +
             (geometry.length > 0 ? `\nGEOMETRY issues:\n` + geometry.map((g) => `  ⚠ ${g}`).join("\n") : "") +
+            (brokenImages.length > 0 ? `\nBROKEN IMAGES:\n` + brokenImages.map((b) => `  ⚠ ${b}`).join("\n") : "") +
             (hiddenFileInputs.length > 0
                 ? `\nFILE INPUTS not listed above (hidden behind a styled control — a user never sees the input itself): ${hiddenFileInputs.join("; ")}. ` +
                     `scout_upload {ref} on the control that opens one, or scout_upload {} when it is the page's only file input.`
                 : "") +
+            this.socketNotice() +
             formatViolations(this.oracles.drain()) +
             (elements.length === 0 ? "\n⚠ DEAD END: no interactable elements found on this page." : ""));
     }
@@ -732,7 +765,7 @@ export class BrowserEngine {
         if (el.role === "textbox" || el.role === "file")
             return null;
         if (el.destructive || isDestructive(liveLabel)) {
-            return destructiveRefusal(liveLabel || el.name || el.testid || el.ref);
+            return destructiveRefusal(liveLabel || el.name || el.testid || el.ref, this.mode);
         }
         return null;
     }
@@ -741,13 +774,22 @@ export class BrowserEngine {
         await this.settle();
         let url = page.url();
         if (url !== "about:blank" && !this.isSameOrigin(url)) {
-            // A click carried us off the app's origin — bounce back and say so.
+            // Either a click carried us off the app's origin, or the write policy
+            // aborted a NAVIGATION (a native form post) and the browser is showing
+            // its error page. The second is the tester's own doing and must say so:
+            // reported as an off-origin bounce, it hid the block, and the caller then
+            // read the unchanged URL as "the app silently discarded the data".
+            const policyAbortedNavigation = url.startsWith("chrome-error://") && this.blockedRequests.length > 0;
             this.logAction({ action, target, url });
-            this.logAction({ action: "origin-fence:bounced", target: url.slice(0, 200), url });
+            this.logAction({ action: policyAbortedNavigation ? "write-policy:navigation-blocked" : "origin-fence:bounced", target: url.slice(0, 200), url });
             await page.goBack({ waitUntil: "domcontentloaded", timeout: 10000 }).catch(() => { });
             url = page.url();
             this.refs.clear();
-            return (`OK: ${action} ${target}\nNavigated off-origin and was bounced back to ${url}. Exploration is fenced to ${this.baseUrl}.` +
+            const blocked = this.drainBlocked();
+            return ((policyAbortedNavigation
+                ? `OK: ${action} ${target}\nThe page tried to navigate with a request the write policy blocked, so the browser showed an error page; returned to ${url}.`
+                : `OK: ${action} ${target}\nNavigated off-origin and was bounced back to ${url}. Exploration is fenced to ${this.baseUrl}.`) +
+                blocked +
                 formatViolations(this.oracles.drain()));
         }
         this.logAction({ action, target, url });
@@ -821,9 +863,20 @@ export class BrowserEngine {
         this.blockedRequests = [];
         return (`\n🛡 WRITE-POLICY blocked (${this.mode}): ${list}${extra}. ` +
             `This is the tester's safety policy, NOT an app bug — do not file a finding for the resulting error UI. ` +
-            (this.mode === "read-only"
-                ? `Re-attach with mode="safe-write" to test create/edit flows, or "destructive" (user-approved disposable env only).`
-                : `In safe-write, updates/deletes are only allowed on resources this session created (${this.createdResources.length} so far).`));
+            (this.mode === "observe"
+                ? `observe mode blocks every request that is not a GET, so no form submission reaches the server. Re-attach with mode="read-only" ONLY if the user confirms that ordinary form submissions are acceptable on this target.`
+                : this.mode === "read-only"
+                    ? `Re-attach with mode="safe-write" to test create/edit flows, or "destructive" (user-approved disposable env only).`
+                    : `In safe-write, updates/deletes are only allowed on resources this session created (${this.createdResources.length} so far).`));
+    }
+    /** Once per session, in observe mode only: say that socket frames are outside the policy. */
+    socketNotice() {
+        if (this.mode !== "observe" || this.socketsWarned || this.openSockets.size === 0)
+            return "";
+        this.socketsWarned = true;
+        return (`\n⚠ OBSERVE LIMIT: this app holds an open WebSocket (${[...this.openSockets].slice(0, 2).join(", ")}). ` +
+            `The write policy blocks HTTP requests; frames sent over a socket are NOT inspected. ` +
+            `Do not perform actions that send data over it (chat messages, live edits, presence) — look, do not type, in socket-driven widgets — and say so in your summary.`);
     }
     /** xhr/fetch requests seen this session — lets clicks detect silent no-op submits. */
     xhrCount = 0;
@@ -851,7 +904,7 @@ export class BrowserEngine {
             .join("; ");
         const extra = fresh.length > 5 ? ` (+${fresh.length - 5} more)` : "";
         return this.readOnly
-            ? `\n⚠ READ-ONLY notice: this action fired state-changing requests — server state may have mutated despite read-only mode: ${list}${extra}. Consider whether this flow should be avoided or the environment confirmed disposable.`
+            ? `\n⚠ READ-ONLY notice: this action fired state-changing requests — server state may have mutated despite ${this.mode} mode: ${list}${extra}. Consider whether this flow should be avoided or the environment confirmed disposable.`
             : `\n(state-changing requests: ${list}${extra})`;
     }
     /**
@@ -934,7 +987,10 @@ export class BrowserEngine {
         const forcedNote = forced
             ? `\nℹ NOTE: the strict click timed out waiting for this element to be the stable, unobstructed top hit at its coordinates, so a forced click was used instead (which still landed — this succeeded). Something is likely rendered on top of it (an icon, a decorative layer, an animating wrapper) or it delegates via a label; cross-check against any GEOMETRY overlap on this element before treating that as a real bug.`
             : "";
-        if (submitLike && this.xhrCount === xhrBefore && page.url() === this.snapshotUrl) {
+        // Not when the write policy blocked the submission: a native form POST or a
+        // beacon is not counted as xhr/fetch, so an aborted one looks exactly like
+        // "fired nothing" — and the note would blame the app for the tool's block.
+        if (submitLike && this.xhrCount === xhrBefore && this.lastActionBlocked === 0 && page.url() === this.snapshotUrl) {
             return (result +
                 `\nℹ NOTE: this submit-style click fired ZERO network requests and no navigation — if the UI showed success, the data may have been silently discarded (worth verifying; category: other/silent-failure).` +
                 forcedNote);
@@ -1033,7 +1089,7 @@ export class BrowserEngine {
                     .catch(() => ""));
                 if (isDestructive(submitLabel)) {
                     this.logAction({ action: "type:enter-refused", target: submitLabel, url: page.url() });
-                    return `Filled ${el.role} "${el.name}" but did NOT press Enter. ` + destructiveRefusal(submitLabel);
+                    return `Filled ${el.role} "${el.name}" but did NOT press Enter. ` + destructiveRefusal(submitLabel, this.mode);
                 }
             }
             await locator.press("Enter", { timeout: ACTION_TIMEOUT_MS });
@@ -1232,16 +1288,7 @@ export class BrowserEngine {
         const bodyAfter = (await page.evaluate(`document.body ? document.body.innerText : ""`).catch(() => null));
         if (bodyAfter === null)
             return { revealed: [], fallbackUsed: false };
-        const beforeLines = new Set(bodyBefore
-            .split("\n")
-            .map((l) => l.trim())
-            .filter(Boolean));
-        revealed = bodyAfter
-            .split("\n")
-            .map((l) => l.trim())
-            .filter((l) => l && !beforeLines.has(l))
-            .slice(0, 5)
-            .map((l) => l.slice(0, 300));
+        revealed = revealedLines(bodyBefore, bodyAfter);
         return { revealed, fallbackUsed: revealed.length > 0 };
     }
     /** Pre-hover baselines: overlay texts, body text, and whether the page is already churning on its own. */
@@ -1307,7 +1354,7 @@ export class BrowserEngine {
                 .catch(() => ""));
             if (isDestructive(value) || isDestructive(optionLabel)) {
                 this.logAction({ action: "select:refused", target: optionLabel || value, url: page.url() });
-                return destructiveRefusal(optionLabel || value);
+                return destructiveRefusal(optionLabel || value, this.mode);
             }
         }
         await page.locator(`xpath=${el.xpath}`).selectOption(value, { timeout: ACTION_TIMEOUT_MS });
@@ -1329,7 +1376,7 @@ export class BrowserEngine {
             .catch(() => "");
         if (typeof focusedLabel === "string" && isDestructive(focusedLabel)) {
             this.logAction({ action: "press:refused", target: focusedLabel, url: page.url() });
-            return destructiveRefusal(focusedLabel);
+            return destructiveRefusal(focusedLabel, this.mode);
         }
         return null;
     }
@@ -1689,7 +1736,7 @@ export class BrowserEngine {
                     const label = await liveLabel(loc);
                     preLabel = label;
                     if (this.readOnly && (step.action === "click" || step.action === "select" || step.action === "upload") && isDestructive(label, step.value)) {
-                        transcript.push(`${desc} → ${destructiveRefusal(label || step.target)}`);
+                        transcript.push(`${desc} → ${destructiveRefusal(label || step.target, this.mode)}`);
                         break;
                     }
                     if (step.action === "click")
@@ -1711,7 +1758,7 @@ export class BrowserEngine {
                                 const submit = loc.locator("xpath=ancestor::form[1]").locator('[type="submit"], button:not([type="button"]):not([type="reset"])').first();
                                 const submitLabel = (await submit.textContent({ timeout: 1000 }).catch(() => "")) ?? "";
                                 if (isDestructive(submitLabel)) {
-                                    transcript.push(`${desc} → filled, Enter withheld: ${destructiveRefusal(submitLabel.trim())}`);
+                                    transcript.push(`${desc} → filled, Enter withheld: ${destructiveRefusal(submitLabel.trim(), this.mode)}`);
                                     break;
                                 }
                             }
@@ -1878,15 +1925,18 @@ export class BrowserEngine {
      * On the first failure or timeout, reap orphaned Playwright processes and
      * try once more before giving up with a diagnosable error.
      */
-    async launchWithRecovery(headed) {
+    async launchWithRecovery(engine, headed) {
+        const types = { chromium, firefox, webkit };
         const attempt = async () => {
             // The marker is what makes reapOrphanBrowsers safe to run at startup:
             // it appears in the child's command line, so the sweep can tell a browser
             // WE leaked from one belonging to somebody else's Playwright run.
             // `--enable-features` takes arbitrary names and ignores unknown ones.
-            const launch = chromium.launch({
+            // It is a Chromium switch: Firefox and WebKit are launched without it,
+            // so a leaked one of those is not reaped and has to be closed by hand.
+            const launch = types[engine].launch({
                 headless: !headed,
-                args: [`--enable-features=${BROWSER_MARKER}`],
+                args: engine === "chromium" ? [`--enable-features=${BROWSER_MARKER}`] : [],
             });
             let timer;
             try {
@@ -1913,13 +1963,13 @@ export class BrowserEngine {
             const firstMessage = firstErr instanceof Error ? firstErr.message : String(firstErr);
             // A browser that was never downloaded will not appear on a second try.
             if (isMissingBrowser(firstMessage))
-                throw new Error(explainLaunchFailure(firstMessage, 0));
+                throw new Error(explainLaunchFailure(firstMessage, 0, { engine, headed }));
             const reaped = reapOrphanBrowsers();
             try {
                 return await attempt();
             }
             catch {
-                throw new Error(explainLaunchFailure(firstMessage, reaped));
+                throw new Error(explainLaunchFailure(firstMessage, reaped, { engine, headed }));
             }
         }
     }

package/dist/engine/collector.js

@@ -18,6 +18,14 @@ export const VISIBLE_SRC = `(el) => {
     const style = window.getComputedStyle(el);
     return style.visibility !== "hidden" && style.display !== "none";
   }`;
+/**
+ * Anything that plausibly presents as a modal/dialog panel. Deliberately wider
+ * than the ARIA set: a hand-rolled role-less modal must still count as "an
+ * overlay is up", or the scroll-lock oracle files a false leaked-lock finding
+ * against every healthy modal that locks the page behind it.
+ */
+export const DIALOG_LIKE_SEL = '[role="dialog"], [role="alertdialog"], dialog[open], [aria-modal="true"], [class*="modal" i], [class*="dialog" i]';
+// Declared above the collector script because that script interpolates it.
 /**
  * Page-side interactable collector. Shipped as a STRING, not a function:
  * loader transforms (tsx/vitest esbuild hooks inject a `__name` helper) break
@@ -61,6 +69,10 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
       if (named) return named.replace(/\\s+/g, " ").slice(0, 80);
     }
     const tag = el.tagName.toLowerCase();
+    // An image's name is its alt text. Without this an <img> read as
+    // "(unnamed)" even when it was labelled, and a missing alt looked the same
+    // as a present one.
+    if (tag === "img") return (el.getAttribute("alt") || "").trim().slice(0, 80);
     if (tag === "input" || tag === "textarea") {
       const id = el.getAttribute("id");
       if (id) {
@@ -119,6 +131,75 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
     }
     return { layer, chrome };
   };
+  // A pinned control (inside position:fixed/sticky chrome) whose centre is
+  // owned by ANOTHER piece of pinned chrome. Two pieces of chrome overlapping
+  // is usually intended layering, which is why the box-overlap oracle skips
+  // that pair — but boxes cannot tell which one is on top. A hit test can: if
+  // the point at the control's centre belongs to a different pinned element,
+  // a click aimed at the control lands on that element instead.
+  // Deliberately narrow, to stay quiet on intended layering:
+  //  - only interactive controls, and only while their centre is in the viewport;
+  //  - the control must be pinned with NO scrollable pane anywhere above it, or
+  //    scrolling that pane would simply bring it out from under;
+  //  - dialogs, menus, consent banners, toasts and anything covering half the
+  //    viewport are overlays, not chrome.
+  const INTERACTIVE_ROLES = ["button", "link", "textbox", "combobox", "checkbox", "radio", "switch", "tab", "menuitem", "file"];
+  const isScroller = (n) => {
+    const cs = window.getComputedStyle(n);
+    return /(auto|scroll)/.test(cs.overflowY + cs.overflowX) && (n.scrollHeight > n.clientHeight + 1 || n.scrollWidth > n.clientWidth + 1);
+  };
+  /** Nearest fixed/sticky ancestor-or-self. */
+  const pinnedRootOf = (node) => {
+    for (let n = node; n && n !== document.documentElement; n = n.parentElement) {
+      const pos = window.getComputedStyle(n).position;
+      if (pos === "fixed" || pos === "sticky") return n;
+    }
+    return null;
+  };
+  /**
+   * Is there a scrollable pane anywhere between this node and the document?
+   * Checked over the WHOLE chain, above the pinned root as well as below it: a
+   * sticky first-column cell inside a scrolling grid is pinned within that
+   * grid, and scrolling the grid brings it out from under the sticky header.
+   * position:fixed escapes every ancestor's scrolling, so the walk stops there.
+   */
+  const insideScrollablePane = (node) => {
+    for (let n = node; n && n !== document.body && n !== document.documentElement; n = n.parentElement) {
+      if (n !== node && isScroller(n)) return true;
+      if (window.getComputedStyle(n).position === "fixed") return false;
+    }
+    return false;
+  };
+  // Pinned things that are overlays by nature, not layout: consent banners sit
+  // over everything until dismissed, toasts are gone in seconds. A click they
+  // intercept is real but it is not an app defect, and the consent case would
+  // otherwise fire on the first snapshot of nearly every site.
+  const TRANSIENT_SEL = '[role="alert"], [role="status"], [aria-live], [class*="toast" i], [class*="snackbar" i], [class*="cookie" i], [class*="consent" i], [id*="cookie" i], [id*="consent" i]';
+  const describe = (node) => {
+    const tid = node.getAttribute("data-testid");
+    if (tid) return "[" + tid + "]";
+    const text = (node.innerText || node.textContent || "").trim().replace(/\\s+/g, " ").slice(0, 40);
+    return "<" + node.tagName.toLowerCase() + ">" + (text ? ' "' + text + '"' : "");
+  };
+  const coveredByPinnedChrome = (el, rect, role) => {
+    if (INTERACTIVE_ROLES.indexOf(role) === -1) return null;
+    const cx = rect.left + rect.width / 2, cy = rect.top + rect.height / 2;
+    if (cx < 0 || cy < 0 || cx >= window.innerWidth || cy >= window.innerHeight) return null;
+    const ownRoot = pinnedRootOf(el);
+    if (!ownRoot || insideScrollablePane(el)) return null;
+    const top = document.elementFromPoint(cx, cy);
+    if (!top || top === el || el.contains(top) || top.contains(el)) return null;
+    const coverRoot = pinnedRootOf(top);
+    if (!coverRoot || coverRoot === ownRoot || coverRoot.contains(ownRoot) || ownRoot.contains(coverRoot)) return null;
+    // A dialog's fixed wrapper often carries no role or class itself; the
+    // role="dialog" is on a child. Look both ways.
+    const OVERLAY_SEL = '${DIALOG_LIKE_SEL}, ' + TRANSIENT_SEL + ', [role="menu"], [role="listbox"], [role="tooltip"]';
+    if (coverRoot.closest(OVERLAY_SEL) || coverRoot.querySelector(OVERLAY_SEL) || top.closest(OVERLAY_SEL)) return null;
+    const cr = coverRoot.getBoundingClientRect();
+    if (cr.width * cr.height > window.innerWidth * window.innerHeight * 0.5) return null;
+    return describe(coverRoot);
+  };
+
   for (const el of Array.from(document.querySelectorAll(selector))) {
     if (seen.has(el) || !visible(el)) continue;
     seen.add(el);
@@ -136,6 +217,7 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
           // Its own role routes it to scout_upload instead.
           : inputType === "file" ? "file"
           : "textbox")
+        : tag === "img" ? "image"
         : "generic");
     const rect = el.getBoundingClientRect();
     // Below-the-fold is reachable (scroll); clipped INSIDE an overflow-hidden
@@ -171,6 +253,7 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
       }
     }
     out.push({
+      coveredBy: coveredByPinnedChrome(el, rect, role),
       tag,
       role,
       name: accessibleName(el),
@@ -193,13 +276,6 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
   }
   return out;
 })()`;
-/**
- * Anything that plausibly presents as a modal/dialog panel. Deliberately wider
- * than the ARIA set: a hand-rolled role-less modal must still count as "an
- * overlay is up", or the scroll-lock oracle files a false leaked-lock finding
- * against every healthy modal that locks the page behind it.
- */
-export const DIALOG_LIKE_SEL = '[role="dialog"], [role="alertdialog"], dialog[open], [aria-modal="true"], [class*="modal" i], [class*="dialog" i]';
 /**
  * Deterministic geometry oracles — the checks people reach for screenshots to
  * do, computed from layout boxes instead: interactables rendered fully outside
@@ -231,6 +307,20 @@ export function geometryIssues(elements, viewport) {
     if (clippedTotal > 3) {
         issues.push(`…and ${clippedTotal - 3} more controls clipped inside overflow-hidden ancestors`);
     }
+    // Pinned controls sitting underneath other pinned chrome (hit-tested in the
+    // page; see coveredByPinnedChrome). Reported before the box overlaps because
+    // an unclickable Save button outranks two badges touching.
+    let coveredTotal = 0;
+    for (const el of elements) {
+        if (!el.coveredBy)
+            continue;
+        coveredTotal += 1;
+        if (coveredTotal <= 3) {
+            issues.push(`${el.ref} ${el.role} "${el.name}" is COVERED by pinned chrome ${el.coveredBy} at this scroll position — a click aimed at it lands on that element instead`);
+        }
+    }
+    if (coveredTotal > 3)
+        issues.push(`…and ${coveredTotal - 3} more pinned controls covered by other pinned chrome`);
     const overlapArea = (a, b) => {
         const w = Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x);
         const h = Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y);
@@ -264,3 +354,54 @@ export function geometryIssues(elements, viewport) {
     }
     return issues;
 }
+/**
+ * Images that failed to load, read from the DOM rather than from the network.
+ *
+ * A 404 on an image already shows up as an HTTP violation, but a broken image
+ * is not always a failed request: a 200 that returns an HTML error page, a
+ * truncated upload, a wrong content type or a blocked cross-origin file all
+ * respond successfully and still render as the browser's broken-image icon.
+ * `complete` with no intrinsic size is what "the browser gave up" looks like.
+ * SVGs are skipped: one without intrinsic dimensions reports 0×0 while
+ * rendering correctly.
+ */
+export const BROKEN_IMAGES_SCRIPT = `(() => {
+  const images = [];
+  let total = 0;
+  for (const img of Array.from(document.images)) {
+    const src = img.currentSrc || img.getAttribute("src") || "";
+    if (!src || src.indexOf("data:") === 0 || /\\.svg(\\?|#|$)/i.test(src)) continue;
+    if (!img.complete || img.naturalWidth > 0 || img.naturalHeight > 0) continue;
+    // Visible means it occupies space. The box test is what catches an image
+    // inside a display:none ANCESTOR (a closed modal, an inactive tab): display
+    // is not inherited, so the image's own computed style still says "inline".
+    // It also drops tracking pixels, whose endpoint answers 204 by design.
+    const r = img.getBoundingClientRect();
+    if (r.width <= 2 || r.height <= 2) continue;
+    const cs = window.getComputedStyle(img);
+    if (cs.display === "none" || cs.visibility === "hidden") continue;
+    total += 1;
+    if (images.length < 20) images.push({ alt: (img.getAttribute("alt") || "").trim().slice(0, 80), src: src.slice(0, 160), testid: img.getAttribute("data-testid") });
+  }
+  return { images, total };
+})()`;
+/** Snapshot lines for images that failed to load. The origin is dropped when it is the page's own, to keep the line short. */
+export function brokenImageIssues(scan, pageUrl) {
+    let origin = "";
+    try {
+        origin = new URL(pageUrl).origin;
+    }
+    catch {
+        /* an unparseable page URL just means the full src is shown */
+    }
+    // Only a real origin match: "http://x" is also a prefix of "http://x.other.test/a.png".
+    const short = (src) => (origin && (src === origin || src.startsWith(`${origin}/`)) ? src.slice(origin.length) || "/" : src);
+    const lines = scan.images.slice(0, 5).map((img) => {
+        const name = img.alt ? `"${img.alt}"` : "(no alt text)";
+        return `image ${name}${img.testid ? ` [testid=${img.testid}]` : ""} FAILED TO LOAD — ${short(img.src)}`;
+    });
+    const total = Math.max(scan.total, scan.images.length);
+    if (total > 5)
+        lines.push(`…and ${total - 5} more images that failed to load`);
+    return lines;
+}

package/dist/engine/hover.js

@@ -0,0 +1,42 @@
+/**
+ * The page-text fallback for hover: which text is new after the pointer moved.
+ *
+ * Pure, so the rule can be table-tested. The browser side only supplies the
+ * two `innerText` readings.
+ */
+const squash = (s) => s.replace(/\s+/g, " ").trim();
+/** How many times `needle` occurs in `haystack`, overlaps not counted. */
+function occurrences(haystack, needle) {
+    let n = 0;
+    for (let at = haystack.indexOf(needle); at >= 0; at = haystack.indexOf(needle, at + needle.length))
+        n++;
+    return n;
+}
+/**
+ * Lines present after the hover whose text was not on the page before it.
+ *
+ * Comparing line by line is not enough. When something that was showing goes
+ * away — the previous hover's tooltip closing as the pointer leaves it — the
+ * text around it can re-flow onto a line of its own, and that line is "new"
+ * only as a line: every word of it was already visible. How text re-flows
+ * differs between browsers. So a line counts as revealed when its text occurs
+ * MORE often after the hover than before: text that only moved occurs as often
+ * as it did, while a tooltip reading "Delete" on a page that already says
+ * "Delete account" occurs once more and is still reported.
+ */
+export function revealedLines(bodyBefore, bodyAfter, limit = 5) {
+    const beforeText = squash(bodyBefore);
+    const afterText = squash(bodyAfter);
+    const seen = new Set();
+    return bodyAfter
+        .split("\n")
+        .map(squash)
+        .filter((l) => {
+        if (!l || seen.has(l))
+            return false;
+        seen.add(l);
+        return occurrences(afterText, l) > occurrences(beforeText, l);
+    })
+        .slice(0, limit)
+        .map((l) => l.slice(0, 300));
+}

package/dist/engine/launch.js

@@ -2,21 +2,28 @@
  * Turning a failed browser launch into something the person can act on.
  *
  * For anyone who installed from npm and never ran the setup step, the first
- * attach fails because Chromium was never downloaded — and Playwright reports
+ * attach fails because the browser was never downloaded — and Playwright reports
  * that as a multi-line box of text with a path in it. That is the single most
  * likely first-run failure, so it gets one plain instruction instead.
  */
+import { APPROX_DISK_MB, launchTarget } from "../browsers.js";
 /** Playwright's wording when the browser binary is not on disk. */
 const MISSING_BROWSER_RE = /Executable doesn't exist|playwright install|browserType\.launch:.*(not found|ENOENT)/i;
 export function isMissingBrowser(message) {
     return MISSING_BROWSER_RE.test(message);
 }
 /** The error text for a launch that failed. `reaped` is how many orphaned browsers were cleaned up between attempts. */
-export function explainLaunchFailure(message, reaped) {
+export function explainLaunchFailure(message, reaped, need = { engine: "chromium", headed: false }) {
     if (isMissingBrowser(message)) {
-        return (`Chromium has not been downloaded yet (one-time, ~150 MB). Run this once, then attach again:\n` +
-            `  npx -y scenescout install --browser-only\n` +
-            `(from a clone: npm run setup). On Linux, if system libraries are missing: npx playwright install --with-deps chromium`);
+        const target = launchTarget(need.engine, need.headed);
+        // Someone who installed only the headless shell did run install, so say what is different about a headed run.
+        const why = target === "chromium" && need.headed
+            ? "A headed run needs the full Chromium browser, which has not been downloaded (the headless shell alone cannot open a window)"
+            : `The ${target} build has not been downloaded yet`;
+        return (`${why} (one-time, about ${APPROX_DISK_MB[target]} MB on disk). Run this once, then attach again:\n` +
+            `  npx -y scenescout install --browser-only --browsers ${target}\n` +
+            `(from a clone: node dist/cli.js install --browser-only --browsers ${target}). ` +
+            `On Linux, if system libraries are missing: npx playwright install --with-deps ${target}`);
     }
     const firstLine = message.split("\n")[0];
     return (`browser launch failed twice (${firstLine})` +