scenescout 3.8.0 → 3.9.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # scenescout
 
+## 3.9.0
+
+### Minor Changes
+
+- e2cf5bb: Snapshots list the controls inside the page's frames, each marked with its frame, and every action works on them by ref. In a frame of another site, container text is masked and typed markup, fuzzing-length values, repeated-click probes and uploads are refused in every mode; ordinary clicks and typing are allowed, and the write policy still refuses the writes such a frame sends outside the app.
+- 5a48f6c: What happens inside another site's frame is attributed to it: failing requests and error responses it sent outside the app are labelled with its origin, kept at medium severity at most and grouped in their own report section (a request it sent to the app stays the app's), and its controls are counted apart from the app's coverage and gap ledger.
+- fa71eb8: `scout_attach` takes `trustedEmbeds`, a list of origins the user trusts (a provider in test mode, say): in safe-write mode only, the writes their frames send outside the app go out, provided every other site involved (each frame up to the page, and the Origin header) is trusted. Anything that is not a plain http(s) origin is refused at attach, trust is ignored in the other modes, and the report names the list.
+
 ## 3.8.0
 
 ### Minor Changes

package/dist/engine/browser.js

@@ -7,7 +7,7 @@ import { normalizeTask } from "./task.js";
 import { CLAIM_SCAN_SCRIPT, findContradictions } from "./claims.js";
 import { describeInjection, newInjections, probeQueries, probeScript, probeShape, rememberProbe } from "./injection.js";
 import { AuthLossTracker } from "./authloss.js";
-import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, frameLines, hasVisibleFrame, displayName, missingName, } from "./collector.js";
+import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, frameLines, hasVisibleFrame, frameElementKey, frameLabel, masksForeignName, MASKED_NAME, capForeignName, stripForeignHref, frameToPageRect, displayName, missingName, } 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, foreignFrameOrigin, foreignWrite, withForeignFrameSandbox, offAppPageWrite, EmbedMoveTracker, sandboxedRedirectPage, allowsForeignWriteOnSignIn, isAuthExempt, } from "./policy.js";
+import { answersWithRefusal, destructiveRefusal, isDestructive, isDestructiveWire, allowsWrite, policyRefusal, foreignFrameOrigin, foreignWrite, withForeignFrameSandbox, offAppPageWrite, embedOfRequest, hostileForEmbed, trustedEmbedOrigins, MAX_TRUSTED_EMBEDS, trustsForeignWrite, embedProbeRefusal, EmbedMoveTracker, sandboxedRedirectPage, allowsForeignWriteOnSignIn, isAuthExempt, } from "./policy.js";
 import { scanProject } from "../scan.js";
 import { analyzeDesign, DESIGN_COLLECT_SCRIPT } from "./design.js";
 import { acceptMatches, generatedUpload } from "./fixtures.js";
@@ -77,6 +77,8 @@ function requestSource(req) {
 }
 /** The `why` of a top-window navigation refused as a possible frame escape; the notice words it on its own. */
 const ESCAPE_REFUSAL = "a possible frame escape";
+/** The most frames a snapshot reads controls from. */
+const MAX_READ_FRAMES = 10;
 /** How long a snapshot waits for its frames' elements to answer. */
 const FRAME_READ_MS = 1500;
 /** In-page XPath lookup fragment for string-expression evaluates. */
@@ -180,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
@@ -628,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);
@@ -665,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,
@@ -996,7 +1025,7 @@ export class BrowserEngine {
             `Memory: ${this.memory.dir}.${this.memory.loadWarning ? ` WARNING: ${this.memory.loadWarning}` : ""}` +
             (this.memory.prunedStates > 0 ? ` Trimmed ${this.memory.prunedStates} old page state(s) from the history; coverage is unchanged.` : "") +
             `${this.memory.legacyDirNote ? ` ${this.memory.legacyDirNote}` : ""}` +
-            `${this.memory.gitIgnoreNote ? ` ${this.memory.gitIgnoreNote}` : ""} Call scout_snapshot to see the current state.` +
+            `${this.memory.gitIgnoreNote ? ` ${this.memory.gitIgnoreNote}` : ""}${this.trustNotice} Call scout_snapshot to see the current state.` +
             authWarning);
     }
     /** Whether the page was moved off the app by one of its embeds (policy.ts EmbedMoveTracker). */
@@ -1154,31 +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
@@ -1285,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.
@@ -1334,7 +1488,15 @@ 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);
@@ -1350,7 +1512,13 @@ export class BrowserEngine {
             (geometry.length > 0 ? `\nGEOMETRY issues:\n` + geometry.map((g) => `  ⚠ ${g}`).join("\n") : "") +
             (brokenImages.length > 0 ? `\nBROKEN IMAGES:\n` + brokenImages.map((b) => `  ⚠ ${b}`).join("\n") : "") +
             (frames.length > 0 || nestedFrames > 0
-                ? `\n` + frameLines(this.baseUrl, frames, { nested: nestedFrames, writesRefused: this.mode !== "destructive" }).join("\n")
+                ? `\n` +
+                    frameLines(this.baseUrl, frames, {
+                        nested: this.unreadNestedFrames(page, nestedFrames),
+                        writesRefused: this.mode !== "destructive",
+                        trustedWrites: this.mode === "safe-write" ? this.trustedEmbeds : undefined,
+                        read: new Set([...this.framesRead].map((f) => f.url())),
+                    }).join("\n")
                 : "") +
             (hiddenFileInputs.length > 0
                 ? `\nFILE INPUTS not listed above (hidden behind a styled control — a user never sees the input itself): ${hiddenFileInputs.join("; ")}. ` +
@@ -1384,7 +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));
@@ -1605,15 +1773,14 @@ export class BrowserEngine {
         }
         // Frames still attached that hold, or held, another site: one that moved itself to data: is no longer foreign by its URL.
         const pageHasForeignFrame = this.embeddedSites().size > 0;
-        const foreign = foreignWrite(this.baseUrl, {
-            url: req.url(),
-            originHeader: req.headers()["origin"],
-            unadoptedPageUrl,
-            pageHasForeignFrame,
-            ...requestSource(req),
-        });
+        const source = requestSource(req);
+        const originHeader = req.headers()["origin"];
+        const foreign = foreignWrite(this.baseUrl, { url: req.url(), originHeader, unadoptedPageUrl, pageHasForeignFrame, ...source });
         if (foreign && allowsForeignWriteOnSignIn(this.mode, this.page?.url() ?? "", this.baseUrl))
             return null;
+        // Frames of origins the user named as trusted, in safe-write, every one involved: the ordinary rules.
+        if (foreign && trustsForeignWrite(this.mode, this.trustedEmbeds, this.baseUrl, { frameChain: source.frameChain, originHeader, unadoptedPageUrl }))
+            return null;
         return foreign;
     }
     /** Report (and clear) write-policy blocks since the last action. */
@@ -1740,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
@@ -1854,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"])'); ` +
@@ -1897,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)
@@ -2094,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.
@@ -2104,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+/)) { ` +
@@ -2136,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); ` +
@@ -2147,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");
@@ -2160,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(() => "");

package/dist/engine/collector.js

@@ -402,13 +402,89 @@ export const BROKEN_IMAGES_SCRIPT = `(() => {
   }
   return { images, total };
 })()`;
+/**
+ * An element's coverage key inside a frame: the frame's origin (another site)
+ * or path (the app's own) before the element's own key, so a "Submit" in an
+ * embed is not the page's "Submit". Elements of the page itself keep their key
+ * unchanged, so pages without frames keep the coverage they had.
+ */
+export function frameElementKey(baseKey, frame) {
+    if (!frame)
+        return baseKey;
+    let where = frame.origin || frame.url;
+    if (!frame.foreign) {
+        try {
+            const u = new URL(frame.url);
+            // A frame with no web address (srcdoc, about:blank) is told apart by its title.
+            where = u.protocol === "http:" || u.protocol === "https:" ? u.pathname : `${frame.url}#${frame.title}`;
+        }
+        catch {
+            where = `${frame.url}#${frame.title}`;
+        }
+    }
+    return `frame:${where}|${baseKey}`;
+}
+/** The longest name kept for a control in another site's frame: a chat that renders messages as buttons would otherwise print them whole. */
+export const MAX_FOREIGN_NAME = 40;
+/** A control's name from another site's frame, cut to MAX_FOREIGN_NAME. */
+export function capForeignName(name) {
+    return name.length > MAX_FOREIGN_NAME ? `${name.slice(0, MAX_FOREIGN_NAME)}…` : name;
+}
+/** A link's address from another site's frame without its query and fragment, where tokens and addresses travel. */
+export function stripForeignHref(href) {
+    try {
+        const u = new URL(href);
+        return u.origin + u.pathname;
+    }
+    catch {
+        return href.split(/[?#]/)[0];
+    }
+}
+/**
+ * A rect read inside a frame, in the page's document coordinates: the frame
+ * element's box on screen, less the frame's own scroll, plus the page's.
+ */
+export function frameToPageRect(rect, box, frameScroll, pageScroll) {
+    return { ...rect, x: rect.x + box.x + pageScroll.x - frameScroll.x, y: rect.y + box.y + pageScroll.y - frameScroll.y };
+}
+/** How a snapshot line names the frame an element is in. */
+export function frameLabel(frame) {
+    let where = frame.url;
+    if (!frame.foreign) {
+        try {
+            const u = new URL(frame.url);
+            where = u.pathname + u.search;
+        }
+        catch {
+            /* shown as it is */
+        }
+    }
+    else if (frame.origin)
+        where = frame.origin;
+    return `${frame.foreign ? "cross-origin" : "same-origin"} frame ${where.slice(0, 80)}${frame.title ? ` "${frame.title.slice(0, 40)}"` : ""}`;
+}
+/**
+ * Whether an element's name, read from another site's frame, is masked. A
+ * name taken from a container's text — a select's options, a textarea's
+ * contents, a tagged <div> — can carry other people's data (a support chat,
+ * a customer record) into the snapshot, the transcript and the report. The
+ * label of a link, a button or a field is the interface itself and is kept:
+ * the agent needs it to act.
+ */
+export function masksForeignName(tag, role) {
+    if (tag === "a" || tag === "button" || tag === "input")
+        return false;
+    return !/^(button|link|tab|menuitem|checkbox|switch|radio)$/.test(role);
+}
+/** The name shown for a masked element. */
+export const MASKED_NAME = "(content masked: another site's frame)";
 /** A frame smaller than this in both directions is plumbing (a tracking pixel, a messaging bridge), not something a user sees. */
 const VISIBLE_FRAME_PX = 2;
 /**
- * The snapshot's account of the page's frames. Nothing inside a frame is
- * collected or can be acted on yet, and a page that shows its form in an
- * embed used to look like a page with no form at all: say what is there,
- * where it comes from, and that it was not looked inside. `nested` counts
+ * The snapshot's account of the page's frames: what is embedded, where it
+ * comes from, and whether its controls were read (`read`, by frame URL) —
+ * a page that shows its form in an embed used to look like a page with no
+ * form at all. Without `read`, nothing was looked inside. `nested` counts
  * frames that are not read: nested inside others, or past the first 30; `writesRefused` is false only in
  * destructive mode, where a foreign frame's writes do go out.
  */
@@ -436,12 +512,22 @@ export function frameLines(appUrl, frames, opts = {}) {
             /* about:blank, srcdoc: shown as they are */
         }
         const label = f.title ? ` "${f.title.slice(0, 60)}"` : "";
+        let frameOrigin = "";
+        try {
+            frameOrigin = new URL(f.url).origin;
+        }
+        catch {
+            /* no origin */
+        }
         const writes = f.foreign
             ? opts.writesRefused === false
                 ? " — its writes go out (destructive mode)"
-                : " — writes it sends outside the app are refused"
+                : opts.trustedWrites?.has(frameOrigin)
+                    ? " — trusted embed: its writes go out (safe-write)"
+                    : " — writes it sends outside the app are refused"
             : "";
-        return `  ${f.foreign ? "cross-origin" : "same-origin"} ${where.slice(0, 120)}${label} ${f.width}×${f.height}${writes}`;
+        const read = opts.read ? (opts.read.has(f.url) ? " — controls listed above" : " — not read") : "";
+        return `  ${f.foreign ? "cross-origin" : "same-origin"} ${where.slice(0, 120)}${label} ${f.width}×${f.height}${read}${writes}`;
     });
     if (visible.length > 10)
         lines.push(`  … +${visible.length - 10} more`);
@@ -449,7 +535,14 @@ export function frameLines(appUrl, frames, opts = {}) {
         lines.push(`  (+${hidden} hidden frame${hidden === 1 ? "" : "s"})`);
     if (nested > 0)
         lines.push(`  (+${nested} more frame${nested === 1 ? "" : "s"}, nested inside those or past the first 30, not read)`);
-    return [`FRAMES not explored — their controls are not listed above and cannot be acted on:`, ...lines];
+    const header = opts.read && opts.read.size > 0
+        ? "FRAMES — the controls of each frame read are listed above, marked ⟨in … frame⟩, and can be acted on by ref" +
+            (visible.some((f) => f.foreign)
+                ? "; in another site's frame, content is masked and hostile input, repeated-click probes and uploads are refused"
+                : "") +
+            ":"
+        : "FRAMES not explored — their controls are not listed above and cannot be acted on:";
+    return [header, ...lines];
 }
 /** Whether any frame on the page is one a user can see. */
 export function hasVisibleFrame(frames) {

package/dist/engine/memory.js

@@ -282,6 +282,14 @@ function decisionKey(d) {
  * project would otherwise accumulate every decision ever made and re-serialise
  * them on each save, which is what made an old history slow to open.
  */
+/**
+ * Whether a coverage key belongs to a control inside another site's frame:
+ * those keys carry the frame's origin (collector.ts frameElementKey), where
+ * the app's own frames carry a path. Not the app's to cover.
+ */
+export function isEmbedKey(key) {
+    return /^frame:https?:\/\//.test(key);
+}
 export const MAX_LANE_DECISIONS = 1000;
 /**
  * Most options a dropdown may have and still be tracked for unchosen options.
@@ -1388,6 +1396,7 @@ export class MemoryStore {
         let elementsTotal = 0;
         let elementsExercised = 0;
         const unexercised = [];
+        const embeds = { total: 0, exercised: 0 };
         for (const [route, elements] of byRoute) {
             const own = [];
             // The route's OWN element count — deduped across states and with shared
@@ -1398,6 +1407,12 @@ export class MemoryStore {
             // untouched route silently drops out of the gap ledger.
             let ownTotal = 0;
             for (const [key, done] of elements) {
+                if (isEmbedKey(key)) {
+                    embeds.total += 1;
+                    if (done)
+                        embeds.exercised += 1;
+                    continue;
+                }
                 if (isChrome(key)) {
                     chrome.set(key, (chrome.get(key) ?? false) || done);
                     continue;
@@ -1424,7 +1439,7 @@ export class MemoryStore {
         if (chromeLeft.length > 0) {
             unexercised.push({ state: SHARED_CHROME_ROUTE, keys: chromeLeft, total: chrome.size });
         }
-        return { states: Object.keys(this.data.states).length, elementsTotal, elementsExercised, unexercised };
+        return { states: Object.keys(this.data.states).length, elementsTotal, elementsExercised, unexercised, embeds };
     }
     /**
      * Remember which styled-element signatures the design audit saw on a route.

package/dist/engine/oracles.js

@@ -84,6 +84,7 @@ export class OracleMonitor {
                 severity: "medium",
                 detail: `${req.method()} ${req.url().slice(0, 200)} → ${failure}`,
                 url: page.url(),
+                embed: this.embedOfRequest(req) ?? undefined,
             });
         });
         page.on("response", (res) => {
@@ -106,6 +107,7 @@ export class OracleMonitor {
                 severity: status >= 500 ? "high" : "medium",
                 detail: `${res.request().method()} ${res.url().slice(0, 200)} → HTTP ${status}`,
                 url: page.url(),
+                embed: this.embedOfRequest(res.request()) ?? undefined,
             });
         });
     }
@@ -128,6 +130,17 @@ export class OracleMonitor {
      * errors look the same.
      */
     policyAttributed = 0;
+    embedOfRequest = () => null;
+    /**
+     * The engine knows which frame a request came from; a failing request is
+     * attributed to an embed through this. Console and page errors are not
+     * attributed: a console message says where its script was served from, not
+     * which frame ran it, so an SDK the app's page loads from the embed's own
+     * site would be taken for the embed.
+     */
+    setEmbedAttribution(ofRequest) {
+        this.embedOfRequest = ofRequest;
+    }
     /** The engine knows exactly which requests its policy stopped; failed requests and stand-in refusals are matched against that, not against wording. */
     setPolicyRefusalCheck(check) {
         this.refusedByPolicy = check;
@@ -158,7 +171,11 @@ export class OracleMonitor {
             this.policyAttributed += 1;
             return;
         }
-        const violation = { ...redactViolation(v), at: new Date().toISOString() };
+        // Another site's frame: its behaviour, reported, but never as the app's high-severity defect.
+        const attributed = v.embed ? { ...v, severity: "medium" } : v;
+        if (!attributed.embed)
+            delete attributed.embed;
+        const violation = { ...redactViolation(attributed), at: new Date().toISOString() };
         this.buffer.push(violation);
         this.all.push(violation);
     }
@@ -179,7 +196,8 @@ export class OracleMonitor {
         for (const v of out) {
             // Same normalization as the report rollup, so "the same violation"
             // means the same thing in tool output and in the final report.
-            const sig = `${v.kind}: ${v.detail
+            // An embed's violation is not the app's: its signature says whose it is.
+            const sig = `${v.embed ? `[${v.embed}] ` : ""}${v.kind}: ${v.detail
                 .replace(/\b\d+\b/g, ":n")
                 .replace(/[0-9a-f]{8,}/gi, ":h")
                 .slice(0, 140)}`;
@@ -205,7 +223,9 @@ export function formatViolations(violations) {
     if (fresh.length === 0) {
         return `\nORACLE: ${repeats} repeat violation(s) of previously reported signatures — nothing new.`;
     }
-    const lines = fresh.slice(0, 10).map((v) => `  ⚠ [${v.severity}] ${v.kind}: ${v.detail}`);
+    const lines = fresh
+        .slice(0, 10)
+        .map((v) => `  ⚠ [${v.severity}] ${v.kind}${v.embed ? ` (in an embed of ${v.embed}: its behaviour, not the app's)` : ""}: ${v.detail}`);
     const more = fresh.length > 10 ? `\n  … and ${fresh.length - 10} more` : "";
     return `\nORACLE VIOLATIONS since last action (${fresh.length} new):\n${lines.join("\n")}${more}${repeatLine}`;
 }

package/dist/engine/policy.js

@@ -394,6 +394,124 @@ export function allowsForeignWriteOnSignIn(mode, topPageUrl, appUrl) {
     const last = (segments[segments.length - 1] ?? "").replace(/\.[a-z0-9]+$/i, "").replace(/_/g, "-");
     return SIGN_IN_SEGMENT_RE.test(last);
 }
+/**
+ * The embed a failing request is attributed to: the other site whose frame
+ * sent it (`frameSite`, judged on the frame chain), unless the request went to
+ * the app itself — a 500 from the app is the app's to answer, whoever called.
+ */
+export function embedOfRequest(appUrl, requestUrl, frameSite) {
+    if (!frameSite)
+        return null;
+    return foreignFrameOrigin(appUrl, [requestUrl]) === null ? null : frameSite;
+}
+/** The most origins a session may trust with its embeds' writes. */
+export const MAX_TRUSTED_EMBEDS = 10;
+/**
+ * The origins a session was told to trust, normalised, and what was given
+ * that is not one. An entry must be a plain http(s) origin — scheme, host and
+ * port, nothing after — so a path or a wildcard cannot widen it by accident.
+ */
+export function trustedEmbedOrigins(list) {
+    const origins = [];
+    const rejected = [];
+    const overflow = [];
+    for (const raw of list ?? []) {
+        let u;
+        try {
+            u = new URL(raw.trim());
+        }
+        catch {
+            rejected.push(raw);
+            continue;
+        }
+        const bare = u.pathname === "/" && !u.search && !u.hash && !u.username && !u.password;
+        if ((u.protocol !== "http:" && u.protocol !== "https:") || !bare || raw.includes("*")) {
+            rejected.push(raw);
+            continue;
+        }
+        // "pay.example.com." is "pay.example.com": one origin, one slot.
+        const origin = u.origin.replace(/\.(?=(:\d+)?$)/, "");
+        if (origins.includes(origin))
+            continue;
+        if (origins.length < MAX_TRUSTED_EMBEDS)
+            origins.push(origin);
+        else
+            overflow.push(raw);
+    }
+    return { origins, rejected, overflow };
+}
+/**
+ * Whether the writes a frame of `origin` sends outside the app may go out
+ * after all: only for an origin the user named as trusted (a provider in test
+ * mode, say), and only in safe-write — read-only and observe keep their
+ * promise, and destructive allows everything already.
+ */
+export function trustsEmbedWrite(mode, trusted, origin) {
+    return mode === "safe-write" && trusted.has(origin);
+}
+/**
+ * Whether a foreign write may go out because of trust: every other site
+ * involved — each http(s) frame from the sender up to the page, and the
+ * Origin header when it names one — must be trusted, so an untrusted embed
+ * cannot borrow a trusted one it wraps. A page the session never adopted (a
+ * popup) is not a frame, and trust does not reach it.
+ */
+export function trustsForeignWrite(mode, trusted, appUrl, req) {
+    if (mode !== "safe-write" || trusted.size === 0 || req.unadoptedPageUrl)
+        return false;
+    const originOf = (url) => {
+        if (!url)
+            return null;
+        try {
+            const u = new URL(url);
+            return u.protocol === "http:" || u.protocol === "https:" ? u.origin : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const app = originOf(appUrl);
+    const involved = new Set();
+    for (const url of req.frameChain) {
+        // A blank or srcdoc frame is its parent's, and the parent is judged next.
+        // Any other frame with no web address (blob:, data:) could be an untrusted
+        // site that moved itself there to wrap a trusted one: no trust through it.
+        if (/^about:(blank|srcdoc)/i.test(url))
+            continue;
+        const o = originOf(url);
+        if (!o)
+            return false;
+        if (o !== app)
+            involved.add(o);
+    }
+    const header = originOf(req.originHeader);
+    if (header && header !== app)
+        involved.add(header);
+    return involved.size > 0 && [...involved].every((o) => trustsEmbedWrite(mode, trusted, o));
+}
+/** The longest text typed into another site's frame; past it, a value is a fuzzing probe, not a user's input. */
+export const MAX_EMBED_TEXT = 200;
+/**
+ * Why a value must not be typed into another site's frame, or null when it
+ * may be. The tester is authorised to test the app, not the embeds of
+ * others: markup, fuzzing lengths and control characters typed there would
+ * be probing a third party's system without its leave.
+ */
+export function hostileForEmbed(text) {
+    if (/<\s*[a-z!/?]/i.test(text) || /javascript:/i.test(text))
+        return "it is markup";
+    if (text.length > MAX_EMBED_TEXT)
+        return `it is longer than ${MAX_EMBED_TEXT} characters`;
+    if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(text))
+        return "it holds control characters";
+    return null;
+}
+/** The refusal for a probe aimed at another site's frame. */
+export function embedProbeRefusal(what, origin) {
+    return (`REFUSED: ${what} inside a frame of ${origin}, another site embedded in the page. The tester is authorised to test the app, ` +
+        `not the embeds of others, so hostile input, repeated-click probes and file uploads are never sent into one, in any mode. ` +
+        `Ordinary clicks and typing there are allowed; the embed's writes out of the app are refused by the write policy.`);
+}
 /**
  * The sandbox given to every document a frame of another origin loads, outside
  * destructive mode: scripts, forms and its own origin keep working, and no

package/dist/engine/report.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { SHARED_CHROME_ROUTE } from "./memory.js";
+import { SHARED_CHROME_ROUTE, isEmbedKey } from "./memory.js";
 import { sayVerification } from "./verify.js";
 import { feedForSession } from "./live.js";
 import { buildReplayHtml, evidenceFor } from "./replay.js";
@@ -59,6 +59,38 @@ function violationRollup(oracleLog) {
         ``,
     ];
 }
+/**
+ * What came from other sites' frames: their controls, and the violations
+ * they caused, by origin. Kept apart from the app's coverage and rollup —
+ * an embed's failing request is the embed's behaviour, and its controls are
+ * not the app's to cover — but listed, since the app chose to embed them.
+ */
+export function embedSection(violations, coverage) {
+    if (violations.length === 0 && coverage.total === 0)
+        return [];
+    const lines = [`## Embeds (other sites' frames)`, ``];
+    if (coverage.total > 0) {
+        lines.push(`${coverage.exercised}/${coverage.total} of their controls exercised; not counted in the app's coverage or its gap ledger.`, ``);
+    }
+    if (violations.length > 0) {
+        const byOrigin = new Map();
+        for (const v of violations) {
+            const origin = v.embed ?? "";
+            const sig = `${v.kind}: ${v.detail.replace(/\b\d+\b/g, ":n").slice(0, 120)}`;
+            const sigs = byOrigin.get(origin) ?? new Map();
+            sigs.set(sig, (sigs.get(sig) ?? 0) + 1);
+            byOrigin.set(origin, sigs);
+        }
+        lines.push(`Violations inside them (${violations.length}), reported as the embed's behaviour, not the app's:`, ``, `| Embed | Count | Signature |`, `|---|---|---|`);
+        for (const [origin, sigs] of byOrigin) {
+            for (const [sig, count] of [...sigs.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8)) {
+                lines.push(`| \`${escapeTableCell(origin)}\` | ${count} | \`${escapeTableCell(sig)}\` |`);
+            }
+        }
+        lines.push(``);
+    }
+    return lines;
+}
 const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
 const SEVERITY_ICON = { high: "🔴", medium: "🟠", low: "🟡" };
 /**
@@ -253,13 +285,15 @@ export function classifyFilledStates(memory, facts) {
     const unsubmitted = new Set();
     const noSubmitControl = new Set();
     for (const st of Object.values(memory.states)) {
-        const keys = Object.keys(st.elements);
+        // Another site's frame is not the app's form: typing into an embed's chat leaves no app form unsubmitted.
+        const own = Object.fromEntries(Object.entries(st.elements).filter(([key]) => !isEmbedKey(key)));
+        const keys = Object.keys(own);
         const filledForReal = keys.some((key) => st.elements[key].exercised && /^(type|select|upload|plan:(type|select|upload))/.test(st.elements[key].lastAction ?? "") && !isFilterKey(key));
         if (!filledForReal)
             continue;
         if (facts[st.route]?.mutated || mutatedSiblingStep(st.route, facts))
             continue;
-        if (offersSubmit(st.elements) || keys.length >= COLLECTOR_CAP)
+        if (offersSubmit(own) || keys.length >= COLLECTOR_CAP)
             unsubmitted.add(st.route);
         else
             noSubmitControl.add(st.route);
@@ -431,7 +465,8 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
     lines.push(`| States explored | ${cov.states} |`);
     if (extras)
         lines.push(`| Design audits this run (all sessions) | ${extras.designAudits} |`);
-    lines.push(`| Oracle violations this session | ${oracleLog.length} |`);
+    const fromEmbeds = oracleLog.filter((v) => v.embed).length;
+    lines.push(`| Oracle violations this session | ${oracleLog.length - fromEmbeds}${fromEmbeds > 0 ? ` (plus ${fromEmbeds} inside other sites' frames)` : ""} |`);
     if (extras?.policyAttributed) {
         lines.push(`| Errors caused by the tester's own write-policy blocks (not counted above) | ${extras.policyAttributed} |`);
     }
@@ -614,7 +649,21 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
             lines.push(`- \`${r}\``);
         lines.push(``);
     }
-    lines.push(...violationRollup(oracleLog));
+    if (extras?.trustedEmbeds && extras.trustedEmbeds.length > 0) {
+        lines.push(`## Trusted embeds`);
+        lines.push(``);
+        lines.push(extras.mode === "safe-write"
+            ? `Writes that frames of these origins sent outside the app were allowed, as the user asked; anything they created lives with that provider, and SceneScout cannot list it:`
+            : extras.mode === "destructive"
+                ? `Named as trusted, and not needed: destructive mode let every embed's writes out:`
+                : `Named as trusted, but not applied: trust only counts in safe-write mode, and this run was ${extras.mode ?? "read-only"}:`);
+        lines.push(``);
+        for (const o of extras.trustedEmbeds)
+            lines.push(`- \`${o}\``);
+        lines.push(``);
+    }
+    lines.push(...violationRollup(oracleLog.filter((v) => !v.embed)));
+    lines.push(...embedSection(oracleLog.filter((v) => v.embed), cov.embeds));
     if (cov.unexercised.length > 0) {
         lines.push(`## Unexplored surface (for the next run)`);
         lines.push(``);

package/dist/mcp-server.js

@@ -243,6 +243,7 @@ function reportExtras(eng) {
         createdResources: eng.createdResources,
         unvisitedRoutes: unvisited,
         mode: eng.mode,
+        trustedEmbeds: [...eng.trustedEmbeds],
         policyAttributed: eng.oracleLog.policyAttributed,
         version: PKG_VERSION,
         attachedSessions: [...engines.keys()],
@@ -628,6 +629,12 @@ server.registerTool("scout_attach", {
             .max(60000)
             .optional()
             .describe("A floor between actions, in milliseconds, for when a person is watching and needs to keep up — following a flow, taking notes, demonstrating. Default 0: as fast as the page allows, which is what a run wants otherwise. Changeable mid-run with scout_session {paceMs}."),
+        trustedEmbeds: z
+            .array(z.string().max(200))
+            .max(10)
+            .optional()
+            .describe('Origins of embedded frames (e.g. "https://pay.example.com") whose writes out of the app may go out — ONLY when the user named them, typically a provider in test mode, and only in safe-write mode. ' +
+            "Never add one yourself. Hostile input, repeated-click probes and uploads stay refused in them."),
         record: z
             .boolean()
             .default(false)
@@ -639,7 +646,7 @@ server.registerTool("scout_attach", {
             .optional()
             .describe("Session name for multi-role runs (e.g. 'admin', 'qa'). Creates/replaces that session's browser and makes it the default. Default: 'default'."),
     },
-}, serializedControl(async ({ url, projectPath, storageStatePath, mode, headed, browser, viewportWidth, viewportHeight, objective, task, record, paceMs, session, }) => {
+}, serializedControl(async ({ url, projectPath, storageStatePath, mode, headed, browser, viewportWidth, viewportHeight, objective, task, record, trustedEmbeds, paceMs, session, }) => {
     try {
         const target = session ?? activeName;
         if (session) {
@@ -722,6 +729,7 @@ server.registerTool("scout_attach", {
             paceMs,
             task: objective ? task : undefined,
             record,
+            trustedEmbeds,
             memoryStore: store,
         });
         eng.role = storageStatePath ? path.basename(storageStatePath).replace(/\.json$/i, "") : "anonymous";
@@ -1169,7 +1177,7 @@ server.registerTool("scout_coverage", {
                     `⚠ MEMORY WRITE FAILING: ${eng.memory.lastSaveError} — coverage/findings since the last successful write are NOT persisted to disk. If this doesn't clear on its own, check the project directory still exists and is writable.`,
                 ]
                 : []),
-            `States known: ${cov.states} · Elements exercised: ${cov.elementsExercised}/${cov.elementsTotal}`,
+            `States known: ${cov.states} · Elements exercised: ${cov.elementsExercised}/${cov.elementsTotal}${cov.embeds.total > 0 ? ` (plus ${cov.embeds.exercised}/${cov.embeds.total} inside other sites' frames, not counted)` : ""}`,
             formatRouteCoverage(eng.allKnownRoutes(), unvisited),
             `Unexercised elements by route:`,
             ...cov.unexercised.slice(0, 25).map((u) => `  ${u.state}: ${u.keys.slice(0, 6).join(", ")}${u.keys.length > 6 ? ` … +${u.keys.length - 6}` : ""}`),
@@ -1254,6 +1262,7 @@ server.registerTool("scout_report", {
             createdResources: eng.createdResources,
             unvisitedRoutes: unvisited,
             mode: eng.mode,
+            trustedEmbeds: [...eng.trustedEmbeds],
             policyAttributed: eng.oracleLog.policyAttributed,
             // Which sessions are still open decides whether a quiet one is holding a browser, and how long its trailing idle runs.
             attachedSessions: [...engines.keys()],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenescout",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "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",

package/skills/scenescout/SKILL.md

@@ -34,7 +34,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.
-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. A FRAMES line means part of the page is an embed (`<iframe>`) whose controls are not listed and cannot be acted on yet: say in your summary that its contents were not explored, and never file its absence as a missing feature. Writes a cross-origin frame sends outside the app are refused in every mode but destructive, because they reach the third party serving it.
+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.
 7. **Say what you are doing: `task` is required before a tool acts.** A session shows two lines to whoever is watching. Its **objective** is the whole remit you were given, set once at `scout_attach {objective}` ("Admin lane: §2 registers, §7 plan gating", "Approve and reject orders as a manager"). Its **task** is what you are doing *right now*, and every tool that changes the app or the page — `scout_navigate`, `scout_back`, `scout_click`, `scout_type`, `scout_select`, `scout_press`, `scout_upload`, `scout_run_plan` — takes it: a few words for the batch in front of you ("Filtering the documents register by status", "Filling the deviation form with invalid dates", "Signing in as QA_Team"). Say what you are DOING, not what you are checking — "§2.4 filtering narrows the set and is reflected in the URL" is the acceptance criteria, which is the result you will judge, not the batch you are running; naming the item is fine ("§2.4: filtering the documents register"). The task STAYS SET until you pass a different one, so a batch costs a few words, not one per call — pass a fresh one whenever you move on. Acting with none standing is refused: the person watching would otherwise see a session clicking through their app with nothing to say why. `scout_journey {action:"start", goal:…}` sets the task too while it runs — use a journey when you are MEASURING a whole user task, the parameter for everything else.