scenescout 3.7.0 → 3.9.0

package/dist/engine/browser.js

@@ -1,4 +1,4 @@
-import { chromium, firefox, webkit } from "playwright";
+import { chromium, firefox, webkit, } from "playwright";
 import fs from "node:fs";
 import path from "node:path";
 import { elementKey, fingerprintState, isNonPageRoute, normalizePath } from "./fingerprint.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, 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, } from "./collector.js";
 import { OracleMonitor, formatViolations } from "./oracles.js";
 import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js";
 import { formatJourney, measureJourney } from "./journey.js";
@@ -20,7 +20,7 @@ import { explainLaunchFailure, isMissingBrowser } from "./launch.js";
 import { ACTION_TIMEOUT_MS, performScroll, probeFocusIndicators, probeOverlays, scrollContainer } from "./probes.js";
 import { BROWSER_MARKER, reapOrphanBrowsers } from "./reaper.js";
 import { planUploadOptions, resolveDiskUpload } from "./uploads.js";
-import { answersWithRefusal, destructiveRefusal, isDestructive, isDestructiveWire, allowsWrite, policyRefusal, isAuthExempt, } from "./policy.js";
+import { answersWithRefusal, destructiveRefusal, isDestructive, isDestructiveWire, allowsWrite, policyRefusal, foreignFrameOrigin, foreignWrite, withForeignFrameSandbox, offAppPageWrite, embedOfRequest, hostileForEmbed, trustedEmbedOrigins, MAX_TRUSTED_EMBEDS, trustsForeignWrite, embedProbeRefusal, EmbedMoveTracker, sandboxedRedirectPage, allowsForeignWriteOnSignIn, isAuthExempt, } from "./policy.js";
 import { scanProject } from "../scan.js";
 import { analyzeDesign, DESIGN_COLLECT_SCRIPT } from "./design.js";
 import { acceptMatches, generatedUpload } from "./fixtures.js";
@@ -52,6 +52,35 @@ const CHOOSER_GRACE_MS = 2000;
 const HOVER_REVEAL_WINDOW_MS = 2500;
 /** Non-GET traffic that is auth/telemetry plumbing, not tester-caused state mutation. */
 const BENIGN_MUTATION_RE = /\/auth\/(refresh|token|session)|refresh[-_]?token|\/telemetry|\/analytics|\/heartbeat|\/sentry|\/collect\b|\/logs?\b|\/metrics\b/i;
+/**
+ * What the policy needs to know about where a request came from: the URLs of
+ * the frame that sent it and of its parents, up to but not including the top
+ * document, and that frame's own URL (null when the browser attributes it to no
+ * frame, as for a new window or a service worker).
+ */
+function requestSource(req) {
+    const frameChain = [];
+    let frame;
+    try {
+        frame = req.frame();
+    }
+    catch {
+        return { frameChain, frameUrl: null };
+    }
+    const frameUrl = frame.url();
+    const top = frame.page().mainFrame();
+    while (frame && frame !== top) {
+        frameChain.push(frame.url());
+        frame = frame.parentFrame();
+    }
+    return { frameChain, frameUrl };
+}
+/** The `why` of a top-window navigation refused as a possible frame escape; the notice words it on its own. */
+const ESCAPE_REFUSAL = "a possible frame escape";
+/** The most frames a snapshot reads controls from. */
+const MAX_READ_FRAMES = 10;
+/** How long a snapshot waits for its frames' elements to answer. */
+const FRAME_READ_MS = 1500;
 /** 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`;
@@ -153,6 +182,9 @@ export class BrowserEngine {
     projectDirNote = "";
     memory = null;
     mode = "read-only";
+    /** Origins named as trusted embeds (policy.ts trustsEmbedWrite decides when that counts). */
+    trustedEmbeds = new Set();
+    trustNotice = "";
     /** Human label for the auth identity driving this session (the server sets it from the storage-state filename). */
     role = "anonymous";
     /** Named-session id (the server sets it; every engine shares one MemoryStore, so
@@ -601,6 +633,18 @@ export class BrowserEngine {
             throw new Error(`storageStatePath does not exist: ${opts.storageStatePath}`);
         }
         this.mode = opts.mode ?? "read-only";
+        const trust = trustedEmbedOrigins(opts.trustedEmbeds);
+        this.trustedEmbeds = new Set(trust.origins);
+        this.trustNotice =
+            (trust.origins.length > 0
+                ? this.mode === "safe-write"
+                    ? ` Trusted embeds: ${trust.origins.join(", ")} — writes their frames send outside the app go out in this mode; hostile input, repeated-click probes and uploads stay refused.`
+                    : this.mode === "destructive"
+                        ? ` Trusted embeds (${trust.origins.join(", ")}) are not needed in destructive mode, which lets every embed's writes out.`
+                        : ` Trusted embeds (${trust.origins.join(", ")}) are ignored in ${this.mode} mode: they apply in safe-write only.`
+                : "") +
+                (trust.rejected.length > 0 ? ` Not a plain http(s) origin, so not trusted: ${trust.rejected.join(", ")}.` : "") +
+                (trust.overflow.length > 0 ? ` More than ${MAX_TRUSTED_EMBEDS} trusted embeds; not trusted: ${trust.overflow.join(", ")}.` : "");
         this.sessionObjective = (opts.objective ?? "").trim().replace(/\s+/g, " ").slice(0, 300);
         // An agent-supplied task counts as stated; the placeholder does not.
         this.setTask(opts.task ?? "Attaching and taking stock", opts.task !== undefined);
@@ -616,6 +660,7 @@ export class BrowserEngine {
         this.contradictionsReported = new Set();
         this.pendingCreations = new Set();
         this.baseUrl = opts.url.replace(/\/$/, "");
+        this.embedMoves = new EmbedMoveTracker(this.baseUrl);
         // Ownership (ownedIds/createdResources) deliberately NOT reset here: it
         // lives on the shared MemoryStore for the whole run, so re-attaching one
         // role must not discard what another role already created — otherwise
@@ -637,6 +682,18 @@ export class BrowserEngine {
         }
         this.oracles = new OracleMonitor();
         this.oracles.setPolicyRefusalCheck((req) => this.refusedByPolicy.has(req));
+        // A request an embed sends to the app is the app's to answer: only one headed outside the app is the embed's.
+        this.oracles.setEmbedAttribution((req) => {
+            let site = null;
+            try {
+                const frame = req.frame();
+                site = frame === frame.page().mainFrame() ? null : this.foreignOriginOf(frame);
+            }
+            catch {
+                /* no frame: a service worker's or a new window's first request */
+            }
+            return embedOfRequest(this.baseUrl, req.url(), site);
+        });
         this.lastSnap = null;
         this.designAuditCount = 0;
         // The engine learns the route list itself so completion is an objective,
@@ -688,6 +745,17 @@ export class BrowserEngine {
             this.watchResponse(res.request(), res.status());
         });
         this.context.on("request", (req) => {
+            // Who moved the driven page, decided on its navigation's first request
+            // (this event fires before the route handler judges that page's writes).
+            if (req.isNavigationRequest() && !req.redirectedFrom()) {
+                try {
+                    if (this.page && req.frame() === this.page.mainFrame())
+                        this.embedMoves.navigationStarted(req.url(), req.headers()["referer"], this.embeddedSites());
+                }
+                catch {
+                    /* no frame: not the driven page */
+                }
+            }
             this.inFlight += 1;
             this.lastRequestStart = Date.now();
             const type = req.resourceType();
@@ -716,6 +784,13 @@ export class BrowserEngine {
                 return;
             if (this.readOnly && isDestructiveWire(pathnameOf(req.url()), req.postData()))
                 return;
+            // A foreign frame's write is refused in every mode the route handler runs in.
+            if (this.mode !== "destructive" && this.foreignWriteOf(req))
+                return;
+            if (this.mode !== "destructive" &&
+                offAppPageWrite(this.baseUrl, this.page?.url(), req.url(), this.embedMoves.movedTo) &&
+                !isAuthExempt(this.mode, method, pathnameOf(req.url()), isDestructiveWire(pathnameOf(req.url()), req.postData())))
+                return;
             const pageUrl = this.page?.url();
             if (pageUrl && this.memory) {
                 try {
@@ -731,12 +806,111 @@ export class BrowserEngine {
             await this.context.route("**/*", async (route) => {
                 const req = route.request();
                 const method = req.method();
+                // A redirect is followed by the browser without asking, so its target
+                // would load unsandboxed: a frame's redirect is answered with a
+                // sandboxed page that navigates there itself, and the next hop comes
+                // back here. Built from scratch: a redirect's framing or script
+                // headers never applied to a redirect, and would block this page.
+                const standIn = async (location, setCookie) => {
+                    const headers = {
+                        "content-type": "text/html; charset=utf-8",
+                        "content-security-policy": withForeignFrameSandbox(undefined),
+                        "cache-control": "no-store",
+                    };
+                    if (setCookie)
+                        headers["set-cookie"] = setCookie;
+                    await route.fulfill({ status: 200, headers, body: sandboxedRedirectPage(new URL(location, req.url()).href) });
+                };
+                // WebKit drops the sandbox for a frame that loads a data: URL in its own
+                // place. A top-window navigation out of the app, with no Referer, while
+                // a frame that held another site sits on a non-web URL, is that frame's
+                // escape: refused, judged on the page as it is when the request arrives.
+                if (method === "GET" && req.resourceType() === "document" && this.embedEscapeNavigation(req)) {
+                    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.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();
+                    await route.abort("blockedbyclient").catch(() => { });
+                    return;
+                }
+                const frameDoc = method === "GET" && req.resourceType() === "document" ? this.frameDocumentKind(req) : null;
+                // A document loading into a frame of another origin gets the sandbox
+                // that forbids popups and top-window navigation (policy.ts says why).
+                if (frameDoc === "foreign") {
+                    try {
+                        const res = await route.fetch({ maxRedirects: 0 });
+                        const headers = res.headers();
+                        const location = res.status() >= 300 && res.status() < 400 ? headers["location"] : undefined;
+                        if (location) {
+                            await standIn(location, headers["set-cookie"]);
+                            return;
+                        }
+                        headers["content-security-policy"] = withForeignFrameSandbox(headers["content-security-policy"]);
+                        await route.fulfill({ response: res, headers });
+                        return;
+                    }
+                    catch {
+                        // Fail closed: a frame that cannot be sandboxed is not loaded.
+                        await route.abort("blockedbyclient").catch(() => { });
+                        return;
+                    }
+                }
+                // The app's own frame document can redirect into another site, whose
+                // page would then load unsandboxed. Asked first, one hop at a time; a
+                // document that does not redirect loads as it would have, sent on
+                // rather than served from here — a served document counts as public in
+                // Chromium and could no longer reach an app on localhost. The price is
+                // a second GET of the app's frame documents that are not redirects.
+                if (frameDoc === "app") {
+                    try {
+                        const res = await route.fetch({ maxRedirects: 0 });
+                        const location = res.status() >= 300 && res.status() < 400 ? res.headers()["location"] : undefined;
+                        // Every hop, not only one out of the app: Playwright does not route the
+                        // later hops of a redirect, so a chain through the app and then out
+                        // would go unseen, and each hop is then fetched once, not twice.
+                        if (location) {
+                            await standIn(location, res.headers()["set-cookie"]);
+                            return;
+                        }
+                    }
+                    catch {
+                        /* could not ask: load it as it would have loaded */
+                    }
+                    await route.continue().catch(() => { });
+                    return;
+                }
                 if (method === "GET" || method === "HEAD" || method === "OPTIONS")
                     return route.continue();
                 const url = req.url();
                 const pathname = pathnameOf(url);
+                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.logAction({ action: "write-policy:blocked", target: `${method} ${pathname}${why ? ` (${why})` : ""}`, url: this.page?.url() ?? "" });
+                    this.refusedByPolicy.add(req);
+                    this.oracles.notePolicyBlock();
+                    // A script's request is answered with a refusal, so the page's handling
+                    // of one actually runs; a navigation is dropped (policy.ts says why).
+                    // Caught: a request the page has already cancelled rejects these, and an unhandled rejection ends the process.
+                    if (answered)
+                        return route.fulfill(policyRefusal(this.mode, method, pathname, req.headers()["origin"], why)).catch(() => { });
+                    return route.abort("blockedbyclient").catch(() => { });
+                };
+                // An embedded widget from another site writes to that site, not to the
+                // app under test: refused before any other rule, login included.
+                const foreign = this.foreignWriteOf(req);
+                if (foreign)
+                    return refuse(`sent from a frame of ${foreign}`);
                 this.rememberAuthHeader(req.headers());
                 const destructiveWire = isDestructiveWire(pathname, req.postData());
+                // An embed moved the session's page off the app: its writes out are not the app's, a sign-in excepted.
+                const offApp = offAppPageWrite(this.baseUrl, this.page?.url(), url, this.embedMoves.movedTo);
+                if (offApp && !isAuthExempt(this.mode, method, pathname, destructiveWire))
+                    return refuse(`sent from a page of ${offApp}, outside the app`);
                 // Auth/session flows must work in every mode — but never a destructive
                 // one, and in observe only the requests a login itself needs.
                 if (isAuthExempt(this.mode, method, pathname, destructiveWire))
@@ -776,17 +950,7 @@ export class BrowserEngine {
                     }
                     return route.continue();
                 }
-                const answered = answersWithRefusal(req.resourceType());
-                if (this.blockedRequests.length < 20)
-                    this.blockedRequests.push({ at: Date.now(), sig: `${method} ${url.slice(0, 140)}`, answered });
-                this.logAction({ action: "write-policy:blocked", target: `${method} ${pathname}`, url: this.page?.url() ?? "" });
-                this.refusedByPolicy.add(req);
-                this.oracles.notePolicyBlock();
-                // A script's request is answered with a refusal, so the page's handling
-                // of one actually runs; a navigation is dropped (policy.ts says why).
-                if (answered)
-                    return route.fulfill(policyRefusal(this.mode, method, pathname, req.headers()["origin"]));
-                return route.abort("blockedbyclient");
+                return refuse();
             });
         }
         // Popups / target=_blank: adopt same-origin pages as the active page (with
@@ -807,6 +971,7 @@ export class BrowserEngine {
                 if (sameOrigin) {
                     this.oracles.attach(newPage);
                     this.wireDialogHandler(newPage);
+                    this.wireEmbedMoves(newPage);
                     this.page = newPage;
                     this.refs.clear();
                     this.snapshotUrl = "";
@@ -819,6 +984,7 @@ export class BrowserEngine {
                 .catch(() => { });
         });
         this.wireDialogHandler(this.page);
+        this.wireEmbedMoves(this.page);
         try {
             await this.page.goto(opts.url, { waitUntil: "domcontentloaded", timeout: 20000 });
         }
@@ -859,9 +1025,51 @@ export class BrowserEngine {
             `Memory: ${this.memory.dir}.${this.memory.loadWarning ? ` WARNING: ${this.memory.loadWarning}` : ""}` +
             (this.memory.prunedStates > 0 ? ` Trimmed ${this.memory.prunedStates} old page state(s) from the history; coverage is unchanged.` : "") +
             `${this.memory.legacyDirNote ? ` ${this.memory.legacyDirNote}` : ""}` +
-            `${this.memory.gitIgnoreNote ? ` ${this.memory.gitIgnoreNote}` : ""} Call scout_snapshot to see the current state.` +
+            `${this.memory.gitIgnoreNote ? ` ${this.memory.gitIgnoreNote}` : ""}${this.trustNotice} Call scout_snapshot to see the current state.` +
             authWarning);
     }
+    /** Whether the page was moved off the app by one of its embeds (policy.ts EmbedMoveTracker). */
+    embedMoves = new EmbedMoveTracker("");
+    /**
+     * Frames that have held a document of another origin, with the first such
+     * origin. A frame that has since moved itself to a data: URL is still that
+     * site's; it leaves the record when it leaves the page, as every frame of a
+     * replaced document does, so nothing has to be cleared at the right moment.
+     * Sticky on purpose: a frame that went back to the app (a silent-renew frame
+     * landing on the app's callback) keeps counting as an embed, which refuses
+     * more, never less.
+     */
+    foreignFrames = new WeakMap();
+    /** The other sites the driven page embeds right now, by the frames still attached to it. */
+    embeddedSites() {
+        const out = new Set();
+        const page = this.page;
+        if (!page)
+            return out;
+        const top = page.mainFrame();
+        for (const frame of page.frames()) {
+            if (frame === top)
+                continue;
+            const origin = this.foreignFrames.get(frame) ?? foreignFrameOrigin(this.baseUrl, [frame.url()]);
+            if (origin)
+                out.add(origin);
+        }
+        return out;
+    }
+    /** Feed the page's navigations to the embed-move tracker and the foreign-frame record. Wired on every page we drive, like the dialog handler. */
+    wireEmbedMoves(page) {
+        page.on("framenavigated", (frame) => {
+            if (page !== this.page)
+                return;
+            if (frame === page.mainFrame()) {
+                this.embedMoves.pageLoaded(frame.url());
+                return;
+            }
+            const origin = foreignFrameOrigin(this.baseUrl, [frame.url()]);
+            if (origin && !this.foreignFrames.has(frame))
+                this.foreignFrames.set(frame, origin);
+        });
+    }
     /** Dialogs (confirm/alert): dismiss in read-only mode, accept otherwise. Must be wired on every page we drive, including adopted popups. */
     wireDialogHandler(page) {
         page.on("dialog", (dialog) => {
@@ -975,31 +1183,156 @@ export class BrowserEngine {
             if (stable)
                 break;
         }
+        const mainCount = rawElements.length;
+        // Then each frame's own controls, read once, each within its own limit.
+        const framed = await this.collectFrames(page);
         // Element identity is the coverage key (testid or role+name, ordinal-
         // disambiguated). When a key persists across snapshots of the same route,
         // its ref is REUSED — diffs stay meaningful and the agent's mental model
-        // (and previously issued refs) survive re-snapshots.
+        // (and previously issued refs) survive re-snapshots. An element inside a
+        // frame carries the frame in its key (collector.ts frameElementKey).
         const route = normalizePath(page.url());
         const prevByKey = this.lastSnap?.route === route ? this.lastSnap.byKey : null;
         this.refs.clear();
+        this.refFrames.clear();
         const keyCounts = new Map();
-        const elements = rawElements.map((el) => {
-            const baseKey = elementKey(el);
+        const all = [
+            ...rawElements.map((raw) => ({ raw })),
+            ...framed.flatMap((g) => g.raws.map((raw) => ({ raw: raw, frame: g.frame, tag: g.tag }))),
+        ];
+        const elements = all.map(({ raw: el, frame, tag }) => {
+            const baseKey = frameElementKey(elementKey(el), tag);
             const count = keyCounts.get(baseKey) ?? 0;
             keyCounts.set(baseKey, count + 1);
             const key = count === 0 ? baseKey : `${baseKey}~${count}`;
             const ref = prevByKey?.get(key)?.ref ?? `e${++this.refCounter}`;
             const full = {
                 ...el,
+                ...(tag ? { frame: tag } : {}),
+                // Judged on the real label, then masked: the policy must see what a click would press.
+                destructive: isDestructive(el.name, el.testid),
+                ...(tag?.foreign ? { name: masksForeignName(el.tag, el.role) ? MASKED_NAME : capForeignName(el.name) } : {}),
+                ...(tag?.foreign && el.href ? { href: stripForeignHref(el.href) } : {}),
                 ref,
                 key,
-                destructive: isDestructive(el.name, el.testid),
             };
             this.refs.set(ref, full);
+            if (frame)
+                this.refFrames.set(ref, frame);
             return full;
         });
-        this.harvestRoutes(elements);
-        return { elements, truncated: rawElements.length >= 150 };
+        this.harvestRoutes(elements.filter((el) => !el.frame?.foreign));
+        this.framesRead = new Set(framed.map((g) => g.frame));
+        return { elements, truncated: mainCount >= 150 };
+    }
+    /**
+     * The controls inside the page's frames, up to MAX_READ_FRAMES visible ones,
+     * each read within FRAME_READ_MS so one busy frame cannot stall a snapshot.
+     * Positions are moved into the page's coordinates (the frame element's box
+     * on screen, the frame's own scroll, the page's scroll), so geometry and
+     * the design audit can place them.
+     */
+    async collectFrames(page) {
+        const top = page.mainFrame();
+        const frames = page.frames().filter((f) => f !== top && !f.isDetached());
+        if (frames.length === 0)
+            return [];
+        const pageScroll = (await page.evaluate("({ x: window.scrollX, y: window.scrollY })").catch(() => null)) ?? {
+            x: 0,
+            y: 0,
+        };
+        const read = async (frame) => {
+            let timer;
+            const work = (async () => {
+                const el = await frame.frameElement();
+                const box = await el.boundingBox();
+                if (!box || box.width < 2 || box.height < 2)
+                    return null;
+                const title = ((await el.getAttribute("title")) || (await el.getAttribute("name")) || "").trim();
+                const got = (await frame.evaluate(`(() => ({ els: ${COLLECT_INTERACTABLES_SCRIPT}, sx: window.scrollX, sy: window.scrollY }))()`));
+                const raws = got.els.map((r) => ({ ...r, rect: frameToPageRect(r.rect, box, { x: got.sx, y: got.sy }, pageScroll) }));
+                let origin = "";
+                try {
+                    const u = new URL(frame.url());
+                    if (u.protocol === "http:" || u.protocol === "https:")
+                        origin = u.origin;
+                }
+                catch {
+                    /* no web address */
+                }
+                const foreignOrigin = this.foreignOriginOf(frame);
+                return { frame, tag: { url: frame.url(), origin: foreignOrigin ?? origin, title, foreign: foreignOrigin !== null }, raws };
+            })().catch(() => null);
+            const limit = new Promise((resolve) => {
+                timer = setTimeout(() => resolve(null), FRAME_READ_MS);
+            });
+            return Promise.race([work, limit]).finally(() => clearTimeout(timer));
+        };
+        // Visible frames first: a page's hidden plumbing frames must not use up the budget.
+        const boxes = await Promise.all(frames.map((f) => this.withinFrameLimit(f.frameElement().then((el) => el.boundingBox()))));
+        const visible = frames.filter((_, i) => {
+            const b = boxes[i];
+            return !!b && b.width >= 2 && b.height >= 2;
+        });
+        const got = await Promise.all(visible.slice(0, MAX_READ_FRAMES).map(read));
+        return got.filter((g) => g !== null);
+    }
+    /** The origin of another site's frame an element is in, or null for the page and the app's own frames. */
+    foreignEmbedOf(el) {
+        const frame = this.refFrames.get(el.ref);
+        const now = frame ? this.foreignOriginOf(frame) : null;
+        if (now)
+            return now;
+        return el.frame?.foreign ? el.frame.origin || el.frame.url : null;
+    }
+    /**
+     * The other site a frame belongs to, judged on the whole chain up to the
+     * page: a blank or srcdoc frame inside another site's frame is that site's,
+     * and so is a frame that once held its document (the foreign-frame record).
+     */
+    foreignOriginOf(frame) {
+        const top = frame.page().mainFrame();
+        const chain = [];
+        for (let f = frame; f && f !== top; f = f.parentFrame()) {
+            const recorded = this.foreignFrames.get(f);
+            if (recorded)
+                return recorded;
+            chain.push(f.url());
+        }
+        return foreignFrameOrigin(this.baseUrl, chain);
+    }
+    /** A frame read that gives up after FRAME_READ_MS, answering null. */
+    async withinFrameLimit(work) {
+        let timer;
+        const limit = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(null), FRAME_READ_MS);
+        });
+        return Promise.race([work.catch(() => null), limit]).finally(() => clearTimeout(timer));
+    }
+    /** Frames not directly under the page, less those whose controls were read anyway. */
+    unreadNestedFrames(page, nested) {
+        const top = page.mainFrame();
+        const readNested = [...this.framesRead].filter((f) => !f.isDetached() && f.parentFrame() !== top).length;
+        return Math.max(0, nested - readNested);
+    }
+    /** The frames whose controls the last snapshot listed. */
+    framesRead = new Set();
+    /** The frame each ref of the last snapshot lives in; refs of the page itself are absent. */
+    refFrames = new Map();
+    /**
+     * Where to look for a ref's element: its frame, or the page. A frame that has
+     * gone makes the ref stale, like a page that has navigated.
+     */
+    scopeOf(el) {
+        const frame = this.refFrames.get(el.ref);
+        if (!frame)
+            return this.requirePage();
+        if (frame.isDetached())
+            throw new Error(`The frame holding ${el.ref} has gone — take a new scout_snapshot.`);
+        // A frame that navigated holds a new document: the ref, and what it knew of the frame's site, are stale.
+        if (el.frame && frame.url() !== el.frame.url)
+            throw new Error(`The frame holding ${el.ref} has navigated — take a new scout_snapshot.`);
+        return frame;
     }
     /**
      * Collect the current page and REGISTER it as a visited state, returning the
@@ -1106,7 +1439,7 @@ export class BrowserEngine {
                 memory.wasExercised(fp, el.key) ? "done" : null,
                 el.href ? `href=${el.href.slice(0, 60)}` : null,
             ].filter(Boolean);
-            return `${el.ref} ${el.role} "${displayName(el)}"${flags.length ? ` [${flags.join(", ")}]` : ""}`;
+            return `${el.ref} ${el.role} "${displayName(el)}"${flags.length ? ` [${flags.join(", ")}]` : ""}${el.frame ? ` ⟨in ${frameLabel(el.frame)}⟩` : ""}`;
         };
         // Diff mode: when re-snapshotting the same route, report only what
         // changed — same idea as UI reconciliation, applied to agent context.
@@ -1155,10 +1488,19 @@ export class BrowserEngine {
                 `Interactables (${elements.length}${truncated ? "+ — TRUNCATED at 150, dense page" : ""}${missingTestids ? `, ${missingTestids} missing data-testid` : ""}):\n` +
                     elements.map(line).join("\n");
         }
-        const geometry = geometryIssues(elements, page.viewportSize() ?? { width: 1280, height: 900 });
+        // 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 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();
         const title = await page.title();
@@ -1169,13 +1511,26 @@ export class BrowserEngine {
             body +
             (geometry.length > 0 ? `\nGEOMETRY issues:\n` + geometry.map((g) => `  ⚠ ${g}`).join("\n") : "") +
             (brokenImages.length > 0 ? `\nBROKEN IMAGES:\n` + brokenImages.map((b) => `  ⚠ ${b}`).join("\n") : "") +
+            (frames.length > 0 || nestedFrames > 0
+                ? `\n` +
+                    frameLines(this.baseUrl, frames, {
+                        nested: this.unreadNestedFrames(page, nestedFrames),
+                        writesRefused: this.mode !== "destructive",
+                        trustedWrites: this.mode === "safe-write" ? this.trustedEmbeds : undefined,
+                        read: new Set([...this.framesRead].map((f) => f.url())),
+                    }).join("\n")
+                : "") +
             (hiddenFileInputs.length > 0
                 ? `\nFILE INPUTS not listed above (hidden behind a styled control — a user never sees the input itself): ${hiddenFileInputs.join("; ")}. ` +
                     `scout_upload {ref} on the control that opens one, or scout_upload {} when it is the page's only file input.`
                 : "") +
             this.socketNotice() +
             formatViolations(this.oracles.drain()) +
-            (elements.length === 0 ? "\n⚠ DEAD END: no interactable elements found on this page." : ""));
+            (elements.length === 0
+                ? hasVisibleFrame(frames)
+                    ? "\n⚠ No interactable elements in the page itself: what it shows is inside the frames listed above, which were not explored."
+                    : "\n⚠ DEAD END: no interactable elements found on this page."
+                : ""));
     }
     /**
      * Resolve a ref and re-verify the live element at action time. Refs are
@@ -1197,7 +1552,7 @@ export class BrowserEngine {
         }
         // String EXPRESSION via page.evaluate (locator.evaluate treats a string as
         // an expression, not a function — the element arg never binds).
-        const live = (await page
+        const live = (await this.scopeOf(el)
             .evaluate(`(() => { const node = ${xpathLookup(el.xpath)}; if (!node) return null; ` +
             `return { testid: node.getAttribute('data-testid'), label: (node.getAttribute('aria-label') || node.innerText || node.textContent || node.getAttribute('placeholder') || '').trim().slice(0, 120) }; })()`)
             .catch(() => null));
@@ -1314,6 +1669,120 @@ export class BrowserEngine {
     lateMark(entry) {
         return entry.at < this.actionStartedAt ? `${entry.sig} (late — likely from a previous action)` : entry.sig;
     }
+    /**
+     * The frames directly under the page, read from their <iframe> elements in
+     * one pass each, all at once. Each read gets FRAME_READ_MS: a frame that
+     * cannot answer in time (a busy ad loop in its own process) is left out on
+     * its own rather than stalling the snapshot or dropping the others. Frames
+     * inside frames, and direct frames past the first 30, are only counted.
+     */
+    async frameInventory(page) {
+        const top = page.mainFrame();
+        const all = page.frames().filter((f) => f !== top);
+        const direct = all.filter((f) => f.parentFrame() === top);
+        const read = async (frame) => {
+            let timer;
+            const box = await Promise.race([
+                frame
+                    .frameElement()
+                    .then((el) => el.evaluate((node) => {
+                    const r = node.getBoundingClientRect();
+                    return {
+                        title: (node.getAttribute("title") || node.getAttribute("name") || "").trim(),
+                        width: Math.round(r.width),
+                        height: Math.round(r.height),
+                    };
+                }))
+                    .catch(() => null),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(null), FRAME_READ_MS);
+                }),
+            ]).finally(() => clearTimeout(timer));
+            return box ? { url: frame.url(), ...box, foreign: foreignFrameOrigin(this.baseUrl, [frame.url()]) !== null } : null;
+        };
+        const frames = (await Promise.all(direct.slice(0, 30).map(read))).filter((f) => f !== null);
+        return { frames, nested: all.length - Math.min(direct.length, 30) };
+    }
+    /**
+     * Whether a document request is the top window leaving the app, with no
+     * Referer, while a frame that held another site's document now sits on a
+     * data: or blob: URL — where WebKit no longer applies its sandbox.
+     */
+    embedEscapeNavigation(req) {
+        const page = this.page;
+        if (!page || !req.isNavigationRequest() || req.redirectedFrom())
+            return false;
+        try {
+            if (req.frame() !== page.mainFrame())
+                return false;
+        }
+        catch {
+            return false;
+        }
+        if (req.headers()["referer"])
+            return false;
+        if (foreignFrameOrigin(this.baseUrl, [req.url()]) === null)
+            return false;
+        const top = page.mainFrame();
+        // data: and blob: only: where WebKit drops the sandbox. A frame the app set back to about:blank is not an escape.
+        return page.frames().some((f) => f !== top && this.foreignFrames.has(f) && /^(data|blob):/i.test(f.url()));
+    }
+    /**
+     * What a document request loads into: a frame (not the top window) of
+     * another origin than the app's, a frame of the app's own origin, or
+     * neither (null). On the app's own sign-in pages frames are left alone: a
+     * "sign in with" button is a foreign frame that has to open its popup.
+     */
+    frameDocumentKind(req) {
+        let frame;
+        try {
+            frame = req.frame();
+        }
+        catch {
+            return null;
+        }
+        if (frame === frame.page().mainFrame())
+            return null;
+        if (allowsForeignWriteOnSignIn(this.mode, this.page?.url() ?? "", this.baseUrl))
+            return null;
+        let url;
+        try {
+            url = new URL(req.url());
+        }
+        catch {
+            return null;
+        }
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return null;
+        return foreignFrameOrigin(this.baseUrl, [req.url()]) ? "foreign" : "app";
+    }
+    /**
+     * The foreign origin behind a write headed outside the app (policy.ts
+     * foreignWrite), or null — also null on the app's own sign-in page, where a
+     * captcha frame's writes must go out for a login to work.
+     */
+    foreignWriteOf(req) {
+        let unadoptedPageUrl = null;
+        try {
+            const from = req.frame().page();
+            if (this.page && from !== this.page)
+                unadoptedPageUrl = from.url();
+        }
+        catch {
+            /* no frame: a new window's first request, or a service worker */
+        }
+        // Frames still attached that hold, or held, another site: one that moved itself to data: is no longer foreign by its URL.
+        const pageHasForeignFrame = this.embeddedSites().size > 0;
+        const source = requestSource(req);
+        const originHeader = req.headers()["origin"];
+        const foreign = foreignWrite(this.baseUrl, { url: req.url(), originHeader, unadoptedPageUrl, pageHasForeignFrame, ...source });
+        if (foreign && allowsForeignWriteOnSignIn(this.mode, this.page?.url() ?? "", this.baseUrl))
+            return null;
+        // Frames of origins the user named as trusted, in safe-write, every one involved: the ordinary rules.
+        if (foreign && trustsForeignWrite(this.mode, this.trustedEmbeds, this.baseUrl, { frameChain: source.frameChain, originHeader, unadoptedPageUrl }))
+            return null;
+        return foreign;
+    }
     /** Report (and clear) write-policy blocks since the last action. */
     drainBlocked() {
         this.lastActionBlocked = this.blockedRequests.length;
@@ -1325,9 +1794,18 @@ export class BrowserEngine {
             .join("; ");
         const extra = this.blockedRequests.length > 5 ? ` (+${this.blockedRequests.length - 5} more)` : "";
         const answered = this.blockedRequests.some((e) => e.answered);
+        const reasons = new Set(this.blockedRequests.map((e) => e.why).filter((w) => !!w));
+        const escaped = reasons.delete(ESCAPE_REFUSAL);
+        const foreign = [...reasons];
         this.blockedRequests = [];
         return (`\n🛡 WRITE-POLICY blocked (${this.mode}): ${list}${extra}. ` +
             `This is the tester's safety policy, NOT an app bug — do not file a finding for the resulting error UI. ` +
+            (foreign.length > 0
+                ? `Refused because it was ${foreign.join("; ")}: it would reach a site embedded in the page rather than the app, which no mode but destructive allows. `
+                : "") +
+            (escaped
+                ? `A move of the whole page off the app, with no Referer, was refused: a frame that held another site now sits on a data: or blob: URL, where WebKit drops the frame's sandbox, so the move may be that frame's. No mode but destructive allows it. `
+                : "") +
             (answered
                 ? `The page's own requests were answered with a 403 in the server's place, so the page's handling of a refusal is real: an error message is correct, and a success message is a false_success violation. `
                 : "") +
@@ -1429,11 +1907,16 @@ export class BrowserEngine {
             this.logAction({ action: "click:refused", target: liveLabel || el.name, url: page.url() });
             return refusal;
         }
+        const embed = this.foreignEmbedOf(el);
+        if (embed && clicks > 1) {
+            this.logAction({ action: "click:refused", target: `${clicks} clicks in a frame of ${embed}`, url: page.url() });
+            return embedProbeRefusal(`a ${clicks}-click probe`, embed);
+        }
         // Submit-shaped clicks that fire zero network requests are a smell
         // (silent no-op forms): capture the count before to compare after.
         const xhrBefore = this.xhrCount;
         const submitLike = el.role === "button" && /submit|send|save|create|apply|subscribe|register|sign|post|add\b/i.test(el.name + " " + (el.testid ?? ""));
-        const { forced } = await this.resilientClick(page.locator(`xpath=${el.xpath}`), ACTION_TIMEOUT_MS, clicks);
+        const { forced } = await this.resilientClick(this.scopeOf(el).locator(`xpath=${el.xpath}`), ACTION_TIMEOUT_MS, clicks);
         this.memory.markExercised(this.currentFingerprint, el.key, clicks > 1 ? `click×${clicks}` : "click");
         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
@@ -1543,15 +2026,28 @@ export class BrowserEngine {
         const refusal = this.actionPolicyCheck(el, liveLabel);
         if (refusal)
             return refusal;
-        const locator = page.locator(`xpath=${el.xpath}`);
-        // Before the fill: a page that reflects input as it is typed already holds the element afterwards.
-        await this.noteProbe(text, `${el.role} "${el.name}"`);
-        const fillNote = await this.fillOrAppend(locator, text, replace);
+        const embed = this.foreignEmbedOf(el);
+        if (embed) {
+            const hostile = hostileForEmbed(text);
+            if (hostile) {
+                this.logAction({ action: "type:refused", target: `${el.role} in a frame of ${embed} (${hostile})`, url: page.url() });
+                return embedProbeRefusal(`typing this value (${hostile})`, embed);
+            }
+        }
+        const locator = this.scopeOf(el).locator(`xpath=${el.xpath}`);
+        // Before the fill: a page that reflects input as it is typed already holds
+        // the element afterwards. Never for another site's frame: no probe is placed there.
+        if (!embed)
+            await this.noteProbe(text, `${el.role} "${el.name}"`);
+        let fillNote = await this.fillOrAppend(locator, text, replace);
+        // What another site's field already held is its business, not the report's.
+        if (embed)
+            fillNote = fillNote.replace(/existing content "(?:[^"\\]|\\.)*"/g, "existing content (masked: another site's frame)");
         if (pressEnter) {
             // Enter inside a form submits it — check the form's submit target, or
             // pressEnter becomes a read-only bypass for destructive submits.
             if (this.readOnly) {
-                const submitLabel = (await page
+                const submitLabel = (await this.scopeOf(el)
                     .evaluate(`(() => { const node = ${xpathLookup(el.xpath)}; if (!node) return ''; ` +
                     `const f = node.form || node.closest('form'); if (!f) return ''; ` +
                     `const s = f.querySelector('[type="submit"], button:not([type="button"]):not([type="reset"])'); ` +
@@ -1586,7 +2082,10 @@ export class BrowserEngine {
             const refusal = this.actionPolicyCheck(el, resolved.liveLabel);
             if (refusal)
                 return refusal;
-            locator = page.locator(`xpath=${el.xpath}`);
+            const embed = this.foreignEmbedOf(el);
+            if (embed)
+                return embedProbeRefusal("a file upload", embed);
+            locator = this.scopeOf(el).locator(`xpath=${el.xpath}`);
         }
         const outcome = await this.performUpload(locator, opts);
         if (outcome.refused)
@@ -1783,7 +2282,7 @@ export class BrowserEngine {
         const page = this.requirePage();
         const { el } = await this.resolveForAction(ref);
         const { before, bodyBefore, churning } = await this.hoverBaselines();
-        const locator = page.locator(`xpath=${el.xpath}`);
+        const locator = this.scopeOf(el).locator(`xpath=${el.xpath}`);
         await locator.hover({ timeout: ACTION_TIMEOUT_MS });
         // Wiggle inside the element: pointer-tracking libraries distinguish real
         // movement from a single synthetic hover event.
@@ -1793,7 +2292,7 @@ export class BrowserEngine {
             await page.mouse.move(box.x + box.width / 2 - 2, box.y + box.height / 2 - 1);
         }
         const { revealed, fallbackUsed } = await this.detectHoverReveal(before, bodyBefore, churning);
-        const attrTexts = (await page
+        const attrTexts = (await this.scopeOf(el)
             .evaluate(`(() => { const node = ${xpathLookup(el.xpath)}; if (!node) return []; const out = []; ` +
             `const t = node.getAttribute('title'); if (t) out.push('title: ' + t.slice(0, 300)); ` +
             `const d = node.getAttribute('aria-describedby'); if (d) { for (const id of d.split(/\\s+/)) { ` +
@@ -1825,7 +2324,7 @@ export class BrowserEngine {
             return refusal;
         if (this.readOnly) {
             // Bulk-action dropdowns fire on change — vet the chosen option itself.
-            const optionLabel = (await page
+            const optionLabel = (await this.scopeOf(el)
                 .evaluate(`(() => { const node = ${xpathLookup(el.xpath)}; if (!node) return ''; const v = ${JSON.stringify(value)}; ` +
                 `const opts = Array.from(node.options || []); ` +
                 `const o = opts.find(o => o.value === v || o.label === v || (o.textContent || '').trim() === v); ` +
@@ -1836,7 +2335,7 @@ export class BrowserEngine {
                 return destructiveRefusal(optionLabel || value, this.mode);
             }
         }
-        const loc = page.locator(`xpath=${el.xpath}`);
+        const loc = this.scopeOf(el).locator(`xpath=${el.xpath}`);
         const options = el.tag === "select" ? await readSelectOptions(loc) : null;
         const picked = await loc.selectOption(value, { timeout: ACTION_TIMEOUT_MS });
         this.memory.markExercised(this.currentFingerprint, el.key, "select");
@@ -1849,11 +2348,37 @@ export class BrowserEngine {
      * policy as click, or the keyboard becomes a read-only bypass. Shared by
      * scout_press and plan press steps; returns a refusal message or null.
      */
+    /**
+     * The frame that holds keyboard focus: the page, or — when the page's
+     * focused element is a frame — that frame, followed down as far as focus goes.
+     */
+    async focusedFrame(page) {
+        let scope = page;
+        let current = page.mainFrame();
+        for (let depth = 0; depth < 5; depth++) {
+            let next = null;
+            for (const child of current.childFrames()) {
+                // Within the frame limit: a frame that never answers must not hold up a key press.
+                const holds = await this.withinFrameLimit(child.frameElement().then((el) => el.evaluate((node) => node === node.ownerDocument?.activeElement)));
+                if (holds) {
+                    next = child;
+                    break;
+                }
+            }
+            if (!next)
+                break;
+            scope = next;
+            current = next;
+        }
+        return scope;
+    }
     async vetFocusedActivation(key) {
         if (!(this.readOnly && /^(Enter|NumpadEnter|Space| )$/i.test(key)))
             return null;
         const page = this.requirePage();
-        const focusedLabel = await page
+        // Focus inside a frame reads, from the page, as the <iframe> itself: follow it down.
+        const focused = await this.focusedFrame(page);
+        const focusedLabel = await focused
             .evaluate(`(() => { const el = document.activeElement; if (!el) return ""; ` +
             `return (el.getAttribute("aria-label") || el.getAttribute("data-testid") || el.innerText || el.textContent || "").trim().slice(0, 120); })()`)
             .catch(() => "");