scenescout 3.10.0 → 3.11.1

package/dist/engine/unload.js

@@ -0,0 +1,201 @@
+/**
+ * Writes the context's route handler never sees, and how the engine judges
+ * them anyway.
+ *
+ * In Chromium, a request a page sends while it is being left (a
+ * `navigator.sendBeacon` or a `fetch(..., { keepalive: true })` on
+ * `pagehide`, `visibilitychange` or `unload`, or one still leaving as a page
+ * is closed) is never handed to the context's route handler: it arrives with
+ * no network id, or after the page's own DevTools session has gone, and the
+ * driver lets it through unseen. Left alone it reached the server in every
+ * mode, observe included. The engine therefore also intercepts at the
+ * browser level (the DevTools Fetch domain on the browser target, which does
+ * pause these requests) and judges there every write the route handler did
+ * not already judge, by the same rules (ADR 2). Which engines need this is
+ * `unloadWriteInterception` in `browsers.ts`.
+ *
+ * Everything here is pure, so the rules are table-tested in policy-test; the
+ * wiring to the browser lives in `browser.ts`.
+ */
+import { createHash } from "node:crypto";
+import { allowsForeignWriteOnSignIn, allowsWrite, foreignWrite, isAuthExempt, offAppPageWrite, trustsForeignWrite } from "./policy.js";
+/** Whether a method sends nothing the write policy judges. */
+export function isReadMethod(method) {
+    return method === "GET" || method === "HEAD" || method === "OPTIONS";
+}
+/**
+ * Who sent a write the route handler never saw, as far as its headers tell:
+ * the embed it is charged to (`foreign`) and the off-app page it came from
+ * (`offApp`), the two inputs `judgeUnseenWrite` takes from the sender.
+ *
+ * The sending frame may be gone, so its URL is not known. The page it was
+ * sent from is its Referer; where there is none, the page the session drives
+ * stands in for `offApp` only.
+ *
+ * - `foreign`: policy.ts `foreignWrite` with no frame chain, so a write out of
+ *   the app whose Origin header names another site is that site's embed's. A
+ *   sign-in provider's page reached as the whole page, beaconing to itself as
+ *   it is left, is therefore refused outside destructive; the route handler,
+ *   which knows the frame, would let it through. The cautious direction. An
+ *   `Origin: null` write out of the app is taken to be an embed's too, whether
+ *   or not the page embeds anything, since the page can no longer be asked.
+ * - The sign-in exception (a captcha on the app's own sign-in page) is judged
+ *   against the Referer, the page the request was sent from, never against
+ *   whatever page the session has moved to by the time the request is seen.
+ *   With no Referer it does not apply.
+ * - Trusted embeds (safe-write only) are judged by the Origin header alone.
+ */
+export function unseenWriteSource(input) {
+    const { appUrl, mode, url, originHeader, referer } = input;
+    let foreign = foreignWrite(appUrl, { url, frameChain: [], frameUrl: null, originHeader, pageHasForeignFrame: true });
+    if (foreign && referer && allowsForeignWriteOnSignIn(mode, referer, appUrl))
+        foreign = null;
+    if (foreign && trustsForeignWrite(mode, input.trustedEmbeds, appUrl, { frameChain: [], originHeader, unadoptedPageUrl: null }))
+        foreign = null;
+    const offApp = offAppPageWrite(appUrl, referer ?? input.currentPageUrl, url, input.movedByEmbed);
+    return { foreign, offApp };
+}
+/**
+ * The route handler's verdict on a write, from what a browser-level
+ * interception can know about it. Same rules in the same order: a write
+ * another site's frame sends outside the app is refused; so is one sent from
+ * a page an embed moved off the app, a sign-in excepted; a sign-in passes;
+ * then the mode decides. `foreign` and `offApp` come from
+ * `unseenWriteSource`, since the sending frame may no longer exist.
+ * The one step it does not take is safe-write's short wait for a creation
+ * still in flight: a page being left has nothing more to wait for.
+ */
+export function judgeUnseenWrite(input) {
+    const { mode, method, pathname, destructiveWire } = input;
+    if (mode === "destructive" || isReadMethod(method))
+        return { allow: true };
+    if (input.foreign)
+        return { allow: false, why: `sent from a frame of ${input.foreign}` };
+    const authExempt = isAuthExempt(mode, method, pathname, destructiveWire);
+    if (input.offApp && !authExempt)
+        return { allow: false, why: `sent from a page of ${input.offApp}, outside the app` };
+    if (authExempt)
+        return { allow: true };
+    return allowsWrite(mode, method, destructiveWire, input.owned) ? { allow: true } : { allow: false };
+}
+/**
+ * How long a write the route handler let through stays on the ledger. The
+ * browser-level pause follows the route handler's `continue` within
+ * milliseconds; an entry that outlives this is a request that never reached
+ * the network (answered by a service worker, cancelled by the page).
+ */
+export const ROUTED_WRITE_TTL_MS = 5000;
+/** Entries past this many are dropped oldest first: a page that posts in a loop cannot grow the ledger without bound. */
+const MAX_ROUTED_WRITES = 200;
+/** A request body's identity for the ledger: the SHA-256 of its bytes, or "" for no body. */
+export function bodyDigest(body) {
+    return body && body.length > 0 ? createHash("sha256").update(body).digest("hex") : "";
+}
+/**
+ * The writes the route handler has already judged and let through, so the
+ * browser-level interception, which sees them again, lets them pass without
+ * judging them twice. The key is the mode, the method, the URL and the body's
+ * digest (`bodyDigest`), so a write let through can only excuse the very same
+ * request: never one with another body to the same URL, such as a delete
+ * command sent where a harmless save was allowed a moment before, and never
+ * one sent after a flow switched to a stricter rule. A write is claimed once:
+ * two identical requests, one routed and one not, leave the second to be
+ * judged. Requests the route handler refused never reach the browser level,
+ * so they are not recorded.
+ */
+export class RoutedWrites {
+    ttlMs;
+    entries = [];
+    constructor(ttlMs = ROUTED_WRITE_TTL_MS) {
+        this.ttlMs = ttlMs;
+    }
+    static key(mode, method, url, digest) {
+        return `${mode} ${method} ${url.split("#")[0]} ${digest}`;
+    }
+    prune(now) {
+        this.entries = this.entries.filter((e) => now - e.at <= this.ttlMs);
+        if (this.entries.length > MAX_ROUTED_WRITES)
+            this.entries = this.entries.slice(-MAX_ROUTED_WRITES);
+    }
+    note(mode, method, url, digest, now = Date.now()) {
+        this.prune(now);
+        this.entries.push({ key: RoutedWrites.key(mode, method, url, digest), at: now });
+    }
+    /** Whether the route handler let this write through a moment ago; each note is claimed at most once. */
+    claim(mode, method, url, digest, now = Date.now()) {
+        this.prune(now);
+        const key = RoutedWrites.key(mode, method, url, digest);
+        const i = this.entries.findIndex((e) => e.key === key);
+        if (i < 0)
+            return false;
+        this.entries.splice(i, 1);
+        return true;
+    }
+    clear() {
+        this.entries = [];
+    }
+}
+/** How long a write refused at the browser level stays recognisable to the driver's request events. */
+export const UNSEEN_REFUSAL_TTL_MS = 10000;
+/**
+ * Writes refused at the browser level, which the driver may still report as
+ * requests of its own: a 307 or 308 hop is a request Playwright knows, and it
+ * then sees it fail (ERR_BLOCKED_BY_CLIENT). Without this the refusal was also
+ * filed as the app's failed request and listed as a possible mutation. Keyed
+ * by method and URL (fragment dropped), since the driver's request object is
+ * not the paused one; kept briefly, and not consumed, since several listeners
+ * ask about the same request.
+ */
+export class UnseenRefusals {
+    ttlMs;
+    entries = [];
+    constructor(ttlMs = UNSEEN_REFUSAL_TTL_MS) {
+        this.ttlMs = ttlMs;
+    }
+    static key(method, url) {
+        return `${method} ${url.split("#")[0]}`;
+    }
+    prune(now) {
+        this.entries = this.entries.filter((e) => now - e.at <= this.ttlMs);
+        if (this.entries.length > MAX_ROUTED_WRITES)
+            this.entries = this.entries.slice(-MAX_ROUTED_WRITES);
+    }
+    note(method, url, now = Date.now()) {
+        this.prune(now);
+        this.entries.push({ key: UnseenRefusals.key(method, url), at: now });
+    }
+    has(method, url, now = Date.now()) {
+        this.prune(now);
+        const key = UnseenRefusals.key(method, url);
+        return this.entries.some((e) => e.key === key);
+    }
+    clear() {
+        this.entries = [];
+    }
+}
+/**
+ * The body of a request paused by the DevTools Fetch domain, as bytes: the
+ * base64 entries decoded and joined, else the plain `postData`. Undefined when
+ * the protocol sent neither (a body too large to include). Its digest then
+ * matches no routed write, so the request is judged, on its URL alone.
+ */
+export function pausedRequestBytes(request) {
+    const entries = request.postDataEntries?.filter((e) => typeof e.bytes === "string");
+    if (entries && entries.length > 0)
+        return Buffer.concat(entries.map((e) => Buffer.from(e.bytes, "base64")));
+    return request.postData === undefined ? undefined : Buffer.from(request.postData, "utf8");
+}
+/** The same body as text, for the policy's body rules. */
+export function pausedRequestBody(request) {
+    return pausedRequestBytes(request)?.toString("utf8");
+}
+/** A header's value from a DevTools header map, whose names keep the case they were sent with. */
+export function headerOf(headers, name) {
+    if (!headers)
+        return undefined;
+    const wanted = name.toLowerCase();
+    for (const [k, v] of Object.entries(headers))
+        if (k.toLowerCase() === wanted)
+            return v;
+    return undefined;
+}

package/dist/engine/verify.js

@@ -23,6 +23,7 @@
  * Pure, so the ordering and the wording can be table-tested.
  */
 import { normalizePath } from "./fingerprint.js";
+import { failingSignatures } from "./memory.js";
 /** What a re-test found. */
 export const VERDICTS = ["gone", "present", "changed"];
 export const VERDICT_MEANING = {
@@ -140,3 +141,121 @@ export function sayVerification(f) {
         return ` · re-tested ${on}, behaviour has changed since it was filed`;
     return ` · re-tested ${on}`;
 }
+// ---------------------------------------------------------------------------
+// Re-testing by page load, for `scenescout check`.
+//
+// The campaign above hands findings to an agent, who re-walks them with
+// judgement. A check has none, so it re-tests only the findings whose
+// reproduction is mechanical: the evidence names a GET that failed with a
+// status, and the finding's repro shows nothing done on its page but looking
+// at it. Loading that page again and watching the same request is then the
+// whole reproduction, and its answer is a fact rather than an opinion.
+// ---------------------------------------------------------------------------
+/**
+ * Actions that only look at a page. A repro whose steps on the finding's page
+ * are all of these was reproduced by loading the page; any other step (a
+ * click, a typed value, a replayed request, anything this list does not know)
+ * means loading it is not the reproduction.
+ */
+const LOOK_ONLY = new Set([
+    "attach",
+    "navigate",
+    "plan:navigate",
+    "crawl",
+    "back",
+    "snapshot",
+    "screenshot",
+    "design-audit",
+    "task",
+    "journey:start",
+    "journey:end",
+    "record:full",
+]);
+/** How the finding's page is reached again, or null when a check cannot re-test it deterministically. */
+export function loadRetest(item) {
+    const signatures = [...failingSignatures(item.evidence)];
+    // A POST that failed is not re-sent by loading a page, and a check would refuse to send it anyway.
+    if (signatures.length === 0 || signatures.some((s) => !s.startsWith("GET ")))
+        return null;
+    // The first repro line is how the page was reached; every later one happened on it.
+    if (item.repro.length === 0)
+        return null;
+    for (const line of item.repro.slice(1)) {
+        if (!LOOK_ONLY.has(line.split(/\s/, 1)[0]))
+            return null;
+    }
+    let url;
+    try {
+        url = new URL(item.url);
+    }
+    catch {
+        return null;
+    }
+    // A secret was redacted out of the stored URL: loading what is left is a different page.
+    if (/redacted/i.test(item.url))
+        return null;
+    return { item, path: `${url.pathname}${url.search}`, signatures };
+}
+export const RETEST_VERDICTS = ["reproduces", "possibly-fixed", "not-reached"];
+/**
+ * Each re-testable finding against the page load that re-tests it.
+ *
+ * `reproduces` when the load saw one of the finding's failing requests fail
+ * with the same status; `possibly-fixed` when the page loaded and none did —
+ * possibly, because the page may simply not have asked this time; and
+ * `not-reached` when the page did not load or bounced to sign-in, which says
+ * nothing about the finding either way.
+ */
+export function retestResults(candidates, pages) {
+    return candidates.map(({ item, path, signatures }) => {
+        const base = { id: item.id, severity: item.severity, title: item.title, path, signatures };
+        const page = pages.find((p) => p.path === path);
+        if (!page)
+            return { ...base, verdict: "not-reached", note: "the page was not visited" };
+        if (page.loadError !== undefined)
+            return { ...base, verdict: "not-reached", note: "the page did not load" };
+        if (page.loginRedirect)
+            return { ...base, verdict: "not-reached", note: "the page sent the browser to sign-in" };
+        const seen = new Set();
+        for (const detail of page.httpErrors)
+            for (const s of failingSignatures(detail))
+                seen.add(s);
+        // The document's own failure is left out of the violations (withoutOwnResponse), so it is added back here.
+        if (page.status !== null && page.status >= 400)
+            for (const s of failingSignatures(`GET ${page.path.split("?")[0]} ${page.status}`))
+                seen.add(s);
+        return { ...base, verdict: signatures.some((s) => seen.has(s)) ? "reproduces" : "possibly-fixed" };
+    });
+}
+/**
+ * The findings a check re-tests: the open ones it can reproduce by loading a
+ * page, in the campaign's order and within its cap, plus how many open
+ * findings there are in all, so the report can say how many it left to a run.
+ */
+export function checkRetestPlan(findings) {
+    const open = findings.filter((f) => (f.status ?? "open") !== "resolved");
+    const eligible = open.filter((f) => loadRetest(item(f)) !== null);
+    const candidates = verifyWorklist(eligible)
+        .map(loadRetest)
+        .filter((c) => c !== null);
+    return { candidates, open: open.length };
+}
+/**
+ * The entries of a memory file's findings list a re-test can read. The file is
+ * JSON someone may have edited; an entry missing the fields the rules read is
+ * left out rather than failing the check, which only ever reports re-tests.
+ */
+export function wellFormedFindings(list) {
+    return list.filter((f) => {
+        if (typeof f !== "object" || f === null)
+            return false;
+        const x = f;
+        return (typeof x.id === "string" &&
+            typeof x.url === "string" &&
+            typeof x.title === "string" &&
+            typeof x.severity === "string" &&
+            (x.evidence === undefined || typeof x.evidence === "string") &&
+            Array.isArray(x.repro) &&
+            x.repro.every((r) => typeof r === "string"));
+    });
+}

package/dist/mcp-server.js

@@ -34,7 +34,7 @@ import { ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, McpError }
 import { z } from "zod";
 import { BrowserEngine } from "./engine/browser.js";
 import { reapOrphanBrowsers } from "./engine/reaper.js";
-import { FINDING_CATEGORIES, MemoryStore, redactSecrets } from "./engine/memory.js";
+import { FINDING_CATEGORIES, MemoryStore, mergeableCategories, redactSecrets } from "./engine/memory.js";
 import { decodedEntitiesNote, LANE_NAME_MAX, LaneLedger, laneCloseGuard, laneReportInstruction, parseLaneReport, summarizeLaneReport } from "./engine/lane.js";
 import { MAX_UNFILED_NAMED, unfiledDefects } from "./engine/calibration.js";
 import { SessionQueue, withWatchdog } from "./engine/dispatch.js";
@@ -849,7 +849,7 @@ server.registerTool("scout_crawl", {
     }
 }, 600_000));
 server.registerTool("scout_run_plan", {
-    description: "Execute up to 20 actions in ONE call — use for mechanical sequences (fill a form, walk a wizard) so each step doesn't cost a round-trip. Targets resolve at execution time by semantic locator: 'testid=…', 'text=…', or 'label=…' (never snapshot refs). An `upload` step attaches a file as scout_upload does (target required — the file input or the control that opens its chooser; value = a fixture kind or a project-relative path). The plan ABORTS at the first NEW oracle violation, policy refusal, or failed step, returning a transcript of how far it got; repeats of already-reported violations do not abort (they stay logged for the report).",
+    description: "Execute up to 20 actions in ONE call — use for mechanical sequences (fill a form, walk a wizard) so each step doesn't cost a round-trip. Targets resolve at execution time by semantic locator: 'testid=…', 'text=…', 'label=…' or 'role=button[name=Save]' (never snapshot refs). The same steps, saved to .scenescout/flows/<name>.json with expect-text / expect-url / expect-request steps added, are replayed by `scenescout check` on every pull request. An `upload` step attaches a file as scout_upload does (target required — the file input or the control that opens its chooser; value = a fixture kind or a project-relative path). The plan ABORTS at the first NEW oracle violation, policy refusal, or failed step, returning a transcript of how far it got; repeats of already-reported violations do not abort (they stay logged for the report).",
     inputSchema: {
         steps: z
             .array(z.object({
@@ -857,7 +857,7 @@ server.registerTool("scout_run_plan", {
             target: z
                 .string()
                 .optional()
-                .describe("testid=…, text=…, label=… (or a path for navigate; 'top'/'bottom'/±px for scroll; for upload: the file input or the control that opens its chooser)"),
+                .describe("testid=…, text=…, label=…, role=<role>[name=\"…\"] (or a path for navigate; 'top'/'bottom'/±px for scroll; for upload: the file input or the control that opens its chooser)"),
             value: z
                 .string()
                 .optional()
@@ -1168,7 +1168,7 @@ server.registerTool("scout_finding", {
             ? `Finding recorded: [${finding.severity}] ${finding.title} (id ${finding.id})`
             : finding.regressedAt
                 ? `⟳ REOPENED as a REGRESSION: finding ${finding.id} was previously resolved but the evidence reproduces again (seen in ${finding.runs} runs). Worth calling out to the user.`
-                : `Not recorded as new: merged into existing finding ${finding.id} — [${finding.severity}] ${finding.title}${finding.evidence ? ` (evidence: ${finding.evidence.slice(0, 160)})` : " (no evidence)"}, seen in ${finding.runs} runs. If yours is a different bug, file it again with evidence naming the request that failed for you (method and path): two findings are kept apart when both name requests and none is shared.`, session);
+                : `Not recorded as new: merged into existing finding ${finding.id} — [${finding.severity}] ${finding.title}${finding.evidence ? ` (evidence: ${finding.evidence.slice(0, 160)})` : " (no evidence)"}, filed as ${finding.category}, seen in ${finding.runs} runs. If yours is a different bug, file it again: under the category that says what is wrong if it is another kind of defect (a finding filed as ${category} merges only with one filed as ${mergeableCategories(category).join(" or ")}), or with evidence naming the request that failed for you (method and path) — two findings are kept apart when both name requests and none is shared.`, session);
     }
     catch (err) {
         return errorText(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenescout",
-  "version": "3.10.0",
+  "version": "3.11.1",
   "description": "SceneScout — exploratory UI testing for AI coding agents. An MCP server that gives any agent (Claude Code, Cursor, VS Code Copilot, Codex, Gemini CLI and others) a structured view of a running web app, always-on oracles, a network-level write policy, memory across runs and a gap-checked report.",
   "license": "MIT",
   "author": "brunoboto96",
@@ -64,6 +64,7 @@
     "format:check": "prettier --check .",
     "demo": "npm run build && tsx scripts/demo.ts",
     "demo:serve": "node demo-app/server.mjs",
+    "holdout:serve": "node holdout-app/server.mjs",
     "dev": "tsx src/cli.ts",
     "serve": "node dist/mcp-server.js",
     "smoke": "npm run build && npm run smoke:run",
@@ -71,7 +72,7 @@
     "mcp-check": "npm run build && npm run mcp-check:run",
     "mcp-check:run": "tsx scripts/mcp-check.ts",
     "test": "npm run build && npm run test:unit && npm run smoke:run && npm run mcp-check:run",
-    "test:unit": "npm run scan-test && npm run oracle-test && npm run policy-test && npm run fixture-test && npm run dispatch-test && npm run design-test && npm run check-test && npm run contract-test && npm run pace-test && npm run request-test && npm run settle-test && npm run claims-test && npm run verify-test && npm run brief-test && npm run lane-test && npm run calibration-test && npm run bench-test && npm run memory-test && npm run install-test && npm run live-test && npm run demo-test && npm run hygiene-test",
+    "test:unit": "npm run scan-test && npm run oracle-test && npm run policy-test && npm run fixture-test && npm run dispatch-test && npm run design-test && npm run check-test && npm run contract-test && npm run pace-test && npm run request-test && npm run settle-test && npm run claims-test && npm run verify-test && npm run brief-test && npm run lane-test && npm run calibration-test && npm run bench-test && npm run memory-test && npm run install-test && npm run live-test && npm run demo-test && npm run holdout-test && npm run hygiene-test",
     "scan-test": "tsx scripts/scan-test.ts",
     "oracle-test": "tsx --test scripts/oracle-test.ts",
     "policy-test": "tsx --test scripts/policy-test.ts",
@@ -85,6 +86,7 @@
     "install-test": "tsx --test scripts/install-test.ts",
     "live-test": "tsx --test scripts/live-test.ts",
     "demo-test": "tsx --test scripts/demo-test.ts",
+    "holdout-test": "tsx --test scripts/holdout-test.ts",
     "hygiene-test": "tsx --test scripts/hygiene-test.ts",
     "pace-test": "tsx --test scripts/pace-test.ts",
     "request-test": "tsx --test scripts/request-test.ts",

package/skills/scenescout/SKILL.md

@@ -33,7 +33,7 @@ You are the brain of an exploratory UI tester. The SceneScout MCP server gives y
 
 1. **`scout_crawl` first, always.** One call visits every known route (pass `paths` to sweep a specific subset instead), records coverage, and returns per-route health. This is the whole breadth pass — do not visit routes one-by-one with navigate+snapshot.
 2. **Investigate what the crawl flagged.** For each problem route (violations, dead-ends, auth-redirects): navigate there, `scout_snapshot`, reproduce, then `scout_finding`.
-3. **Run journeys with `scout_run_plan {steps}`.** Mechanical sequences (fill form → submit → check) go in ONE plan call — `steps` is an ordered list of `{action, target, value}` — with `testid=`/`text=`/`label=` targets — not one LLM turn per click. The plan aborts at the first violation and tells you where; that's your cue to investigate interactively.
+3. **Run journeys with `scout_run_plan {steps}`.** Mechanical sequences (fill form → submit → check) go in ONE plan call — `steps` is an ordered list of `{action, target, value}` — with `testid=`/`text=`/`label=`/`role=button[name="Save"]` targets — not one LLM turn per click. The plan aborts at the first violation and tells you where; that's your cue to investigate interactively. When the user wants a flow kept working, save the plan that walked it as `.scenescout/flows/<name>.json` — `{"name", "steps"}`, the same steps, starting with a `navigate`, plus `{"action":"expect-text","text"}`, `{"action":"expect-url","pattern"}` or `{"action":"expect-request","request":"GET /api/…","status":200}` where the outcome shows — and `scenescout check` replays it on every pull request. Save only flows that read: a check replays flows under observe's rule unless the project passes `--flow-writes allow`, so a step that sends a write is reported as "could not run" and the check exits 2.
 4. **Snapshot economics:** `scout_snapshot` after landing somewhere new; re-snapshots of the same route return *diffs* with stable refs — "No element changes" costs you almost nothing. `scout_screenshot` ONLY for suspected pixel-native issues (a canvas, a rendering glitch); geometry problems (overlap, off-screen, a covered control) are already in the snapshot as GEOMETRY issues, and images that failed to load are listed under BROKEN IMAGES — file those, quoting the line. Controls inside embeds (`<iframe>`) are listed with the page's, each marked `⟨in … frame⟩`, and act by ref like any other. A frame of the app's own origin is the app: test it fully. A frame of another site (`cross-origin`) is someone else's system that the user has not authorised you to test: click and type there as a user would, to see the embed render and respond, but never send it hostile input — the engine refuses markup, values over 200 characters, control characters, repeated-click probes and uploads there, and you must not try SQL, template or other injection shapes either — and file what you find there as the embed's behaviour, naming its origin, not as the app's bug. A failing request such a frame sent outside the app says so (`in an embed of …`) and is kept at medium; console errors cannot be told apart by frame and stay the app's; its controls are counted apart and never enter the app's coverage or gap ledger. Its container text is masked, and the writes it sends outside the app are refused in every mode but destructive — unless the user names that origin as a trusted embed (a provider in test mode, say): pass it in `scout_attach {trustedEmbeds: ["https://…"]}` and, in safe-write only, its writes go out. Never add an origin the user did not name. The FRAMES line names frames that were not read; say in your summary that their contents were not explored.
 5. **Native-user behaviours.** `scout_type {ref, textValue}` (or its alias `value`, matching `scout_select` and a plan step) APPENDS when a field already has content (menu clicks often insert @-mention chips or commands into composers — appending preserves them; the result reports what was already there); pass `replace=true` only to deliberately clear, and `pressEnter=true` to submit from the field the way a user would. Before concluding a badge, icon, or "N errors" indicator *does nothing*, `scout_hover` it — tooltips and hover cards are invisible to snapshots and clicks, and hover output includes what appeared. In HEADED mode (`scout_attach {headed:true}`, which the user asks for when they want to watch) the user's physical mouse competes with the synthetic pointer: if a hover reveals nothing and the finding matters, ask the user to move their mouse off the browser window and retry before filing. **Scroll long pages with `scout_scroll`** — the design audit and snapshot measure at the current scroll position, so judge deep sections by scrolling then re-auditing; it refuses to scroll where a real user couldn't and reports SCROLL LOCKED (the leaked modal scroll-lock that silently amputates everything below the fold — snapshots also flag it passively as an OVERLAY line), and scrolling triggers lazy-loaded content whose failures surface as fresh oracle violations. Elements fully clipped inside an overflow-hidden container are flagged UNREACHABLE in GEOMETRY issues — no amount of scrolling reveals them; that's a high-value layout bug, distinct from merely below-the-fold content. **A page can hold SEVERAL independent scroll regions** and plain `scout_scroll` moves the largest one, so a sidebar nav beside a taller main pane never budges: pass `scout_scroll {target:"testid=…"}` to scroll one region. Never report a nav item, tab or list row as missing/truncated until you have scrolled ITS container — content scrolled out of a secondary pane looks exactly like content that was cut off.
 6. **The rest of the input vocabulary.** `scout_select` sets a `<select>` option by value or visible label — use it rather than clicking a native dropdown open, which does not render as page DOM. `scout_press` sends a real key to the focused element (`Escape` to dismiss a modal, `Tab` to walk focus order, `Enter` to submit from a field); it is also how the keyboard-only pass at `extensive` is performed, and it vets the focused control first so a destructive action cannot be triggered blind in read-only mode. **`scout_upload {ref}` attaches a file the way a user does** — `ref` is a visible `<input type=file>` (snapshots list these with role `file`; `scout_type` on one redirects here) OR the button/label/dropzone that opens the file chooser (the chooser is intercepted and answered — that is how the hidden input behind a styled "Choose file" control is reached); omit `ref` when the page has exactly one file input, hidden or not (snapshots disclose hidden ones on a FILE INPUTS line). Nothing needs to exist on disk: a small VALID fixture is generated in memory, its kind inferred from the input's `accept` attribute or chosen with `fixture` (`pdf`, `png`, `txt`, `csv`, `json`); `filePath` uploads a real file but must live inside the attached project (fenced, like navigation is fenced to the origin); `name` overrides the filename. The result flags a file that violates `accept` (a mismatch the app then ACCEPTS is a validation finding), warns when the app cleared the input after selection, and says whether a state-changing request fired on selection — if none did, either click the form's submit or read the next snapshot for a client-side rejection. Plans take `{action:"upload", target, value:"pdf"}` steps (`target` required). When the input or its trigger was addressed by `ref`, the gap ledger counts an attached-but-unsent file as filled-never-submitted; the ref-less path has no listed element to mark.