[feat]: add context.addInitScript()

[seanmcguire12]

why

• adds a public facing API to inject scripts into new pages before existing JS is run

what changed

• added context.addInitScripts() which calls Page.addScriptToEvaluateOnNewDocument whenever we attach to a page target

test plan

• added unit tests which check that the injected scripts are run before existing scripts

[changeset-bot]

🦋 Changeset detected

Latest commit: b45d574

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

[seanmcguire12]

@greptileai

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds context.addInitScript() which injects JavaScript into pages before any existing scripts run, mirroring Playwright's API. The implementation properly handles script normalization (functions, strings, or file paths), applies scripts to all existing pages and their OOPIF sessions, and ensures new pages receive the scripts automatically.

Major changes:

• Added normalizeInitScriptSource() to handle function serialization with arguments, file path loading, and sourceURL annotations
• Implemented context.addInitScript() that stores scripts and applies them to all pages
• Added page.registerInitScript() to fan out scripts to all CDP sessions (main + OOPIFs)
• Enhanced OOPIF adoption to replay init scripts via applyInitScriptsToSession()
• Comprehensive test coverage validates script execution order and cross-navigation persistence

Confidence Score: 5/5

• This PR is safe to merge with no issues found
• The implementation is well-designed with proper error handling, follows existing patterns in the codebase, includes comprehensive test coverage, and correctly handles complex scenarios like OOPIF sessions and navigation persistence
• No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
.changeset/tender-moons-laugh.md	5/5	Standard changeset file documenting the new context.addInitScript() feature
packages/core/lib/v3/tests/context-addInitScript.spec.ts	5/5	Comprehensive test coverage for init script injection, including navigation persistence and argument passing
packages/core/lib/v3/understudy/context.ts	5/5	Implements context.addInitScript() with proper script normalization, applies scripts to existing and new pages
packages/core/lib/v3/understudy/page.ts	5/5	Handles per-page init script registration and application to all sessions including OOPIFs

Sequence Diagram

sequenceDiagram
    participant User
    participant V3Context
    participant Page
    participant CDPSession
    participant Browser

    User->>V3Context: addInitScript(script, arg?)
    V3Context->>V3Context: normalizeInitScriptSource(script, arg)
    V3Context->>V3Context: store script in initScripts[]
    V3Context->>V3Context: pages()
    loop For each existing page
        V3Context->>Page: registerInitScript(source)
        Page->>Page: check if script already registered
        Page->>Page: add to initScripts[]
        Page->>CDPSession: Page.addScriptToEvaluateOnNewDocument
        loop For all sessions (main + OOPIFs)
            CDPSession->>Browser: Register init script
        end
    end

    Note over User,Browser: When new page is created

    User->>V3Context: newPage()
    V3Context->>Browser: Target.createTarget
    Browser->>V3Context: attachedToTarget event
    V3Context->>Page: create Page instance
    V3Context->>V3Context: applyInitScriptsToPage(page)
    loop For each stored script
        V3Context->>Page: registerInitScript(source)
        Page->>CDPSession: Page.addScriptToEvaluateOnNewDocument
        CDPSession->>Browser: Register init script
    end

    Note over User,Browser: When OOPIF is attached

    Browser->>Page: adoptOopifSession(childSession)
    Page->>Page: applyInitScriptsToSession(childSession)
    loop For each stored script
        Page->>CDPSession: Page.addScriptToEvaluateOnNewDocument
        CDPSession->>Browser: Register init script for OOPIF
    end

Loading

[greptile-apps]

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}