set default viewport when running on browserbase

[seanmcguire12]

why

• need to set default viewport when running on browserbase. previously, we only defined the default inside the exported StagehandConfig

what changed

• set default viewport to 1288 * 711 when running on browserbase

test plan

• tested locally,
• regression evals

[changeset-bot]

🦋 Changeset detected

Latest commit: 97ccc5e

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

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

Summary

This PR introduces a default viewport setting for Browserbase sessions to ensure consistent browser dimensions across all sessions. The change addresses an inconsistency where default viewport settings (1288x711) were only defined in the exported `StagehandConfig` but weren't actually applied when creating Browserbase sessions through the SDK.

The implementation creates a new utility module browserbaseDefaults.ts that exports a DEFAULT_BROWSERBASE_VIEWPORT constant and an applyDefaultBrowserSettingsViewport function. This function merges user-provided session parameters with default viewport settings, ensuring that every Browserbase session has consistent dimensions unless explicitly overridden.

The changes are applied in two key locations:

1. Session Creation (lib/index.ts): Both in the getBrowser() method when creating new sessions and in the constructor when storing session parameters
2. API Layer (lib/api.ts): When preparing session creation parameters for the Browserbase API

This approach maintains backward compatibility while ensuring that all Browserbase sessions have predictable viewport behavior, which is crucial for web automation reliability and consistent screenshot/interaction behavior.

Important Files Changed

Changed Files

Filename	Score	Overview
lib/browserbaseDefaults.ts	5/5	New utility file that defines default viewport constants and helper function for applying defaults
lib/index.ts	4/5	Applies default viewport settings during session creation and constructor initialization
lib/api.ts	5/5	Ensures default viewport is applied when creating sessions through the API layer

Confidence score: 5/5

• This PR is safe to merge with minimal risk as it only adds default values and doesn't change existing behavior when users provide explicit viewport settings
• Score reflects well-structured implementation with proper separation of concerns and consistent application across the codebase
• No files require special attention as the changes are straightforward and follow good software engineering practices

Sequence Diagram

sequenceDiagram
    participant User
    participant Stagehand
    participant StagehandAPI
    participant browserbaseDefaults
    participant getBrowser
    participant Browserbase

    User->>Stagehand: "new Stagehand(constructorParams)"
    Stagehand->>browserbaseDefaults: "applyDefaultBrowserSettingsViewport(browserbaseSessionCreateParams)"
    browserbaseDefaults-->>Stagehand: "params with default viewport (1288x711)"
    
    User->>Stagehand: "init()"
    
    alt usingAPI is true
        Stagehand->>StagehandAPI: "new StagehandAPI({apiKey, projectId, logger})"
        Stagehand->>StagehandAPI: "init({modelName, browserbaseSessionCreateParams, ...})"
        StagehandAPI->>browserbaseDefaults: "applyDefaultBrowserSettingsViewport(browserbaseSessionCreateParams)"
        browserbaseDefaults-->>StagehandAPI: "sessionCreateParams with default viewport"
        StagehandAPI->>Browserbase: "POST /sessions/start with sessionCreateParams"
        Browserbase-->>StagehandAPI: "session response"
        StagehandAPI-->>Stagehand: "{sessionId, available}"
    end
    
    Stagehand->>getBrowser: "getBrowser(apiKey, projectId, env, ...browserbaseSessionCreateParams)"
    
    alt env === "BROWSERBASE"
        getBrowser->>browserbaseDefaults: "applyDefaultBrowserSettingsViewport(browserbaseSessionCreateParams)"
        browserbaseDefaults-->>getBrowser: "sessionCreateParams with default viewport (1288x711)"
        getBrowser->>Browserbase: "sessions.create({projectId, ...sessionCreateParams})"
        Browserbase-->>getBrowser: "session with connectUrl"
        getBrowser->>Browserbase: "chromium.connectOverCDP(connectUrl)"
        Browserbase-->>getBrowser: "browser context"
    else env === "LOCAL"
        getBrowser->>getBrowser: "chromium.launchPersistentContext with viewport (1288x711)"
    end
    
    getBrowser-->>Stagehand: "{browser, context, debugUrl, sessionUrl, sessionId}"
    Stagehand-->>User: "{debugUrl, sessionUrl, sessionId}"

Loading

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}