Pass local launch options when attaching over CDP

[shriyatheunicorn]

Summary

• Pass localBrowserLaunchOptions into V3Context.create() when LOCAL mode attaches to an existing browser via cdpUrl.
• Add a regression test that verifies the CDP attach path forwards viewport, device scale factor, and CDP headers through context creation.
• Add a patch changeset for the published Stagehand runtime behavior change.

Why

The launch path already passes local browser options into V3Context, which lets Page.create() apply the configured viewport and deviceScaleFactor. The CDP attach path only forwarded env and cdpHeaders, so attached local sessions skipped that Page-level viewport setup.

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
pnpm install --frozen-lockfile	Installed all 7 workspace projects from the lockfile; completed with Done in 13.9s.	Confirms the fresh PR worktree can resolve dependencies exactly from the committed lockfile.
pnpm exec turbo run build:esm --filter=@browserbasehq/stagehand	Turbo ran gen-version, build-dom-scripts, and build:esm; output ended with Tasks: 3 successful, 3 total.	Builds the exact local package under review, including generated runtime artifacts needed by the ESM output.
pnpm --filter @browserbasehq/stagehand exec vitest run --config vitest.esm.config.mjs dist/esm/tests/unit/browserbase-session-accessors.test.js	Vitest output: Test Files 1 passed (1), Tests 6 passed (6).	Confirms the regression test and nearby Browserbase/LOCAL accessor tests pass against the built ESM output.
node --input-type=module <inline LOCAL CDP attach viewport smoke>	Launched local Stagehand, reattached via cdpUrl with viewport: { width: 1440, height: 900 }, and printed {"status":"pass","cdpAttachViewport":{"innerWidth":1440,"innerHeight":900,"devicePixelRatio":1,"bottomRightHit":"target"}}.	Exercises the real built Stagehand package against a real local Chrome CDP session. Proves explicit CDP attach viewport settings control browser CSS viewport and bottom-right coordinate hit-testing; does not exercise kernel.sh specifically.
pnpm exec changeset status --since=origin/main	Changesets reported patch bumps for @browserbasehq/stagehand and dependent workspace packages.	Confirms the new changeset is detected as a release-triggering patch for this runtime behavior fix.

[changeset-bot]

🦋 Changeset detected

Latest commit: 9b8bb88

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

This PR includes changesets to release 5 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/browse-cli	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v3	Patch
@browserbasehq/stagehand-server-v4	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

[shriyatheunicorn]

bugbot run

[cursor]

Skipping Bugbot: Bugbot is disabled for this repository. Visit the Bugbot dashboard to update your settings.

[shrey150]

nice!

[cubic-dev-ai]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Client as Client Code
    participant V3 as V3 Class
    participant Context as V3Context
    participant Page as Page

    Note over Client,Page: LOCAL CDP Attach Path (New Flow)

    Client->>V3: new V3({ localBrowserLaunchOptions })
    V3->>V3: init()
    
    alt env === "LOCAL" with cdpUrl
        V3->>V3: Determine attach mode via cdpUrl
        
        Note over V3,Context: NEW: Forward full localBrowserLaunchOptions
        V3->>Context: V3Context.create(cdpUrl, {<br/>  env: "LOCAL",<br/>  cdpHeaders: lbo.cdpHeaders,<br/>  localBrowserLaunchOptions: lbo<br/>})
        
        Context->>Context: Create CDP connection
        Context-->>V3: ctx instance
        
        V3->>Context: ctx.conn.onTransportClosed(callback)
        
        Note over Context,Page: Viewport/DSF applied via launchOptions
        Context->>Page: Page.applyLaunchOptions({<br/>  viewport,<br/>  deviceScaleFactor<br/>})
        Page-->>Context: Page configured
        
        Context-->>V3: Ready for use
        V3-->>Client: Instance ready
    end

    alt env === "LOCAL" without cdpUrl (Launch Path - unchanged)
        Note over V3,Context: Existing launch path (not changed)
        V3->>Context: V3Context.create(env, launchOptions)
        Context-->>V3: ctx instance
    end

Loading

_{Re-trigger cubic}

[pirate]

This starts to drift from the naming of localBrowserLaunchOptions, it's a bit of a slippery slope, but it's fine for now.

In the future we should probably split stuff like viewport settings out into a separate browser_options or something to indicate it's applied to all browsers we connect to, not only browsers we launch.