[V3]: fix xpath building logic for coordinates inside of iframes

[seanmcguire12]

why

coordinate based targeting can resolve elements inside iframes differently depending on chrome's frame site isolation behavior. when chrome reports the inner frame directly, stagehand was returning the element path inside the iframe without the owning iframe path from the parent page. this caused the xpath-for-location-deep.spec.ts test to fail

this showed up in when using the --disable-features=SitePerProcess chrome flag

this PR also replaces the incorrect -disable-features=site-per-process flag with the correct --disable-features=SitePerProcess flag

what changed

• updated coordinate xpath resolution to handle direct child frame hits from chrome
• when DOM.getNodeForLocation reports a different frameId, stagehand now looks up that frame's owning iframe with DOM.getFrameOwner
• the owning iframe is added to the xpath chain before resolving the inner-frame node
• this keeps coordinate based iframe targeting consistent across same-process and isolated iframe behavior

test plan

• e2e test for resolveNodeForLocationDeep now passes

---

Summary by cubic

Fixes coordinate-based iframe targeting so XPath resolution stays consistent when DOM.getNodeForLocation reports a frame other than the current one, including nested iframes.

• Resolves each intermediate owning iframe via DOM.getFrameOwner and prepends them to the XPath chain.
• Returns no XPath when the reported frame's ancestry can't be fully traced to the current frame.
• Replaces the incorrect --site-per-process flag with --disable-features=SitePerProcess.

^{Written for commit f48ea11. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: f48ea11

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

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v3	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 3 files

Architecture diagram

sequenceDiagram
    participant CDP as Chrome DevTools Protocol
    participant CR as coordinateResolver.ts
    participant Page as Page (Session Manager)
    participant BAP as buildAbsoluteXPathFromChain
    participant Map as parentByFrame Map

    Note over CDP,Map: Coordinate-based XPath resolution with cross-frame support

    CR->>CDP: DOM.getNodeForLocation(x, y)
    CDP-->>CR: { backendNodeId, frameId }

    alt Reported frame matches current frame
        CR->>BAP: Build XPath from current iframe chain
        BAP-->>CR: absoluteXPath
        CR-->>CDP: Return { frameId, backendNodeId, absoluteXPath }
    else Reported frame is different (cross-frame hit)
        CR->>Map: Look up parent frame for reportedFrameId
        alt Parent frame found in map
            Map-->>CR: parentFrameId
            CR->>Page: getSessionForFrame(parentFrameId)
            Page-->>CR: parentSession
        else No parent frame in map
            CR->>Page: getSessionForFrame(currentFrameId)
            Page-->>CR: curSession
        end

        CR->>CDP: DOM.getFrameOwner(frameId: reportedFrameId)
        CDP-->>CR: { backendNodeId: iframeBackendNodeId }

        alt Valid iframe backendNodeId returned
            CR->>CR: Append { parentSession, iframeBackendNodeId } to iframe chain
        else Frame owner lookup failed
            CR->>CR: Silently skip (catch block)
        end

        CR->>Page: getSessionForFrame(reportedFrameId)
        Page-->>CR: leafSession

        CR->>BAP: buildAbsoluteXPathFromChain(chain, leafSession)
        BAP-->>CR: absoluteXPath

        alt XPath resolved successfully
            CR-->>CDP: Return { frameId: reportedFrameId, backendNodeId, absoluteXPath }
        else XPath resolution returned null
            CR-->>CDP: Return null
        end
    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 2 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 1 file (changes from recent commits).

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

Re-trigger cubic</sub>