scenescout 3.9.0 → 3.11.0

package/dist/engine/browser.js

@@ -2,20 +2,22 @@ import { chromium, firefox, webkit, } from "playwright";
 import fs from "node:fs";
 import path from "node:path";
 import { elementKey, fingerprintState, isNonPageRoute, normalizePath } from "./fingerprint.js";
-import { AUTH_LOSS_PREFIX, JOURNEY_END, JOURNEY_START, MemoryStore, TASK_SET } from "./memory.js";
+import { AUTH_LOSS_PREFIX, JOURNEY_END, JOURNEY_START, MemoryStore, redactSecrets, TASK_SET } from "./memory.js";
 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 { OracleMonitor, formatViolations } from "./oracles.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, httpErrorDetail } from "./oracles.js";
 import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js";
 import { formatJourney, measureJourney } from "./journey.js";
+import { describeStep, FLOW_AFTER_LAST_STEP_MS, FLOW_STEP_TIMEOUT_MS, isAction, matchRequest, parseTarget, splitRefusals, TARGET_HELP, urlMatches, } from "./flow.js";
 import { framePath, RECORD_MAX_FRAMES } from "./replay.js";
 import { keepWatchingUrl, normalizePace, SETTLE_TICK_MS, shouldKeepWaiting } from "./settle.js";
 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 +83,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 +715,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.
@@ -829,7 +850,7 @@ export class BrowserEngine {
                     const why = ESCAPE_REFUSAL;
                     // Reported like any refusal, so a click whose navigation this stopped does not read as a click that did nothing.
                     if (this.blockedRequests.length < 20)
-                        this.blockedRequests.push({ at: Date.now(), sig: `navigation to ${req.url().slice(0, 140)}`, answered: false, why });
+                        this.blockedRequests.push({ at: Date.now(), sig: `navigation to ${req.url().slice(0, 140)}`, answered: false, why, type: req.resourceType() });
                     this.logAction({ action: "write-policy:blocked", target: `navigation to ${req.url().slice(0, 140)} (${why})`, url: this.page?.url() ?? "" });
                     this.refusedByPolicy.add(req);
                     this.oracles.notePolicyBlock();
@@ -889,7 +910,7 @@ export class BrowserEngine {
                 const refuse = (why) => {
                     const answered = answersWithRefusal(req.resourceType());
                     if (this.blockedRequests.length < 20)
-                        this.blockedRequests.push({ at: Date.now(), sig: `${method} ${url.slice(0, 140)}`, answered, why });
+                        this.blockedRequests.push({ at: Date.now(), sig: `${method} ${url.slice(0, 140)}`, answered, why, type: req.resourceType() });
                     this.logAction({ action: "write-policy:blocked", target: `${method} ${pathname}${why ? ` (${why})` : ""}`, url: this.page?.url() ?? "" });
                     this.refusedByPolicy.add(req);
                     this.oracles.notePolicyBlock();
@@ -1184,6 +1205,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 +1247,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 +1377,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 };
     }
     /**
@@ -1354,7 +1390,11 @@ export class BrowserEngine {
      * route classes (including ?tab= screens) that feed the completion contract,
      * so the contract works for any app, not just filesystem-routed Next.
      */
+    /** Set while a measure-only crawl reads a page: its links are not the app's route list. */
+    harvestPaused = false;
     harvestRoutes(elements) {
+        if (this.harvestPaused)
+            return;
         if (!this.memory)
             return;
         const found = [];
@@ -1414,13 +1454,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 +1478,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 +1533,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 +1934,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 +2033,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 +2181,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 +2338,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 +2557,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 +2704,57 @@ 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) {
+    /**
+     * `measureOnly`: load and measure the pages and nothing else. No route is
+     * harvested from their links, none is marked visited or attempted, and a
+     * failed load is not remembered, so the pages and what they link to stay on
+     * the unvisited list exactly as before. A check's re-test loads use it.
+     */
+    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,24 +2775,54 @@ 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.
+                if (!opts.measureOnly)
+                    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();
+            this.harvestPaused = opts.measureOnly === true;
+            const { elements, forms } = await this.collect().finally(() => (this.harvestPaused = false));
             const finalUrl = page.url();
             const route = normalizePath(finalUrl);
             const fp = fingerprintState(finalUrl, elements);
-            memory.visitState(fp, finalUrl, route, elements.map((el) => el.key));
-            memory.recordRoleAccess(this.role, route, "reached");
+            if (!opts.measureOnly) {
+                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
             // can't see /admin must not block the completion contract forever. An
             // auth-loss bounce is recorded under a prefix that does NOT count.
             const requestedRoute = normalizePath(url);
             const loginRedirect = this.authLoss.isLoginRedirect(path, finalUrl, this.baseUrl);
-            if (route !== requestedRoute) {
+            if (route !== requestedRoute && !opts.measureOnly) {
                 const outcome = loginRedirect ? `${AUTH_LOSS_PREFIX}${route}` : `landed:${route}`;
                 memory.markAttempted(requestedRoute, outcome, this.role);
                 memory.recordRoleAccess(this.role, requestedRoute, outcome);
@@ -2614,14 +2834,33 @@ export class BrowserEngine {
             this.authLoss.clear();
             // Error-status routes render but would otherwise be re-crawled forever —
             // an attempt with the status satisfies the contract.
-            if (typeof status === "number" && status >= 400)
+            if (typeof status === "number" && status >= 400 && !opts.measureOnly)
                 memory.markAttempted(requestedRoute, `status:${status}`, this.role);
             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` +
@@ -2665,13 +2904,10 @@ export class BrowserEngine {
         const page = this.requirePage();
         const transcript = [];
         const resolveTarget = (target) => {
-            if (target.startsWith("testid="))
-                return page.locator(`[data-testid=${JSON.stringify(target.slice(7))}]`).first();
-            if (target.startsWith("text="))
-                return page.getByText(target.slice(5), { exact: false }).first();
-            if (target.startsWith("label="))
-                return page.getByLabel(target.slice(6)).first();
-            throw new Error(`Plan targets must be "testid=…", "text=…", or "label=…" (got: ${target})`);
+            const parsed = parseTarget(target);
+            if (!parsed)
+                throw new Error(`Plan targets must be ${TARGET_HELP} (got: ${target})`);
+            return BrowserEngine.locatorFor(page, parsed).first();
         };
         /** Last state captured this plan — reused as the next step's pre-state while the page has not moved. */
         let lastCapture = null;
@@ -2697,6 +2933,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 +2964,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 +3001,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 +3030,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 +3054,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 +3070,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
@@ -2888,8 +3150,234 @@ export class BrowserEngine {
         const ran = transcript.filter((l) => /^\d+\. /.test(l)).length;
         return `PLAN (${ran}/${Math.min(steps.length, 20)} steps ran):\n${transcript.join("\n")}\nTake scout_snapshot to see the resulting state.`;
     }
+    /** A plan's or a flow's target as a Playwright locator (every match; callers pick). */
+    static locatorFor(page, target) {
+        switch (target.by) {
+            case "testid":
+                return page.locator(`[data-testid=${JSON.stringify(target.value)}]`);
+            case "text":
+                return page.getByText(target.value, { exact: false });
+            case "label":
+                return page.getByLabel(target.value);
+            case "role":
+                return page.getByRole(target.role, target.name === undefined ? {} : { name: target.name });
+        }
+    }
+    /**
+     * Replay one saved flow for `scenescout check`. Acts and reports only: the
+     * schema, the matching rules and what an outcome means live in flow.ts and
+     * check.ts. It stops at the first step that breaks, or that the write policy
+     * refuses, and hands back what the oracles caught on the way.
+     *
+     * Stricter than a plan on purpose: a click is never forced through
+     * something covering its target (a user could not click it either), and a
+     * step does not count as done until the page has settled.
+     */
+    async replayFlow(steps, mode = this.mode === "observe" ? "observe" : "read-only") {
+        const page = this.requirePage();
+        // The write policy reads this.mode on every request, so the flow's rule holds for exactly as long as the flow runs.
+        const crawlMode = this.mode;
+        this.mode = mode;
+        const context = this.context;
+        const violations = [];
+        const here = () => {
+            try {
+                const u = new URL(this.page?.url() ?? "");
+                return `${u.pathname}${u.search}`;
+            }
+            catch {
+                return "/";
+            }
+        };
+        /** Responses since the most recent action step: what an expect-request looks through. */
+        let seen = [];
+        const onResponse = (res) => {
+            seen.push({ method: res.request().method(), url: res.url(), status: res.status() });
+        };
+        context.on("response", onResponse);
+        const appOrigin = new URL(this.baseUrl).origin;
+        const refusedBackground = [];
+        const websockets = new Set();
+        const onSocket = (ws) => void websockets.add(ws.url().slice(0, 120));
+        page.on("websocket", onSocket);
+        /** Refused writes since the last call that a step is charged with; background ones (beacons, pings) are only listed (splitRefusals). */
+        const ownRefusals = () => {
+            const { charged, background } = splitRefusals(this.blockedRequests.splice(0), appOrigin);
+            for (const sig of background)
+                if (!refusedBackground.includes(sig) && refusedBackground.length < 20)
+                    refusedBackground.push(sig);
+            return charged;
+        };
+        const done = (outcome) => ({ outcome, violations, refusedBackground, websockets: [...websockets] });
+        // Nothing from the crawl before this flow is charged to it.
+        this.oracles.drain(false);
+        this.blockedRequests = [];
+        const collect = (except) => {
+            const path = here();
+            for (const v of this.oracles.drain())
+                if (v.detail !== except)
+                    violations.push({ path, violation: { kind: v.kind, severity: v.severity, detail: v.detail, url: v.url, ...(v.embed ? { embed: v.embed } : {}) } });
+        };
+        const poll = async (done) => {
+            const until = Date.now() + FLOW_STEP_TIMEOUT_MS;
+            for (;;) {
+                if (done())
+                    return true;
+                if (Date.now() >= until)
+                    return false;
+                await (this.page ?? page).waitForTimeout(100).catch(() => { });
+            }
+        };
+        const firstLine = (err) => (err instanceof Error ? err.message : String(err))
+            .split("\n")[0]
+            .replace(/^[a-z]+\.[a-zA-Z]+: /, "")
+            .trim();
+        try {
+            for (const [i, step] of steps.entries()) {
+                const n = i + 1;
+                const did = describeStep(step);
+                if (isAction(step))
+                    seen = [];
+                let failure = null;
+                let refusal = null;
+                this.actionStartedAt = Date.now();
+                try {
+                    const current = this.requirePage();
+                    if (step.action === "navigate") {
+                        const url = `${this.baseUrl}${step.target}`;
+                        const resp = await current.goto(url, { waitUntil: "domcontentloaded", timeout: 15000 });
+                        await this.settle();
+                        const status = resp?.status() ?? null;
+                        if (status !== null && status >= 400) {
+                            failure = `the page answered HTTP ${status}`;
+                            // The page's own status is this step's failure; the oracle's record of the same response is not a second issue.
+                            // The oracle stores its details redacted (redactViolation), so the comparison is redacted too.
+                            collect(redactSecrets(httpErrorDetail("GET", current.url().replace(/#.*$/, ""), status)));
+                        }
+                    }
+                    else if (step.action === "press") {
+                        refusal = await this.vetFocusedActivation(step.value);
+                        if (!refusal) {
+                            await current.keyboard.press(step.value);
+                            await this.settle();
+                        }
+                    }
+                    else if (step.action === "click" || step.action === "type" || step.action === "select") {
+                        const loc = BrowserEngine.locatorFor(current, parseTarget(step.target)).first();
+                        const found = await loc
+                            .waitFor({ state: "visible", timeout: FLOW_STEP_TIMEOUT_MS })
+                            .then(() => true)
+                            .catch(() => false);
+                        if (!found) {
+                            failure = `nothing visible matches ${step.target} within ${FLOW_STEP_TIMEOUT_MS / 1000}s`;
+                        }
+                        else {
+                            const label = ((await loc.getAttribute("aria-label").catch(() => null)) ??
+                                (await loc.textContent({ timeout: 1000 }).catch(() => null)) ??
+                                "").trim();
+                            if (this.readOnly && step.action !== "type" && isDestructive(label, step.action === "select" ? step.value : undefined)) {
+                                refusal = destructiveRefusal(label || step.target, this.mode);
+                            }
+                            else if (step.action === "click") {
+                                await loc.click({ timeout: FLOW_STEP_TIMEOUT_MS });
+                            }
+                            else if (step.action === "select") {
+                                await loc.selectOption(step.value, { timeout: FLOW_STEP_TIMEOUT_MS });
+                            }
+                            else {
+                                await this.noteProbe(step.value, step.target);
+                                await this.fillOrAppend(loc, step.value, step.replace ?? false);
+                                if (step.pressEnter) {
+                                    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(() => "")) ?? "").trim();
+                                    if (this.readOnly && isDestructive(submitLabel))
+                                        refusal = destructiveRefusal(submitLabel, this.mode);
+                                    else
+                                        await loc.press("Enter", { timeout: FLOW_STEP_TIMEOUT_MS });
+                                }
+                            }
+                            if (!refusal)
+                                await this.settle();
+                        }
+                    }
+                    else if (step.action === "expect-text") {
+                        const visible = current.getByText(step.text, { exact: false }).filter({ visible: true }).first();
+                        const ok = await visible
+                            .waitFor({ state: "visible", timeout: FLOW_STEP_TIMEOUT_MS })
+                            .then(() => true)
+                            .catch(() => false);
+                        if (!ok)
+                            failure = `no visible text ${JSON.stringify(step.text)} within ${FLOW_STEP_TIMEOUT_MS / 1000}s`;
+                    }
+                    else if (step.action === "expect-url") {
+                        const ok = await poll(() => urlMatches(step.pattern, this.page?.url() ?? ""));
+                        if (!ok)
+                            failure = `the page is at ${here()}, which does not match /${step.pattern}/`;
+                    }
+                    else {
+                        let last = { ok: false, reason: "" };
+                        await poll(() => (last = matchRequest(step, seen)).ok);
+                        if (!last.ok)
+                            failure = last.reason;
+                    }
+                }
+                catch (err) {
+                    failure = firstLine(err);
+                }
+                await this.scanForInjections().catch(() => { });
+                await this.scanForContradictions().catch(() => { });
+                // What the write policy refused of the app's own requests while this step ran is the step's, whatever caused it.
+                const blocked = ownRefusals();
+                if (!refusal && blocked.length > 0)
+                    refusal = `the ${this.mode} write policy refused ${blocked.join(", ")}`;
+                collect();
+                if (refusal)
+                    return done({ status: "refused", step: n, did, reason: refusal.split("\n")[0], path: here() });
+                if (failure)
+                    return done({ status: "failed", step: n, did, reason: failure, path: here() });
+            }
+            // A write the last step set off can land after its checks ran (a debounced save): wait a moment, settle, look
+            // again; then leave the page while the flow's rule still holds, so nothing it sends on the way out goes under
+            // the crawl's rule, and look once more.
+            await (this.page ?? page).waitForTimeout(FLOW_AFTER_LAST_STEP_MS).catch(() => { });
+            await this.settle().catch(() => { });
+            const late = ownRefusals();
+            collect();
+            await (this.page ?? page).goto("about:blank").catch(() => { });
+            await this.settle().catch(() => { });
+            late.push(...ownRefusals());
+            const last = steps[steps.length - 1];
+            if (late.length > 0 && last) {
+                return done({
+                    status: "refused",
+                    step: steps.length,
+                    did: describeStep(last),
+                    reason: `after the last step, the ${this.mode} write policy refused ${late.join(", ")}`,
+                    path: here(),
+                });
+            }
+            return done({ status: "passed" });
+        }
+        finally {
+            // Leave the flow's page before the crawl's rule comes back, so nothing it still sends goes out under a looser one.
+            await (this.page ?? page).goto("about:blank").catch(() => { });
+            this.blockedRequests = [];
+            this.oracles.drain(false);
+            this.mode = crawlMode;
+            page.off("websocket", onSocket);
+            context.off("response", onResponse);
+            this.refs.clear();
+            this.lastSnap = null;
+            this.snapshotUrl = "";
+        }
+    }
     /** 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 +3389,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 +3401,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