scenescout 1.0.0 → 1.1.0

package/dist/engine/browser.js

@@ -4,7 +4,7 @@ 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";
@@ -12,7 +12,7 @@ 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 +125,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 +135,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;
     /**
@@ -299,6 +308,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 +337,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 +361,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 +382,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
@@ -668,6 +688,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 +698,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 +755,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 +764,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 +853,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 +894,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 +977,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 +1079,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 });
@@ -1307,7 +1353,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 +1375,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 +1735,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 +1757,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;
                                 }
                             }

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/policy.js

@@ -77,8 +77,60 @@ export const AUTH_FLOW_RE = /\/(auth|login|logout|signin|sign-in|signup|sign-up|
 export function isDestructive(...labels) {
     return labels.some((label) => typeof label === "string" && label.length > 0 && DESTRUCTIVE_PATTERNS.some((re) => re.test(label)));
 }
-export function destructiveRefusal(label) {
-    return (`REFUSED by read-only policy: "${label}" matches a destructive-action pattern. ` +
-        `This run is read-only; do not attempt this element again. If destructive flows must be tested, ` +
+export function destructiveRefusal(label, mode = "read-only") {
+    return (`REFUSED by ${mode} policy: "${label}" matches a destructive-action pattern. ` +
+        `This run is ${mode}; do not attempt this element again. If destructive flows must be tested, ` +
         `the user has to re-attach with mode="destructive" against a disposable/seeded environment.`);
 }
+export const WRITE_MODES = ["observe", "read-only", "safe-write", "destructive"];
+/**
+ * May this non-GET request leave the page? Auth-flow requests are let through
+ * before this is asked. `owned` means the request addresses a record this run
+ * created (always false outside safe-write, where nothing is tracked).
+ */
+/**
+ * In observe mode, the only auth requests let through are the ones a session
+ * needs in order to exist: logging in, logging out, refreshing a token. Whole
+ * path SEGMENTS, never substrings — `/users/login-history/clear` and
+ * `/api/tokens` (mint an API token) are not logins — and `session(s)` only as
+ * the last segment, where a POST means "log in", not "act on session 123".
+ */
+const OBSERVE_AUTH_SEGMENT_RE = /^(login|log-in|signin|sign-in|logout|log-out|signout|sign-out|refresh|token|oauth|oauth2|sso|callback|authorize|authenticate)$/i;
+/**
+ * Is this request an auth flow that must work even though the mode would
+ * otherwise block it?
+ *
+ * Never for a destructive-looking request, in any mode: the exemption used to
+ * be tested first, so `POST /api/session/123/delete` went through in read-only
+ * because its path contains "session".
+ *
+ * In observe mode the exemption is much narrower than elsewhere. Signing up,
+ * changing or resetting a password, verifying an email and creating a user all
+ * change data on the target, and observe promises that nothing is created.
+ */
+export function isAuthExempt(mode, method, pathname, destructiveWire) {
+    if (method !== "POST" || destructiveWire)
+        return false;
+    if (mode !== "observe")
+        return AUTH_FLOW_RE.test(pathname);
+    const segments = pathname.split("/").filter(Boolean);
+    if (segments.length === 0)
+        return false;
+    const last = segments[segments.length - 1];
+    if (/^sessions?$/i.test(last))
+        return true;
+    // The matching segment must be at, or next to, the end: /auth/token/refresh, /oauth/token, /login.
+    return (segments.slice(-2).some((seg) => OBSERVE_AUTH_SEGMENT_RE.test(seg)) &&
+        !/^(users?|accounts?|members?|password|signup|sign-up|register|verify|invite|invitations?)$/i.test(last));
+}
+export function allowsWrite(mode, method, destructiveWire, owned) {
+    if (mode === "destructive")
+        return true;
+    if (mode === "observe")
+        return false;
+    // POST: creation/RPC passes unless it looks destructive and is not ours.
+    if (method === "POST")
+        return !destructiveWire || owned;
+    // PUT/PATCH/DELETE: only in safe-write, only on this run's own records.
+    return mode === "safe-write" && owned;
+}

package/dist/engine/report.js

@@ -289,7 +289,12 @@ export function computeGaps(memory, extras) {
     // and let a mutation anywhere in a wizard clear its sibling steps.
     const { unsubmitted } = classifyFilledStates(memory, facts);
     if (unsubmitted.length > 0) {
-        gaps.push(`${unsubmitted.length} route(s) had a form filled but NEVER submitted (no state-changing request left the page): ${unsubmitted.slice(0, 8).join(", ")}${unsubmitted.length > 8 ? " …" : ""}`);
+        gaps.push(`${unsubmitted.length} route(s) had a form filled but NEVER submitted (no state-changing request left the page): ${unsubmitted.slice(0, 8).join(", ")}${unsubmitted.length > 8 ? " …" : ""}` +
+            // In observe mode this is the mode working, not the run falling short —
+            // but it is still untested surface, so it stays in the ledger, explained.
+            (extras?.mode === "observe"
+                ? ` — expected in observe mode, which blocks every form submission by design; what the server does with these forms is untested. Cover them in read-only mode against an environment where creating records is acceptable.`
+                : ""));
     }
     const journeyTotal = Object.values(facts).reduce((a, f) => a + (f.journeysCompleted ?? 0), 0);
     if (journeyTotal === 0) {

package/dist/installer.js

@@ -243,24 +243,36 @@ export function parseRegistration(listing) {
     const field = (name) => new RegExp(`^[ \\t]*${name}:[ \\t]*(\\S.*?)[ \\t]*$`, "m").exec(listing)?.[1] ?? null;
     return { command: field("Command"), serverPath: field("Args") };
 }
+/**
+ * The command that repairs a setup, for THIS kind of install. A source checkout
+ * has `npm run setup`; someone who installed from npm has no such script, and
+ * telling them to run it sends them looking for a package.json they never had.
+ */
+export function repairCommands(packageRoot) {
+    const isCheckout = fs.existsSync(path.join(packageRoot, "tsconfig.json")) && fs.existsSync(path.join(packageRoot, "src"));
+    return isCheckout
+        ? { setup: "npm run setup", build: "npm run build" }
+        : { setup: "npx -y scenescout install", build: "npx -y scenescout@latest install   (the installed package is incomplete; fetch it again)" };
+}
 /** Everything a working setup needs, each with the command that repairs it. */
 export function diagnose(opts) {
     const checks = [];
+    const repair = repairCommands(opts.packageRoot);
     const major = Number(opts.nodeVersion.replace(/^v/, "").split(".")[0]);
     checks.push({ name: "node >= 20", ok: major >= 20, detail: opts.nodeVersion, fix: "install Node 20 or newer" });
     const server = path.join(opts.packageRoot, "dist", "mcp-server.js");
-    checks.push({ name: "engine built", ok: fs.existsSync(server), detail: server, fix: "npm run build" });
+    checks.push({ name: "engine built", ok: fs.existsSync(server), detail: server, fix: repair.build });
     const chromiumOk = !!opts.chromiumPath && fs.existsSync(opts.chromiumPath);
     checks.push({
         name: "chromium downloaded",
         ok: chromiumOk,
         detail: opts.chromiumPath ?? "playwright could not name a browser path",
-        fix: "npm run setup   (or: npx playwright install chromium)",
+        fix: `${repair.setup}   (or: npx playwright install chromium)`,
     });
     if (opts.scope === "engine")
         return checks;
     const skill = path.join(opts.claudeDir, "skills", SKILL_NAME, "SKILL.md");
-    checks.push({ name: "skill installed", ok: fs.existsSync(skill), detail: skill, fix: "npm run setup" });
+    checks.push({ name: "skill installed", ok: fs.existsSync(skill), detail: skill, fix: repair.setup });
     const got = opts.run("claude", ["mcp", "get", MCP_NAME]);
     if (got.missing) {
         checks.push({
@@ -273,7 +285,7 @@ export function diagnose(opts) {
     else {
         const listing = got.stdout + got.stderr;
         if (got.status !== 0) {
-            checks.push({ name: "MCP server registered", ok: false, detail: "no server named scenescout", fix: "npm run setup" });
+            checks.push({ name: "MCP server registered", ok: false, detail: "no server named scenescout", fix: repair.setup });
         }
         else {
             const { command, serverPath } = parseRegistration(listing);
@@ -289,12 +301,12 @@ export function diagnose(opts) {
                     name: "MCP server registered",
                     ok: absolute,
                     detail: absolute ? `via ${command} ${serverPath}` : `registered with a bare \`${command}\` command, which Claude Code may not find on its PATH`,
-                    fix: "scenescout install",
+                    fix: repair.setup,
                 });
             }
             else if (!samePath(serverPath, server)) {
                 // The usual aftermath of moving or deleting a checkout.
-                checks.push({ name: "MCP server registered", ok: false, detail: `registered, but pointing at ${serverPath} — not this install`, fix: "npm run setup" });
+                checks.push({ name: "MCP server registered", ok: false, detail: `registered, but pointing at ${serverPath} — not this install`, fix: repair.setup });
             }
             else if (command !== null && !path.isAbsolute(command)) {
                 // A bare "node" resolves in your shell and then fails inside Claude
@@ -303,7 +315,7 @@ export function diagnose(opts) {
                     name: "MCP server registered",
                     ok: false,
                     detail: `registered with a bare \`${command}\` command, which Claude Code may not find on its PATH`,
-                    fix: "npm run setup",
+                    fix: repair.setup,
                 });
             }
             else {

package/dist/mcp-server.js

@@ -179,13 +179,13 @@ server.registerTool("scout_scan", {
     }
 }));
 server.registerTool("scout_attach", {
-    description: "Launch a browser and attach to a running web app. Write policy is enforced at the NETWORK layer: mode='read-only' (default) blocks destructive-labeled elements AND all PUT/PATCH/DELETE + destructive POSTs; mode='safe-write' allows creating data and permits updates/deletes ONLY on resources this session created (use when the user wants create/edit flows tested); mode='destructive' allows everything — ONLY when the user explicitly confirmed a disposable/seeded environment. Pass a Playwright storage-state JSON to explore as an authenticated role. Pass `session` to keep MULTIPLE roles alive at once (one browser each, genuinely concurrent) for collaboration testing — target each directly with every tool's `session` param, or use scout_session to set which one is the default; coverage and findings merge into one project memory.",
+    description: "Launch a browser and attach to a running web app. Write policy is enforced at the NETWORK layer: mode='observe' blocks EVERY request that is not a GET (login and token refresh excepted) — choose it for a target that holds real data, where even an ordinary form submission would create a record; mode='read-only' (default) blocks destructive-labeled elements AND all PUT/PATCH/DELETE + destructive POSTs, but lets ordinary form POSTs through; mode='safe-write' allows creating data and permits updates/deletes ONLY on resources this session created (use when the user wants create/edit flows tested); mode='destructive' allows everything — ONLY when the user explicitly confirmed a disposable/seeded environment. Pass a Playwright storage-state JSON to explore as an authenticated role. Pass `session` to keep MULTIPLE roles alive at once (one browser each, genuinely concurrent) for collaboration testing — target each directly with every tool's `session` param, or use scout_session to set which one is the default; coverage and findings merge into one project memory.",
     inputSchema: {
         url: z.string().describe("Base URL of the running app, e.g. http://localhost:3000"),
         projectPath: z.string().describe("Absolute path to the project (memory + report live in .scenescout/ here)"),
         storageStatePath: z.string().optional().describe("Optional Playwright storage-state JSON path for authenticated exploration"),
         mode: z
-            .enum(["read-only", "safe-write", "destructive"])
+            .enum(["observe", "read-only", "safe-write", "destructive"])
             .default("read-only")
             .describe("Write policy (see tool description). Never choose 'destructive' yourself — user opt-in only."),
         headed: z.boolean().default(false).describe("Show the browser window"),
@@ -563,7 +563,7 @@ server.registerTool("scout_note", {
     }
 }));
 server.registerTool("scout_screenshot", {
-    description: "Take a JPEG screenshot of the current viewport. LAST RESORT: geometry issues are in scout_snapshot and style/contrast/spacing issues are in scout_design_audit — use a screenshot only for pixel-native content (broken images, canvas, visual gestalt) that computed data cannot capture.",
+    description: "Take a JPEG screenshot of the current viewport. LAST RESORT: geometry issues are in scout_snapshot and style/contrast/spacing issues are in scout_design_audit — images that failed to load are listed in scout_snapshot under BROKEN IMAGES — use a screenshot only for pixel-native content (a canvas, visual gestalt) that computed data cannot capture.",
     inputSchema: { session: sessionParam },
 }, serializedPerSession("scout_screenshot", async (_args, session) => {
     try {
@@ -702,9 +702,13 @@ server.registerTool("scout_report", {
             routesTotal: all.length,
             designAudits: eng.designAuditCount,
             unvisitedRoutes: unvisited,
+            mode: eng.mode,
         });
         if (lvl === "extensive" && gapList.length > 0) {
             gates.push(`Level 'extensive' claims completeness, so it refuses while the GAP LEDGER is non-empty:\n` +
+                (eng.mode === "observe"
+                    ? `(observe mode blocks every form submission, so the unsubmitted-forms gap cannot be closed in this mode: report at level 'medium', which discloses it.)\n`
+                    : "") +
                 gapList.map((g) => `  ⚠ ${g}`).join("\n") +
                 `\nClose the gaps (or report at level 'medium', which discloses them instead).`);
         }
@@ -718,6 +722,7 @@ server.registerTool("scout_report", {
             designAudits: eng.designAuditCount,
             createdResources: eng.createdResources,
             unvisitedRoutes: unvisited,
+            mode: eng.mode,
             policyAttributed: eng.oracleLog.policyAttributed,
         });
         void p;