set default viewport when running on browserbase (#1114)

# 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

Author: seanmcguire12

.changeset/funky-showers-rush.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+configure default viewport when running on browserbase

lib/api.ts

@@ -28,6 +28,7 @@ import {
   StagehandResponseParseError,
 } from "../types/stagehandApiErrors";
 import makeFetchCookie from "fetch-cookie";
+import { applyDefaultBrowserSettingsViewport } from "./browserbaseDefaults";
 import { STAGEHAND_VERSION } from "./version";
 
 export class StagehandAPI {
@@ -64,7 +65,10 @@ export class StagehandAPI {
     }
     this.modelApiKey = modelApiKey;
 
-    const region = browserbaseSessionCreateParams?.region;
+    const sessionCreateParams = applyDefaultBrowserSettingsViewport(
+      browserbaseSessionCreateParams,
+    );
+    const region = sessionCreateParams?.region;
     if (region && region !== "us-west-2") {
       return { sessionId: browserbaseSessionID ?? null, available: false };
     }
@@ -84,7 +88,7 @@ export class StagehandAPI {
         selfHeal,
         waitForCaptchaSolves,
         actionTimeoutMs,
-        browserbaseSessionCreateParams,
+        browserbaseSessionCreateParams: sessionCreateParams,
         browserbaseSessionID,
       }),
     });

lib/browserbaseDefaults.ts

@@ -0,0 +1,32 @@
+import Browserbase from "@browserbasehq/sdk";
+
+export type BrowserbaseSessionCreateParams = Omit<
+  Browserbase.Sessions.SessionCreateParams,
+  "projectId"
+> & { projectId?: string };
+
+export const DEFAULT_BROWSERBASE_VIEWPORT = {
+  width: 1288,
+  height: 711,
+} as const;
+
+export function applyDefaultBrowserSettingsViewport(
+  params?: BrowserbaseSessionCreateParams,
+): BrowserbaseSessionCreateParams {
+  const paramsWithDefaults = {
+    ...(params ?? {}),
+  } as BrowserbaseSessionCreateParams;
+
+  const viewport = paramsWithDefaults.browserSettings?.viewport ?? {
+    width: DEFAULT_BROWSERBASE_VIEWPORT.width,
+    height: DEFAULT_BROWSERBASE_VIEWPORT.height,
+  };
+
+  return {
+    ...paramsWithDefaults,
+    browserSettings: {
+      ...(paramsWithDefaults.browserSettings ?? {}),
+      viewport,
+    },
+  };
+}

lib/index.ts

@@ -45,6 +45,7 @@ import { StagehandAgentHandler } from "./handlers/stagehandAgentHandler";
 import { StagehandLogger } from "./logger";
 import { connectToMCPServer } from "./mcp/connection";
 import { resolveTools } from "./mcp/utils";
+import { applyDefaultBrowserSettingsViewport } from "./browserbaseDefaults";
 import { isRunningInBun, loadApiKeyFromEnv } from "./utils";
 
 dotenv.config({ path: ".env" });
@@ -158,11 +159,14 @@ async function getBrowser(
         );
       }
 
+      const sessionCreateParams = applyDefaultBrowserSettingsViewport(
+        browserbaseSessionCreateParams,
+      );
       const session = await browserbase.sessions.create({
         projectId,
-        ...browserbaseSessionCreateParams,
+        ...sessionCreateParams,
         userMetadata: {
-          ...(browserbaseSessionCreateParams?.userMetadata || {}),
+          ...(sessionCreateParams?.userMetadata || {}),
           stagehand: "true",
         },
       });