[feat]: add `page.addInitScript()` #1335

seanmcguire12 · 2025-12-02T20:06:04Z

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 cf41afd. Summary will update automatically on new commits.}

changeset-bot · 2025-12-02T20:06:08Z

🦋 Changeset detected

Latest commit: cf41afd

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 · 2025-12-02T20:08:49Z

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>

greptile-apps

_{6 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

cubic-dev-ai

No issues found across 7 files

# 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: - [x] 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 <sup>Written for commit cf41afd. Summary will update automatically on new commits.</sup>

@miguelg719

This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. # Releases ## @browserbasehq/[email protected] ### Patch Changes - [#1388](#1388) [`605ed6b`](605ed6b) Thanks [@miguelg719](https://github.com/miguelg719)! - Fix multiple click event dispatches on CDP and Anthropic CUA handling (double clicks) - [#1400](#1400) [`34e7e5b`](34e7e5b) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - don't write base64 encoded screenshots to disk when caching agent actions - [#1345](#1345) [`943d2d7`](943d2d7) Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for aborting / stopping an agent run & continuing an agent run using messages from prior runs - [#1334](#1334) [`0e95cd2`](0e95cd2) Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for google vertex provider - [#1410](#1410) [`d4237e4`](d4237e4) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: include extract in stagehand.history() - [#1315](#1315) [`86975e7`](86975e7) Thanks [@tkattkat](https://github.com/tkattkat)! - Add streaming support to agent through stream:true in the agent config - [#1304](#1304) [`d5e119b`](d5e119b) Thanks [@miguelg719](https://github.com/miguelg719)! - Add support for Microsoft's Fara-7B - [#1346](#1346) [`4e051b2`](4e051b2) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: don't attach to targets twice - [#1327](#1327) [`6b5a3c9`](6b5a3c9) Thanks [@miguelg719](https://github.com/miguelg719)! - Informed error parsing from api - [#1335](#1335) [`bb85ad9`](bb85ad9) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - add support for page.addInitScript() - [#1331](#1331) [`88d28cc`](88d28cc) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: page.evaluate() now works with scripts injected via context.addInitScript() - [#1316](#1316) [`45bcef0`](45bcef0) Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for callbacks in stagehand agent - [#1374](#1374) [`6aa9d45`](6aa9d45) Thanks [@miguelg719](https://github.com/miguelg719)! - Fix key action mapping in Anthropic CUA - [#1330](#1330) [`d382084`](d382084) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: make act, extract, and observe respect user defined timeout param - [#1336](#1336) [`1df08cc`](1df08cc) Thanks [@tkattkat](https://github.com/tkattkat)! - Patch agent on api - [#1358](#1358) [`2b56600`](2b56600) Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for 4.5 opus in cua agent ## @browserbasehq/[email protected] ### Patch Changes - [#1364](#1364) [`ca0630e`](ca0630e) Thanks [@tkattkat](https://github.com/tkattkat)! - Update model handling in agent evals cli - Updated dependencies \[[`605ed6b`](605ed6b), [`34e7e5b`](34e7e5b), [`943d2d7`](943d2d7), [`0e95cd2`](0e95cd2), [`d4237e4`](d4237e4), [`86975e7`](86975e7), [`d5e119b`](d5e119b), [`4e051b2`](4e051b2), [`6b5a3c9`](6b5a3c9), [`bb85ad9`](bb85ad9), [`88d28cc`](88d28cc), [`45bcef0`](45bcef0), [`6aa9d45`](6aa9d45), [`d382084`](d382084), [`1df08cc`](1df08cc), [`2b56600`](2b56600)]: - @browserbasehq/[email protected] ## @browserbasehq/[email protected] ### Patch Changes - Updated dependencies \[[`605ed6b`](605ed6b), [`34e7e5b`](34e7e5b), [`943d2d7`](943d2d7), [`0e95cd2`](0e95cd2), [`d4237e4`](d4237e4), [`86975e7`](86975e7), [`d5e119b`](d5e119b), [`4e051b2`](4e051b2), [`6b5a3c9`](6b5a3c9), [`bb85ad9`](bb85ad9), [`88d28cc`](88d28cc), [`45bcef0`](45bcef0), [`6aa9d45`](6aa9d45), [`d382084`](d382084), [`1df08cc`](1df08cc), [`2b56600`](2b56600)]: - @browserbasehq/[email protected] Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

@miguelg719

greptile-apps bot reviewed Dec 2, 2025

View reviewed changes

mintlify bot deployed to staging - packages/docs December 2, 2025 20:10 View deployment

cubic-dev-ai bot reviewed Dec 2, 2025

View reviewed changes

tkattkat approved these changes Dec 4, 2025

View reviewed changes

add page.addInitScript()

cf41afd

seanmcguire12 force-pushed the seanmcguire/stg-990-add-pageaddinitscript branch from e2505ce to cf41afd Compare December 4, 2025 18:27

mintlify bot deployed to staging - packages/docs December 4, 2025 18:28 View deployment

seanmcguire12 merged commit bb85ad9 into main Dec 4, 2025
27 of 28 checks passed

github-actions bot mentioned this pull request Dec 4, 2025

Version Packages #1305

Merged

This was referenced Dec 5, 2025

Version Packages evolv3ai/stagehand#1

Open

Version Packages CloudEngineHub/stagehand#1

Open

Version Packages AlexOcculate/stagehand#1

Open

Version Packages qa-nparekh/stagehand#1

Open

Version Packages afanty2021/stagehand#1

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[feat]: add `page.addInitScript()` #1335

[feat]: add `page.addInitScript()` #1335

Uh oh!

seanmcguire12 commented Dec 2, 2025 •

edited by cubic-dev-ai bot

Loading

Uh oh!

changeset-bot bot commented Dec 2, 2025 •

edited

Loading

Uh oh!

greptile-apps bot commented Dec 2, 2025

Uh oh!

greptile-apps bot left a comment

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

[feat]: add page.addInitScript() #1335

[feat]: add page.addInitScript() #1335

Uh oh!

Conversation

seanmcguire12 commented Dec 2, 2025 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

why

what changed

test plan

Summary by cubic

Why:

What:

Test Plan:

Uh oh!

changeset-bot bot commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

greptile-apps bot commented Dec 2, 2025

Greptile Overview

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

[feat]: add `page.addInitScript()` #1335

[feat]: add `page.addInitScript()` #1335

seanmcguire12 commented Dec 2, 2025 •

edited by cubic-dev-ai bot

Loading

changeset-bot bot commented Dec 2, 2025 •

edited

Loading