scenescout 3.9.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, frameElementKey, frameLabel, masksForeignName, MASKED_NAME, capForeignName, stripForeignHref, frameToPageRect, 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,6 +16,7 @@ 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";
@@ -81,6 +82,23 @@ const ESCAPE_REFUSAL = "a possible frame escape";
 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`;
@@ -696,6 +714,8 @@ export class BrowserEngine {
         });
         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.
@@ -1184,6 +1204,9 @@ export class BrowserEngine {
                 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-
@@ -1223,8 +1246,18 @@ export class BrowserEngine {
         });
         this.harvestRoutes(elements.filter((el) => !el.frame?.foreign));
         this.framesRead = new Set(framed.map((g) => g.frame));
-        return { elements, truncated: mainCount >= 150 };
+        // 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.
@@ -1343,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 };
     }
     /**
@@ -1414,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
@@ -1436,6 +1473,7 @@ 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);
@@ -1490,16 +1528,8 @@ export class BrowserEngine {
         }
         // 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 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 { 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();
@@ -1899,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);
@@ -1916,8 +2028,14 @@ export class BrowserEngine {
         // (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(this.scopeOf(el).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
@@ -2058,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}`);
@@ -2211,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
@@ -2413,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}`);
         }
@@ -2554,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.";
@@ -2585,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
@@ -2619,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` +
@@ -2697,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 ?? "/");
@@ -2726,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 {
@@ -2754,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 });
@@ -2777,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 });
                         }
                     }
@@ -2796,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
@@ -2810,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
@@ -2890,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));
@@ -2901,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
@@ -2913,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