clean up page methods (#1407)

# why

Currently we use multiple overloads for click, scroll, and draganddrop 

# what changed

simplified code to always return a value, that is either an xpath, or
empty string

# test plan

updated tests, and ran them 







<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Simplified page interaction methods by removing overloads and making
returns predictable. click(), hover(), and scroll() now always return a
string, and dragAndDrop() returns [fromXpath, toXpath], using empty
strings when no XPath is available.

- **Refactors**
- Removed TypeScript overloads for Page.click, Page.hover, Page.scroll,
and Page.dragAndDrop.
  - click/hover/scroll now return an XPath string or "".
  - dragAndDrop returns [fromXpath, toXpath] or ["", ""].
  - Updated tests to assert empty strings instead of undefined.

- **Migration**
  - Replace any undefined checks with "" (and ["", ""] for dragAndDrop).

<sup>Written for commit 0d162af.
Summary will update automatically on new commits.</sup>

<!-- End of auto-generated description by cubic. -->

Author: tkattkat

.changeset/shy-bears-dress.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Clean up page methods

packages/core/lib/v3/tests/page-drag-and-drop.spec.ts

@@ -312,7 +312,7 @@ test.describe("Page.dragAndDrop() - dragging elements", () => {
     expect(toXpath.length).toBeGreaterThan(0);
   });
 
-  test("drag and drop without returnXpath returns void", async () => {
+  test("drag and drop without returnXpath returns empty strings", async () => {
     const page = v3.context.pages()[0];
 
     await page.goto(
@@ -358,9 +358,11 @@ test.describe("Page.dragAndDrop() - dragging elements", () => {
     const toX = item2Location.x + item2Location.width / 2;
     const toY = item2Location.y + item2Location.height / 2;
 
-    const result = await page.dragAndDrop(fromX, fromY, toX, toY);
+    const [fromXpath, toXpath] = await page.dragAndDrop(fromX, fromY, toX, toY);
 
-    expect(result).toBeUndefined();
+    // Should return empty strings when returnXpath is not set
+    expect(fromXpath).toBe("");
+    expect(toXpath).toBe("");
   });
 
   test("drag and drop with different mouse buttons", async () => {

packages/core/lib/v3/tests/page-hover.spec.ts

@@ -107,7 +107,7 @@ test.describe("Page.hover() - mouse hover at coordinates", () => {
     expect(xpath.toLowerCase()).toMatch(/div|target/);
   });
 
-  test("hover without returnXpath returns void", async () => {
+  test("hover without returnXpath returns empty string", async () => {
     const page = v3.context.pages()[0];
 
     await page.goto(
@@ -122,8 +122,8 @@ test.describe("Page.hover() - mouse hover at coordinates", () => {
     // Hover without returnXpath
     const result = await page.hover(50, 50);
 
-    // Should return undefined (void)
-    expect(result).toBeUndefined();
+    // Should return empty string
+    expect(result).toBe("");
   });
 
   test("hover triggers CSS :hover styles", async () => {

packages/core/lib/v3/tests/page-scroll.spec.ts

@@ -216,7 +216,7 @@ test.describe("Page.scroll() - mouse wheel scrolling", () => {
     expect(xpath.toLowerCase()).toMatch(/div|target/);
   });
 
-  test("scroll without returnXpath returns void", async () => {
+  test("scroll without returnXpath returns empty string", async () => {
     const page = v3.context.pages()[0];
 
     await page.goto(
@@ -231,8 +231,8 @@ test.describe("Page.scroll() - mouse wheel scrolling", () => {
     // Scroll without returnXpath
     const result = await page.scroll(640, 400, 0, 200);
 
-    // Should return undefined (void)
-    expect(result).toBeUndefined();
+    // Should return empty string
+    expect(result).toBe("");
   });
 
   test("multiple sequential scrolls accumulate", async () => {

packages/core/lib/v3/understudy/page.ts

@@ -1275,33 +1275,6 @@ export class Page {
    * on the top-level page target's session. Coordinates are relative to the
    * viewport origin (top-left). Does not scroll.
    */
-  async click(
-    x: number,
-    y: number,
-    options: {
-      button?: "left" | "right" | "middle";
-      clickCount?: number;
-      returnXpath: true;
-    },
-  ): Promise<string>;
-  async click(
-    x: number,
-    y: number,
-    options?: {
-      button?: "left" | "right" | "middle";
-      clickCount?: number;
-      returnXpath?: false;
-    },
-  ): Promise<void>;
-  async click(
-    x: number,
-    y: number,
-    options: {
-      button?: "left" | "right" | "middle";
-      clickCount?: number;
-      returnXpath: boolean;
-    },
-  ): Promise<void | string>;
   @logAction("Page.click")
   async click(
     x: number,
@@ -1311,7 +1284,7 @@ export class Page {
       clickCount?: number;
       returnXpath?: boolean;
     },
-  ): Promise<void | string> {
+  ): Promise<string> {
     const button = options?.button ?? "left";
     const clickCount = options?.clickCount ?? 1;
 
@@ -1377,30 +1350,21 @@ export class Page {
         clickCount: i,
       } as Protocol.Input.DispatchMouseEventRequest);
     }
-    if (options?.returnXpath) return xpathResult ?? "";
+
+    return xpathResult ?? "";
   }
 
   /**
    * Hover at absolute page coordinates (CSS pixels).
    * Dispatches mouseMoved via CDP Input domain on the top-level page target's
    * session.
    */
-  async hover(
-    x: number,
-    y: number,
-    options: { returnXpath: true },
-  ): Promise<string>;
-  async hover(
-    x: number,
-    y: number,
-    options?: { returnXpath?: false },
-  ): Promise<void>;
   @logAction("Page.hover")
   async hover(
     x: number,
     y: number,
     options?: { returnXpath?: boolean },
-  ): Promise<void | string> {
+  ): Promise<string> {
     let xpathResult: string | undefined;
     if (options?.returnXpath) {
       try {
@@ -1443,38 +1407,17 @@ export class Page {
       button: "none",
     } as Protocol.Input.DispatchMouseEventRequest);
 
-    if (options?.returnXpath) return xpathResult ?? "";
+    return xpathResult ?? "";
   }
 
-  async scroll(
-    x: number,
-    y: number,
-    deltaX: number,
-    deltaY: number,
-    options: { returnXpath: true },
-  ): Promise<string>;
-  async scroll(
-    x: number,
-    y: number,
-    deltaX: number,
-    deltaY: number,
-    options?: { returnXpath?: false },
-  ): Promise<void>;
-  async scroll(
-    x: number,
-    y: number,
-    deltaX: number,
-    deltaY: number,
-    options: { returnXpath: boolean },
-  ): Promise<void | string>;
   @logAction("Page.scroll")
   async scroll(
     x: number,
     y: number,
     deltaX: number,
     deltaY: number,
     options?: { returnXpath?: boolean },
-  ): Promise<void | string> {
+  ): Promise<string> {
     let xpathResult: string | undefined;
     if (options?.returnXpath) {
       try {
@@ -1503,49 +1446,13 @@ export class Page {
       deltaY,
     } as Protocol.Input.DispatchMouseEventRequest);
 
-    if (options?.returnXpath) return xpathResult ?? "";
+    return xpathResult ?? "";
   }
 
   /**
    * Drag from (fromX, fromY) to (toX, toY) using mouse events.
    * Sends mouseMoved → mousePressed → mouseMoved (steps) → mouseReleased.
    */
-  async dragAndDrop(
-    fromX: number,
-    fromY: number,
-    toX: number,
-    toY: number,
-    options: {
-      button?: "left" | "right" | "middle";
-      steps?: number;
-      delay?: number;
-      returnXpath: true;
-    },
-  ): Promise<[string, string]>;
-  async dragAndDrop(
-    fromX: number,
-    fromY: number,
-    toX: number,
-    toY: number,
-    options?: {
-      button?: "left" | "right" | "middle";
-      steps?: number;
-      delay?: number;
-      returnXpath?: false;
-    },
-  ): Promise<void>;
-  async dragAndDrop(
-    fromX: number,
-    fromY: number,
-    toX: number,
-    toY: number,
-    options: {
-      button?: "left" | "right" | "middle";
-      steps?: number;
-      delay?: number;
-      returnXpath: boolean;
-    },
-  ): Promise<void | [string, string]>;
   @logAction("Page.dragAndDrop")
   async dragAndDrop(
     fromX: number,
@@ -1558,7 +1465,7 @@ export class Page {
       delay?: number;
       returnXpath?: boolean;
     },
-  ): Promise<void | [string, string]> {
+  ): Promise<[string, string]> {
     const button = options?.button ?? "left";
     const steps = Math.max(1, Math.floor(options?.steps ?? 1));
     const delay = Math.max(0, options?.delay ?? 0);
@@ -1642,7 +1549,7 @@ export class Page {
       clickCount: 1,
     } as Protocol.Input.DispatchMouseEventRequest);
 
-    if (options?.returnXpath) return [fromXpath ?? "", toXpath ?? ""];
+    return [fromXpath ?? "", toXpath ?? ""];
   }
 
   /**