@enricai/barnacle 1.6.6 → 1.6.8

package/dist/scraper/frame-target.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Cross-origin frame resolver: the single seam that lets every downstream
+ * helper (flow-runner primitives, guarded Stagehand calls) act on either the
+ * main frame or a resolved cross-origin OOPIF without knowing which. Some
+ * ATS integrations (e.g. UCHealth's Talemetry wizard) embed their entire
+ * application form inside a cross-origin `<iframe>` rather than navigating
+ * the top window to it, and `document`-rooted helpers (`page.evaluate`,
+ * `page.locator`) cannot reach across that boundary — `contentDocument` on a
+ * cross-origin iframe element is `null` from page script's perspective.
+ * `resolveFrameTarget` finds the child `Frame` Stagehand's CDP layer already
+ * attached to and wraps it in a uniform `FrameTarget` surface.
+ */
+import type { Page } from "@browserbasehq/stagehand";
+/** The frame handle type `Page.frames()` returns, without a deep import into Stagehand's understudy internals. */
+type StagehandFrame = ReturnType<Page["frames"]>[number];
+/**
+ * Uniform evaluate/locator/url/title surface bound to either the main frame
+ * (`frame: null`) or a resolved cross-origin child frame. `frameSelector` is
+ * the CSS selector of the scoped frame (or `null` for main), carried so
+ * callers can pass it straight through to `ObserveOptions.selector` /
+ * `ExtractOptions.selector` and scope Stagehand's own observe/extract calls
+ * to the same frame this target evaluates and locates against.
+ */
+export interface FrameTarget {
+    /** The resolved child frame, or `null` when this target is bound to the main frame. */
+    readonly frame: StagehandFrame | null;
+    /** CSS selector for the Stagehand scope hint (`ObserveOptions.selector` / `ExtractOptions.selector`), or `null` for the main frame. */
+    readonly frameSelector: string | null;
+    /** Evaluate a function or expression against the resolved frame (or the main frame when unresolved). */
+    evaluate<R = unknown, Arg = unknown>(pageFunctionOrExpression: string | ((arg: Arg) => R | Promise<R>), arg?: Arg): Promise<R>;
+    /** Build a Locator scoped to the resolved frame (or the main frame when unresolved). */
+    locator(selector: string): ReturnType<Page["locator"]>;
+    /** Current URL of the resolved frame (or the main frame when unresolved). */
+    url(): Promise<string>;
+    /** Current document title. Cross-origin child frames have no accessible `document.title` distinct from the top document via CDP `Page.title`, so this always reads the top document's title. */
+    title(): Promise<string>;
+}
+/**
+ * Builds the main-frame `FrameTarget`: every method delegates straight to
+ * `Page`, matching today's behavior for every site whose ATS form never
+ * leaves the top window. Exported so call sites that have not yet resolved
+ * a `FrameTarget` from `deps.frameSelector` can still pass a target-shaped
+ * value to helpers that now require one.
+ */
+export declare function mainFrameTarget(page: Page): FrameTarget;
+/**
+ * Resolves the `FrameTarget` for `frameSelector` against `page`, falling
+ * back to the main-frame target whenever resolution can't confidently
+ * succeed rather than throwing:
+ *
+ * 1. `frameSelector` is `null`/`undefined` → main-frame target (today's
+ *    behavior, unchanged).
+ * 2. No element in the main document matches `frameSelector`, or it isn't
+ *    an `<iframe>`/has no `src` → main-frame target.
+ * 3. No frame in `page.frames()` has an origin matching the `<iframe>`
+ *    element's `src` → main-frame target.
+ * 4. Otherwise → a child-frame target bound to the first matching frame.
+ *
+ * Step 2 reads the `src` attribute (not `contentDocument`) via `page.evaluate`
+ * on the main frame, which stays readable across the cross-origin boundary —
+ * only same-origin script access to the child's document is blocked.
+ */
+export declare function resolveFrameTarget(page: Page, frameSelector?: string | null): Promise<FrameTarget>;
+/**
+ * Composes a Stagehand hop-notation scope string from a frame selector and an
+ * inner selector, for callers building `ObserveOptions.selector` /
+ * `ExtractOptions.selector` values — kept separate from `FrameTarget` itself
+ * so `resolveFrameTarget` keeps receiving only the bare iframe-id hop (the
+ * contract `frame-resolve.test.ts` pins) rather than a pre-composed string.
+ */
+export declare function buildHopSelector(frameSelector: string | null | undefined, innerSelector: string): string;
+/** Shared delay helper — `FrameTarget` has no `waitForTimeout` since it isn't frame-scoped. */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Blocks until a resolved child frame has a live document (`document.readyState`
+ * is `"interactive"` or `"complete"`), so callers do not observe/act against a
+ * frame that CDP has attached to but that has not yet navigated past `about:blank`
+ * — the state right after `Target.setAutoAttach` fires and before the OOPIF's own
+ * navigation lands. Best-effort like `waitForSpaReady`: never throws, just resolves
+ * once ready or once `timeoutMs` elapses, so a frame that never becomes ready
+ * degrades to "proceed anyway" rather than hanging the flow.
+ */
+export declare function waitForChildFrameReady(target: FrameTarget, opts?: {
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=frame-target.d.ts.map

package/dist/scraper/frame-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-target.d.ts","sourceRoot":"","sources":["../../src/scraper/frame-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAMrD,kHAAkH;AAClH,KAAK,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,uIAAuI;IACvI,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,wGAAwG;IACxG,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,EACjC,wBAAwB,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,EACjE,GAAG,CAAC,EAAE,GAAG,GACR,OAAO,CAAC,CAAC,CAAC,CAAC;IACd,wFAAwF;IACxF,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IACvD,6EAA6E;IAC7E,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACvB,gMAAgM;IAChM,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,CASvD;AAoCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAC5B,OAAO,CAAC,WAAW,CAAC,CAsBtB;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,aAAa,EAAE,MAAM,GACpB,MAAM,CAOR;AAMD,+FAA+F;AAC/F,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GACjD,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/scraper/frame-target.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * Cross-origin frame resolver: the single seam that lets every downstream
+ * helper (flow-runner primitives, guarded Stagehand calls) act on either the
+ * main frame or a resolved cross-origin OOPIF without knowing which. Some
+ * ATS integrations (e.g. UCHealth's Talemetry wizard) embed their entire
+ * application form inside a cross-origin `<iframe>` rather than navigating
+ * the top window to it, and `document`-rooted helpers (`page.evaluate`,
+ * `page.locator`) cannot reach across that boundary — `contentDocument` on a
+ * cross-origin iframe element is `null` from page script's perspective.
+ * `resolveFrameTarget` finds the child `Frame` Stagehand's CDP layer already
+ * attached to and wraps it in a uniform `FrameTarget` surface.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mainFrameTarget = mainFrameTarget;
+exports.resolveFrameTarget = resolveFrameTarget;
+exports.buildHopSelector = buildHopSelector;
+exports.sleep = sleep;
+exports.waitForChildFrameReady = waitForChildFrameReady;
+const logging_1 = require("../lib/logging");
+const logger = (0, logging_1.getLogger)({ name: "scraper/frame-target" });
+/**
+ * Builds the main-frame `FrameTarget`: every method delegates straight to
+ * `Page`, matching today's behavior for every site whose ATS form never
+ * leaves the top window. Exported so call sites that have not yet resolved
+ * a `FrameTarget` from `deps.frameSelector` can still pass a target-shaped
+ * value to helpers that now require one.
+ */
+function mainFrameTarget(page) {
+    return {
+        frame: null,
+        frameSelector: null,
+        evaluate: (pageFunctionOrExpression, arg) => page.evaluate(pageFunctionOrExpression, arg),
+        locator: (selector) => page.locator(selector),
+        url: () => Promise.resolve(page.url()),
+        title: () => page.title(),
+    };
+}
+/**
+ * Builds a child-frame `FrameTarget`: `evaluate`/`locator` delegate to the
+ * resolved `Frame` (reaching across the cross-origin boundary via its own
+ * CDP session), while `url`/`title` fall back to the frame's own
+ * `location.href` and the top document's title respectively — `Frame` has
+ * no `title()` of its own.
+ */
+function childFrameTarget(page, frame, frameSelector) {
+    return {
+        frame,
+        frameSelector,
+        evaluate: (pageFunctionOrExpression, arg) => frame.evaluate(pageFunctionOrExpression, arg),
+        locator: (selector) => frame.locator(selector),
+        url: () => frame.evaluate("location.href"),
+        title: () => page.title(),
+    };
+}
+/**
+ * Reads the origin (scheme + host) off a URL string, or `null` if it isn't
+ * parseable — used to match a candidate `page.frames()` entry against the
+ * `<iframe>` element's `src` attribute without requiring an exact URL match
+ * (the iframe `src` and the frame's live `location.href` commonly differ by
+ * path/query after the child navigates, e.g. an application UUID appended
+ * post-load).
+ */
+function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolves the `FrameTarget` for `frameSelector` against `page`, falling
+ * back to the main-frame target whenever resolution can't confidently
+ * succeed rather than throwing:
+ *
+ * 1. `frameSelector` is `null`/`undefined` → main-frame target (today's
+ *    behavior, unchanged).
+ * 2. No element in the main document matches `frameSelector`, or it isn't
+ *    an `<iframe>`/has no `src` → main-frame target.
+ * 3. No frame in `page.frames()` has an origin matching the `<iframe>`
+ *    element's `src` → main-frame target.
+ * 4. Otherwise → a child-frame target bound to the first matching frame.
+ *
+ * Step 2 reads the `src` attribute (not `contentDocument`) via `page.evaluate`
+ * on the main frame, which stays readable across the cross-origin boundary —
+ * only same-origin script access to the child's document is blocked.
+ */
+async function resolveFrameTarget(page, frameSelector) {
+    if (!frameSelector)
+        return mainFrameTarget(page);
+    const iframeSrcExpr = `(() => {
+    const el = document.querySelector(${JSON.stringify(frameSelector)});
+    if (!el || el.tagName !== "IFRAME") return null;
+    return el.getAttribute("src");
+  })()`;
+    const iframeSrc = await page.evaluate(iframeSrcExpr);
+    if (!iframeSrc)
+        return mainFrameTarget(page);
+    const targetOrigin = originOf(iframeSrc);
+    if (!targetOrigin)
+        return mainFrameTarget(page);
+    const candidates = page.frames();
+    for (const candidate of candidates) {
+        const candidateUrl = await candidate.evaluate("location.href").catch(() => null);
+        if (candidateUrl && originOf(candidateUrl) === targetOrigin) {
+            return childFrameTarget(page, candidate, frameSelector);
+        }
+    }
+    return mainFrameTarget(page);
+}
+const HOP_SEPARATOR = " >> ";
+/**
+ * Composes a Stagehand hop-notation scope string from a frame selector and an
+ * inner selector, for callers building `ObserveOptions.selector` /
+ * `ExtractOptions.selector` values — kept separate from `FrameTarget` itself
+ * so `resolveFrameTarget` keeps receiving only the bare iframe-id hop (the
+ * contract `frame-resolve.test.ts` pins) rather than a pre-composed string.
+ */
+function buildHopSelector(frameSelector, innerSelector) {
+    if (!frameSelector)
+        return innerSelector;
+    const trimmedFrameSelector = frameSelector.trimEnd();
+    if (trimmedFrameSelector.endsWith(">>")) {
+        return `${trimmedFrameSelector} ${innerSelector.trimStart()}`;
+    }
+    return `${trimmedFrameSelector}${HOP_SEPARATOR}${innerSelector.trimStart()}`;
+}
+/** Readiness-wait defaults — cheap poll, short timeout: an attached-but-not-yet-navigated child frame should settle in well under a second. */
+const FRAME_READY_TIMEOUT_MS = 5_000;
+const FRAME_READY_POLL_MS = 100;
+/** Shared delay helper — `FrameTarget` has no `waitForTimeout` since it isn't frame-scoped. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Blocks until a resolved child frame has a live document (`document.readyState`
+ * is `"interactive"` or `"complete"`), so callers do not observe/act against a
+ * frame that CDP has attached to but that has not yet navigated past `about:blank`
+ * — the state right after `Target.setAutoAttach` fires and before the OOPIF's own
+ * navigation lands. Best-effort like `waitForSpaReady`: never throws, just resolves
+ * once ready or once `timeoutMs` elapses, so a frame that never becomes ready
+ * degrades to "proceed anyway" rather than hanging the flow.
+ */
+async function waitForChildFrameReady(target, opts = {}) {
+    if (!target.frame)
+        return;
+    const timeoutMs = opts.timeoutMs ?? FRAME_READY_TIMEOUT_MS;
+    const pollMs = opts.pollMs ?? FRAME_READY_POLL_MS;
+    const isReady = async () => {
+        const readyState = await target.evaluate("document.readyState").catch(() => null);
+        return readyState === "interactive" || readyState === "complete";
+    };
+    if (await isReady())
+        return;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await sleep(pollMs);
+        if (await isReady())
+            return;
+    }
+    logger.warn(`child frame ${target.frameSelector ?? "(unresolved)"} still not ready after ${timeoutMs}ms — proceeding anyway`);
+}
+//# sourceMappingURL=frame-target.js.map

package/dist/scraper/frame-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-target.js","sourceRoot":"","sources":["../../src/scraper/frame-target.ts"],"names":[],"mappings":"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"}

package/dist/scraper/retry.d.ts

@@ -16,8 +16,8 @@ export interface RetryOptions {
  * Wraps a scraper task with p-retry and a classification policy aligned
  * with our ScraperError hierarchy:
  *
- * - CaptchaError + EmptyResultsError → AbortError, no retry.
- * - SessionTimeoutError → invoke onSessionRestart once (guarded by sessionRestartEntry.done), then retry up to maxAttempts.
+ * - CaptchaError + EmptyResultsError + StepVerificationError → AbortError, no retry.
+ * - SessionTimeoutError → invoke onSessionRestart before every retry, then retry up to maxAttempts.
  * - SelectorFailureError + UnknownScraperError → retry up to maxAttempts.
  * - Anything non-ScraperError → wrap in UnknownScraperError and retry.
  *

package/dist/scraper/retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/scraper/retry.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,YAAY,EAIb,MAAM,kBAAkB,CAAC;AAI1B;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,mEAAmE;IACnE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAkDZ;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAmB/D"}
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/scraper/retry.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,YAAY,EAKb,MAAM,kBAAkB,CAAC;AAI1B;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,mEAAmE;IACnE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAoDZ;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAmB/D"}

package/dist/scraper/retry.js

@@ -44,8 +44,8 @@ const logger = (0, logging_1.getLogger)({ name: "scraper/retry" });
  * Wraps a scraper task with p-retry and a classification policy aligned
  * with our ScraperError hierarchy:
  *
- * - CaptchaError + EmptyResultsError → AbortError, no retry.
- * - SessionTimeoutError → invoke onSessionRestart once (guarded by sessionRestartEntry.done), then retry up to maxAttempts.
+ * - CaptchaError + EmptyResultsError + StepVerificationError → AbortError, no retry.
+ * - SessionTimeoutError → invoke onSessionRestart before every retry, then retry up to maxAttempts.
  * - SelectorFailureError + UnknownScraperError → retry up to maxAttempts.
  * - Anything non-ScraperError → wrap in UnknownScraperError and retry.
  *
@@ -54,7 +54,6 @@ const logger = (0, logging_1.getLogger)({ name: "scraper/retry" });
  */
 async function withScraperRetry(task, options = {}) {
     const maxAttempts = options.maxAttempts ?? 3;
-    const sessionRestartEntry = { done: false };
     return (0, p_retry_1.default)(async () => {
         try {
             return await task();
@@ -72,11 +71,12 @@ async function withScraperRetry(task, options = {}) {
                 logger.warn(`scraper returned empty results — aborting retry: ${err.message}`);
                 throw new p_retry_1.AbortError(err.message);
             }
-            if (err instanceof errors_2.SessionTimeoutError && !sessionRestartEntry.done) {
-                sessionRestartEntry.done = true;
-                if (options.onSessionRestart) {
-                    await options.onSessionRestart();
-                }
+            if (err instanceof errors_2.StepVerificationError) {
+                logger.warn(`step verification failed deterministically — aborting retry: ${err.message}`);
+                throw new p_retry_1.AbortError(err.message);
+            }
+            if (err instanceof errors_2.SessionTimeoutError && options.onSessionRestart) {
+                await options.onSessionRestart();
             }
             throw err;
         }

package/dist/scraper/retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/scraper/retry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/scraper/retry.ts"],"names":[],"mappings":"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"}

package/dist/scraper/stagehand-guard.d.ts

@@ -39,6 +39,7 @@
 import type { Action, ActOptions, ActResult, ExtractOptions, ObserveOptions, Stagehand } from "@browserbasehq/stagehand";
 import { z } from "zod/v4";
 import { type LlmCallInput } from "../lib/telemetry/call-capture";
+import { type FrameTarget } from "../scraper/frame-target";
 /**
  * Injectable capture function — matches `captureLlmCall`'s signature. Same
  * shape as `JudgeCaptureFn` in `@/lib/llm/judge`. Lets each guard call route
@@ -109,20 +110,47 @@ export declare class StagehandSchemaError extends Error {
  * `Action` (from a prior `observe`). On the happy path, returns Stagehand's
  * `ActResult` verbatim. On envelope drift, throws `StagehandSchemaError`
  * and logs `failureKind: "schema-validation-failed"`.
+ *
+ * Accepts the same trailing `frameTarget` param as `guardedObserve`/
+ * `guardedExtract` for signature symmetry, but does not forward it into
+ * `ActOptions` — `ActOptions` has no `selector` field, and its `page`
+ * override only accepts a full Playwright/Puppeteer/Patchright/understudy
+ * `Page`, not the `Frame` handle `FrameTarget.frame` exposes (the
+ * understudy `Page` constructor is private, so there is no way to
+ * synthesize a frame-scoped `Page`). Scope `act` at the call site instead:
+ * pair a frame-scoped `guardedObserve` (whose returned `Action.selector`
+ * already targets the resolved frame's DOM) with `guardedAct` called on
+ * that `Action` — the `observe(...)[0] -> act(target)` pattern already used
+ * throughout `flow-runner.ts`.
  */
-export declare function guardedAct(stagehand: Stagehand, input: string | Action, options?: ActOptions, captureFn?: StagehandCaptureFn): Promise<ActResult>;
+export declare function guardedAct(stagehand: Stagehand, input: string | Action, options?: ActOptions, captureFn?: StagehandCaptureFn, _frameTarget?: FrameTarget): Promise<ActResult>;
 /**
  * Schema-guarded wrapper around Stagehand's `observe`. Mirrors the
  * Stagehand overloads: no args, options-only, instruction-only,
  * instruction + options. On envelope drift (the `Action[]` shape changes),
  * throws `StagehandSchemaError`.
+ *
+ * When `frameTarget` resolves to a cross-origin child frame, its
+ * `frameSelector` is merged into `ObserveOptions.selector` so Stagehand's
+ * snapshot/candidate search is scoped to that frame's DOM instead of only
+ * the top frame. A caller-supplied `options.selector` wins over
+ * `frameTarget.frameSelector` — the caller made an explicit choice. The
+ * main-frame target (`frameTarget` omitted, or its `frameSelector` is
+ * `null`) leaves `options` untouched, so every existing call site is
+ * byte-identical to today.
  */
-export declare function guardedObserve(stagehand: Stagehand, instruction?: string, options?: ObserveOptions, captureFn?: StagehandCaptureFn): Promise<Action[]>;
+export declare function guardedObserve(stagehand: Stagehand, instruction?: string, options?: ObserveOptions, captureFn?: StagehandCaptureFn, frameTarget?: FrameTarget): Promise<Action[]>;
 /**
  * Schema-guarded wrapper around Stagehand's `extract` 3-arg overload. The
  * caller's Zod schema is what Stagehand asks the LLM to satisfy AND what we
  * `safeParse` against caller-side. Refuse the 1-arg / 2-arg defaults; every
  * extract call in the codebase must enforce a schema.
+ *
+ * When `frameTarget` resolves to a cross-origin child frame, its
+ * `frameSelector` is merged into `ExtractOptions.selector` so Stagehand
+ * extracts from that frame's DOM instead of only the top frame. A
+ * caller-supplied `options.selector` wins over `frameTarget.frameSelector`.
+ * The main-frame target leaves `options` untouched.
  */
-export declare function guardedExtract<T extends z.ZodTypeAny>(stagehand: Stagehand, instruction: string, schema: T, options?: ExtractOptions, captureFn?: StagehandCaptureFn): Promise<z.infer<T>>;
+export declare function guardedExtract<T extends z.ZodTypeAny>(stagehand: Stagehand, instruction: string, schema: T, options?: ExtractOptions, captureFn?: StagehandCaptureFn, frameTarget?: FrameTarget): Promise<z.infer<T>>;
 //# sourceMappingURL=stagehand-guard.d.ts.map

package/dist/scraper/stagehand-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stagehand-guard.d.ts","sourceRoot":"","sources":["../../src/scraper/stagehand-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EACV,SAAS,EACT,cAAc,EACd,cAAc,EACd,SAAS,EACV,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,8BAA8B,CAAC;AAOtC;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAExE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa;;;;;iBAKxB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;iBAM5B,CAAC;AAEH;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAG,0BAA0B,CAAU;IACpD,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B,YACE,SAAS,EAAE,KAAK,GAAG,SAAS,GAAG,SAAS,EACxC,QAAQ,EAAE,CAAC,CAAC,QAAQ,EACpB,WAAW,EAAE,OAAO,EAOrB;CACF;AAoBD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE,UAAU,EACpB,SAAS,CAAC,EAAE,kBAAkB,GAC7B,OAAO,CAAC,SAAS,CAAC,CAqEpB;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,SAAS,EACpB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,cAAc,EACxB,SAAS,CAAC,EAAE,kBAAkB,GAC7B,OAAO,CAAC,MAAM,EAAE,CAAC,CAkEnB;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACzD,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,cAAc,EACxB,SAAS,CAAC,EAAE,kBAAkB,GAC7B,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAsErB"}
+{"version":3,"file":"stagehand-guard.d.ts","sourceRoot":"","sources":["../../src/scraper/stagehand-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EACV,SAAS,EACT,cAAc,EACd,cAAc,EACd,SAAS,EACV,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,8BAA8B,CAAC;AAMtC,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE5E;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAExE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa;;;;;iBAKxB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;iBAM5B,CAAC;AAEH;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAG,0BAA0B,CAAU;IACpD,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B,YACE,SAAS,EAAE,KAAK,GAAG,SAAS,GAAG,SAAS,EACxC,QAAQ,EAAE,CAAC,CAAC,QAAQ,EACpB,WAAW,EAAE,OAAO,EAOrB;CACF;AAwCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE,UAAU,EACpB,SAAS,CAAC,EAAE,kBAAkB,EAC9B,YAAY,CAAC,EAAE,WAAW,GACzB,OAAO,CAAC,SAAS,CAAC,CAqEpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,SAAS,EACpB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,cAAc,EACxB,SAAS,CAAC,EAAE,kBAAkB,EAC9B,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,MAAM,EAAE,CAAC,CAmEnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACzD,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,cAAc,EACxB,SAAS,CAAC,EAAE,kBAAkB,EAC9B,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAsErB"}

package/dist/scraper/stagehand-guard.js

@@ -46,6 +46,7 @@ const node_crypto_1 = require("node:crypto");
 const v4_1 = require("zod/v4");
 const call_capture_1 = require("../lib/telemetry/call-capture");
 const call_types_1 = require("../lib/telemetry/call-types");
+const frame_target_1 = require("../scraper/frame-target");
 /**
  * Zod mirror of Stagehand's public `Action` shape (from
  * `@browserbasehq/stagehand/.../public/methods.d.ts`):
@@ -118,14 +119,43 @@ function safeStringify(value, cap = 4000) {
 function actInstructionOf(input) {
     return typeof input === "string" ? input : input.description;
 }
+/**
+ * Merges `frameTarget.frameSelector` into `options.selector` for
+ * `ObserveOptions`/`ExtractOptions`, composed as Stagehand `">>"` hop
+ * notation (`buildHopSelector`) rather than the bare iframe selector —
+ * `resolveCssFocusFrameAndTail` only crosses into the child frame's own CDP
+ * session when the selector has a hop segment before `>>`; a bare selector
+ * performs zero hops and scopes to the (empty) `<iframe>` element itself.
+ * The inner segment defaults to `*` (whole-frame scope) since callers don't
+ * supply one here. Returns `options` untouched when `frameTarget` is
+ * unresolved (main frame) or a caller-supplied `selector` is already
+ * present — both cases must leave today's call sites byte-identical.
+ */
+function frameScopedOptions(options, frameTarget) {
+    if (!frameTarget?.frameSelector || options?.selector !== undefined)
+        return options;
+    return { ...options, selector: (0, frame_target_1.buildHopSelector)(frameTarget.frameSelector, "*") };
+}
 /**
  * Schema-guarded wrapper around Stagehand's `act`. Same signature as the
  * underlying call: accepts either an instruction string or a structured
  * `Action` (from a prior `observe`). On the happy path, returns Stagehand's
  * `ActResult` verbatim. On envelope drift, throws `StagehandSchemaError`
  * and logs `failureKind: "schema-validation-failed"`.
+ *
+ * Accepts the same trailing `frameTarget` param as `guardedObserve`/
+ * `guardedExtract` for signature symmetry, but does not forward it into
+ * `ActOptions` — `ActOptions` has no `selector` field, and its `page`
+ * override only accepts a full Playwright/Puppeteer/Patchright/understudy
+ * `Page`, not the `Frame` handle `FrameTarget.frame` exposes (the
+ * understudy `Page` constructor is private, so there is no way to
+ * synthesize a frame-scoped `Page`). Scope `act` at the call site instead:
+ * pair a frame-scoped `guardedObserve` (whose returned `Action.selector`
+ * already targets the resolved frame's DOM) with `guardedAct` called on
+ * that `Action` — the `observe(...)[0] -> act(target)` pattern already used
+ * throughout `flow-runner.ts`.
  */
-async function guardedAct(stagehand, input, options, captureFn) {
+async function guardedAct(stagehand, input, options, captureFn, _frameTarget) {
     const callId = (0, node_crypto_1.randomUUID)();
     const userContent = actInstructionOf(input);
     const t0 = performance.now();
@@ -192,19 +222,29 @@ async function guardedAct(stagehand, input, options, captureFn) {
  * Stagehand overloads: no args, options-only, instruction-only,
  * instruction + options. On envelope drift (the `Action[]` shape changes),
  * throws `StagehandSchemaError`.
+ *
+ * When `frameTarget` resolves to a cross-origin child frame, its
+ * `frameSelector` is merged into `ObserveOptions.selector` so Stagehand's
+ * snapshot/candidate search is scoped to that frame's DOM instead of only
+ * the top frame. A caller-supplied `options.selector` wins over
+ * `frameTarget.frameSelector` — the caller made an explicit choice. The
+ * main-frame target (`frameTarget` omitted, or its `frameSelector` is
+ * `null`) leaves `options` untouched, so every existing call site is
+ * byte-identical to today.
  */
-async function guardedObserve(stagehand, instruction, options, captureFn) {
+async function guardedObserve(stagehand, instruction, options, captureFn, frameTarget) {
     const callId = (0, node_crypto_1.randomUUID)();
     const userContent = instruction ?? "";
     const t0 = performance.now();
+    const scopedOptions = frameScopedOptions(options, frameTarget);
     try {
         // Match Stagehand's overloads: pass instruction only when defined, so
         // the SDK falls through to its no-arg/options-only path otherwise.
         const raw = instruction === undefined
-            ? options === undefined
+            ? scopedOptions === undefined
                 ? await stagehand.observe()
-                : await stagehand.observe(options)
-            : await stagehand.observe(instruction, options);
+                : await stagehand.observe(scopedOptions)
+            : await stagehand.observe(instruction, scopedOptions);
         const latencyMs = performance.now() - t0;
         const parsed = v4_1.z.array(exports.ACTION_SCHEMA).safeParse(raw);
         if (!parsed.success) {
@@ -257,8 +297,14 @@ async function guardedObserve(stagehand, instruction, options, captureFn) {
  * caller's Zod schema is what Stagehand asks the LLM to satisfy AND what we
  * `safeParse` against caller-side. Refuse the 1-arg / 2-arg defaults; every
  * extract call in the codebase must enforce a schema.
+ *
+ * When `frameTarget` resolves to a cross-origin child frame, its
+ * `frameSelector` is merged into `ExtractOptions.selector` so Stagehand
+ * extracts from that frame's DOM instead of only the top frame. A
+ * caller-supplied `options.selector` wins over `frameTarget.frameSelector`.
+ * The main-frame target leaves `options` untouched.
  */
-async function guardedExtract(stagehand, instruction, schema, options, captureFn) {
+async function guardedExtract(stagehand, instruction, schema, options, captureFn, frameTarget) {
     const callId = (0, node_crypto_1.randomUUID)();
     const t0 = performance.now();
     try {
@@ -270,7 +316,7 @@ async function guardedExtract(stagehand, instruction, schema, options, captureFn
         // the cleanest public-API way to express "whatever overload-2 expects."
         // The `as unknown` step is needed because TS won't accept a single
         // direct cast across the entire overload set.
-        const raw = await stagehand.extract(instruction, schema, options);
+        const raw = await stagehand.extract(instruction, schema, frameScopedOptions(options, frameTarget));
         const latencyMs = performance.now() - t0;
         const parsed = schema.safeParse(raw);
         if (!parsed.success) {

package/dist/scraper/stagehand-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"stagehand-guard.js","sourceRoot":"","sources":["../../src/scraper/stagehand-guard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stagehand-guard.js","sourceRoot":"","sources":["../../src/scraper/stagehand-guard.ts"],"names":[],"mappings":"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"}

package/dist/scraper/submit-control.d.ts

@@ -22,8 +22,16 @@
  * re-runs the identical traversal and clicks the element at that index, so
  * the caller can locate once, decide which candidate to try, then click by
  * index without holding a live element handle across the two round trips.
+ *
+ * `root` overrides the traversal root expression (default `"document"`),
+ * interpolated verbatim into the generated code so a caller evaluating
+ * this expression via `Frame.evaluate` can pass `"document"` and still
+ * resolve that frame's own document — the expression never captures an
+ * outer `document` reference. {@link buildClickByDeepIndexExpr} must be
+ * given the same `root` so its re-run traversal produces the same
+ * `deepIndex` ordering as the one this call returned.
  */
-export declare function buildRankSubmitCandidatesExpr(): string;
+export declare function buildRankSubmitCandidatesExpr(root?: string): string;
 /**
  * Builds a self-contained `page.evaluate` expression string that re-runs
  * the same deterministic deep traversal as {@link buildRankSubmitCandidatesExpr}
@@ -32,8 +40,13 @@ export declare function buildRankSubmitCandidatesExpr(): string;
  * convention). Returns `{ clicked: false }` without throwing if the index is
  * out of range for the current DOM (e.g. the page changed between the
  * locate and click calls).
+ *
+ * `root` overrides the traversal root expression (default `"document"`)
+ * and must match the `root` passed to the {@link buildRankSubmitCandidatesExpr}
+ * call that produced `deepIndex`, or the re-run traversal order will not
+ * line up with the original ranking.
  */
-export declare function buildClickByDeepIndexExpr(deepIndex: number): string;
+export declare function buildClickByDeepIndexExpr(deepIndex: number, root?: string): string;
 /** Confidence tier for a ranked submit candidate — higher is more confident. See {@link buildRankSubmitCandidatesExpr}. */
 export type SubmitCandidateTier = 1 | 2 | 3;
 /** One ranked candidate returned by {@link buildRankSubmitCandidatesExpr}'s `page.evaluate` call. */

package/dist/scraper/submit-control.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"submit-control.d.ts","sourceRoot":"","sources":["../../src/scraper/submit-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAyEH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,6BAA6B,IAAI,MAAM,CAsBtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAYnE;AAED,2HAA2H;AAC3H,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAE5C,qGAAqG;AACrG,MAAM,WAAW,eAAe;IAC9B,mIAAmI;IACnI,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;CAClB"}
+{"version":3,"file":"submit-control.d.ts","sourceRoot":"","sources":["../../src/scraper/submit-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAyEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,SAAa,GAAG,MAAM,CAsBvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,SAAa,GAAG,MAAM,CAYtF;AAED,2HAA2H;AAC3H,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAE5C,qGAAqG;AACrG,MAAM,WAAW,eAAe;IAC9B,mIAAmI;IACnI,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;CAClB"}