[feat]: add page.addInitScript()

[seanmcguire12]

why

• we currently have context.addInitScript(), which adds initialization scripts to all new pages
• we want users to be able to add init scripts to individual pages

what changed

• adds page.addInitScript(), which just wraps & exposes logic that was already in place for context.addInitScript(), namely normalizeInitScriptSources() and registerInitScript()

test plan

• added unit tests

---

Summary by cubic

Adds page.addInitScript() to inject initialization scripts for a single page across navigations. Enables per-page scoping and function args, mirroring Playwright behavior.

Why:

• We only had context.addInitScript() (all pages). Users need per-page control.

What:

• New API: page.addInitScript(script, arg?)
• Shared helper: normalizeInitScriptSource in lib/v3/understudy/initScripts.ts, used by page and context
• New type: InitScriptSource in internal types
• Docs: page reference updated with usage and semantics
• Changeset: patch release entry

Test Plan:

• Unit tests cover:
  • Runs on real navigations
  • Scoped to the page only
  • Supports function args
• Manual: override Math.random via page.addInitScript, navigate, confirm it applies only on that page
• Docs: follow the example in page.mdx to verify behavior and API shape

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

[changeset-bot]

🦋 Changeset detected

Latest commit: e2505ce

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

Added page.addInitScript() to allow injecting initialization scripts scoped to individual pages, complementing the existing context.addInitScript() which applies to all pages.

• Refactored normalizeInitScriptSource() into a reusable module in initScripts.ts with configurable caller parameter for improved error messages
• Moved InitScriptSource type to shared types/private/internal.ts for reuse across context and page
• Added page.addInitScript() method that wraps existing registerInitScript() infrastructure
• Comprehensive test coverage validates script execution, page-level scoping, and argument passing
• Documentation includes clear examples and cross-reference to context.addInitScript()

Confidence Score: 5/5

• This PR is safe to merge with no concerns
• The implementation is clean, well-tested, and follows existing patterns. The refactoring extracts shared logic without changing behavior. All changes reuse existing infrastructure (registerInitScript), have comprehensive unit tests covering key scenarios, and include proper documentation.
• No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
packages/core/lib/v3/tests/page-addInitScript.spec.ts	5/5	Added comprehensive unit tests covering real navigation, page scoping, and argument passing
packages/core/lib/v3/understudy/initScripts.ts	5/5	Extracted normalizeInitScriptSource() into reusable module with configurable caller parameter for better error messages
packages/core/lib/v3/understudy/context.ts	5/5	Refactored to use extracted normalizeInitScriptSource() function and import shared type
packages/core/lib/v3/understudy/page.ts	5/5	Added page.addInitScript() method that wraps existing registerInitScript() logic with normalization

Sequence Diagram

sequenceDiagram
    participant User
    participant Page
    participant InitScripts
    participant RegisterInit
    participant CDP

    User->>Page: addInitScript(script, arg)
    Page->>InitScripts: normalizeInitScriptSource(script, arg, "page.addInitScript")
    
    alt script is function
        InitScripts->>InitScripts: Convert to IIFE with JSON.stringify(arg)
    else script is string
        InitScripts->>InitScripts: Return as-is
    else script is {path}
        InitScripts->>InitScripts: Read file & append sourceURL
    else script is {content}
        InitScripts->>InitScripts: Return content
    end
    
    InitScripts-->>Page: normalized source string
    Page->>RegisterInit: registerInitScript(source)
    RegisterInit->>RegisterInit: Check if already registered
    RegisterInit->>RegisterInit: Add to initScripts array
    RegisterInit->>CDP: installInitScriptOnSession(mainSession, source)
    CDP->>CDP: Page.addScriptToEvaluateOnNewDocument
    
    loop For each adopted OOPIF session
        RegisterInit->>CDP: installInitScriptOnSession(session, source)
        CDP->>CDP: Page.addScriptToEvaluateOnNewDocument
    end
    
    RegisterInit-->>Page: Complete
    Page-->>User: Promise<void>

Loading

[greptile-apps]

_{6 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[cubic-dev-ai]

No issues found across 7 files