Resolve facade locators and snapshot refs across frames

[miguelg719]

Composes facade locators through same-origin and out-of-process frames and preserves global snapshot references without duplicating unresolved frame maps. Adds operator documentation for ownership, deadlines, and disconnect behavior.

Also repairs failures exposed by stack CI:

• Background-tab screenshots activate their target and serialize activation/capture across the browser. Setup and cleanup are serialized per page, so a stalled page cannot block other tabs. Capture deadlines stop waiting for stalled CDP responses; late responses cannot re-enter cleanup. Calls on a page with unfinished timeout recovery fail promptly until cleanup settles, after which screenshots resume.
• The Vantech Journal scorer identifies the archive’s Load more link by destination and text instead of an obsolete absolute XPath. Strict DOM element-identity scoring and the 80% gate remain unchanged.
• CLI test deadlines account for the bounded child processes they launch, including multi-command tests.

Validation: 24 local screenshot/lifecycle tests and 66 CLI/help tests passed, along with relevant typechecks and Go extension archive checks. Tests cover timeout rejection, isolation across tabs, and recovery after delayed setup/cleanup settles. Live Chrome verification accepts the recorded correct Vantech observation and rejects an unrelated element. Fresh CI is running on the updated head.

Stack position: 6/11 in the current review scope through #2901. Base: evals/consolidation-05-locator-wait-contract.

Reviewer entry points:

• Frame facade implementation
• Snapshot frame maps
• Screenshot lifecycle
• Archive scorer

[changeset-bot]

🦋 Changeset detected

Latest commit: 3ae8d85

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>

[cubic-dev-ai]

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

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

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

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

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

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

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

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

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

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>