support popups (#374)

* more descriptive errors

* ctx-level new page detection

* improve nav performance

* remove new tab log

* remove unused imports

* changeset

* page listener returns StagehandPage

* add popup example

* clean imports

* override on(popup)

* add guiding comment

* update err message

* update tests & add act page handler back

* fix non popup events

* enhance on() tests

* Update few-elephants-cough.md

* err msg renaming

Author: sameelarif

Diff for: .changeset/few-elephants-cough.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": minor
+---
+
+Pass in a Stagehand Page object into the `on("popup")` listener to allow for multi-page handling.

Diff for: .gitignore

@@ -16,4 +16,5 @@ evals/public
 evals/playground.ts
 tmp/
 eval-summary.json
-pnpm-lock.yaml
+pnpm-lock.yaml
+evals/deterministic/tests/BrowserContext/tmp-test.har

Diff for: evals/deterministic/tests/page/on.test.ts

@@ -0,0 +1,134 @@
+import { expect, test } from "@playwright/test";
+import { Stagehand } from "../../../../lib";
+import StagehandConfig from "../../stagehand.config";
+
+test.describe("StagehandPage - page.on()", () => {
+  test("should click on the crewAI blog tab", async () => {
+    const stagehand = new Stagehand(StagehandConfig);
+    await stagehand.init();
+
+    const page = stagehand.page;
+    await page.goto(
+      "https://docs.browserbase.com/integrations/crew-ai/introduction",
+    );
+
+    let clickPromise: Promise<void>;
+
+    page.on("popup", async (newPage) => {
+      clickPromise = newPage.click(
+        "body > div.page-wrapper > div.navbar-2.w-nav > div.padding-global.top-bot > div > div.navigation-left > nav > a:nth-child(7)",
+      );
+    });
+
+    await page.goto(
+      "https://docs.browserbase.com/integrations/crew-ai/introduction",
+    );
+
+    await page.click(
+      "#content-area > div.relative.mt-8.prose.prose-gray.dark\\:prose-invert > p:nth-child(2) > a",
+    );
+
+    await clickPromise;
+
+    await stagehand.close();
+  });
+
+  test("should close the new tab and navigate to it on the existing page", async () => {
+    const stagehand = new Stagehand(StagehandConfig);
+    await stagehand.init();
+
+    const page = stagehand.page;
+    await page.goto(
+      "https://docs.browserbase.com/integrations/crew-ai/introduction",
+    );
+
+    let navigatePromise: Promise<unknown>;
+
+    page.on("popup", async (newPage) => {
+      navigatePromise = Promise.allSettled([
+        newPage.close(),
+        page.goto(newPage.url(), { waitUntil: "domcontentloaded" }),
+      ]);
+    });
+
+    // Click on the crewAI blog tab
+    await page.click(
+      "#content-area > div.relative.mt-8.prose.prose-gray.dark\\:prose-invert > p:nth-child(2) > a",
+    );
+
+    await navigatePromise;
+
+    await page.click(
+      "body > div.page-wrapper > div.navbar-2.w-nav > div.padding-global.top-bot > div > div.navigation-left > nav > a:nth-child(3)",
+    );
+
+    await page.waitForLoadState("domcontentloaded");
+
+    const currentUrl = page.url();
+    expect(currentUrl).toBe("https://www.crewai.com/open-source");
+
+    await stagehand.close();
+  });
+
+  test("should handle console events", async () => {
+    const stagehand = new Stagehand(StagehandConfig);
+    await stagehand.init();
+
+    const page = stagehand.page;
+    await page.goto("https://example.com");
+
+    const messages: string[] = [];
+    page.on("console", (msg) => {
+      messages.push(msg.text());
+    });
+
+    await page.evaluate(() => console.log("Test console log"));
+
+    expect(messages).toContain("Test console log");
+
+    await stagehand.close();
+  });
+
+  test("should handle dialog events", async () => {
+    const stagehand = new Stagehand(StagehandConfig);
+    await stagehand.init();
+
+    const page = stagehand.page;
+    await page.goto("https://example.com");
+
+    page.on("dialog", async (dialog) => {
+      expect(dialog.message()).toBe("Test alert");
+      await dialog.dismiss();
+    });
+
+    await page.evaluate(() => alert("Test alert"));
+
+    await stagehand.close();
+  });
+
+  test("should handle request and response events", async () => {
+    const stagehand = new Stagehand(StagehandConfig);
+    await stagehand.init();
+
+    const page = stagehand.page;
+    await page.goto("https://example.com");
+
+    const requests: string[] = [];
+    const responses: string[] = [];
+
+    page.on("request", (request) => {
+      requests.push(request.url());
+    });
+
+    page.on("response", (response) => {
+      responses.push(response.url());
+    });
+
+    await page.goto("https://example.com");
+
+    expect(requests).toContain("https://example.com/");
+    expect(responses).toContain("https://example.com/");
+
+    await stagehand.close();
+  });
+});

Diff for: examples/popup.ts

@@ -0,0 +1,46 @@
+/**
+ * This file is meant to be used as a scratchpad for developing new evals.
+ * To create a Stagehand project with best practices and configuration, run:
+ *
+ * npx create-browser-app@latest my-browser-app
+ */
+
+import { ObserveResult, Stagehand } from "../lib";
+import StagehandConfig from "./stagehand.config";
+
+async function example() {
+  const stagehand = new Stagehand(StagehandConfig);
+  await stagehand.init();
+
+  const page = await stagehand.page;
+
+  let observePromise: Promise<ObserveResult[]>;
+
+  page.on("popup", async (newPage) => {
+    observePromise = newPage.observe({
+      instruction: "return all the next possible actions from the page",
+    });
+  });
+
+  await page.goto(
+    "https://docs.browserbase.com/integrations/crew-ai/introduction",
+  );
+
+  await page.click(
+    "#content-area > div.relative.mt-8.prose.prose-gray.dark\\:prose-invert > p:nth-child(2) > a",
+  );
+
+  await page.waitForTimeout(5000);
+
+  if (observePromise) {
+    const observeResult = await observePromise;
+
+    console.log("Observed", observeResult.length, "actions");
+  }
+
+  await stagehand.close();
+}
+
+(async () => {
+  await example();
+})();

Diff for: lib/StagehandPage.ts

@@ -34,13 +34,24 @@ export class StagehandPage {
   ) {
     this.intPage = Object.assign(page, {
       act: () => {
-        throw new Error("act() is not implemented on the base page object");
+        throw new Error(
+          "You seem to be calling `act` on a page in an uninitialized `Stagehand` object. Ensure you are running `await stagehand.init()` on the Stagehand object before referencing the `page` object.",
+        );
       },
       extract: () => {
-        throw new Error("extract() is not implemented on the base page object");
+        throw new Error(
+          "You seem to be calling `extract` on a page in an uninitialized `Stagehand` object. Ensure you are running `await stagehand.init()` on the Stagehand object before referencing the `page` object.",
+        );
       },
       observe: () => {
-        throw new Error("observe() is not implemented on the base page object");
+        throw new Error(
+          "You seem to be calling `observe` on a page in an uninitialized `Stagehand` object. Ensure you are running `await stagehand.init()` on the Stagehand object before referencing the `page` object.",
+        );
+      },
+      on: () => {
+        throw new Error(
+          "You seem to be referencing a page in an uninitialized `Stagehand` object. Ensure you are running `await stagehand.init()` on the Stagehand object before referencing the `page` object.",
+        );
       },
     });
     this.stagehand = stagehand;
@@ -105,9 +116,38 @@ export class StagehandPage {
           };
         }
 
+        if (prop === "on") {
+          return (event: string, listener: (param: unknown) => void) => {
+            if (event === "popup") {
+              return this.context.on("page", async (page) => {
+                const newContext = await StagehandContext.init(
+                  page.context(),
+                  stagehand,
+                );
+                const newStagehandPage = new StagehandPage(
+                  page,
+                  stagehand,
+                  newContext,
+                  this.llmClient,
+                );
+
+                await newStagehandPage.init();
+
+                listener(newStagehandPage.page);
+              });
+            }
+
+            return this.context.on(
+              event as keyof PlaywrightPage["on"],
+              listener,
+            );
+          };
+        }
+
         return target[prop as keyof PlaywrightPage];
       },
     });
+
     await this._waitForSettledDom();
     return this;
   }

Diff for: lib/handlers/actHandler.ts

@@ -8,10 +8,10 @@ import { ActionCache } from "../cache/ActionCache";
 import { act, fillInVariables, verifyActCompletion } from "../inference";
 import { LLMClient } from "../llm/LLMClient";
 import { LLMProvider } from "../llm/LLMProvider";
+import { StagehandContext } from "../StagehandContext";
+import { StagehandPage } from "../StagehandPage";
 import { generateId } from "../utils";
 import { ScreenshotService } from "../vision";
-import { StagehandPage } from "../StagehandPage";
-import { StagehandContext } from "../StagehandContext";
 
 export class StagehandActHandler {
   private readonly stagehandPage: StagehandPage;

Diff for: package.json

@@ -6,6 +6,7 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
+    "popup": "npm run build-dom-scripts && tsx examples/popup.ts",
     "2048": "npm run build-dom-scripts && tsx examples/2048.ts",
     "example": "npm run build-dom-scripts && tsx examples/example.ts",
     "debug-url": "npm run build-dom-scripts && tsx examples/debugUrl.ts",

Diff for: types/page.ts

@@ -1,6 +1,9 @@
-import type { Page as PlaywrightPage } from "@playwright/test";
-import type { BrowserContext as PlaywrightContext } from "@playwright/test";
-import type { Browser as PlaywrightBrowser } from "@playwright/test";
+import type {
+  Browser as PlaywrightBrowser,
+  BrowserContext as PlaywrightContext,
+  Page as PlaywrightPage,
+} from "@playwright/test";
+import type { z } from "zod";
 import type {
   ActOptions,
   ActResult,
@@ -9,13 +12,17 @@ import type {
   ObserveOptions,
   ObserveResult,
 } from "./stagehand";
-import type { z } from "zod";
-export interface Page extends PlaywrightPage {
+
+export interface Page extends Omit<PlaywrightPage, "on"> {
   act: (options: ActOptions) => Promise<ActResult>;
   extract: <T extends z.AnyZodObject>(
     options: ExtractOptions<T>,
   ) => Promise<ExtractResult<T>>;
   observe: (options?: ObserveOptions) => Promise<ObserveResult[]>;
+
+  on: {
+    (event: "popup", listener: (page: Page) => unknown): Page;
+  } & PlaywrightPage["on"];
 }
 
 // Empty type for now, but will be used in the future