Align label, strict locator, and URL wait semantics

[miguelg719]

Aligns the shared facade’s label matching, strict locator operations and URL waits with supported Playwright behavior. All consuming harnesses get these semantics through the same facade.

Scoped role matches now follow shadow hosts instead of relying on DOM containment. CSS, label, and snapshot-derived queries can access closed author shadow roots through a narrow extension batch operation. Temporary CDP references are released best-effort after each query; fixed typed errors avoid exposing page exception text, and the evaluator remains off the public SDK type; locator callbacks continue to execute in the page main world. The Go-embedded extension is rebuilt to match.

Adds local-browser comparisons against native Playwright alongside deterministic URL-wait tests. Frame composition is isolated in the next change.

Checkbox probes share the operation timeout; nested role filters are resolved before matching. The real DOM contract suite is registered in Turbo.

Validation: 144 shared integration unit tests, five local Chrome DOM tests, and 19 callback/shadow-reference tests pass. The new open/closed-root regressions fail against the previous implementation. A real Stagehand SDK + local extension smoke passes scoped lookup, fill, click, and main-world callback checks inside a closed root. Extension, SDK, integration, and eval typechecks pass; extension/integration builds, formatting, and Go extension drift check pass.

Stack position: 5/17. Base: evals/consolidation-04-cdp-diagnostics. Each PR contains the change relative to its immediate predecessor.

Reviewer entry points:

• packages/integrations/core/src/facade/runtime.ts
• packages/integrations/core/integration/facade-dom.test.ts
• packages/integrations/core/tests/facade-wait-for-url.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]

⚠️ No Changeset found

Latest commit: 16717f6

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[cubic-dev-ai]

All reported issues were addressed across 7 files

Architecture diagram

sequenceDiagram
    participant T as Test Harness
    participant F as Facade Runtime
    participant L as Raw Locator
    participant P as Raw Page
    participant B as Browser/CDP
    participant PW as Native Playwright

    Note over T,PW: Core Facade Alignment Flow

    T->>F: getByLabel(label, {exact})
    F->>B: Query DOM for labels (labelledby > aria-label > label)
    B-->>F: Matching elements
    F-->>T: Locator with matches
    
    alt Strict mode violation (multiple matches)
        T->>F: locator.textContent({timeout})
        F->>B: Detect multiple candidates
        B-->>F: Ambiguous elements
        F-->>T: Throw strict mode violation with candidates
    end

    T->>F: locator.inputValue({timeout})
    F->>L: Query strict single match
    L->>B: Wait for element
    alt Element appears
        B-->>L: Single element
        L-->>F: Value
        F-->>T: Return value
    else Element missing
        B-->>L: Not found
        L-->>F: Timeout error
        F-->>T: Throw timeout
    end

    T->>F: getByRole(role, {name})
    F->>B: DOM role matching
    alt No DOM matches
        F->>P: page.snapshot() - accessibility tree
        P-->>F: Formatted tree + xpathMap
        F->>F: Resolve role to XPaths
        F->>L: Apply xpath steps
        L-->>F: Elements
    end
    F-->>T: Locator result

    T->>F: waitForURL(glob, {timeout})
    F->>B: Read current URL
    
    loop Poll until timeout or match
        B-->>F: URL string
        F->>F: Match against Playwright glob semantics
        alt URL matches
            alt waitUntil specified
                F->>P: waitForLoadState(waitUntil, remainingTimeout)
            else default load
                F->>P: waitForLoadState("load", remainingTimeout)
            end
            P-->>F: Load complete
            F-->>T: Resolve
        else URL no match
            F->>B: Continue polling
        end
    end

    Note over F,T: Timeout=0 disables deadline (waits indefinitely)

    alt Callback evaluation
        T->>F: locator.evaluate(fn)
        F->>L: Serialize function
        L->>B: Execute in page context
        B-->>L: Result
        L-->>F: Return value
        F-->>T: Result
    end

    Note over B,PW: Contract comparison tests
    T->>T: Run test suite
    alt Integration tests
        T->>B: Launch local Chrome
        T->>PW: Native Playwright queries
        T->>F: Facade queries (same fixture)
        B-->>T: Results comparison
    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 9 files (changes from recent commits).

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

Re-trigger cubic</sub>