Resolve facade locators and snapshot refs across frames

[miguelg719]

Composes facade locators through same-origin and out-of-process frames and preserves global snapshot refs without duplicating unresolved frame maps. This connects the existing SDK frame capability to the shared facade.

Includes extension snapshot regressions and real local Chrome tests for both frame types. Adds operator documentation for the combined ownership, deadline and disconnect controls, including remaining shutdown limitations.

Frame focus and scrolling use existing native primitives with effect-based tests. Selector lists, indexed all(), nested-frame scope and non-piercing snapshot traversal have regression coverage; unsupported regex attribute queries fail explicitly.

Validation: 158 unit tests, four real Chrome DOM/frame tests, direct Chrome CDP non-piercing capture check, core/extension builds and typechecks, refreshed Go embed/drift/packaging checks; Frame-composition and extension snapshot units; local Chrome same-origin and confirmed OOPIF checks.

Stack position: 6/17. Base: evals/consolidation-05-locator-wait-contract. Each PR contains the change relative to its immediate predecessor.

Reviewer entry points:

• packages/integrations/core/src/facade/tools.ts
• packages/extension/understudy/a11y/snapshot/capture.ts
• packages/integrations/core/integration/facade-dom.test.ts

Readiness: local validation is described above; GitHub CI and automated review feedback are pending. This PR is open as non-draft so automated reviewers can run.

[changeset-bot]

🦋 Changeset detected

Latest commit: 06d5b34

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@browserbasehq/stagehand-extension	Patch
@browserbasehq/stagehand-go	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

All reported issues were addressed across 8 files

Architecture diagram

sequenceDiagram
    participant SDK as Stagehand SDK
    participant Facade as Facade Runtime
    participant RawPage as Raw Page
    participant Snap as Snapshot Capture
    participant FrameMap as Frame DOM Maps
    participant Ext as Extension (Frame Resolution)

    Note over SDK,Ext: Frame Locator Composition Flow

    SDK->>Facade: frameLocator("#outer")
    Facade->>Facade: Compile hop selectors
    Facade->>Facade: frameLocator("#middle")
    Facade->>Facade: locator("form input")
    Facade->>RawPage: locator("#outer >> #middle >> form input")
    RawPage-->>Facade: RawLocator

    Note over Facade,Snap: Frame-Scoped Semantic Query Flow
    
    SDK->>Facade: frameLocator("#checkout").getByRole("button", { name: "Save" })
    Facade->>Facade: Check role filter support
    alt Unsupported role filter
        Facade-->>SDK: Throw guidance error
    else Supported query
        Facade->>Snap: Get accessibility snapshot (includeIframes)
        Snap->>FrameMap: Resolve frame document roots
        FrameMap->>Ext: NEW: resolveFrameDocRootBackendId()
        alt Same-session child frame missing
            Ext-->>FrameMap: Return undefined (skip frame)
            FrameMap-->>Snap: Preserve parent map only
        else Valid frame found
            Ext-->>FrameMap: Backend node ID
            FrameMap-->>Snap: Frame-scoped XPath map
        end
        Snap-->>Facade: Snapshot with frame XPaths
        Facade->>Facade: Filter to hop iframe subtree
        alt Multiple matches
            Facade-->>SDK: Strict mode violation error
        else Single match
            Facade->>RawPage: locator("xpath=/.../iframe/html/.../button")
        end
    end
    
    Note over RawPage,Ext: Frame Exclusion Intervals
    RawPage->>Facade: Build frame exclusions
    Facade->>FrameMap: Resolve ignored frame roots
    alt Resolved frame
        FrameMap-->>Facade: Exclusion interval
    else Unresolved frame
        FrameMap-->>Facade: Skip (no parent interval inherited)
    end
    
    Note over SDK,Ext: contentFrame() Entry Flow
    SDK->>Facade: locator("iframe").contentFrame()
    alt Not pure CSS selector
        Facade-->>SDK: Throw unsupported error
    else Valid CSS
        Facade->>Facade: Compile into hop notation
        Facade->>RawPage: locator("#outer >> :is(iframe) >> button")
        RawPage-->>Facade: Frame-scoped RawLocator
    end

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 8 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>