scenescout 3.8.0 → 3.10.0

package/dist/engine/browser.js

@@ -7,7 +7,7 @@ import { normalizeTask } from "./task.js";
 import { CLAIM_SCAN_SCRIPT, findContradictions } from "./claims.js";
 import { describeInjection, newInjections, probeQueries, probeScript, probeShape, rememberProbe } from "./injection.js";
 import { AuthLossTracker } from "./authloss.js";
-import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, frameLines, hasVisibleFrame, displayName, missingName, } from "./collector.js";
+import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, frameLines, hasVisibleFrame, frameElementKey, frameLabel, masksForeignName, MASKED_NAME, capForeignName, stripForeignHref, frameToPageRect, displayName, missingName, placeholderOnly, placeholderEvidence, describeControl, labelFlag, } from "./collector.js";
 import { OracleMonitor, formatViolations } from "./oracles.js";
 import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js";
 import { formatJourney, measureJourney } from "./journey.js";
@@ -16,11 +16,12 @@ import { keepWatchingUrl, normalizePace, SETTLE_TICK_MS, shouldKeepWaiting } fro
 import { buildRequestScript, formatReplay, replaySignature, requestHeaders, resolveMethod, resolveRequestUrl, toReplayResult } from "./request.js";
 import { defaultEngine, focusAdvanceKey, REMOVE_SHARED_WORKER_SCRIPT, screencastSupport, serviceWorkerPolicy, sharedWorkersAllowed, } from "../browsers.js";
 import { revealedLines } from "./hover.js";
+import { FORMS_INVENTORY_SCRIPT, FORM_PROBE_BODY, formProbeExpression, formIdentity, formStatus, FORMS_READ_FAILED, FORMS_SUBMIT_UNMATCHED, isEmptySubmit, sameControl, isNavigationTeardown, submits, tracksForm, } from "./forms.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 { answersWithRefusal, destructiveRefusal, isDestructive, isDestructiveWire, allowsWrite, policyRefusal, foreignFrameOrigin, foreignWrite, withForeignFrameSandbox, offAppPageWrite, EmbedMoveTracker, sandboxedRedirectPage, allowsForeignWriteOnSignIn, isAuthExempt, } from "./policy.js";
+import { answersWithRefusal, destructiveRefusal, isDestructive, isDestructiveWire, allowsWrite, policyRefusal, foreignFrameOrigin, foreignWrite, withForeignFrameSandbox, offAppPageWrite, embedOfRequest, hostileForEmbed, trustedEmbedOrigins, MAX_TRUSTED_EMBEDS, trustsForeignWrite, embedProbeRefusal, EmbedMoveTracker, sandboxedRedirectPage, allowsForeignWriteOnSignIn, isAuthExempt, } from "./policy.js";
 import { scanProject } from "../scan.js";
 import { analyzeDesign, DESIGN_COLLECT_SCRIPT } from "./design.js";
 import { acceptMatches, generatedUpload } from "./fixtures.js";
@@ -77,8 +78,27 @@ function requestSource(req) {
 }
 /** The `why` of a top-window navigation refused as a possible frame escape; the notice words it on its own. */
 const ESCAPE_REFUSAL = "a possible frame escape";
+/** The most frames a snapshot reads controls from. */
+const MAX_READ_FRAMES = 10;
 /** How long a snapshot waits for its frames' elements to answer. */
 const FRAME_READ_MS = 1500;
+/** The coverage key of the page's own element at this xpath (never one in a frame: its xpath names a node in another document). */
+function keyAtXpath(elements, xpath) {
+    return elements.find((el) => !el.frame && el.xpath === xpath)?.key ?? null;
+}
+/** The page's own element at the probe's submit xpath, when it really is that control (forms.ts sameControl). */
+function submitControlIn(elements, probe) {
+    const el = elements.find((e) => !e.frame && e.xpath === probe.submit);
+    return el && sameControl(el, probe) ? el : null;
+}
+/** Page-side: the form an element belongs to, and what its fields hold now (forms.ts). */
+const probeFormOf = new Function("node", FORM_PROBE_BODY);
+/**
+ * How long a form read may take: the inventory on every collect, the probe
+ * before a submit-capable action. One pass over document.forms takes a few
+ * milliseconds; this only stops a wedged page stalling the action.
+ */
+const FORM_READ_MS = 1000;
 /** In-page XPath lookup fragment for string-expression evaluates. */
 function xpathLookup(xpath) {
     return `document.evaluate(${JSON.stringify(xpath)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue`;
@@ -180,6 +200,9 @@ export class BrowserEngine {
     projectDirNote = "";
     memory = null;
     mode = "read-only";
+    /** Origins named as trusted embeds (policy.ts trustsEmbedWrite decides when that counts). */
+    trustedEmbeds = new Set();
+    trustNotice = "";
     /** Human label for the auth identity driving this session (the server sets it from the storage-state filename). */
     role = "anonymous";
     /** Named-session id (the server sets it; every engine shares one MemoryStore, so
@@ -628,6 +651,18 @@ export class BrowserEngine {
             throw new Error(`storageStatePath does not exist: ${opts.storageStatePath}`);
         }
         this.mode = opts.mode ?? "read-only";
+        const trust = trustedEmbedOrigins(opts.trustedEmbeds);
+        this.trustedEmbeds = new Set(trust.origins);
+        this.trustNotice =
+            (trust.origins.length > 0
+                ? this.mode === "safe-write"
+                    ? ` Trusted embeds: ${trust.origins.join(", ")} — writes their frames send outside the app go out in this mode; hostile input, repeated-click probes and uploads stay refused.`
+                    : this.mode === "destructive"
+                        ? ` Trusted embeds (${trust.origins.join(", ")}) are not needed in destructive mode, which lets every embed's writes out.`
+                        : ` Trusted embeds (${trust.origins.join(", ")}) are ignored in ${this.mode} mode: they apply in safe-write only.`
+                : "") +
+                (trust.rejected.length > 0 ? ` Not a plain http(s) origin, so not trusted: ${trust.rejected.join(", ")}.` : "") +
+                (trust.overflow.length > 0 ? ` More than ${MAX_TRUSTED_EMBEDS} trusted embeds; not trusted: ${trust.overflow.join(", ")}.` : "");
         this.sessionObjective = (opts.objective ?? "").trim().replace(/\s+/g, " ").slice(0, 300);
         // An agent-supplied task counts as stated; the placeholder does not.
         this.setTask(opts.task ?? "Attaching and taking stock", opts.task !== undefined);
@@ -665,8 +700,22 @@ export class BrowserEngine {
         }
         this.oracles = new OracleMonitor();
         this.oracles.setPolicyRefusalCheck((req) => this.refusedByPolicy.has(req));
+        // A request an embed sends to the app is the app's to answer: only one headed outside the app is the embed's.
+        this.oracles.setEmbedAttribution((req) => {
+            let site = null;
+            try {
+                const frame = req.frame();
+                site = frame === frame.page().mainFrame() ? null : this.foreignOriginOf(frame);
+            }
+            catch {
+                /* no frame: a service worker's or a new window's first request */
+            }
+            return embedOfRequest(this.baseUrl, req.url(), site);
+        });
         this.lastSnap = null;
         this.designAuditCount = 0;
+        // A new attach may be a restarted app: what failed to load before gets another try.
+        this.loadFailedRoutes = new Set();
         // The engine learns the route list itself so completion is an objective,
         // enforceable contract (scout_report refuses while known routes are unvisited)
         // rather than a prompt suggestion the driver may ignore.
@@ -996,7 +1045,7 @@ export class BrowserEngine {
             `Memory: ${this.memory.dir}.${this.memory.loadWarning ? ` WARNING: ${this.memory.loadWarning}` : ""}` +
             (this.memory.prunedStates > 0 ? ` Trimmed ${this.memory.prunedStates} old page state(s) from the history; coverage is unchanged.` : "") +
             `${this.memory.legacyDirNote ? ` ${this.memory.legacyDirNote}` : ""}` +
-            `${this.memory.gitIgnoreNote ? ` ${this.memory.gitIgnoreNote}` : ""} Call scout_snapshot to see the current state.` +
+            `${this.memory.gitIgnoreNote ? ` ${this.memory.gitIgnoreNote}` : ""}${this.trustNotice} Call scout_snapshot to see the current state.` +
             authWarning);
     }
     /** Whether the page was moved off the app by one of its embeds (policy.ts EmbedMoveTracker). */
@@ -1154,31 +1203,169 @@ export class BrowserEngine {
             if (stable)
                 break;
         }
+        const mainCount = rawElements.length;
+        // The page's forms, read in the same settled page as its elements. The
+        // page's own document only: an xpath names a node in one document.
+        const rawForms = ((await this.formRead("form inventory", page.evaluate(FORMS_INVENTORY_SCRIPT))) ?? []);
+        // Then each frame's own controls, read once, each within its own limit.
+        const framed = await this.collectFrames(page);
         // Element identity is the coverage key (testid or role+name, ordinal-
         // disambiguated). When a key persists across snapshots of the same route,
         // its ref is REUSED — diffs stay meaningful and the agent's mental model
-        // (and previously issued refs) survive re-snapshots.
+        // (and previously issued refs) survive re-snapshots. An element inside a
+        // frame carries the frame in its key (collector.ts frameElementKey).
         const route = normalizePath(page.url());
         const prevByKey = this.lastSnap?.route === route ? this.lastSnap.byKey : null;
         this.refs.clear();
+        this.refFrames.clear();
         const keyCounts = new Map();
-        const elements = rawElements.map((el) => {
-            const baseKey = elementKey(el);
+        const all = [
+            ...rawElements.map((raw) => ({ raw })),
+            ...framed.flatMap((g) => g.raws.map((raw) => ({ raw: raw, frame: g.frame, tag: g.tag }))),
+        ];
+        const elements = all.map(({ raw: el, frame, tag }) => {
+            const baseKey = frameElementKey(elementKey(el), tag);
             const count = keyCounts.get(baseKey) ?? 0;
             keyCounts.set(baseKey, count + 1);
             const key = count === 0 ? baseKey : `${baseKey}~${count}`;
             const ref = prevByKey?.get(key)?.ref ?? `e${++this.refCounter}`;
             const full = {
                 ...el,
+                ...(tag ? { frame: tag } : {}),
+                // Judged on the real label, then masked: the policy must see what a click would press.
+                destructive: isDestructive(el.name, el.testid),
+                ...(tag?.foreign ? { name: masksForeignName(el.tag, el.role) ? MASKED_NAME : capForeignName(el.name) } : {}),
+                ...(tag?.foreign && el.href ? { href: stripForeignHref(el.href) } : {}),
                 ref,
                 key,
-                destructive: isDestructive(el.name, el.testid),
             };
             this.refs.set(ref, full);
+            if (frame)
+                this.refFrames.set(ref, frame);
             return full;
         });
-        this.harvestRoutes(elements);
-        return { elements, truncated: rawElements.length >= 150 };
+        this.harvestRoutes(elements.filter((el) => !el.frame?.foreign));
+        this.framesRead = new Set(framed.map((g) => g.frame));
+        // A form is known by its own attributes, else by its submit control's coverage
+        // key (forms.ts formIdentity); a form with neither is not tracked.
+        const forms = rawForms.flatMap((f) => {
+            const status = formStatus(f);
+            const key = status === "untracked" ? null : (formIdentity(f.attrs) ?? keyAtXpath(elements, f.submit));
+            return key ? [{ key, guarded: status === "guarded" }] : [];
+        });
+        this.lastCollectTruncated = mainCount >= 150;
+        return { elements, truncated: mainCount >= 150, forms };
+    }
+    /** Whether the latest collect stopped at the element cap, so some controls have no key at all. */
+    lastCollectTruncated = false;
+    /**
+     * The controls inside the page's frames, up to MAX_READ_FRAMES visible ones,
+     * each read within FRAME_READ_MS so one busy frame cannot stall a snapshot.
+     * Positions are moved into the page's coordinates (the frame element's box
+     * on screen, the frame's own scroll, the page's scroll), so geometry and
+     * the design audit can place them.
+     */
+    async collectFrames(page) {
+        const top = page.mainFrame();
+        const frames = page.frames().filter((f) => f !== top && !f.isDetached());
+        if (frames.length === 0)
+            return [];
+        const pageScroll = (await page.evaluate("({ x: window.scrollX, y: window.scrollY })").catch(() => null)) ?? {
+            x: 0,
+            y: 0,
+        };
+        const read = async (frame) => {
+            let timer;
+            const work = (async () => {
+                const el = await frame.frameElement();
+                const box = await el.boundingBox();
+                if (!box || box.width < 2 || box.height < 2)
+                    return null;
+                const title = ((await el.getAttribute("title")) || (await el.getAttribute("name")) || "").trim();
+                const got = (await frame.evaluate(`(() => ({ els: ${COLLECT_INTERACTABLES_SCRIPT}, sx: window.scrollX, sy: window.scrollY }))()`));
+                const raws = got.els.map((r) => ({ ...r, rect: frameToPageRect(r.rect, box, { x: got.sx, y: got.sy }, pageScroll) }));
+                let origin = "";
+                try {
+                    const u = new URL(frame.url());
+                    if (u.protocol === "http:" || u.protocol === "https:")
+                        origin = u.origin;
+                }
+                catch {
+                    /* no web address */
+                }
+                const foreignOrigin = this.foreignOriginOf(frame);
+                return { frame, tag: { url: frame.url(), origin: foreignOrigin ?? origin, title, foreign: foreignOrigin !== null }, raws };
+            })().catch(() => null);
+            const limit = new Promise((resolve) => {
+                timer = setTimeout(() => resolve(null), FRAME_READ_MS);
+            });
+            return Promise.race([work, limit]).finally(() => clearTimeout(timer));
+        };
+        // Visible frames first: a page's hidden plumbing frames must not use up the budget.
+        const boxes = await Promise.all(frames.map((f) => this.withinFrameLimit(f.frameElement().then((el) => el.boundingBox()))));
+        const visible = frames.filter((_, i) => {
+            const b = boxes[i];
+            return !!b && b.width >= 2 && b.height >= 2;
+        });
+        const got = await Promise.all(visible.slice(0, MAX_READ_FRAMES).map(read));
+        return got.filter((g) => g !== null);
+    }
+    /** The origin of another site's frame an element is in, or null for the page and the app's own frames. */
+    foreignEmbedOf(el) {
+        const frame = this.refFrames.get(el.ref);
+        const now = frame ? this.foreignOriginOf(frame) : null;
+        if (now)
+            return now;
+        return el.frame?.foreign ? el.frame.origin || el.frame.url : null;
+    }
+    /**
+     * The other site a frame belongs to, judged on the whole chain up to the
+     * page: a blank or srcdoc frame inside another site's frame is that site's,
+     * and so is a frame that once held its document (the foreign-frame record).
+     */
+    foreignOriginOf(frame) {
+        const top = frame.page().mainFrame();
+        const chain = [];
+        for (let f = frame; f && f !== top; f = f.parentFrame()) {
+            const recorded = this.foreignFrames.get(f);
+            if (recorded)
+                return recorded;
+            chain.push(f.url());
+        }
+        return foreignFrameOrigin(this.baseUrl, chain);
+    }
+    /** A frame read that gives up after FRAME_READ_MS, answering null. */
+    async withinFrameLimit(work) {
+        let timer;
+        const limit = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(null), FRAME_READ_MS);
+        });
+        return Promise.race([work.catch(() => null), limit]).finally(() => clearTimeout(timer));
+    }
+    /** Frames not directly under the page, less those whose controls were read anyway. */
+    unreadNestedFrames(page, nested) {
+        const top = page.mainFrame();
+        const readNested = [...this.framesRead].filter((f) => !f.isDetached() && f.parentFrame() !== top).length;
+        return Math.max(0, nested - readNested);
+    }
+    /** The frames whose controls the last snapshot listed. */
+    framesRead = new Set();
+    /** The frame each ref of the last snapshot lives in; refs of the page itself are absent. */
+    refFrames = new Map();
+    /**
+     * Where to look for a ref's element: its frame, or the page. A frame that has
+     * gone makes the ref stale, like a page that has navigated.
+     */
+    scopeOf(el) {
+        const frame = this.refFrames.get(el.ref);
+        if (!frame)
+            return this.requirePage();
+        if (frame.isDetached())
+            throw new Error(`The frame holding ${el.ref} has gone — take a new scout_snapshot.`);
+        // A frame that navigated holds a new document: the ref, and what it knew of the frame's site, are stale.
+        if (el.frame && frame.url() !== el.frame.url)
+            throw new Error(`The frame holding ${el.ref} has navigated — take a new scout_snapshot.`);
+        return frame;
     }
     /**
      * Collect the current page and REGISTER it as a visited state, returning the
@@ -1189,10 +1376,12 @@ export class BrowserEngine {
      */
     async captureCoverageState() {
         const page = this.requirePage();
-        const { elements } = await this.collect();
+        const { elements, forms } = await this.collect();
         const url = page.url();
         const fp = fingerprintState(url, elements);
         this.memory?.visitState(fp, url, normalizePath(url), elements.map((el) => el.key));
+        for (const f of forms)
+            this.memory?.recordForm(fp, f.key, f.guarded);
         return { fp, elements, url };
     }
     /**
@@ -1260,13 +1449,15 @@ export class BrowserEngine {
         const page = this.requirePage();
         const memory = this.memory;
         await this.settle();
-        const { elements, truncated } = await this.collect();
+        const { elements, truncated, forms } = await this.collect();
         const url = page.url();
         this.snapshotUrl = url;
         const route = normalizePath(url);
         const fp = fingerprintState(url, elements);
         this.currentFingerprint = fp;
         const isNew = memory.visitState(fp, url, route, elements.map((el) => el.key));
+        for (const f of forms)
+            memory.recordForm(fp, f.key, f.guarded);
         memory.recordRoleAccess(this.role, route, "reached");
         // A snapshot is what an agent takes when it wants to LOOK at something, so
         // it is the frame a reader most wants beside the step. Recording only the
@@ -1282,10 +1473,11 @@ export class BrowserEngine {
                 dup ? `copy#${Number(dup[1]) + 1}` : null,
                 el.disabled ? "disabled" : null,
                 el.destructive ? "DESTRUCTIVE" : null,
+                labelFlag(el),
                 memory.wasExercised(fp, el.key) ? "done" : null,
                 el.href ? `href=${el.href.slice(0, 60)}` : null,
             ].filter(Boolean);
-            return `${el.ref} ${el.role} "${displayName(el)}"${flags.length ? ` [${flags.join(", ")}]` : ""}`;
+            return `${el.ref} ${el.role} "${displayName(el)}"${flags.length ? ` [${flags.join(", ")}]` : ""}${el.frame ? ` ⟨in ${frameLabel(el.frame)}⟩` : ""}`;
         };
         // Diff mode: when re-snapshotting the same route, report only what
         // changed — same idea as UI reconciliation, applied to agent context.
@@ -1334,10 +1526,10 @@ export class BrowserEngine {
                 `Interactables (${elements.length}${truncated ? "+ — TRUNCATED at 150, dense page" : ""}${missingTestids ? `, ${missingTestids} missing data-testid` : ""}):\n` +
                     elements.map(line).join("\n");
         }
-        const geometry = geometryIssues(elements, page.viewportSize() ?? { width: 1280, height: 900 });
-        geometry.push(...(await probeOverlays(page)));
+        // Per document: the page's own controls together, and each frame's apart —
+        // an embed's controls are not laid out against the page's.
+        const { geometry, brokenImages } = await this.measureLayout(page, elements, url);
         const hiddenFileInputs = await this.hiddenFileInputs(page);
-        const brokenImages = brokenImageIssues((await page.evaluate(BROKEN_IMAGES_SCRIPT).catch(() => null)) ?? { images: [], total: 0 }, url);
         const { frames, nested: nestedFrames } = await this.frameInventory(page);
         const cov = memory.coverage();
         const unvisited = this.unvisitedKnownRoutes();
@@ -1350,7 +1542,13 @@ export class BrowserEngine {
             (geometry.length > 0 ? `\nGEOMETRY issues:\n` + geometry.map((g) => `  ⚠ ${g}`).join("\n") : "") +
             (brokenImages.length > 0 ? `\nBROKEN IMAGES:\n` + brokenImages.map((b) => `  ⚠ ${b}`).join("\n") : "") +
             (frames.length > 0 || nestedFrames > 0
-                ? `\n` + frameLines(this.baseUrl, frames, { nested: nestedFrames, writesRefused: this.mode !== "destructive" }).join("\n")
+                ? `\n` +
+                    frameLines(this.baseUrl, frames, {
+                        nested: this.unreadNestedFrames(page, nestedFrames),
+                        writesRefused: this.mode !== "destructive",
+                        trustedWrites: this.mode === "safe-write" ? this.trustedEmbeds : undefined,
+                        read: new Set([...this.framesRead].map((f) => f.url())),
+                    }).join("\n")
                 : "") +
             (hiddenFileInputs.length > 0
                 ? `\nFILE INPUTS not listed above (hidden behind a styled control — a user never sees the input itself): ${hiddenFileInputs.join("; ")}. ` +
@@ -1384,7 +1582,7 @@ export class BrowserEngine {
         }
         // String EXPRESSION via page.evaluate (locator.evaluate treats a string as
         // an expression, not a function — the element arg never binds).
-        const live = (await page
+        const live = (await this.scopeOf(el)
             .evaluate(`(() => { const node = ${xpathLookup(el.xpath)}; if (!node) return null; ` +
             `return { testid: node.getAttribute('data-testid'), label: (node.getAttribute('aria-label') || node.innerText || node.textContent || node.getAttribute('placeholder') || '').trim().slice(0, 120) }; })()`)
             .catch(() => null));
@@ -1605,15 +1803,14 @@ export class BrowserEngine {
         }
         // Frames still attached that hold, or held, another site: one that moved itself to data: is no longer foreign by its URL.
         const pageHasForeignFrame = this.embeddedSites().size > 0;
-        const foreign = foreignWrite(this.baseUrl, {
-            url: req.url(),
-            originHeader: req.headers()["origin"],
-            unadoptedPageUrl,
-            pageHasForeignFrame,
-            ...requestSource(req),
-        });
+        const source = requestSource(req);
+        const originHeader = req.headers()["origin"];
+        const foreign = foreignWrite(this.baseUrl, { url: req.url(), originHeader, unadoptedPageUrl, pageHasForeignFrame, ...source });
         if (foreign && allowsForeignWriteOnSignIn(this.mode, this.page?.url() ?? "", this.baseUrl))
             return null;
+        // Frames of origins the user named as trusted, in safe-write, every one involved: the ordinary rules.
+        if (foreign && trustsForeignWrite(this.mode, this.trustedEmbeds, this.baseUrl, { frameChain: source.frameChain, originHeader, unadoptedPageUrl }))
+            return null;
         return foreign;
     }
     /** Report (and clear) write-policy blocks since the last action. */
@@ -1732,6 +1929,88 @@ export class BrowserEngine {
             return { forced: true };
         }
     }
+    /**
+     * A form read (the inventory, or the probe before a submit), bounded by
+     * FORM_READ_MS. This bookkeeping must never fail or stall the action, so a
+     * failure yields null — but only a page navigating away under the read is
+     * expected; a timeout or any other error goes in the action log.
+     */
+    async formRead(what, work) {
+        let timer;
+        const limit = new Promise((resolve) => {
+            timer = setTimeout(() => resolve("timeout"), FORM_READ_MS);
+        });
+        const outcome = await Promise.race([
+            work.then((value) => ({ value }), (err) => ({ err })),
+            limit,
+        ]).finally(() => clearTimeout(timer));
+        const url = this.page?.url() ?? "";
+        if (outcome === "timeout") {
+            this.logAction({ action: FORMS_READ_FAILED, target: `${what} took over ${FORM_READ_MS} ms`, url });
+            return null;
+        }
+        if ("err" in outcome) {
+            const message = outcome.err instanceof Error ? outcome.err.message.split("\n")[0] : String(outcome.err);
+            if (!isNavigationTeardown(message))
+                this.logAction({ action: FORMS_READ_FAILED, target: `${what}: ${message}`.slice(0, 300), url });
+            return null;
+        }
+        return outcome.value;
+    }
+    /** The form a located element belongs to, read just before an action that may submit it (forms.ts). */
+    probeForm(target) {
+        return this.formRead("form probe", target.evaluate(probeFormOf, undefined, { timeout: FORM_READ_MS }));
+    }
+    /** The form the focused element belongs to, for a key press that may submit through it. */
+    probeFocusedForm() {
+        return this.formRead("form probe", this.requirePage().evaluate(formProbeExpression("document.activeElement")));
+    }
+    /**
+     * A plan's pre-action state, fit to record a submit of this form against.
+     * A plan reuses its previous capture while the URL has not changed, but the
+     * page can shift under the same URL (a control inserted above the form
+     * moves every xpath after it). Only a REUSED capture is suspect: when the
+     * form has no identity of its own and the reused state does not hold its
+     * submit control, the state is captured afresh. A capture this step just
+     * took is never taken twice, and a step with no state gets one.
+     */
+    async stateHolding(probe, state, reused) {
+        if (state && (!reused || formIdentity(probe.attrs) || submitControlIn(state.elements, probe)))
+            return state;
+        return (await this.captureCoverageState().catch(() => null)) ?? state;
+    }
+    /** Whether this probe describes a submit of a tracked form, so the submit is worth recording. */
+    static isTrackedSubmit(kind, probe) {
+        return probe !== null && tracksForm(probe.fields) && submits(kind, probe);
+    }
+    /**
+     * Mark a submit of a listed form against the state it was made in. The
+     * form is known by its own attributes when it has any; otherwise by the
+     * snapshot element at its submit control's xpath, accepted only when that
+     * element's testid and name agree with the control the probe found (for a
+     * click on that control, the element clicked). A submit that matches no
+     * listed form is logged, never dropped silently and never added to the
+     * list. Whether it was a submit, and an empty one, is forms.ts's rule.
+     */
+    noteFormSubmit(state, kind, probe) {
+        if (!this.memory || !BrowserEngine.isTrackedSubmit(kind, probe))
+            return;
+        const empty = isEmptySubmit(kind, probe);
+        const key = formIdentity(probe.attrs) ?? (state ? (submitControlIn(state.elements, probe)?.key ?? null) : null);
+        if (state?.fp && key && this.memory.recordFormSubmit(state.fp, key, empty))
+            return;
+        // A page past the snapshot's element cap may never list this control, so
+        // a fresh snapshot would not help: say it is untracked, not what to retry.
+        const beyondCap = !key && this.lastCollectTruncated && !state?.elements.some((e) => !e.frame && e.xpath === probe.submit);
+        const what = `${empty ? "empty " : ""}${kind} submit of a form (submit control ${JSON.stringify(probe.submitName)} at ${probe.submit})`;
+        this.logAction({
+            action: FORMS_SUBMIT_UNMATCHED,
+            target: beyondCap
+                ? `${what} is untracked: the page has more controls than a snapshot lists, so this form, which has no id, name or action, cannot be keyed`
+                : `${what} matches no form listed for this page, so it is not counted — take a scout_snapshot and submit again`,
+            url: this.page?.url() ?? "",
+        });
+    }
     async click(ref, clicks = 1) {
         const page = this.requirePage();
         const { el, liveLabel } = await this.resolveForAction(ref);
@@ -1740,12 +2019,23 @@ export class BrowserEngine {
             this.logAction({ action: "click:refused", target: liveLabel || el.name, url: page.url() });
             return refusal;
         }
+        const embed = this.foreignEmbedOf(el);
+        if (embed && clicks > 1) {
+            this.logAction({ action: "click:refused", target: `${clicks} clicks in a frame of ${embed}`, url: page.url() });
+            return embedProbeRefusal(`a ${clicks}-click probe`, embed);
+        }
         // Submit-shaped clicks that fire zero network requests are a smell
         // (silent no-op forms): capture the count before to compare after.
         const xhrBefore = this.xhrCount;
         const submitLike = el.role === "button" && /submit|send|save|create|apply|subscribe|register|sign|post|add\b/i.test(el.name + " " + (el.testid ?? ""));
-        const { forced } = await this.resilientClick(page.locator(`xpath=${el.xpath}`), ACTION_TIMEOUT_MS, clicks);
+        const clickTarget = this.scopeOf(el).locator(`xpath=${el.xpath}`);
+        // Read before the click: what the form's fields hold when it goes. Only a
+        // button or an input can submit a form; nothing else is asked.
+        const form = !el.frame && (el.tag === "button" || el.tag === "input") ? await this.probeForm(clickTarget) : null;
+        const formState = { fp: this.currentFingerprint, elements: [...this.refs.values()] };
+        const { forced } = await this.resilientClick(clickTarget, ACTION_TIMEOUT_MS, clicks);
         this.memory.markExercised(this.currentFingerprint, el.key, clicks > 1 ? `click×${clicks}` : "click");
+        this.noteFormSubmit(formState, "click", form);
         const result = await this.afterAction(clicks > 1 ? `click×${clicks}` : "click", `${el.role} "${el.name}"`);
         // Impatient-user probe: a rapid multi-click that fires the SAME
         // state-changing request more than once means the action is not guarded
@@ -1854,15 +2144,28 @@ export class BrowserEngine {
         const refusal = this.actionPolicyCheck(el, liveLabel);
         if (refusal)
             return refusal;
-        const locator = page.locator(`xpath=${el.xpath}`);
-        // Before the fill: a page that reflects input as it is typed already holds the element afterwards.
-        await this.noteProbe(text, `${el.role} "${el.name}"`);
-        const fillNote = await this.fillOrAppend(locator, text, replace);
+        const embed = this.foreignEmbedOf(el);
+        if (embed) {
+            const hostile = hostileForEmbed(text);
+            if (hostile) {
+                this.logAction({ action: "type:refused", target: `${el.role} in a frame of ${embed} (${hostile})`, url: page.url() });
+                return embedProbeRefusal(`typing this value (${hostile})`, embed);
+            }
+        }
+        const locator = this.scopeOf(el).locator(`xpath=${el.xpath}`);
+        // Before the fill: a page that reflects input as it is typed already holds
+        // the element afterwards. Never for another site's frame: no probe is placed there.
+        if (!embed)
+            await this.noteProbe(text, `${el.role} "${el.name}"`);
+        let fillNote = await this.fillOrAppend(locator, text, replace);
+        // What another site's field already held is its business, not the report's.
+        if (embed)
+            fillNote = fillNote.replace(/existing content "(?:[^"\\]|\\.)*"/g, "existing content (masked: another site's frame)");
         if (pressEnter) {
             // Enter inside a form submits it — check the form's submit target, or
             // pressEnter becomes a read-only bypass for destructive submits.
             if (this.readOnly) {
-                const submitLabel = (await page
+                const submitLabel = (await this.scopeOf(el)
                     .evaluate(`(() => { const node = ${xpathLookup(el.xpath)}; if (!node) return ''; ` +
                     `const f = node.form || node.closest('form'); if (!f) return ''; ` +
                     `const s = f.querySelector('[type="submit"], button:not([type="button"]):not([type="reset"])'); ` +
@@ -1873,7 +2176,11 @@ export class BrowserEngine {
                     return `Filled ${el.role} "${el.name}" but did NOT press Enter. ` + destructiveRefusal(submitLabel, this.mode);
                 }
             }
+            // After the fill, before the key: the fields as they are when it submits.
+            const form = !el.frame && el.tag === "input" ? await this.probeForm(locator) : null;
+            const formState = { fp: this.currentFingerprint, elements: [...this.refs.values()] };
             await locator.press("Enter", { timeout: ACTION_TIMEOUT_MS });
+            this.noteFormSubmit(formState, "enter", form);
         }
         this.memory.markExercised(this.currentFingerprint, el.key, "type");
         return this.afterAction("type", `${el.role} "${el.name}" ← ${JSON.stringify(text.slice(0, 60))}${pressEnter ? " + Enter" : ""}${fillNote}`);
@@ -1897,7 +2204,10 @@ export class BrowserEngine {
             const refusal = this.actionPolicyCheck(el, resolved.liveLabel);
             if (refusal)
                 return refusal;
-            locator = page.locator(`xpath=${el.xpath}`);
+            const embed = this.foreignEmbedOf(el);
+            if (embed)
+                return embedProbeRefusal("a file upload", embed);
+            locator = this.scopeOf(el).locator(`xpath=${el.xpath}`);
         }
         const outcome = await this.performUpload(locator, opts);
         if (outcome.refused)
@@ -2023,6 +2333,23 @@ export class BrowserEngine {
     static OVERLAY_SELECTOR = '[role="tooltip"], [data-tippy-root], [data-radix-popper-content-wrapper], [data-floating-ui-portal], ' +
         '[data-slot*="tooltip" i], [data-slot*="popover" i], ' +
         '[class*="tooltip" i], [class*="hovercard" i], [class*="popover" i]';
+    /**
+     * The layout checks a snapshot prints: geometry per document (the page's own
+     * controls together, each frame's apart, since an embed's controls are not
+     * laid out against the page's), the overlay probe, and images that failed.
+     */
+    async measureLayout(page, elements, url) {
+        const viewport = page.viewportSize() ?? { width: 1280, height: 900 };
+        const byDocument = new Map();
+        for (const el of elements) {
+            const doc = el.frame ? el.key.slice(0, el.key.indexOf("|") + 1) : "";
+            byDocument.set(doc, [...(byDocument.get(doc) ?? []), el]);
+        }
+        const geometry = [...byDocument.values()].flatMap((group) => geometryIssues(group, viewport));
+        geometry.push(...(await probeOverlays(page)));
+        const brokenImages = brokenImageIssues((await page.evaluate(BROKEN_IMAGES_SCRIPT).catch(() => null)) ?? { images: [], total: 0 }, url);
+        return { geometry, brokenImages };
+    }
     /**
      * Visible overlay texts right now — diffed before/after a hover to isolate
      * what the hover revealed. Returns null when the read itself failed, so a
@@ -2094,7 +2421,7 @@ export class BrowserEngine {
         const page = this.requirePage();
         const { el } = await this.resolveForAction(ref);
         const { before, bodyBefore, churning } = await this.hoverBaselines();
-        const locator = page.locator(`xpath=${el.xpath}`);
+        const locator = this.scopeOf(el).locator(`xpath=${el.xpath}`);
         await locator.hover({ timeout: ACTION_TIMEOUT_MS });
         // Wiggle inside the element: pointer-tracking libraries distinguish real
         // movement from a single synthetic hover event.
@@ -2104,7 +2431,7 @@ export class BrowserEngine {
             await page.mouse.move(box.x + box.width / 2 - 2, box.y + box.height / 2 - 1);
         }
         const { revealed, fallbackUsed } = await this.detectHoverReveal(before, bodyBefore, churning);
-        const attrTexts = (await page
+        const attrTexts = (await this.scopeOf(el)
             .evaluate(`(() => { const node = ${xpathLookup(el.xpath)}; if (!node) return []; const out = []; ` +
             `const t = node.getAttribute('title'); if (t) out.push('title: ' + t.slice(0, 300)); ` +
             `const d = node.getAttribute('aria-describedby'); if (d) { for (const id of d.split(/\\s+/)) { ` +
@@ -2136,7 +2463,7 @@ export class BrowserEngine {
             return refusal;
         if (this.readOnly) {
             // Bulk-action dropdowns fire on change — vet the chosen option itself.
-            const optionLabel = (await page
+            const optionLabel = (await this.scopeOf(el)
                 .evaluate(`(() => { const node = ${xpathLookup(el.xpath)}; if (!node) return ''; const v = ${JSON.stringify(value)}; ` +
                 `const opts = Array.from(node.options || []); ` +
                 `const o = opts.find(o => o.value === v || o.label === v || (o.textContent || '').trim() === v); ` +
@@ -2147,7 +2474,7 @@ export class BrowserEngine {
                 return destructiveRefusal(optionLabel || value, this.mode);
             }
         }
-        const loc = page.locator(`xpath=${el.xpath}`);
+        const loc = this.scopeOf(el).locator(`xpath=${el.xpath}`);
         const options = el.tag === "select" ? await readSelectOptions(loc) : null;
         const picked = await loc.selectOption(value, { timeout: ACTION_TIMEOUT_MS });
         this.memory.markExercised(this.currentFingerprint, el.key, "select");
@@ -2160,11 +2487,37 @@ export class BrowserEngine {
      * policy as click, or the keyboard becomes a read-only bypass. Shared by
      * scout_press and plan press steps; returns a refusal message or null.
      */
+    /**
+     * The frame that holds keyboard focus: the page, or — when the page's
+     * focused element is a frame — that frame, followed down as far as focus goes.
+     */
+    async focusedFrame(page) {
+        let scope = page;
+        let current = page.mainFrame();
+        for (let depth = 0; depth < 5; depth++) {
+            let next = null;
+            for (const child of current.childFrames()) {
+                // Within the frame limit: a frame that never answers must not hold up a key press.
+                const holds = await this.withinFrameLimit(child.frameElement().then((el) => el.evaluate((node) => node === node.ownerDocument?.activeElement)));
+                if (holds) {
+                    next = child;
+                    break;
+                }
+            }
+            if (!next)
+                break;
+            scope = next;
+            current = next;
+        }
+        return scope;
+    }
     async vetFocusedActivation(key) {
         if (!(this.readOnly && /^(Enter|NumpadEnter|Space| )$/i.test(key)))
             return null;
         const page = this.requirePage();
-        const focusedLabel = await page
+        // Focus inside a frame reads, from the page, as the <iframe> itself: follow it down.
+        const focused = await this.focusedFrame(page);
+        const focusedLabel = await focused
             .evaluate(`(() => { const el = document.activeElement; if (!el) return ""; ` +
             `return (el.getAttribute("aria-label") || el.getAttribute("data-testid") || el.innerText || el.textContent || "").trim().slice(0, 120); })()`)
             .catch(() => "");
@@ -2199,7 +2552,13 @@ export class BrowserEngine {
         // Identify the focused control BEFORE the key lands — activating it may
         // navigate, close a dialog, or otherwise destroy the element.
         const focused = BrowserEngine.ACTIVATION_KEY_RE.test(key) ? await this.focusedInteractable() : null;
+        // Enter submits from a field or a submit control; Space only activates a control.
+        const formKind = BrowserEngine.ACTIVATION_KEY_RE.test(key) ? (/enter/i.test(key) ? "enter" : "click") : null;
+        const form = formKind ? await this.probeFocusedForm() : null;
+        const formState = { fp: this.currentFingerprint, elements: [...this.refs.values()] };
         await page.keyboard.press(key);
+        if (formKind)
+            this.noteFormSubmit(formState, formKind, form);
         if (focused && this.memory && this.currentFingerprint) {
             this.memory.markExercised(this.currentFingerprint, focused, `press:${key}`);
         }
@@ -2340,17 +2699,51 @@ export class BrowserEngine {
     navigablePath(routeClass) {
         return this.memory?.discoveredRoutes[routeClass] ?? routeClass;
     }
+    /** Routes whose page failed to load in this process: still unvisited, but not tried again by a crawl that picks its own targets. */
+    loadFailedRoutes = new Set();
+    /** Unvisited known routes a crawl would still try: those that already failed to load in this process are left out. */
+    crawlableRoutes() {
+        return this.unvisitedKnownRoutes().filter((r) => !this.loadFailedRoutes.has(normalizePath(r)));
+    }
+    /** What the last crawl measured on each route, as data: `scenescout check` builds its verdict from this. */
+    crawlHealth = [];
+    /** The per-route results of the most recent crawl. */
+    get lastCrawlHealth() {
+        return this.crawlHealth;
+    }
+    /** A check's extra measurements on a crawled page: the snapshot's layout checks and the design audit's defects. */
+    async inspectRoute(page, elements, url) {
+        const { geometry, brokenImages } = await this.measureLayout(page, elements, url);
+        try {
+            const { defects, sampled } = await this.auditPage();
+            // Nothing styled to read is not a clean page: contrast, focus and target size went unmeasured.
+            return sampled > 0
+                ? { geometry, brokenImages, design: defects }
+                : { geometry, brokenImages, design: [], auditError: "no visible styled elements to measure" };
+        }
+        catch (err) {
+            // A page that navigated away mid-audit has nothing to measure. The
+            // route's other results still stand, and the report says the audit is missing.
+            return { geometry, brokenImages, design: [], auditError: err instanceof Error ? err.message.split("\n")[0] : String(err) };
+        }
+    }
     /**
      * Engine-side route sweep: visit each path, record the state in memory, and
      * collect per-route health — one tool call instead of one LLM turn per route.
      * Output is anomaly-oriented: a summary line per route, details only where
      * something is wrong. Navigation-only, so it is safe in read-only mode.
      */
-    async crawl(paths) {
+    async crawl(paths, opts = {}) {
         const page = this.requirePage();
         const memory = this.memory;
-        const targets = (paths && paths.length > 0 ? paths : this.unvisitedKnownRoutes().map((r) => this.navigablePath(r))).slice(0, 150);
+        this.crawlHealth = [];
+        const targets = (paths && paths.length > 0 ? paths : this.crawlableRoutes().map((r) => this.navigablePath(r))).slice(0, Math.min(150, opts.limit ?? 150));
         if (targets.length === 0) {
+            const failed = this.unvisitedKnownRoutes().filter((r) => this.loadFailedRoutes.has(normalizePath(r)));
+            if (failed.length > 0) {
+                return (`Nothing new to crawl. ${failed.length} route(s) failed to load earlier in this session and are still unvisited: ${failed.slice(0, 20).join(", ")}${failed.length > 20 ? " …" : ""}. ` +
+                    `A crawl without paths does not retry them; pass them as paths once the app is reachable, e.g. scout_crawl {paths:${JSON.stringify(failed.slice(0, 3).map((r) => this.navigablePath(r)))}}.`);
+            }
             return this.allKnownRoutes().length > 0
                 ? "Nothing to crawl: every known route has been visited. Use scout_coverage for remaining unexercised elements."
                 : "No routes to crawl yet: no scanned or link-discovered routes. Take a snapshot first (links harvest routes) or pass explicit paths.";
@@ -2371,16 +2764,42 @@ export class BrowserEngine {
                 status = resp?.status() ?? "no-response";
             }
             catch (err) {
+                const reason = err instanceof Error ? err.message.split("\n")[0] : String(err);
+                // Not retried by later crawls in this process (a check would otherwise try it
+                // on every discovery round). Deliberately not written to memory: one outage
+                // must not count a route as covered in every later run's gap ledger.
+                this.loadFailedRoutes.add(normalizePath(url));
+                // The browser commits its own error page for this failure tens of
+                // milliseconds after goto has thrown, and that commit interrupts the next
+                // navigation, charging this route's failure to the next one. Wait for it;
+                // a browser that shows no error page simply lets the wait time out.
+                await page.waitForEvent("framenavigated", { predicate: (f) => f === page.mainFrame(), timeout: 1500 }).catch(() => undefined);
                 summary.push(`${path} — LOAD FAILED`);
-                problems.push(`${path}: ${err instanceof Error ? err.message.split("\n")[0] : err}`);
+                problems.push(`${path}: ${reason}`);
+                this.crawlHealth.push({
+                    path,
+                    url,
+                    status: null,
+                    loadError: reason,
+                    loginRedirect: false,
+                    elements: 0,
+                    unnamed: [],
+                    placeholderOnly: [],
+                    violations: [],
+                    geometry: [],
+                    brokenImages: [],
+                    design: [],
+                });
                 continue;
             }
             await this.settle();
-            const { elements } = await this.collect();
+            const { elements, forms } = await this.collect();
             const finalUrl = page.url();
             const route = normalizePath(finalUrl);
             const fp = fingerprintState(finalUrl, elements);
             memory.visitState(fp, finalUrl, route, elements.map((el) => el.key));
+            for (const f of forms)
+                memory.recordForm(fp, f.key, f.guarded);
             memory.recordRoleAccess(this.role, route, "reached");
             // If we landed somewhere else (auth wall, canonical redirect), the
             // REQUESTED route still counts as covered for THIS role — a role that
@@ -2405,9 +2824,28 @@ export class BrowserEngine {
             this.logAction({ action: "crawl", target: path, url: finalUrl, ...(await this.frameFor("crawl")) });
             await this.scanForInjections();
             await this.scanForContradictions();
+            // Measured before the drain: the audit's Tab presses can load things too.
+            const inspected = opts.inspect ? await this.inspectRoute(page, elements, finalUrl) : null;
             const violations = this.oracles.drain();
+            const own = elements.filter((el) => !el.frame?.foreign);
+            this.crawlHealth.push({
+                path,
+                url: finalUrl,
+                status: typeof status === "number" ? status : null,
+                loginRedirect,
+                elements: elements.length,
+                unnamed: own.filter(missingName).map(describeControl),
+                placeholderOnly: own.filter(placeholderOnly).map(placeholderEvidence),
+                violations: violations.map(({ kind, severity, detail, url, embed }) => ({ kind, severity, detail, url, ...(embed ? { embed } : {}) })),
+                geometry: inspected?.geometry ?? [],
+                brokenImages: inspected?.brokenImages ?? [],
+                design: inspected?.design ?? [],
+                ...(inspected?.auditError ? { auditError: inspected.auditError } : {}),
+            });
             const deadEnd = elements.length === 0;
-            const unnamed = elements.filter(missingName).length;
+            // A field labelled only by its placeholder counts here too: to someone reading the crawl, it has no label.
+            // Counted over the page's own controls, as the check's lists are: another site's frame is not this app's to fix.
+            const unnamed = own.filter((el) => missingName(el) || placeholderOnly(el)).length;
             const missingTestid = elements.filter((el) => !el.testid && !el.disabled).length;
             const flags = [loginRedirect ? "AUTH-REDIRECT" : null, deadEnd ? "DEAD-END" : null, violations.length > 0 ? `${violations.length}⚠` : null].filter(Boolean);
             summary.push(`${path} — ${status} · ${elements.length} el` +
@@ -2483,6 +2921,8 @@ export class BrowserEngine {
             // A select step's options and choice, recorded against the dropdown the bookkeeping below finds.
             let chose = null;
             let preState = null;
+            // The form this step may submit, read before it went (forms.ts).
+            let form = null;
             try {
                 if (step.action === "navigate") {
                     const result = await this.navigate(step.target ?? step.value ?? "/");
@@ -2512,6 +2952,15 @@ export class BrowserEngine {
                         transcript.push(`${desc} → ${refusal}`);
                         break;
                     }
+                    if (BrowserEngine.ACTIVATION_KEY_RE.test(key)) {
+                        const kind = /enter/i.test(key) ? "enter" : "click";
+                        const probe = await this.probeFocusedForm();
+                        if (BrowserEngine.isTrackedSubmit(kind, probe)) {
+                            const reusable = lastCapture?.url === page.url() ? lastCapture : null;
+                            preState = await this.stateHolding(probe, reusable, reusable !== null);
+                            form = { kind, probe };
+                        }
+                    }
                     await page.keyboard.press(key);
                 }
                 else {
@@ -2540,8 +2989,14 @@ export class BrowserEngine {
                         transcript.push(`${desc} → ${destructiveRefusal(label || step.target, this.mode)}`);
                         break;
                     }
-                    if (step.action === "click")
+                    if (step.action === "click") {
+                        const probe = await this.probeForm(loc);
+                        if (BrowserEngine.isTrackedSubmit("click", probe)) {
+                            preState = await this.stateHolding(probe, preState, preState !== null && preState === lastCapture);
+                            form = { kind: "click", probe };
+                        }
                         forcedClick = (await this.resilientClick(loc, ACTION_TIMEOUT_MS)).forced;
+                    }
                     else if (step.action === "hover") {
                         const { before, bodyBefore, churning } = await this.hoverBaselines();
                         await loc.hover({ timeout: ACTION_TIMEOUT_MS });
@@ -2563,6 +3018,11 @@ export class BrowserEngine {
                                     break;
                                 }
                             }
+                            const probe = await this.probeForm(loc);
+                            if (BrowserEngine.isTrackedSubmit("enter", probe)) {
+                                preState = await this.stateHolding(probe, preState, preState !== null && preState === lastCapture);
+                                form = { kind: "enter", probe };
+                            }
                             await loc.press("Enter", { timeout: ACTION_TIMEOUT_MS });
                         }
                     }
@@ -2582,6 +3042,8 @@ export class BrowserEngine {
                     }
                 }
                 await this.settle();
+                if (form)
+                    this.noteFormSubmit(preState, form.kind, form.probe);
                 // A plan is the RECOMMENDED way to run a mechanical sequence, so its
                 // steps are where most of a recorded run actually happens. Leaving
                 // them unframed reproduced, inside run_plan, the same hole that crawl
@@ -2596,10 +3058,12 @@ export class BrowserEngine {
                     try {
                         // Record the state the action LANDED on (it may be a new screen
                         // this plan just reached, and it deserves coverage of its own)…
-                        const { elements } = await this.collect();
+                        const { elements, forms } = await this.collect();
                         const url = page.url();
                         const fp = fingerprintState(url, elements);
                         this.memory.visitState(fp, url, normalizePath(url), elements.map((el) => el.key));
+                        for (const f of forms)
+                            this.memory.recordForm(fp, f.key, f.guarded);
                         this.memory.recordRoleAccess(this.role, normalizePath(url), "reached");
                         lastCapture = { fp, elements, url };
                         // …but mark the acted-on element in the state it came FROM, using
@@ -2676,6 +3140,11 @@ export class BrowserEngine {
     }
     /** Computed-style design audit of the current page — visual judgment material without pixels. */
     async designAudit() {
+        const { url, report } = await this.auditPage();
+        return `URL: ${url}\n` + report;
+    }
+    /** The design audit's measurements, as data as well as prose; scout_design_audit and a check's crawl share it. */
+    async auditPage() {
         const page = this.requirePage();
         await this.settle();
         const payload = (await page.evaluate(DESIGN_COLLECT_SCRIPT));
@@ -2687,7 +3156,7 @@ export class BrowserEngine {
         // score with chrome included and later ones don't. That is the same warm-up
         // the coverage census has: nothing is knowable as "shared" until it has been
         // seen on several routes.
-        const { report, score, signatures } = analyzeDesign(payload, page.viewportSize() ?? { width: 1280, height: 900 }, this.memory?.designChromeKeys() ?? new Set());
+        const { report, score, signatures, defects } = analyzeDesign(payload, page.viewportSize() ?? { width: 1280, height: 900 }, this.memory?.designChromeKeys() ?? new Set());
         const route = normalizePath(page.url());
         this.memory?.recordDesignElements(route, signatures);
         // Only a page that actually produced a score counts as audited. An empty or
@@ -2699,7 +3168,7 @@ export class BrowserEngine {
             this.memory?.markRouteFact(route, { audited: true });
         }
         this.logAction({ action: "design-audit", url: page.url(), result: score ? `score:${score.overall}` : undefined, ...(await this.frameFor("design-audit")) });
-        return `URL: ${page.url()}\n` + report;
+        return { url: page.url(), report, defects, sampled: payload.records.length };
     }
     /**
      * Scroll like a user — and notice when the page won't let you. Reports the