fix: preserve OOPIF frame registry parent edge

[monadoid]

why

Stagehand could lose a known parent-child frame relationship after adopting an OOPIF child session. In practice, that meant the registry could forget that a child frame still belonged under the top-level page, leaving later iframe resolution with an incomplete frame tree.

what changed

Added a deterministic FrameRegistry unit test for the OOPIF adoption ordering. Updated seedFromFrameTree() to preserve an already-known parent when a child frame tree snapshot does not include parent metadata.

test plan

Before the fix, the new test failed with expected null to be 'root-frame'. After the fix, this passes:

pnpm --dir packages/core run build:esm && pnpm --dir packages/core run test:core -- packages/core/dist/esm/tests/unit/frame-registry-oopif-adoption.test.js

---

Summary by cubic

Fixes a bug where the frame registry could lose a known parent-child link after adopting an OOPIF child session. Preserves the parent edge when seeding from a child frame tree that lacks parent metadata to keep the iframe tree complete.

• Bug Fixes
  • Updated FrameRegistry.seedFromFrameTree() to retain an existing parent when parentId is missing and to sync child sets accordingly.
  • Added a unit test for OOPIF adoption ordering and seeding to prevent regressions, and a changeset for @browserbasehq/stagehand patch release.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 1e50e9c

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

This PR includes changesets to release 4 packages

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

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Driver as Stagehand Driver
    participant Registry as FrameRegistry
    participant Store as this.frames (Internal Map)
    participant CDP as CDP (Browser Sessions)

    Note over Driver, CDP: Phase 1: Parent Session Discovery
    CDP->>Registry: onFrameAttached(childId, parentId)
    Registry->>Store: ensureNode(childId)
    Registry->>Store: set parentId and update children Set

    Note over Driver, CDP: Phase 2: OOPIF Adoption
    Driver->>Registry: adoptChildSession(childSessionId, childId)
    Registry->>Store: setOwnerSessionIdInternal(childId, childSessionId)

    Note over Driver, CDP: Phase 3: Seeding from Child Session (OOPIF)
    CDP->>Registry: seedFromFrameTree(childSessionId, frameTree)
    
    loop For each node in tree (walk)
        Registry->>Store: get existing info (previousParent)
        
        Note over Registry, Store: CHANGED: Determine nextParent
        Registry->>Registry: nextParent = tree.parentId ?? previousParent

        alt previousParent exists and changed
            Registry->>Store: Remove childId from previousParent's children Set
        end

        Registry->>Store: Update info.parentId = nextParent
        
        opt nextParent is valid
            Registry->>Store: ensureNode(nextParent)
            Registry->>Store: Add childId to nextParent's children Set
        end

        Note over Registry, Store: CHANGED: Reconstruct lastSeen frame metadata
        Registry->>Store: lastSeen = frame + (injected parentId if missing)
        
        opt ownerSessionId unknown
            Registry->>Store: setOwnerSessionIdInternal
        end
    end

    Note over Driver, Registry: Frame resolution now sees complete tree across sessions

Loading