@enricai/barnacle 1.6.6 → 1.6.8

package/dist/scraper/flow-runner.js

@@ -43,6 +43,7 @@ exports.renderUnfocusedObserve = renderUnfocusedObserve;
 exports.pairInvalidWithErrors = pairInvalidWithErrors;
 exports.formatValidationRejectedReason = formatValidationRejectedReason;
 exports.selectBodyExcerpt = selectBodyExcerpt;
+exports.extractLivePageFormEvidence = extractLivePageFormEvidence;
 exports.probeLeafInvalidContainers = probeLeafInvalidContainers;
 exports.renderLeafInvalidFields = renderLeafInvalidFields;
 exports.extractSubmitFailureEvidence = extractSubmitFailureEvidence;
@@ -52,6 +53,8 @@ exports.fillHtml5DateTimeInput = fillHtml5DateTimeInput;
 exports.verifyFillReadback = verifyFillReadback;
 exports.isUploadAffordanceLabel = isUploadAffordanceLabel;
 exports.writeFixtureToTempFile = writeFixtureToTempFile;
+exports.attachToSurfacedInput = attachToSurfacedInput;
+exports.surfaceAndUpload = surfaceAndUpload;
 exports.parseSelectStep = parseSelectStep;
 exports.parseRadioStep = parseRadioStep;
 exports.pollEnumerate = pollEnumerate;
@@ -59,6 +62,9 @@ exports.waitForTransitionBody = waitForTransitionBody;
 exports.chooseRequiredSelectOption = chooseRequiredSelectOption;
 exports.buildRadioIdXPath = buildRadioIdXPath;
 exports.selectRadioGroupOption = selectRadioGroupOption;
+exports.simulateDragDropUpload = simulateDragDropUpload;
+exports.dispatchJqueryChangeEvent = dispatchJqueryChangeEvent;
+exports.verifyDomEffect = verifyDomEffect;
 exports.narrowInvalidFormControl = narrowInvalidFormControl;
 exports.formatStepPrefix = formatStepPrefix;
 exports.probeStepBeforeAttempts = probeStepBeforeAttempts;
@@ -82,6 +88,7 @@ const logging_1 = require("../lib/logging");
 const call_capture_1 = require("../lib/telemetry/call-capture");
 const call_types_1 = require("../lib/telemetry/call-types");
 const errors_2 = require("../scraper/errors");
+const frame_target_1 = require("../scraper/frame-target");
 const phantom_click_1 = require("../scraper/phantom-click");
 const stagehand_guard_1 = require("../scraper/stagehand-guard");
 const submit_control_1 = require("../scraper/submit-control");
@@ -467,11 +474,11 @@ exports.TRAILING_GRACE_WINDOW = 2;
  * shape via Runtime.callFunctionOn.
  */
 const DOM_SNAPSHOT_EXPR = `(() => { const b = document.body; if (!b) return { html: 0, text: "" }; const t = b.innerText || ""; return { html: (b.outerHTML || "").length, text: t.length + ":" + t.slice(0, 200) }; })()`;
-async function snapshotPage(page, signalCounter) {
+async function snapshotPage(target, signalCounter) {
     let bodyHtmlLength = 0;
     let visibleTextSignature = "";
     try {
-        const result = await page.evaluate(DOM_SNAPSHOT_EXPR);
+        const result = await target.evaluate(DOM_SNAPSHOT_EXPR);
         if (result !== null &&
             typeof result === "object" &&
             "html" in result &&
@@ -488,7 +495,7 @@ async function snapshotPage(page, signalCounter) {
     }
     return {
         networkCount: signalCounter.n,
-        url: page.url(),
+        url: await target.url(),
         bodyHtmlLength,
         visibleTextSignature,
     };
@@ -508,6 +515,18 @@ async function snapshotPage(page, signalCounter) {
  * envelope shapes. New ATSs can be added by extending the recognized
  * keys; the existing ones cover the four most common patterns.
  */
+/**
+ * Reads the title/url pair for a step-failure dump, scoped to whichever
+ * frame the step actually ran against — so a triager sees the same frame's
+ * body HTML and url instead of pairing a child frame's DOM with the top
+ * document's url. `title()` intentionally still reads the top document for
+ * a child frame (see `frame-target.ts`); `url()` is the frame discriminator.
+ */
+async function resolveDumpPageIdentity(page, frameTarget) {
+    const pageTitle = await (frameTarget ?? page).title().catch(() => "");
+    const pageUrl = await (frameTarget ? frameTarget.url() : Promise.resolve(page.url())).catch(() => page.url());
+    return { pageTitle, pageUrl };
+}
 /**
  * Detect whether the supplied capture-meta window contains a backend
  * 5xx response that matches the configured submit endpoint pattern.
@@ -851,15 +870,18 @@ function isDomOnlyAdvanceVerified(params) {
     return networkIsRealAdvance || urlChanged;
 }
 /**
- * Read-only count of ng-invalid form controls on the page. Side-effect-free
+ * Read-only count of ng-invalid form controls on the resolved frame. Side-effect-free
  * counterpart to `probeFormValidityBeforeSubmit` (which also auto-fills
  * unselected radio groups via element.click()). Used by the cascade's
  * early-exit predicate to detect "the Submit click revealed new required
  * questions" — when this count grows from 0 (pre-submit) to ≥1 (post-attempt-1),
  * attempts 2-5 cannot succeed and the cascade should route to replan
- * immediately instead of burning Stagehand calls.
+ * immediately instead of burning Stagehand calls. Accepts a `FrameTarget` so a
+ * wizard embedded in a cross-origin iframe (e.g. UCHealth's Talemetry form) is
+ * scanned on its own frame; a main-frame target delegates straight to
+ * `page.evaluate`, matching today's behavior byte-for-byte.
  */
-async function countNgInvalidContainers(page) {
+async function countNgInvalidContainers(target) {
     const expr = `(() => {
     const isInvalid = ${INVALID_MARKER_EL_EXPR};
     let n = 0;
@@ -869,7 +891,7 @@ async function countNgInvalidContainers(page) {
     return n;
   })()`;
     try {
-        const raw = await page.evaluate(expr);
+        const raw = await target.evaluate(expr);
         return typeof raw === "number" ? raw : 0;
     }
     catch {
@@ -1470,10 +1492,10 @@ function selectBodyExcerpt(body) {
     const start = Math.max(0, absoluteIndex - BODY_EXCERPT_FORM_WINDOW / 4);
     return body.slice(start, start + BODY_EXCERPT_FORM_WINDOW);
 }
-async function extractLivePageFormEvidence(page, options) {
+async function extractLivePageFormEvidence(_page, target, options) {
     let body = "";
     try {
-        const raw = await page.evaluate("document.body ? document.body.outerHTML : null");
+        const raw = await target.evaluate("document.body ? document.body.outerHTML : null");
         if (typeof raw === "string")
             body = raw;
     }
@@ -1502,13 +1524,13 @@ async function extractLivePageFormEvidence(page, options) {
     // field was named in FORM FIELDS. Deterministic extraction gives the
     // LLM `"Address" <app-input> — error: "This field is required"` instead.
     const [leafFields, errorVerdict, interactiveTargets] = await Promise.all([
-        probeLeafInvalidContainers(page),
+        probeLeafInvalidContainers(target),
         (0, error_messages_1.judgeErrorMessagesWithLLM)({
             client,
             input: { bodyHtmlExcerpt: bodyExcerpt },
             captureFn,
         }),
-        extractInteractiveTargetsNearInvalid(page).catch(() => []),
+        extractInteractiveTargetsNearInvalid(target).catch(() => []),
     ]);
     // Probe is the primary signal. Judge only runs if probe is empty AND a
     // client is available — so the fallback semantics match today's behavior
@@ -1558,13 +1580,13 @@ async function extractLivePageFormEvidence(page, options) {
  * LLM for fuzzy judgment, deterministic extraction for structurally-derivable
  * signals" — DOM tree walking is the latter.
  *
- * Returns up to 12 leaf records. Empty array on `page.evaluate` failure (safe
+ * Returns up to 12 leaf records. Empty array on evaluate failure (safe
  * fallback to the existing Haiku judge upstream). The `inputTag` and
  * `visibleErrorText` fields let the prompt distinguish a smart-address
  * autocomplete (where typing-only fails and the cascade needs dropdown
  * selection) from a plain text input.
  */
-async function probeLeafInvalidContainers(page) {
+async function probeLeafInvalidContainers(target) {
     const expr = `(() => {
     const SELECTOR =
       "[class*='ng-invalid']:not(:has([class*='ng-invalid'])), " +
@@ -1649,11 +1671,11 @@ async function probeLeafInvalidContainers(page) {
     return out;
   })()`;
     try {
-        const result = await page.evaluate(expr);
+        const result = await target.evaluate(expr);
         return Array.isArray(result) ? result : [];
     }
     catch {
-        // page.evaluate failure (navigation in-flight, CSP, browser detached)
+        // evaluate failure (navigation in-flight, CSP, browser detached)
         // is non-fatal — caller falls back to the Haiku judge.
         return [];
     }
@@ -1676,7 +1698,7 @@ function renderLeafInvalidFields(fields) {
     });
     return lines.join("\n");
 }
-async function extractInteractiveTargetsNearInvalid(page) {
+async function extractInteractiveTargetsNearInvalid(target) {
     const expr = `(() => {
     const out = [];
     const containers = document.querySelectorAll(
@@ -1732,7 +1754,7 @@ async function extractInteractiveTargetsNearInvalid(page) {
     }
     return out;
   })()`;
-    const result = await page.evaluate(expr);
+    const result = await target.evaluate(expr);
     return Array.isArray(result) ? result : [];
 }
 /**
@@ -1988,12 +2010,12 @@ function normalizeDateValue(raw, inputType) {
     }
     return null;
 }
-async function fillHtml5DateTimeInput(page, xpath, value) {
+async function fillHtml5DateTimeInput(target, xpath, value) {
     const HTML5_DATE_TYPES = new Set(["date", "time", "datetime-local", "month", "week"]);
     // K'/H' Change 1: pre-normalize the value before dispatching to the page
     // evaluator. The HTML5 spec rejects programmatic .value writes that don't
     // match the canonical format — see normalizeDateValue TSDoc.
-    // We don't yet know the input type until the page.evaluate runs (we'd
+    // We don't yet know the input type until the evaluate runs (we'd
     // have to probe it first), so we try BOTH the raw value AND a normalized
     // pass: if raw works, fine; if raw fails (post-value mismatch), the
     // returned filled=false signal tells the caller to retry with a normalized
@@ -2022,7 +2044,7 @@ async function fillHtml5DateTimeInput(page, xpath, value) {
     return { filled: el.value === value, postValue: el.value || "", inputType };
   })()`;
     try {
-        const raw = await page.evaluate(expr);
+        const raw = await target.evaluate(expr);
         if (raw === null || typeof raw !== "object")
             return null;
         const r = raw;
@@ -2058,7 +2080,7 @@ async function fillHtml5DateTimeInput(page, xpath, value) {
  * element regardless of framework wrapping. Industry-standard pattern
  * (react-testing-library's `getByDisplayValue` does the same readback).
  */
-async function verifyFillReadback(page, xpath, expectedValue) {
+async function verifyFillReadback(target, xpath, expectedValue) {
     const expr = `(() => {
     const xpath = ${JSON.stringify(xpath)};
     const expected = ${JSON.stringify(expectedValue)};
@@ -2081,7 +2103,7 @@ async function verifyFillReadback(page, xpath, expectedValue) {
     return { outcome, postValue: actual, tag };
   })()`;
     try {
-        const raw = await page.evaluate(expr);
+        const raw = await target.evaluate(expr);
         if (raw === null || typeof raw !== "object")
             return null;
         const r = raw;
@@ -2285,7 +2307,7 @@ function writeFixtureToTempFile(fixture) {
  * existing cascade in that case).
  */
 async function tryUploadPrimitive(params) {
-    const { page, isUploadStep, fixture, logger, signalCounter, recentCaptureMeta } = params;
+    const { page, target, isUploadStep, fixture, logger, signalCounter, recentCaptureMeta } = params;
     if (!isUploadStep) {
         return false;
     }
@@ -2302,7 +2324,7 @@ async function tryUploadPrimitive(params) {
     // already rendered it pay nothing.
     let inputCount = 0;
     try {
-        inputCount = await pollEnumerate(page, "document.querySelectorAll('input[type=file]').length", (n) => (n ?? 0) > 0, { attempts: UPLOAD_WIDGET_RENDER_ATTEMPTS, intervalMs: UPLOAD_WIDGET_RENDER_INTERVAL_MS });
+        inputCount = await pollEnumerate(page, target, "document.querySelectorAll('input[type=file]').length", (n) => (n ?? 0) > 0, { attempts: UPLOAD_WIDGET_RENDER_ATTEMPTS, intervalMs: UPLOAD_WIDGET_RENDER_INTERVAL_MS });
     }
     catch (err) {
         logger.warn(`upload primitive: file-input probe threw: ${(0, errors_1.toErrorMessage)(err)}`);
@@ -2315,6 +2337,7 @@ async function tryUploadPrimitive(params) {
         logger.info("upload primitive: no <input type=file> after render wait; attempting click-to-surface");
         const surfaced = await surfaceAndUpload({
             page,
+            target,
             fixture,
             logger,
             signalCounter,
@@ -2325,7 +2348,7 @@ async function tryUploadPrimitive(params) {
         logger.info("upload primitive: click-to-surface failed; falling through to cascade");
         return false;
     }
-    return attachToSurfacedInput({ page, fixture, logger, signalCounter, recentCaptureMeta });
+    return attachToSurfacedInput({ page, target, fixture, logger, signalCounter, recentCaptureMeta });
 }
 /**
  * Attach the fixture to an already-surfaced `<input type=file>` (raw or freshly
@@ -2335,10 +2358,10 @@ async function tryUploadPrimitive(params) {
  * + drag-drop-fallback implementation.
  */
 async function attachToSurfacedInput(params) {
-    const { page, fixture, logger, signalCounter, recentCaptureMeta } = params;
-    const target = page.locator("xpath=//input[@type='file']").first();
+    const { page, target, fixture, logger, signalCounter, recentCaptureMeta } = params;
+    const inputLocator = target.locator("xpath=//input[@type='file']").first();
     try {
-        await target.setInputFiles({
+        await inputLocator.setInputFiles({
             name: fixture.name,
             mimeType: fixture.mimeType,
             buffer: fixture.buffer,
@@ -2365,7 +2388,7 @@ async function attachToSurfacedInput(params) {
         // Industry-standard workaround documented across Playwright
         // community. Site-agnostic — works for any tenant with framework-
         // wrapped file inputs.
-        await page
+        await target
             .evaluate("(() => { const els = document.querySelectorAll('input[type=file]'); for (const el of els) { if (el.files && el.files.length > 0) { el.dispatchEvent(new Event('input', { bubbles: true })); el.dispatchEvent(new Event('change', { bubbles: true })); return true; } } return false; })()")
             .catch((err) => {
             logger.warn(`upload primitive: change dispatch failed: ${(0, errors_1.toErrorMessage)(err)}`);
@@ -2391,7 +2414,7 @@ async function attachToSurfacedInput(params) {
     // interpolation from external data, no risk of injecting attacker-controlled
     // values into the browser-side JS. Same trust posture as the type-probe
     // expression in verifyDomEffect's click case.
-    const attachedLength = await page
+    const attachedLength = await target
         .evaluate("(() => { const els = document.querySelectorAll('input[type=file]'); for (const el of els) { if (el.files && el.files.length > 0) return el.files.length; } return 0; })()")
         .catch(() => 0);
     if (typeof attachedLength !== "number" || attachedLength === 0) {
@@ -2402,7 +2425,7 @@ async function attachToSurfacedInput(params) {
         // a DataTransfer fires on the visible drop area — they don't observe
         // the hidden input's `files[]` mutations even with synthetic `change`
         // dispatches. This is the documented Playwright community workaround.
-        const dragDropOk = await simulateDragDropUpload(page, fixture, logger);
+        const dragDropOk = await simulateDragDropUpload(target, fixture, logger);
         if (dragDropOk) {
             logger.info(`upload primitive: drag-drop fallback succeeded (name=${fixture.name}, size=${fixture.buffer.length}b)`);
             return true;
@@ -2425,7 +2448,7 @@ async function attachToSurfacedInput(params) {
  * was attached.
  */
 async function surfaceAndUpload(params) {
-    const { page, fixture, logger, signalCounter, recentCaptureMeta } = params;
+    const { page, target, fixture, logger, signalCounter, recentCaptureMeta } = params;
     // Render-gate: the input-less strategies below (drag-drop is one-shot, the
     // affordance click resolves what's in the DOM) all race the async widget
     // mount. Wait (bounded, same window as the raw-input probe) for ANY upload
@@ -2449,7 +2472,7 @@ async function surfaceAndUpload(params) {
     if (btns.some((el) => isUpload(el.getAttribute("aria-label") || el.textContent || ""))) return { present: true };
     return { present: false };
   })()`;
-    const gate = await pollEnumerate(page, targetExpr, (r) => r?.present === true, {
+    const gate = await pollEnumerate(page, target, targetExpr, (r) => r?.present === true, {
         attempts: UPLOAD_WIDGET_RENDER_ATTEMPTS,
         intervalMs: UPLOAD_WIDGET_RENDER_INTERVAL_MS,
     });
@@ -2461,13 +2484,18 @@ async function surfaceAndUpload(params) {
     // Strategy DZ: a synthetic drop is cheap, needs no click/chooser, and the
     // widget IS a dropzone. If it registers the file (upload POST or attached
     // input), we're done without touching CDP.
-    if (await simulateDragDropUpload(page, fixture, logger)) {
+    if (await simulateDragDropUpload(target, fixture, logger)) {
         if (await waitForUploadNetworkSignal({ page, fixture, logger, signalCounter, recentCaptureMeta })) {
             logger.info("upload primitive: resolved via drag-drop onto dropzone");
             return true;
         }
     }
-    const session = page.getSessionForFrame(page.mainFrameId());
+    // The file-chooser CDP interception below must run on the upload target's
+    // OWN session — an OOPIF (e.g. UCHealth's Talemetry wizard) has its own CDP
+    // target, and a chooser it opens is only observable via that frame's
+    // session, not the main session. Main-frame targets fall back to
+    // page.getSessionForFrame(page.mainFrameId()), matching today's behavior.
+    const session = target.frame ? target.frame.session : page.getSessionForFrame(page.mainFrameId());
     let chooserBackendNodeId = null;
     const onChooser = (paramsIn) => {
         const p = paramsIn;
@@ -2477,13 +2505,13 @@ async function surfaceAndUpload(params) {
     // ARM native-chooser interception BEFORE the click. Page.fileChooserOpened
     // only carries a backendNodeId while interception is enabled; without it a
     // chooser-opening click would pop a real OS dialog and hang the run.
-    await page.sendCDP("Page.enable").catch(() => { });
-    await page
-        .sendCDP("Page.setInterceptFileChooserDialog", { enabled: true })
+    await session.send("Page.enable").catch(() => { });
+    await session
+        .send("Page.setInterceptFileChooserDialog", { enabled: true })
         .catch((e) => logger.warn(`upload primitive: chooser-intercept arm failed: ${(0, errors_1.toErrorMessage)(e)}`));
     session.on("Page.fileChooserOpened", onChooser);
     try {
-        if (!(await clickUploadAffordance(page, logger)))
+        if (!(await clickUploadAffordance(page, target, logger)))
             return false;
         // Strategy 0: some MUI widgets XHR straight to attachment_upload_url on
         // click, no chooser, no input.
@@ -2492,10 +2520,17 @@ async function surfaceAndUpload(params) {
             return true;
         }
         // Strategy A: the click lazily mounted a hidden <input type=file>.
-        const appeared = await pollEnumerate(page, "document.querySelectorAll('input[type=file]').length", (n) => (n ?? 0) > 0);
+        const appeared = await pollEnumerate(page, target, "document.querySelectorAll('input[type=file]').length", (n) => (n ?? 0) > 0);
         if ((appeared ?? 0) > 0) {
             logger.info("upload primitive: click surfaced a hidden <input type=file>");
-            if (await attachToSurfacedInput({ page, fixture, logger, signalCounter, recentCaptureMeta })) {
+            if (await attachToSurfacedInput({
+                page,
+                target,
+                fixture,
+                logger,
+                signalCounter,
+                recentCaptureMeta,
+            })) {
                 return true;
             }
         }
@@ -2504,6 +2539,7 @@ async function surfaceAndUpload(params) {
             logger.info(`upload primitive: native file chooser intercepted (backendNodeId=${chooserBackendNodeId}); setting files via CDP`);
             return setFilesViaCdp({
                 page,
+                target,
                 session,
                 backendNodeId: chooserBackendNodeId,
                 fixture,
@@ -2516,7 +2552,7 @@ async function surfaceAndUpload(params) {
     }
     finally {
         session.off("Page.fileChooserOpened", onChooser);
-        await page.sendCDP("Page.setInterceptFileChooserDialog", { enabled: false }).catch(() => { });
+        await session.send("Page.setInterceptFileChooserDialog", { enabled: false }).catch(() => { });
     }
 }
 /**
@@ -2526,8 +2562,11 @@ async function surfaceAndUpload(params) {
  * upload vocabulary as {@link isUploadAffordanceLabel}, preferring controls
  * scoped inside an attachment/upload/resume container. Returns whether a
  * matching control was clicked.
+ *
+ * Takes both `page` (for `pollEnumerate`'s `waitForTimeout`) and `target`
+ * (the frame the enumerate/click runs against).
  */
-async function clickUploadAffordance(page, logger) {
+async function clickUploadAffordance(page, target, logger) {
     // The browser-side matcher mirrors isUploadAffordanceLabel; kept as a literal
     // so the enumerate is a static string (same trust posture as the other
     // primitives). No external interpolation.
@@ -2549,7 +2588,7 @@ async function clickUploadAffordance(page, logger) {
     return { clicked: true, text: norm(chosen.getAttribute("aria-label") || chosen.textContent || "").slice(0, 50) };
   })()`;
     try {
-        const result = (await pollEnumerate(page, expr, (r) => r?.clicked === true)) ?? { clicked: false };
+        const result = (await pollEnumerate(page, target, expr, (r) => r?.clicked === true)) ?? { clicked: false };
         if (result.clicked) {
             logger.info(`upload primitive: clicked upload affordance "${result.text ?? ""}"`);
             return true;
@@ -2570,7 +2609,7 @@ async function clickUploadAffordance(page, logger) {
  * shared upload-network signal.
  */
 async function setFilesViaCdp(params) {
-    const { page, session, backendNodeId, fixture, logger, signalCounter, recentCaptureMeta } = params;
+    const { page, target, session, backendNodeId, fixture, logger, signalCounter, recentCaptureMeta, } = params;
     // CDP needs a filesystem path; the fixture is an in-memory buffer. Write it
     // to a temp file (tiny — a few KB) so the path is always valid regardless of
     // where the recon loaded the fixture from.
@@ -2588,7 +2627,7 @@ async function setFilesViaCdp(params) {
     // CDP-set files don't surface via input.files, so the DOM-attached-files
     // check can't confirm; treat a filename chip appearing in the DOM as the
     // secondary success signal (the MUI widget renders the chosen filename).
-    const nameShown = await page
+    const nameShown = await target
         .evaluate(`document.body && document.body.textContent && document.body.textContent.indexOf(${JSON.stringify(fixture.name)}) !== -1`)
         .catch(() => false);
     if (nameShown === true) {
@@ -2714,14 +2753,20 @@ const PRIMITIVE_ENUMERATE_RETRY_MS = 600;
  * `opts` overrides the attempt count / interval for callers that need a longer
  * window (the resume-upload widget can take 5s+ to mount); omitting it keeps the
  * default ~3s window so every existing caller is unchanged.
+ *
+ * Takes both `page` (for `waitForTimeout`, which `FrameTarget` has no
+ * equivalent of) and `target` (for the enumerate itself), so a widget
+ * rendered inside a resolved cross-origin child frame is polled on its own
+ * frame; a main-frame `target` delegates straight to `page.evaluate`,
+ * matching today's behavior byte-for-byte.
  */
-async function pollEnumerate(page, expr, isPresent, opts) {
+async function pollEnumerate(page, target, expr, isPresent, opts) {
     const attempts = opts?.attempts ?? PRIMITIVE_ENUMERATE_ATTEMPTS;
     const intervalMs = opts?.intervalMs ?? PRIMITIVE_ENUMERATE_RETRY_MS;
-    let result = (await page.evaluate(expr));
+    let result = (await target.evaluate(expr));
     for (let attempt = 1; attempt < attempts && !isPresent(result); attempt++) {
         await page.waitForTimeout(intervalMs);
-        result = (await page.evaluate(expr));
+        result = (await target.evaluate(expr));
     }
     return result;
 }
@@ -2798,8 +2843,13 @@ async function waitForTransitionBody(params) {
  * refuse to claim success on an uncommitted select, routing to the cascade/replan
  * instead of silently advancing. Walks ≤6 ancestors for the invalid marker, same
  * as the radio/checkbox primitives.
+ *
+ * Accepts a `FrameTarget` (plus the underlying `page` for `waitForTimeout`,
+ * which `FrameTarget` has no equivalent of) so a wizard embedded in a
+ * cross-origin iframe is set on its own frame; a main-frame target delegates
+ * straight to `page.evaluate`, matching today's behavior byte-for-byte.
  */
-async function applySelectValue(page, selIdx, value) {
+async function applySelectValue(page, target, selIdx, value) {
     const setExpr = `((selIdx, value) => {
     const sel = Array.from(document.querySelectorAll("select"))[selIdx];
     if (!sel) return { ok: false };
@@ -2810,7 +2860,7 @@ async function applySelectValue(page, selIdx, value) {
     sel.dispatchEvent(new Event("blur", { bubbles: true }));
     return { ok: sel.value === value };
   })(${JSON.stringify(selIdx)}, ${JSON.stringify(value)})`;
-    const setResult = (await page.evaluate(setExpr));
+    const setResult = (await target.evaluate(setExpr));
     if (!setResult?.ok)
         return { ok: false, stillInvalid: false };
     await page.waitForTimeout(SELECT_SETTLE_MS);
@@ -2825,11 +2875,11 @@ async function applySelectValue(page, selIdx, value) {
     }
     return false;
   })(${JSON.stringify(selIdx)})`;
-    const stillInvalid = (await page.evaluate(invalidExpr).catch(() => false));
+    const stillInvalid = (await target.evaluate(invalidExpr).catch(() => false));
     return { ok: true, stillInvalid };
 }
 async function trySelectPrimitive(params) {
-    const { page, instruction, logger, anthropic, captureFn } = params;
+    const { page, target, instruction, logger, anthropic, captureFn } = params;
     const parsed = parseSelectStep(instruction);
     if (!parsed)
         return false;
@@ -2914,7 +2964,7 @@ async function trySelectPrimitive(params) {
     try {
         // Settle-retry: the <select> may render a beat after the step fires (SPA
         // render-lag); poll until it appears or the cap is hit.
-        const enumResult = await pollEnumerate(page, enumerateExpr, (r) => r?.selectPresent === true);
+        const enumResult = await pollEnumerate(page, target, enumerateExpr, (r) => r?.selectPresent === true);
         // No <select> on the page at all (e.g. the question is a radio group) —
         // fall through to the cascade unchanged; the LLM picker can't help here.
         if (!enumResult?.selectPresent) {
@@ -2926,7 +2976,7 @@ async function trySelectPrimitive(params) {
         // is uncommitted (a later worklet re-render will wipe it) — refuse to claim
         // success so the cascade/replan can retry rather than silently advancing.
         if (enumResult.detMatch) {
-            const { ok, stillInvalid } = await applySelectValue(page, enumResult.detMatch.selIdx, enumResult.detMatch.value);
+            const { ok, stillInvalid } = await applySelectValue(page, target, enumResult.detMatch.selIdx, enumResult.detMatch.value);
             if (ok && !stillInvalid) {
                 logger.info(`select primitive: set dropdown to "${enumResult.detMatch.text.trim().slice(0, 40)}" (${optLabel})`);
                 return true;
@@ -2963,7 +3013,7 @@ async function trySelectPrimitive(params) {
         // Apply pass (set + settle + invalid-readback): set the chosen select by its
         // ORIGINAL DOM index, then confirm it committed (cleared the invalid marker),
         // same as the fast path.
-        const { ok, stillInvalid } = await applySelectValue(page, chosenCandidate.selIdx, chosenOption.value);
+        const { ok, stillInvalid } = await applySelectValue(page, target, chosenCandidate.selIdx, chosenOption.value);
         if (ok && !stillInvalid) {
             logger.info(`select primitive: LLM chose "${chosenOption.text.slice(0, 40)}" for ${optLabel} (${verdict.reason.slice(0, 60)})`);
             return true;
@@ -3027,7 +3077,7 @@ function chooseRequiredSelectOption(options) {
  * required-empty select is present, so radio/checkbox catch-alls are unaffected.
  */
 async function tryFillRequiredSelectsPrimitive(params) {
-    const { page, instruction, logger, anthropic, captureFn } = params;
+    const { page, target, instruction, logger, anthropic, captureFn } = params;
     // Gate: catch-all steps only. parseSelectStep returns null for these (its
     // `any remaining` guard), so this never collides with the single-target
     // trySelectPrimitive that owns concrete "select 'X'" steps.
@@ -3085,7 +3135,7 @@ async function tryFillRequiredSelectsPrimitive(params) {
     return { candidates };
   })()`;
     try {
-        const enumResult = await pollEnumerate(page, enumerateExpr, (r) => Array.isArray(r?.candidates));
+        const enumResult = await pollEnumerate(page, target, enumerateExpr, (r) => Array.isArray(r?.candidates));
         const candidates = enumResult?.candidates ?? [];
         if (candidates.length === 0)
             return false;
@@ -3118,7 +3168,7 @@ async function tryFillRequiredSelectsPrimitive(params) {
                 allCommitted = false;
                 continue;
             }
-            const { ok, stillInvalid } = await applySelectValue(page, cand.selIdx, chosen.value);
+            const { ok, stillInvalid } = await applySelectValue(page, target, cand.selIdx, chosen.value);
             if (ok && !stillInvalid) {
                 logger.info(`required-select primitive: filled "${cand.label.slice(0, 40)}" with "${chosen.text.slice(0, 40)}"`);
             }
@@ -3158,7 +3208,7 @@ async function tryFillRequiredSelectsPrimitive(params) {
  * also where `<select>`-only pages go, since trySelectPrimitive runs first).
  */
 async function tryCheckboxPrimitive(params) {
-    const { page, instruction, logger, anthropic, captureFn } = params;
+    const { page, target, instruction, logger, anthropic, captureFn } = params;
     const parsed = parseSelectStep(instruction);
     if (!parsed)
         return false;
@@ -3243,7 +3293,7 @@ async function tryCheckboxPrimitive(params) {
     try {
         // Settle-retry: the checkbox group may render a beat after the step fires
         // (SPA render-lag); poll until it appears or the cap is hit.
-        const enumResult = await pollEnumerate(page, enumerateExpr, (r) => r?.groupPresent === true);
+        const enumResult = await pollEnumerate(page, target, enumerateExpr, (r) => r?.groupPresent === true);
         if (!enumResult?.groupPresent)
             return false; // no checkbox groups → cascade
         if (enumResult.applied && enumResult.ok) {
@@ -3292,7 +3342,7 @@ async function tryCheckboxPrimitive(params) {
       }
       return { ok: cb.checked === true };
     })(${JSON.stringify(chosenGroup.gi)}, ${JSON.stringify(chosenOption.bi)})`;
-        const applyResult = (await page.evaluate(applyExpr));
+        const applyResult = (await target.evaluate(applyExpr));
         if (applyResult?.ok) {
             logger.info(`checkbox primitive: LLM checked "${chosenOption.text.slice(0, 40)}" for ${optLabel} (${verdict.reason.slice(0, 60)})`);
             return true;
@@ -3485,7 +3535,7 @@ function selectRadioGroupOption(params) {
  * (checkbox/select/absent) falls through to the cascade.
  */
 async function tryRadioPrimitive(params) {
-    const { page, instruction, logger, anthropic, captureFn } = params;
+    const { page, target, instruction, logger, anthropic, captureFn } = params;
     const parsed = parseRadioStep(instruction);
     if (!parsed)
         return false;
@@ -3558,7 +3608,7 @@ async function tryRadioPrimitive(params) {
     return { groupPresent: true, groups };
   })(${JSON.stringify(option)})`;
     try {
-        const enumResult = await pollEnumerate(page, enumerateExpr, (r) => r?.groupPresent === true);
+        const enumResult = await pollEnumerate(page, target, enumerateExpr, (r) => r?.groupPresent === true);
         if (!enumResult?.groupPresent)
             return false; // no radio group → cascade
         const groups = enumResult.groups ?? [];
@@ -3570,7 +3620,7 @@ async function tryRadioPrimitive(params) {
         const selection = selectRadioGroupOption({ groups, wantOption: option, questionLabel });
         if (selection !== null && selection !== "ambiguous") {
             const chosenOpt = groups[selection.gi]?.options.find((o) => o.ri === selection.ri);
-            const applied = await applyRadioSelection(page, selection.gi, selection.ri, {
+            const applied = await applyRadioSelection(target, selection.gi, selection.ri, {
                 id: chosenOpt?.id ?? "",
                 xpath: chosenOpt?.xpath ?? "",
             });
@@ -3615,7 +3665,7 @@ async function tryRadioPrimitive(params) {
         // biome-ignore lint/style/noNonNullAssertion: guarded above by the verdict.optionIndex === null early-return
         const chosenOption = chosenGroup.options[verdict.optionIndex];
         const applyResult = {
-            ok: await applyRadioSelection(page, chosenGroup.gi, chosenOption.ri, {
+            ok: await applyRadioSelection(target, chosenGroup.gi, chosenOption.ri, {
                 id: chosenOption.id,
                 xpath: chosenOption.xpath,
             }),
@@ -3649,7 +3699,7 @@ async function tryRadioPrimitive(params) {
  *      detached / non-MUI radios that already commit that way).
  * Returns whether the commit stuck; false → caller falls through to the cascade.
  */
-async function applyRadioSelection(page, gi, ri, hint) {
+async function applyRadioSelection(target, gi, ri, hint) {
     // Post-settle readback for the input identified by id (preferred) or xpath:
     // checked===true AND no INVALID_MARKER_EL_EXPR ancestor within 6 hops.
     const readbackExpr = (sel) => `((id, xp) => {
@@ -3665,15 +3715,15 @@ async function applyRadioSelection(page, gi, ri, hint) {
       return { ok: true };
     })(${JSON.stringify(sel.id)}, ${JSON.stringify(sel.xpath)})`;
     const readback = async () => {
-        await page.waitForTimeout(RADIO_SETTLE_MS);
-        const r = (await page.evaluate(readbackExpr(hint)).catch(() => ({ ok: false })));
+        await (0, frame_target_1.sleep)(RADIO_SETTLE_MS);
+        const r = (await target.evaluate(readbackExpr(hint)).catch(() => ({ ok: false })));
         return r?.ok === true;
     };
     // Tier A — trusted hit-tested click on the input by id (or xpath).
     const inputSel = hint.id ? buildRadioIdXPath(hint.id) : hint.xpath ? `xpath=${hint.xpath}` : null;
     if (inputSel) {
         try {
-            await page.locator(inputSel).first().click();
+            await target.locator(inputSel).first().click();
             if (await readback())
                 return true;
         }
@@ -3684,7 +3734,7 @@ async function applyRadioSelection(page, gi, ri, hint) {
     // Tier B — trusted click on the associated label (MUI hides the real input).
     if (hint.id) {
         try {
-            await page
+            await target
                 .locator(`xpath=//label[@for=${JSON.stringify(hint.id)}]`)
                 .first()
                 .click();
@@ -3717,7 +3767,7 @@ async function applyRadioSelection(page, gi, ri, hint) {
       }
       return { ok: true };
     })(${JSON.stringify(gi)}, ${JSON.stringify(ri)})`;
-    await page.evaluate(applyExpr).catch(() => ({ ok: false }));
+    await target.evaluate(applyExpr).catch(() => ({ ok: false }));
     return await readback();
 }
 /**
@@ -3736,7 +3786,7 @@ async function applyRadioSelection(page, gi, ri, hint) {
  * step (e.g. "dismiss modal" on a modal-less page) has no such control, so the
  * fast-skip the comments call essential is preserved.
  */
-async function hasUnfilledRequiredControlForStep(page, instruction) {
+async function hasUnfilledRequiredControlForStep(target, instruction) {
     const parsed = parseSelectStep(instruction);
     if (!parsed?.questionLabel)
         return false;
@@ -3785,7 +3835,7 @@ async function hasUnfilledRequiredControlForStep(page, instruction) {
     return false;
   })(${JSON.stringify(parsed.questionLabel)})`;
     try {
-        return (await page.evaluate(expr)) === true;
+        return (await target.evaluate(expr)) === true;
     }
     catch {
         return false;
@@ -3807,7 +3857,7 @@ async function hasUnfilledRequiredControlForStep(page, instruction) {
  * drag-and-drop API. Works on react-dropzone, Material Dropzone, custom
  * <uapp-upload>/<app-upload>, and any other drop-zone-based upload UI.
  */
-async function simulateDragDropUpload(page, fixture, logger) {
+async function simulateDragDropUpload(target, fixture, logger) {
     const base64 = fixture.buffer.toString("base64");
     const expr = `(async () => {
     const fileName = ${JSON.stringify(fixture.name)};
@@ -3853,7 +3903,7 @@ async function simulateDragDropUpload(page, fixture, logger) {
     }
   })()`;
     try {
-        const result = await page.evaluate(expr);
+        const result = await target.evaluate(expr);
         if (result && typeof result === "object" && "ok" in result && result.ok === true) {
             const tag = "dropZoneTag" in result ? String(result.dropZoneTag) : "(unknown)";
             logger.info(`upload primitive: drag-drop dispatched on <${tag}>`);
@@ -3889,7 +3939,7 @@ async function simulateDragDropUpload(page, fixture, logger) {
  * safely escapes it into a JS string literal. The expression body is a fixed
  * literal — no user-controlled JS execution.
  */
-async function dispatchJqueryChangeEvent(page, selector) {
+async function dispatchJqueryChangeEvent(target, selector) {
     const xpath = xpathBody(selector);
     if (!xpath)
         return;
@@ -3908,7 +3958,7 @@ async function dispatchJqueryChangeEvent(page, selector) {
     }
   })()`;
     try {
-        await page.evaluate(expr);
+        await target.evaluate(expr);
     }
     catch {
         // best-effort: jQuery dispatch failure shouldn't fail the verifier
@@ -3920,14 +3970,17 @@ async function dispatchJqueryChangeEvent(page, selector) {
  * Re-read DOM state from the same selector Stagehand acted upon and compare
  * against what it tried to write. Falls back to `false` on any locator error
  * so the navigation-class signal is still the deciding vote when this returns.
+ *
+ * `target` scopes both the locator/evaluate reads and the jQuery-change
+ * dispatch to the resolved frame (main or a cross-origin child).
  */
-async function verifyDomEffect(page, action) {
+async function verifyDomEffect(target, action) {
     const selector = action.selector;
     const method = action.method;
     if (!selector || !method)
         return false;
     try {
-        const locator = page.locator(selector).first();
+        const locator = target.locator(selector).first();
         switch (method) {
             case "fill":
             case "type": {
@@ -3943,7 +3996,7 @@ async function verifyDomEffect(page, action) {
                     // delegated handler) record the value
                     // into their internal data model. Without this, the SPA's next
                     // re-render wipes the typed value back to empty.
-                    await dispatchJqueryChangeEvent(page, selector);
+                    await dispatchJqueryChangeEvent(target, selector);
                     // Angular reactive forms (e.g. ADP WOTC questionnaire on tcs.adp.com)
                     // don't pick up CDP Input.insertText OR dispatchEvent('input') —
                     // their FormControl model updates require real keyboard events.
@@ -3991,7 +4044,7 @@ async function verifyDomEffect(page, action) {
                 const expr = `(() => { const r = document.evaluate(${JSON.stringify(xpath)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null); const el = r.singleNodeValue; if (!el || el.tagName !== "SELECT") return null; const opt = el.options[el.selectedIndex]; if (!opt) return { value: "", label: "", text: "" }; return { value: (opt.value || "").trim(), label: (opt.label || "").trim(), text: (opt.textContent || "").trim() }; })()`;
                 let selected = null;
                 try {
-                    const result = await page.evaluate(expr);
+                    const result = await target.evaluate(expr);
                     if (result !== null &&
                         typeof result === "object" &&
                         "value" in result &&
@@ -4032,7 +4085,7 @@ async function verifyDomEffect(page, action) {
                     // Node-side typechecking doesn't choke on the browser globals
                     // `document`/`XPathResult`.
                     const expr = `(() => { const r = document.evaluate(${JSON.stringify(xpath)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null); const el = r.singleNodeValue; return el ? (el.type || null) : null; })()`;
-                    const result = await page.evaluate(expr);
+                    const result = await target.evaluate(expr);
                     inputType = typeof result === "string" ? result : null;
                 }
                 catch {
@@ -4066,7 +4119,7 @@ async function verifyDomEffect(page, action) {
           }
           return false;
         })()`;
-                const ancestorStillInvalid = await page.evaluate(ancestorInvalidExpr).catch(() => false);
+                const ancestorStillInvalid = await target.evaluate(ancestorInvalidExpr).catch(() => false);
                 return !ancestorStillInvalid;
             }
             default:
@@ -4329,9 +4382,9 @@ function formatStepPrefix(stepIndex, totalSteps) {
     return total === undefined ? `step ${stepIndex + 1}` : `step ${stepIndex + 1}/${total}`;
 }
 async function probeFormValidityBeforeSubmit(params) {
-    const { page, stepIndex, totalSteps, logger } = params;
+    const { target, stepIndex, totalSteps, logger } = params;
     try {
-        const raw = await page.evaluate(FORM_VALIDITY_PROBE_EXPR);
+        const raw = await target.evaluate(FORM_VALIDITY_PROBE_EXPR);
         if (!Array.isArray(raw))
             return [];
         const out = [];
@@ -4363,11 +4416,15 @@ async function probeFormValidityBeforeSubmit(params) {
  * candidates for a declarative "Fill in X" step even when the field is present —
  * so a 0-candidate focused result falls back to an unfocused observe before the
  * step is declared "absent". Exported for tests.
+ *
+ * `frameTarget` scopes both observe calls to a resolved cross-origin child
+ * frame when the flow declared `frameSelector`; omitted (main frame) is
+ * byte-identical to today's unscoped calls.
  */
 async function probeStepBeforeAttempts(params) {
-    const { stagehand, step, stepIndex, totalSteps, logger, captureFn } = params;
+    const { stagehand, step, stepIndex, totalSteps, logger, captureFn, frameTarget } = params;
     try {
-        const candidates = await (0, stagehand_guard_1.guardedObserve)(stagehand, step, { timeout: exports.STEP_WATCHDOG_MS }, captureFn);
+        const candidates = await (0, stagehand_guard_1.guardedObserve)(stagehand, step, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget);
         if (candidates.length === 0) {
             // Focused observe under-returns on some controlled-component forms:
             // Stagehand's instruction-scoped observe can resolve zero candidates for a
@@ -4380,7 +4437,7 @@ async function probeStepBeforeAttempts(params) {
             // to the cascade (its observe-act / rephrase attempts recover the field
             // without spending the scarce replan budget). Only genuinely blank pages —
             // where the unfocused observe is also empty — stay "absent".
-            const unfocused = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn);
+            const unfocused = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget);
             if (unfocused.length > 0) {
                 logger.info(`${formatStepPrefix(stepIndex, totalSteps)}: focused probe found 0 candidates but unfocused observe found ${unfocused.length} — treating as present (let cascade resolve)`);
                 return "present";
@@ -4399,7 +4456,7 @@ async function probeStepBeforeAttempts(params) {
     }
 }
 async function executeStepWithHealing(params) {
-    const { stagehand, page, step, optional, upload, submitStep, stepIndex, totalSteps, phase, signalCounter, recentCaptures, recentCaptureMeta, anthropic, logger, captureFn, resumeFixture, isFinalStep, submitEndpointPattern, submittedStateSelectors, requireSubmitEndpointMatch, advanceTransitionBodyPattern, successUrlFragments, successPageTitleHints, ownBackendHostnames, knownErrorClassPrefixes, wizardExitButtonLabels, getSuppressedAisdkElementIdErrorCount, trajectory, onStepFailure, } = params;
+    const { stagehand, page, frameTarget, step, optional, upload, submitStep, stepIndex, totalSteps, phase, signalCounter, recentCaptures, recentCaptureMeta, anthropic, logger, captureFn, resumeFixture, isFinalStep, submitEndpointPattern, submittedStateSelectors, requireSubmitEndpointMatch, advanceTransitionBodyPattern, successUrlFragments, successPageTitleHints, ownBackendHostnames, knownErrorClassPrefixes, wizardExitButtonLabels, getSuppressedAisdkElementIdErrorCount, trajectory, onStepFailure, } = params;
     // Read-once to suppress "unused" — knownErrorClassPrefixes is threaded
     // through executeStepWithHealing's signature so the cascade has it in
     // scope when the invalid-fields judge migration (Task #43) lands. The
@@ -4433,6 +4490,7 @@ async function executeStepWithHealing(params) {
     // the existing cascade.
     if (await tryUploadPrimitive({
         page,
+        target: await (0, frame_target_1.resolveFrameTarget)(page),
         isUploadStep: upload,
         fixture: resumeFixture,
         logger,
@@ -4449,7 +4507,20 @@ async function executeStepWithHealing(params) {
     // cascade would otherwise skip them ("no candidates") and leave a required
     // question unanswered. No-op (returns false → falls through) when the step
     // isn't a single-dropdown select or no option matches.
-    if (await trySelectPrimitive({ page, instruction: step, logger, anthropic, captureFn })) {
+    //
+    // resolveFrameTarget(page) resolves synchronously to the main-frame target
+    // when no frameSelector is set, so this bridge is behavior-identical for
+    // every existing site until the sibling subtask threads a resolved target
+    // through end-to-end.
+    const selectFrameTarget = await (0, frame_target_1.resolveFrameTarget)(page);
+    if (await trySelectPrimitive({
+        page,
+        target: selectFrameTarget,
+        instruction: step,
+        logger,
+        anthropic,
+        captureFn,
+    })) {
         logger.info(`${formatStepPrefix(stepIndex, totalSteps)} resolved by select primitive`);
         trajectory?.push({ stepIndex, verifiedBy: "dom" });
         return "completed";
@@ -4459,7 +4530,14 @@ async function executeStepWithHealing(params) {
     // screening questions this way — answer it directly in the DOM. Runs AFTER
     // trySelectPrimitive (which handles <select> and no-ops on checkbox-only
     // pages). No-op (falls through) when there's no checkbox group or no match.
-    if (await tryCheckboxPrimitive({ page, instruction: step, logger, anthropic, captureFn })) {
+    if (await tryCheckboxPrimitive({
+        page,
+        target: selectFrameTarget,
+        instruction: step,
+        logger,
+        anthropic,
+        captureFn,
+    })) {
         logger.info(`${formatStepPrefix(stepIndex, totalSteps)} resolved by checkbox primitive`);
         trajectory?.push({ stepIndex, verifiedBy: "dom" });
         return "completed";
@@ -4470,7 +4548,14 @@ async function executeStepWithHealing(params) {
     // reach the observe cascade's el.click() fallback that fails to commit MUI/
     // React controlled state (the wizard ATS's Basic-Info Step-2 wall). No-op (falls
     // through) when there's no radio group or no confident option match.
-    if (await tryRadioPrimitive({ page, instruction: step, logger, anthropic, captureFn })) {
+    if (await tryRadioPrimitive({
+        page,
+        target: frameTarget ?? (0, frame_target_1.mainFrameTarget)(page),
+        instruction: step,
+        logger,
+        anthropic,
+        captureFn,
+    })) {
         logger.info(`${formatStepPrefix(stepIndex, totalSteps)} resolved by radio primitive`);
         trajectory?.push({ stepIndex, verifiedBy: "dom" });
         return "completed";
@@ -4481,7 +4566,14 @@ async function executeStepWithHealing(params) {
     // step targets (requisition-specific specialty questions). Runs only on the
     // catch-all (parseSelectStep returns null there, so trySelectPrimitive above
     // skipped it) and no-ops when the page has no required-empty select.
-    if (await tryFillRequiredSelectsPrimitive({ page, instruction: step, logger, anthropic, captureFn })) {
+    if (await tryFillRequiredSelectsPrimitive({
+        page,
+        target: selectFrameTarget,
+        instruction: step,
+        logger,
+        anthropic,
+        captureFn,
+    })) {
         logger.info(`${formatStepPrefix(stepIndex, totalSteps)} resolved by required-select primitive`);
         trajectory?.push({ stepIndex, verifiedBy: "dom" });
         return "completed";
@@ -4501,6 +4593,7 @@ async function executeStepWithHealing(params) {
         totalSteps,
         logger,
         captureFn,
+        frameTarget,
     });
     if (probeResult === "absent") {
         if (optional) {
@@ -4508,7 +4601,7 @@ async function executeStepWithHealing(params) {
             // control this step was meant to answer (SPA hydration lag / observe
             // can't resolve the widget) — skipping would leave a required field empty
             // and silently doom the later submit. Fall through to the cascade instead.
-            if (await hasUnfilledRequiredControlForStep(page, step)) {
+            if (await hasUnfilledRequiredControlForStep(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page), step)) {
                 logger.info(`${formatStepPrefix(stepIndex, totalSteps)} probe-absent but a required unfilled control matches the question; NOT skipping (escalating to cascade)`);
             }
             else {
@@ -4553,19 +4646,19 @@ async function executeStepWithHealing(params) {
         // burns the replan budget in seconds. Embed `see <path>` in the
         // throw message so the existing regex at the dispatcher (`/see
         // (\/[^\s]+)$/`) extracts dumpPath for replanRemainingFlow.
-        const pageTitle = await page.title().catch(() => "");
-        const bodyOuterHtmlRaw = await page
+        const { pageTitle, pageUrl } = await resolveDumpPageIdentity(page, frameTarget);
+        const bodyOuterHtmlRaw = await (frameTarget ?? page)
             .evaluate("document.body ? document.body.outerHTML : null")
             .catch(() => null);
         const bodyOuterHtml = typeof bodyOuterHtmlRaw === "string" ? bodyOuterHtmlRaw.slice(0, 100_000) : null;
-        const unfocusedObserve = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn).catch(() => []);
+        const unfocusedObserve = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
         const dumpPath = onStepFailure?.({
             stepIndex,
             phase,
             originalStep: step,
             attempts: [],
             finalObserve: [],
-            pageUrl: page.url(),
+            pageUrl,
             pageTitle,
             recentCaptures,
             bodyOuterHtml,
@@ -4591,10 +4684,12 @@ async function executeStepWithHealing(params) {
     // form-validity auto-picker runs. The early-exit predicate compares this
     // to the post-attempt-1 count to detect "the click revealed NEW required
     // fields" — a state attempts 2-5 mathematically can't clear.
-    const preSubmitInvalidCount = requireSubmitEndpoint ? await countNgInvalidContainers(page) : 0;
+    const preSubmitInvalidCount = requireSubmitEndpoint
+        ? await countNgInvalidContainers(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page))
+        : 0;
     if (requireSubmitEndpoint) {
         const invalidControls = await probeFormValidityBeforeSubmit({
-            page,
+            target: await (0, frame_target_1.resolveFrameTarget)(page),
             stepIndex,
             totalSteps,
             logger,
@@ -4695,7 +4790,7 @@ async function executeStepWithHealing(params) {
         if (attempt > 1) {
             await page.waitForTimeout(attempt * ATTEMPT_BACKOFF_MS);
         }
-        const pre = await snapshotPage(page, signalCounter);
+        const pre = await snapshotPage(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page), signalCounter);
         // Snapshot the meta-tail length so the final-step pattern gate can scope
         // its URL scan to captures added DURING this attempt (not historical
         // tail from earlier steps).
@@ -4778,7 +4873,7 @@ async function executeStepWithHealing(params) {
                 for (let deepAttempt = 1; deepAttempt <= 2; deepAttempt++) {
                     let ranked;
                     try {
-                        ranked = (await page.evaluate((0, submit_control_1.buildRankSubmitCandidatesExpr)()));
+                        ranked = (await (frameTarget ?? page).evaluate((0, submit_control_1.buildRankSubmitCandidatesExpr)()));
                     }
                     catch (err) {
                         // A thrown evaluate (page navigated away / frame detached) is not
@@ -4798,7 +4893,7 @@ async function executeStepWithHealing(params) {
                     triedSelectors.push(`deep-index:${top.deepIndex}`);
                     let clickResult;
                     try {
-                        clickResult = (await page.evaluate((0, submit_control_1.buildClickByDeepIndexExpr)(top.deepIndex)));
+                        clickResult = (await (frameTarget ?? page).evaluate((0, submit_control_1.buildClickByDeepIndexExpr)(top.deepIndex)));
                     }
                     catch (err) {
                         record.errorMessage = `deep-submit-locator: click evaluate threw ${(0, errors_1.toErrorMessage)(err)}`;
@@ -4828,7 +4923,7 @@ async function executeStepWithHealing(params) {
                         // burn the step budget probing all of them.
                         const runnerUp = ranked[1];
                         if (runnerUp) {
-                            const midPost = await snapshotPage(page, signalCounter);
+                            const midPost = await snapshotPage(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page), signalCounter);
                             const topVerdict = (0, phantom_click_1.classifyPhantomClick)({
                                 actResultSuccess: true,
                                 pre,
@@ -4842,7 +4937,7 @@ async function executeStepWithHealing(params) {
                                     `deep-index:${runnerUp.deepIndex}`,
                                 ];
                                 triedSelectors.push(`deep-index:${runnerUp.deepIndex}`);
-                                const runnerUpClickResult = (await page
+                                const runnerUpClickResult = (await (frameTarget ?? page)
                                     .evaluate((0, submit_control_1.buildClickByDeepIndexExpr)(runnerUp.deepIndex))
                                     .catch(() => ({ clicked: false })));
                                 record.actResultSuccess = runnerUpClickResult.clicked;
@@ -4878,7 +4973,7 @@ async function executeStepWithHealing(params) {
                 const observeOptions = attempt === 4 && triedSelectors.length > 0
                     ? { ignoreSelectors: [...triedSelectors], timeout: exports.STEP_WATCHDOG_MS }
                     : { timeout: exports.STEP_WATCHDOG_MS };
-                const candidates = await (0, stagehand_guard_1.guardedObserve)(stagehand, step, observeOptions, captureFn);
+                const candidates = await (0, stagehand_guard_1.guardedObserve)(stagehand, step, observeOptions, captureFn, frameTarget);
                 if (candidates.length === 0) {
                     record.errorMessage = "observe returned no candidates";
                     // Optional-step short-circuit: when attempt 2 confirms no candidates
@@ -4899,7 +4994,7 @@ async function executeStepWithHealing(params) {
                         // still-empty control matching this step's question is present,
                         // don't fast-skip — let the healing cascade continue so the
                         // required field gets answered instead of silently doomed.
-                        if (await hasUnfilledRequiredControlForStep(page, step)) {
+                        if (await hasUnfilledRequiredControlForStep(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page), step)) {
                             logger.info(`${formatStepPrefix(stepIndex, totalSteps)} no candidates after act+observe but a required unfilled control matches; NOT skipping (continuing cascade)`);
                         }
                         else {
@@ -4956,7 +5051,8 @@ async function executeStepWithHealing(params) {
                         target.arguments.length > 0) {
                         const fillValue = target.arguments[0];
                         if (typeof fillValue === "string") {
-                            const dateFill = await fillHtml5DateTimeInput(page, target.selector, fillValue);
+                            const frameTarget = await (0, frame_target_1.resolveFrameTarget)(page);
+                            const dateFill = await fillHtml5DateTimeInput(frameTarget, target.selector, fillValue);
                             if (dateFill !== null) {
                                 record.errorMessage = dateFill.filled
                                     ? `html5-date-fallback: filled ${dateFill.inputType}="${dateFill.postValue}"`
@@ -4976,7 +5072,7 @@ async function executeStepWithHealing(params) {
                                 // component rejection, masked-input library reformatting).
                                 // Generic primitive that the verifier's existing signals
                                 // (network/url/dom/htmlDelta/textChanged) miss.
-                                const readback = await verifyFillReadback(page, target.selector, fillValue);
+                                const readback = await verifyFillReadback(frameTarget, target.selector, fillValue);
                                 if (readback !== null) {
                                     if (readback.outcome === "rejected") {
                                         record.errorMessage = `fill-value-rejected: tried "${fillValue.slice(0, 60)}" on <${readback.tag}>; element value remains empty (silent rejection — HTML5 type validation, framework controlled-component, or masked-input library)`;
@@ -5094,7 +5190,8 @@ async function executeStepWithHealing(params) {
             return { resolved: true, isCheckable: true, checked: false, strategyUsed: null };
           })()`;
                     try {
-                        const result = await page.evaluate(probeExpr);
+                        const structuredClickTarget = await (0, frame_target_1.resolveFrameTarget)(page);
+                        const result = await structuredClickTarget.evaluate(probeExpr);
                         if (result !== null && typeof result === "object" && "resolved" in result) {
                             const probe = result;
                             if (probe.resolved !== true || probe.isCheckable !== true) {
@@ -5148,7 +5245,7 @@ async function executeStepWithHealing(params) {
                     // Fetch live-page evidence so the rephrase prompt can reason about
                     // form state, not just observe candidates. Mirrors the same
                     // extraction the cascade-exhaust dump path already does.
-                    const livePageEvidence = await extractLivePageFormEvidence(page, {
+                    const livePageEvidence = await extractLivePageFormEvidence(page, frameTarget ?? (0, frame_target_1.mainFrameTarget)(page), {
                         client: anthropic,
                         knownErrorClassPrefixes,
                         captureFn,
@@ -5208,7 +5305,7 @@ async function executeStepWithHealing(params) {
             continue;
         }
         await page.waitForTimeout(STEP_PAUSE_MS);
-        const post = await snapshotPage(page, signalCounter);
+        const post = await snapshotPage(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page), signalCounter);
         record.post = post;
         if (resolvedAction) {
             record.resolvedMethod = resolvedAction.method ?? null;
@@ -5225,7 +5322,7 @@ async function executeStepWithHealing(params) {
         // false for non-radio/non-checkbox clicks so the network/URL signal still
         // decides those. Radios/checkboxes are click-but-no-network just like fills.
         const domVerified = resolvedAction !== null && (isStateClass || isClick)
-            ? await verifyDomEffect(page, resolvedAction)
+            ? await verifyDomEffect(await (0, frame_target_1.resolveFrameTarget)(page), resolvedAction)
             : false;
         // Interior-advance transition gate (opt-in). On SPAs where a page advance
         // and a mere field-edit share one endpoint URL (the wizard ATS's `/gq`:
@@ -5318,7 +5415,8 @@ async function executeStepWithHealing(params) {
             return null;
           })()`;
                 try {
-                    domSubmittedMatch = (await page.evaluate(probeExpr));
+                    const submittedStateTarget = await (0, frame_target_1.resolveFrameTarget)(page);
+                    domSubmittedMatch = (await submittedStateTarget.evaluate(probeExpr));
                 }
                 catch (err) {
                     logger.warn(`submitted-state DOM probe threw: ${(0, errors_1.toErrorMessage)(err)} — judge will reason without it`);
@@ -5330,7 +5428,7 @@ async function executeStepWithHealing(params) {
             // Quick invalid-marker count (deterministic DOM querying — counting
             // structural ng-invalid containers is not fuzzy matching, just
             // observing existence).
-            const invalidMarkerCount = await countNgInvalidContainers(page).catch(() => 0);
+            const invalidMarkerCount = await countNgInvalidContainers(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page)).catch(() => 0);
             const pageTitle = await page.title().catch(() => "");
             const matchedSubmittedSelectors = domSubmittedMatch !== null ? [domSubmittedMatch] : [];
             const judgeVerdict = await (0, verify_submit_1.verifySubmitWithLLM)({
@@ -5442,7 +5540,8 @@ async function executeStepWithHealing(params) {
                     // reliably trigger that default action — same gap N+42 documented
                     // for direct checkbox/radio clicks.
                     const clickExpr = `(() => { const r = document.evaluate(${JSON.stringify(xpath)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null); let el = r.singleNodeValue; if (!el || typeof el.click !== "function") return { fired: false }; if (el.tagName === "LABEL") { const wrapped = el.querySelector("input[type=checkbox], input[type=radio]"); if (wrapped) el = wrapped; } if (el.type === "checkbox" || el.type === "radio") { el.checked = true; el.dispatchEvent(new Event("click", { bubbles: true })); el.dispatchEvent(new Event("change", { bubbles: true })); return { fired: true, kind: "checkbox", checked: el.checked }; } el.click(); return { fired: true, kind: "click" }; })()`;
-                    const probeResult = (await page.evaluate(clickExpr));
+                    const n16FallbackTarget = await (0, frame_target_1.resolveFrameTarget)(page);
+                    const probeResult = (await n16FallbackTarget.evaluate(clickExpr));
                     const fired = probeResult.fired;
                     // Vacuous-click guard for the n+16 fallback. Same rationale as
                     // verifyDomEffect's click case: a checkbox/radio input's .checked
@@ -5465,7 +5564,7 @@ async function executeStepWithHealing(params) {
               }
               return false;
             })()`;
-                        ancestorStillInvalid = (await page
+                        ancestorStillInvalid = (await n16FallbackTarget
                             .evaluate(ancestorInvalidExpr)
                             .catch(() => false));
                     }
@@ -5473,7 +5572,7 @@ async function executeStepWithHealing(params) {
                         probeResult.checked === true &&
                         !ancestorStillInvalid;
                     await page.waitForTimeout(STEP_PAUSE_MS);
-                    const retryPost = await snapshotPage(page, signalCounter);
+                    const retryPost = await snapshotPage(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page), signalCounter);
                     const retryNetworkFired = retryPost.networkCount > pre.networkCount;
                     const retryUrlChanged = retryPost.url !== pre.url;
                     const retryHtmlDelta = retryPost.bodyHtmlLength - pre.bodyHtmlLength;
@@ -5490,7 +5589,9 @@ async function executeStepWithHealing(params) {
                     // Confirmed no-op signature on the wizard ATS's COMPENSATION page (network=false
                     // url=false htmlDelta>0 textChanged) mis-scored verified=true(dom).
                     const clickWasDomOnly = probeResult.kind === "click" && !retryNetworkFired && !retryUrlChanged;
-                    const clickBlockedByInvalid = clickWasDomOnly && (await countNgInvalidContainers(page).catch(() => 0)) > 0;
+                    const clickBlockedByInvalid = clickWasDomOnly &&
+                        (await countNgInvalidContainers(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page)).catch(() => 0)) >
+                            0;
                     // Advance-transition gate (same as the primary verifier, applied to the
                     // n+16 fallback). RC2: for a non-submit ADVANCE/"Next" step (per the
                     // ORIGINAL instruction) the fallback's positive signals — a network POST
@@ -5553,14 +5654,14 @@ async function executeStepWithHealing(params) {
                   return null;
                 })()`;
                             try {
-                                domSubmittedMatch = (await page.evaluate(probeExpr));
+                                domSubmittedMatch = (await (frameTarget ?? page).evaluate(probeExpr));
                             }
                             catch (err) {
                                 logger.warn(`n+16 submitted-state DOM probe threw: ${(0, errors_1.toErrorMessage)(err)}`);
                             }
                         }
-                        const unfocusedForJudge = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn).catch(() => []);
-                        const invalidMarkerCount = await countNgInvalidContainers(page).catch(() => 0);
+                        const unfocusedForJudge = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
+                        const invalidMarkerCount = await countNgInvalidContainers(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page)).catch(() => 0);
                         const pageTitle = await page.title().catch(() => "");
                         const matchedSubmittedSelectors = domSubmittedMatch !== null ? [domSubmittedMatch] : [];
                         const judgeVerdict = await (0, verify_submit_1.verifySubmitWithLLM)({
@@ -5670,7 +5771,7 @@ async function executeStepWithHealing(params) {
         // dumps in a 2026-06-10 survey had the paired touched+dirty + visible
         // error text pattern with 3 distinct rejection messages.
         if (record.resolvedMethod === "click" && (isFinalStep || submitStep)) {
-            const live = await extractLivePageFormEvidence(page, {
+            const live = await extractLivePageFormEvidence(page, frameTarget ?? (0, frame_target_1.mainFrameTarget)(page), {
                 client: anthropic,
                 knownErrorClassPrefixes,
                 captureFn,
@@ -5719,7 +5820,7 @@ async function executeStepWithHealing(params) {
                     : "non-submit step — leaving the normal structured-click/observe-act-exclude ladder intact";
                 logger.warn(`${formatStepPrefix(stepIndex, totalSteps)} phantom click detected on attempt 1 (${record.technique}): reported success with no network/url/dom change${suppressedCount !== undefined ? `; ${suppressedCount} AISDK elementId errors suppressed this session (corroborating, not causal)` : ""} — ${escalationTarget}`);
             }
-            const postAttemptInvalidCount = await countNgInvalidContainers(page);
+            const postAttemptInvalidCount = await countNgInvalidContainers(frameTarget ?? (0, frame_target_1.mainFrameTarget)(page));
             const earlyExit = isSubmitRevealedInvalid({
                 // Treat the canonical submit click as "final" for this predicate
                 // even when it lives mid-flow. See requireSubmitEndpoint derivation
@@ -5759,23 +5860,23 @@ async function executeStepWithHealing(params) {
             }
         }
     }
-    const finalObserve = await (0, stagehand_guard_1.guardedObserve)(stagehand, step, { timeout: exports.STEP_WATCHDOG_MS }, captureFn).catch(() => []);
-    const pageTitle = await page.title().catch(() => "");
+    const finalObserve = await (0, stagehand_guard_1.guardedObserve)(stagehand, step, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
+    const { pageTitle, pageUrl } = await resolveDumpPageIdentity(page, frameTarget);
     // Discriminator data for "Stagehand sees nothing" failures: capture the raw
     // DOM and an unfocused observe so a triager can tell empty-page from
     // Stagehand-can't-see-it without reproducing the failure.
-    const bodyOuterHtmlRaw = await page
+    const bodyOuterHtmlRaw = await (frameTarget ?? page)
         .evaluate("document.body ? document.body.outerHTML : null")
         .catch(() => null);
     const bodyOuterHtml = typeof bodyOuterHtmlRaw === "string" ? bodyOuterHtmlRaw.slice(0, 100_000) : null;
-    const unfocusedObserve = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn).catch(() => []);
+    const unfocusedObserve = await (0, stagehand_guard_1.guardedObserve)(stagehand, undefined, { timeout: exports.STEP_WATCHDOG_MS }, captureFn, frameTarget).catch(() => []);
     const dumpPath = onStepFailure?.({
         stepIndex,
         phase,
         originalStep: step,
         attempts,
         finalObserve,
-        pageUrl: page.url(),
+        pageUrl,
         pageTitle,
         recentCaptures,
         bodyOuterHtml,
@@ -5850,6 +5951,8 @@ async function runHealingFlow(deps) {
     let submitVerified = false;
     let submitStepSkipped = false;
     let lastStepIndex = -1;
+    const frameTarget = await (0, frame_target_1.resolveFrameTarget)(page, deps.frameSelector);
+    await (0, frame_target_1.waitForChildFrameReady)(frameTarget);
     const stopCapture = wireSignalCapture(page, {
         counter,
         signalCounter,
@@ -5887,6 +5990,7 @@ async function runHealingFlow(deps) {
                 anthropic,
                 logger,
                 resumeFixture,
+                frameTarget,
                 isFinalStep: i === steps.length - 1,
                 submitEndpointPattern: deps.submitEndpointPattern ?? null,
                 submittedStateSelectors: deps.submittedStateSelectors ?? [],