[fix]: make page.evaluate() use main world

[seanmcguire12]

why

• currently, we add the init scripts to the main world
• this is problematic, because page.evaluate() uses the v3-world
• this means that you can't easily evaluate the script you add with addInitScript()

what changed

• makes sure that page.evaluate() uses the main world

test plan

• added a test which calls page.evaluate() on a script added via context.addInitScript()

---

Summary by cubic

Fixes a context mismatch: page.evaluate now runs in the main world so scripts injected via context.addInitScript are callable. Frame.evaluate was updated to use the main world too.

Why:

• evaluate() used the v3 isolated world while init scripts were in the main world, making injected globals inaccessible.

What:

• Switched page.evaluate and frame.evaluate to use the main-world execution context via executionContextRegistry.
• Added a test verifying an init-script function is callable from page.evaluate.

Test Plan:

• New test: init-script function is callable from page.evaluate (passes).
• Ran existing context.addInitScript tests to ensure no regressions.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: d4bf59d

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	Patch
@browserbasehq/stagehand-evals	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

[greptile-apps]

Greptile Overview

Greptile Summary

Changed page.evaluate() and frame.evaluate() to execute in the main world instead of an isolated world, fixing compatibility with scripts injected via context.addInitScript().

• Previously, init scripts were installed in the main world but evaluations ran in an isolated v3-world, preventing access to injected functions
• Now uses ExecutionContextRegistry to resolve the main world execution context for each frame
• Updated documentation comments to reflect the change
• Added comprehensive test coverage verifying that functions installed via addInitScript() are callable from page.evaluate()

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The changes are well-tested, properly documented, and address a clear bug where init scripts couldn't be accessed from evaluations due to execution context isolation. The implementation uses an existing, well-designed execution context registry to resolve main world contexts. The test coverage is comprehensive and validates the fix.
• No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
packages/core/lib/v3/understudy/frame.ts	5/5	Replaced isolated world execution with main world execution for frame.evaluate(), using execution context registry
packages/core/lib/v3/understudy/page.ts	5/5	Replaced isolated world execution with main world execution for page.evaluate(), page.title(), and lifecycle checks

Sequence Diagram

sequenceDiagram
    participant User
    participant Context
    participant Page
    participant CDPSession
    participant ExecutionContextRegistry
    participant Browser

    User->>Context: addInitScript(script)
    Context->>Page: registerInitScript(source)
    Page->>CDPSession: Page.addScriptToEvaluateOnNewDocument
    CDPSession->>Browser: Install script in main world

    User->>Page: goto(url)
    Browser->>CDPSession: Runtime.executionContextCreated
    CDPSession->>ExecutionContextRegistry: Register main world context
    Note over ExecutionContextRegistry: Tracks frameId -> contextId mapping<br/>for main world (isDefault=true)

    User->>Page: evaluate(function)
    Page->>ExecutionContextRegistry: waitForMainWorld(frameId)
    ExecutionContextRegistry-->>Page: Return main world contextId
    Page->>CDPSession: Runtime.evaluate(contextId)
    Note over CDPSession,Browser: Executes in main world<br/>where init scripts are available
    Browser-->>Page: Return result

Loading

[greptile-apps]

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[cubic-dev-ai]

1 issue found across 4 files

Prompt for AI agents (all 1 issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/core/lib/v3/tests/context-addInitScript.spec.ts">

<violation number="1" location="packages/core/lib/v3/tests/context-addInitScript.spec.ts:127">
P2: This test uses an external URL (`https://example.com`) while all other tests in this file use the `toDataUrl()` helper to create data URLs. Using an external URL makes the test dependent on network connectivity and potentially flaky. Consider using a data URL for consistency and reliability.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}

[cubic-dev-ai]

1 issue found across 4 files

Prompt for AI agents (all 1 issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/core/lib/v3/tests/context-addInitScript.spec.ts">

<violation number="1" location="packages/core/lib/v3/tests/context-addInitScript.spec.ts:127">
P2: This test uses an external URL (`https://example.com`) while all other tests in this file use `toDataUrl()` for network-independent data URLs. This introduces unnecessary network dependency and potential test flakiness.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}