[v4]: update stubs to return selector obj (browserbase#1865)

Author: seanmcguire12

packages/server-v4/src/routes/v4/page/click.ts

@@ -6,7 +6,7 @@ import {
   PageClickActionSchema,
   PageClickRequestSchema,
   PageClickResponseSchema,
-  PageXPathResultSchema,
+  PageClickResultSchema,
 } from "../../../schemas/v4/page.js";
 import { createPageActionHandler, pageErrorResponses } from "./shared.js";
 
@@ -26,11 +26,8 @@ const clickRoute: RouteOptions = {
   handler: createPageActionHandler({
     method: "click",
     actionSchema: PageClickActionSchema,
-    execute: async ({ params }) => {
-      const sel = params.selector;
-      return PageXPathResultSchema.parse({
-        xpath: "xpath" in sel ? sel.xpath : "xpath=//stub-click",
-      });
+    execute: async () => {
+      return PageClickResultSchema.parse({ selector: {} });
     },
   }),
 };

packages/server-v4/src/routes/v4/page/dragAndDrop.ts

@@ -26,11 +26,10 @@ const dragAndDropRoute: RouteOptions = {
   handler: createPageActionHandler({
     method: "dragAndDrop",
     actionSchema: PageDragAndDropActionSchema,
-    execute: async ({ params }) => {
+    execute: async () => {
       return PageDragAndDropResultSchema.parse({
-        fromXpath:
-          "xpath" in params.from ? params.from.xpath : "xpath=//stub-from",
-        toXpath: "xpath" in params.to ? params.to.xpath : "xpath=//stub-to",
+        startSelector: {},
+        endSelector: {},
       });
     },
   }),

packages/server-v4/src/routes/v4/page/hover.ts

@@ -6,7 +6,7 @@ import {
   PageHoverActionSchema,
   PageHoverRequestSchema,
   PageHoverResponseSchema,
-  PageXPathResultSchema,
+  PageHoverResultSchema,
 } from "../../../schemas/v4/page.js";
 import { createPageActionHandler, pageErrorResponses } from "./shared.js";
 
@@ -26,11 +26,8 @@ const hoverRoute: RouteOptions = {
   handler: createPageActionHandler({
     method: "hover",
     actionSchema: PageHoverActionSchema,
-    execute: async ({ params }) => {
-      const sel = params.selector;
-      return PageXPathResultSchema.parse({
-        xpath: "xpath" in sel ? sel.xpath : "xpath=//stub-hover",
-      });
+    execute: async () => {
+      return PageHoverResultSchema.parse({ selector: {} });
     },
   }),
 };

packages/server-v4/src/routes/v4/page/scroll.ts

@@ -6,7 +6,7 @@ import {
   PageScrollActionSchema,
   PageScrollRequestSchema,
   PageScrollResponseSchema,
-  PageXPathResultSchema,
+  PageScrollResultSchema,
 } from "../../../schemas/v4/page.js";
 import { createPageActionHandler, pageErrorResponses } from "./shared.js";
 
@@ -28,9 +28,9 @@ const scrollRoute: RouteOptions = {
     actionSchema: PageScrollActionSchema,
     execute: async ({ params }) => {
       const sel = params.selector;
-      return PageXPathResultSchema.parse({
-        xpath: "xpath" in sel ? sel.xpath : "xpath=//stub-scroll",
-      });
+      const x = "x" in sel ? sel.x : 0;
+      const y = "y" in sel ? sel.y : 0;
+      return PageScrollResultSchema.parse({ x, y });
     },
   }),
 };

packages/server-v4/src/routes/v4/page/shared.ts

@@ -37,14 +37,6 @@ type PageActionHandlerContext<TAction extends PageAction> = {
   sessionId: string;
 };
 
-// Selector is a discriminated union of xpath, css, text, or coordinate types.
-// Only xpath is fully resolved today; other types fall back to a stub xpath.
-function normalizeXPath(xpath: string): string {
-  return xpath.startsWith("xpath=") || xpath.startsWith("/")
-    ? xpath
-    : `xpath=${xpath}`;
-}
-
 export function getPageId(params: unknown): string | undefined {
   if (
     typeof params === "object" &&
@@ -190,5 +182,3 @@ export const pageActionListHandler: RouteHandlerMethod = async (
     ] as PageAction[],
   });
 };
-
-export { normalizeXPath };

packages/server-v4/src/schemas/v4/page.ts

@@ -270,12 +270,14 @@ export const PageClickParamsSchema = PageWithPageIdSchema.extend({
   selector: SelectorSchema,
   button: MouseButtonSchema.optional(),
   clickCount: z.number().int().min(1).optional(),
+  returnSelector: z.boolean().optional(),
 })
   .strict()
   .meta({ id: "PageClickParams" });
 
 export const PageHoverParamsSchema = PageWithPageIdSchema.extend({
   selector: SelectorSchema,
+  returnSelector: z.boolean().optional(),
 })
   .strict()
   .meta({ id: "PageHoverParams" });
@@ -305,6 +307,7 @@ export const PageDragAndDropParamsSchema = PageWithPageIdSchema.extend({
   button: MouseButtonSchema.optional(),
   steps: z.number().int().positive().optional(),
   delay: z.number().int().min(0).optional(),
+  returnSelector: z.boolean().optional(),
 })
   .strict()
   .meta({ id: "PageDragAndDropParams" });
@@ -622,17 +625,47 @@ export const PageCloseRequestSchema = createPageRequestSchema(
   PageCloseParamsSchema,
 );
 
-export const PageXPathResultSchema = z
+export const PageScrollResultSchema = z
+  .object({
+    x: z.number(),
+    y: z.number(),
+  })
+  .strict()
+  .meta({ id: "PageScrollResult" });
+
+export const ResultSelectorSchema = z
   .object({
     xpath: z.string().optional(),
+    css: z.string().optional(),
+    text: z.string().optional(),
+    coordinates: z
+      .object({
+        x: z.number(),
+        y: z.number(),
+      })
+      .optional(),
+  })
+  .strict()
+  .meta({ id: "ResultSelector" });
+
+export const PageClickResultSchema = z
+  .object({
+    selector: ResultSelectorSchema,
+  })
+  .strict()
+  .meta({ id: "PageClickResult" });
+
+export const PageHoverResultSchema = z
+  .object({
+    selector: ResultSelectorSchema,
   })
   .strict()
-  .meta({ id: "PageXPathResult" });
+  .meta({ id: "PageHoverResult" });
 
 export const PageDragAndDropResultSchema = z
   .object({
-    fromXpath: z.string().optional(),
-    toXpath: z.string().optional(),
+    startSelector: ResultSelectorSchema,
+    endSelector: ResultSelectorSchema,
   })
   .strict()
   .meta({ id: "PageDragAndDropResult" });
@@ -821,21 +854,21 @@ export const PageClickActionSchema = createPageActionSchema(
   "PageClickAction",
   "click",
   PageClickParamsSchema,
-  PageXPathResultSchema,
+  PageClickResultSchema,
 );
 
 export const PageHoverActionSchema = createPageActionSchema(
   "PageHoverAction",
   "hover",
   PageHoverParamsSchema,
-  PageXPathResultSchema,
+  PageHoverResultSchema,
 );
 
 export const PageScrollActionSchema = createPageActionSchema(
   "PageScrollAction",
   "scroll",
   PageScrollParamsSchema,
-  PageXPathResultSchema,
+  PageScrollResultSchema,
 );
 
 export const PageDragAndDropActionSchema = createPageActionSchema(
@@ -1280,6 +1313,7 @@ export const pageOpenApiComponents = {
     CoordinateSelector: CoordinateSelectorSchema,
     Selector: SelectorSchema,
     ElementSelector: ElementSelectorSchema,
+    ResultSelector: ResultSelectorSchema,
     PageHeaders: PageHeadersSchema,
     PageInitScript: PageInitScriptSchema,
     PageClip: PageClipSchema,