@tontoko/fast-playwright-mcp 0.1.0 → 0.1.2

package/lib/tools/dialogs.js

@@ -26,11 +26,11 @@ var handleDialog = defineTabTool({
   schema: {
     name: "browser_handle_dialog",
     title: "Handle a dialog",
-    description: `Handle a dialog(alert,confirm,prompt).accept:true to accept,false to dismiss.promptText:"answer" for prompt dialogs.expectation:{includeSnapshot:true} to see page after dialog handling.USE batch_execute if dialog appears during workflow.`,
+    description: "Handle a dialog (alert, confirm, prompt)",
     inputSchema: z.object({
-      accept: z.boolean().describe("Whether to accept the dialog."),
-      promptText: z.string().optional().describe("The text of the prompt in case of a prompt dialog."),
-      expectation: expectationSchema
+      accept: z.boolean().describe("Accept (true) or dismiss (false)"),
+      promptText: z.string().optional().describe("Text for prompt dialogs"),
+      expectation: expectationSchema.describe("Page state after dialog. Use batch_execute for workflows")
     }),
     type: "destructive"
   },

package/lib/tools/evaluate.js

@@ -20,31 +20,35 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 // src/tools/evaluate.ts
 import { z } from "zod";
 import { expectationSchema } from "../schemas/expectation.js";
+import { elementSelectorSchema } from "../types/selectors.js";
 import { quote } from "../utils/codegen.js";
 import { defineTabTool } from "./tool.js";
 import { generateLocator } from "./utils.js";
+var selectorsSchema = z.array(elementSelectorSchema).min(1).max(5).describe("Array of element selectors (max 5) supporting ref, role, CSS, or text-based selection");
 var evaluateSchema = z.object({
-  function: z.string().describe("() => { /* code */ } or (element) => { /* code */ } when element is provided"),
-  element: z.string().optional().describe("Human-readable element description used to obtain permission to interact with the element"),
-  ref: z.string().optional().describe('System-generated element ID from previous tool results (e.g., "rNODE-45-1"). Never use custom values.'),
-  expectation: expectationSchema
+  function: z.string().describe("JS function: () => {...} or (element) => {...}"),
+  selectors: selectorsSchema.optional().describe("Optional element selectors. If provided, function receives element as parameter"),
+  expectation: expectationSchema.describe("Page state config. false for data extraction, true for DOM changes")
 });
 var evaluate = defineTabTool({
   capability: "core",
   schema: {
     name: "browser_evaluate",
     title: "Evaluate JavaScript",
-    description: "Evaluate JavaScript expression on page or element.Returns evaluation result.USE CASES:extract data,modify DOM,trigger events.expectation:{includeSnapshot:false} for data extraction,true if modifying page.element+ref to run on specific element.CONSIDER batch_execute for multiple evaluations.",
+    description: "Evaluate JavaScript expression on page or element and return result",
     inputSchema: evaluateSchema,
     type: "destructive"
   },
   handle: async (tab, params, response) => {
     let locator;
-    if (params.ref && params.element) {
-      locator = await tab.refLocator({
-        ref: params.ref,
-        element: params.element
-      });
+    if (params.selectors && params.selectors.length > 0) {
+      const resolutionResults = await tab.resolveElementLocators(params.selectors);
+      const successfulResults = resolutionResults.filter((r) => r.locator && !r.error);
+      if (successfulResults.length === 0) {
+        const errors = resolutionResults.map((r) => r.error || "Unknown error").join(", ");
+        throw new Error(`Failed to resolve element selectors: ${errors}`);
+      }
+      locator = successfulResults[0].locator;
       response.addCode(`await page.${await generateLocator(locator)}.evaluate(${quote(params.function)});`);
     } else {
       response.addCode(`await page.evaluate(${quote(params.function)});`);

package/lib/tools/files.js

@@ -26,10 +26,10 @@ var uploadFile = defineTabTool({
   schema: {
     name: "browser_file_upload",
     title: "Upload files",
-    description: `Upload one or multiple files to file input.paths:["/path/file1.jpg","/path/file2.pdf"] for multiple files.expectation:{includeSnapshot:true,snapshotOptions:{selector:"form"}} to verify upload.Must be triggered after file input interaction.USE batch_execute for click→upload workflows.`,
+    description: "Upload one or multiple files to file input",
     inputSchema: z.object({
-      paths: z.array(z.string()).describe("The absolute paths to the files to upload. Can be a single file or multiple files."),
-      expectation: expectationSchema
+      paths: z.array(z.string()).describe("Absolute paths to upload (array)"),
+      expectation: expectationSchema.describe("Page state config. Use batch_execute for click→upload")
     }),
     type: "destructive"
   },

package/lib/tools/inspect-html.js

@@ -0,0 +1,238 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/tools/inspect-html.ts
+import { z } from "zod";
+import { expectationSchema } from "../schemas/expectation.js";
+import { htmlInspectionOptionsSchema } from "../types/html-inspection.js";
+import { HTMLInspector } from "../utilities/html-inspector.js";
+import { defineTabTool } from "./tool.js";
+var browserInspectHtmlSchema = htmlInspectionOptionsSchema.extend({
+  includeSuggestions: z.boolean().optional().default(false).describe("Include CSS selector suggestions in output"),
+  includeChildren: z.boolean().optional().default(true).describe("Include child elements in extraction"),
+  optimizeForLLM: z.boolean().optional().default(false).describe("Optimize extracted HTML for LLM consumption"),
+  expectation: expectationSchema.optional().describe("Page state config (minimal for HTML inspection)")
+});
+function formatConfiguration(params) {
+  let text = `**Configuration:**
+`;
+  text += `- selectors: ${params.selectors.length} selector(s)
+`;
+  text += `- depth: ${params.depth || 2}
+`;
+  text += `- format: ${params.format || "html"}
+`;
+  text += `- maxSize: ${params.maxSize || 50000} bytes
+`;
+  text += `- includeAttributes: ${params.includeAttributes !== false}
+`;
+  text += `- optimizeForLLM: ${params.optimizeForLLM}
+
+`;
+  return text;
+}
+function formatTiming(timing) {
+  let text = `**Timing:**
+`;
+  text += `- total: ${timing.totalMs}ms
+`;
+  text += `- selector resolution: ${timing.selectorResolutionMs}ms
+`;
+  text += `- extraction: ${timing.extractionMs}ms
+
+`;
+  return text;
+}
+function formatStatistics(stats, totalSizeBytes, truncated) {
+  let text = `**Statistics:**
+`;
+  text += `- elements found: ${stats.elementsFound}
+`;
+  text += `- selectors not found: ${stats.selectorsNotFound}
+`;
+  text += `- average depth: ${stats.averageDepth.toFixed(1)}
+`;
+  text += `- Total size: ${totalSizeBytes} bytes
+`;
+  text += `- truncated: ${truncated}
+
+`;
+  return text;
+}
+function formatElementInfo(index, element, includeChildren = false) {
+  let selectorInfo = "unknown";
+  if ("ref" in element.matchedSelector && element.matchedSelector.ref) {
+    selectorInfo = `ref=${element.matchedSelector.ref}`;
+  } else if ("css" in element.matchedSelector && element.matchedSelector.css) {
+    selectorInfo = element.matchedSelector.css;
+  } else if ("role" in element.matchedSelector && element.matchedSelector.role) {
+    selectorInfo = element.matchedSelector.role;
+  } else if ("text" in element.matchedSelector && element.matchedSelector.text) {
+    selectorInfo = element.matchedSelector.text;
+  }
+  let text = `### Element ${index} (${selectorInfo})
+`;
+  text += `**Tag:** ${element.metadata.tagName}
+`;
+  text += `**Size:** ${element.metadata.sizeBytes} bytes
+`;
+  if (element.error) {
+    text += `**Error:** ${element.error}
+
+`;
+    return text;
+  }
+  if (element.metadata.attributes && Object.keys(element.metadata.attributes).length > 0) {
+    text += `**Attributes:** ${JSON.stringify(element.metadata.attributes)}
+`;
+  }
+  text += "\n```html\n";
+  text += element.html;
+  text += "\n```\n\n";
+  if (includeChildren && element.children && element.children.length > 0) {
+    text += formatChildren(element.children);
+  }
+  return text;
+}
+function formatChildren(children) {
+  let text = `**Children (${children.length}):**
+`;
+  for (const child of children) {
+    text += `- <${child.metadata.tagName}`;
+    if (child.metadata.attributes?.id) {
+      text += ` id="${child.metadata.attributes.id}"`;
+    }
+    if (child.metadata.attributes?.class) {
+      text += ` class="${child.metadata.attributes.class}"`;
+    }
+    text += `> (${child.metadata.sizeBytes} bytes)
+`;
+  }
+  text += `
+`;
+  return text;
+}
+function formatFullResponse(params, result, suggestions) {
+  let text = `## HTML Inspection Results
+
+`;
+  text += formatConfiguration(params);
+  text += formatTiming(result.timing);
+  text += formatStatistics(result.stats, result.totalSizeBytes, result.truncated);
+  if (result.stats.elementsFound > 0) {
+    text += `**Extracted HTML Content:**
+
+`;
+    for (const [index, element] of Object.entries(result.elements)) {
+      text += formatElementInfo(index, element, params.includeChildren);
+    }
+  } else {
+    text += `**No elements found matching the provided selectors.**
+
+`;
+  }
+  if (params.includeSuggestions && suggestions.length > 0) {
+    text += `**CSS Selector Suggestions:**
+`;
+    const limitedSuggestions = suggestions.slice(0, 10);
+    for (const suggestion of limitedSuggestions) {
+      text += `- ${suggestion}
+`;
+    }
+    text += `
+`;
+  }
+  if (result.suggestions && result.suggestions.length > 0) {
+    text += `**Suggestions:**
+`;
+    for (const suggestion of result.suggestions) {
+      text += `- ${suggestion}
+`;
+    }
+    text += `
+`;
+  }
+  return text;
+}
+async function performInspection(inspector, params) {
+  const inspectionOptions = {
+    selectors: params.selectors,
+    depth: params.depth,
+    includeStyles: params.includeStyles,
+    maxSize: params.maxSize,
+    format: params.format,
+    includeAttributes: params.includeAttributes,
+    preserveWhitespace: params.preserveWhitespace,
+    excludeSelector: params.excludeSelector
+  };
+  const inspectionResult = await inspector.extractHTML(inspectionOptions);
+  const finalResult = params.optimizeForLLM ? await inspector.optimizeForLLM(inspectionResult) : inspectionResult;
+  let suggestions = [];
+  if (params.includeSuggestions) {
+    const cssSuggestions = inspector.suggestCSSSelectors(finalResult);
+    suggestions = cssSuggestions.map((s) => `${s.selector} (confidence: ${s.confidence}) - ${s.description}`);
+  }
+  return { result: finalResult, suggestions };
+}
+var browserInspectHtml = defineTabTool({
+  capability: "core",
+  schema: {
+    name: "browser_inspect_html",
+    title: "HTML inspection",
+    description: "Extract and analyze HTML content from web pages with intelligent filtering and size control. Optimized for LLM consumption with configurable depth, format options, and automatic truncation.",
+    inputSchema: browserInspectHtmlSchema,
+    type: "readOnly"
+  },
+  handle: async (tab, params, response) => {
+    try {
+      const inspector = new HTMLInspector(tab.page);
+      const { result: finalResult, suggestions } = await performInspection(inspector, params);
+      const responseText = formatFullResponse(params, finalResult, suggestions);
+      response.addResult(responseText);
+      response.addCode("// HTML inspection completed");
+      if (finalResult.stats.elementsFound > 0) {
+        response.addCode(`// Extracted ${finalResult.stats.elementsFound} element(s) in ${finalResult.timing.totalMs}ms`);
+      }
+      if (params.expectation?.includeSnapshot) {
+        const snapshot = await tab.captureSnapshot();
+        response.setTabSnapshot(snapshot);
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      response.addResult(`## HTML Inspection Error
+
+An error occurred during HTML inspection: ${errorMessage}
+
+**Troubleshooting:**
+- Verify that the page has loaded completely
+- Check that the provided selectors are valid CSS selectors or roles
+- Ensure the elements exist on the current page
+- Consider reducing the depth or size limits if the page is very large
+
+Use browser_snapshot to see the current page state.`);
+      response.addCode(`// HTML inspection failed: ${errorMessage}`);
+      throw error;
+    }
+  }
+});
+var inspect_html_default = [browserInspectHtml];
+export {
+  inspect_html_default as default,
+  browserInspectHtml
+};

package/lib/tools/keyboard.js

@@ -20,9 +20,13 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 // src/tools/keyboard.ts
 import { z } from "zod";
 import { expectationSchema } from "../schemas/expectation.js";
+import { elementSelectorSchema } from "../types/selectors.js";
 import { quote } from "../utils/codegen.js";
 import { generateKeyPressCode } from "../utils/common-formatters.js";
-import { baseElementSchema as elementSchema } from "./base-tool-handler.js";
+import {
+  handleSnapshotExpectation,
+  resolveFirstElement
+} from "./shared-element-utils.js";
 import { defineTabTool } from "./tool.js";
 import { generateLocator } from "./utils.js";
 var pressKey = defineTabTool({
@@ -30,10 +34,10 @@ var pressKey = defineTabTool({
   schema: {
     name: "browser_press_key",
     title: "Press a key",
-    description: "Press a key on the keyboard.Common keys:Enter,Escape,ArrowUp/Down/Left/Right,Tab,Backspace.expectation:{includeSnapshot:false} for navigation keys,true for content changes.CONSIDER batch_execute for multiple key presses.",
+    description: "Press a key on the keyboard",
     inputSchema: z.object({
-      key: z.string().describe("Name of the key to press or a character to generate, such as `ArrowLeft` or `a`"),
-      expectation: expectationSchema
+      key: z.string().describe("Key to press"),
+      expectation: expectationSchema.describe("Page state config. Use batch_execute for multiple keys")
     }),
     type: "destructive"
   },
@@ -43,31 +47,28 @@ var pressKey = defineTabTool({
     await tab.waitForCompletion(async () => {
       await tab.page.keyboard.press(params.key);
     });
-    if (params.expectation?.includeSnapshot) {
-      const newSnapshot = await tab.captureSnapshot();
-      response.setTabSnapshot(newSnapshot);
-    }
+    await handleSnapshotExpectation(tab, params.expectation, response);
   }
 });
-var typeSchema = elementSchema.extend({
-  element: z.string().describe("Human-readable element description used to obtain permission to interact with the element"),
-  ref: z.string().describe('System-generated element ID from previous tool results (e.g., "rNODE-45-1"). Never use custom values.'),
+var selectorsSchema = z.array(elementSelectorSchema).min(1).max(5).describe("Array of element selectors (max 5) supporting ref, role, CSS, or text-based selection");
+var typeSchema = z.object({
+  selectors: selectorsSchema,
   text: z.string().describe("Text to type into the element"),
-  submit: z.boolean().optional().describe("Whether to submit entered text (press Enter after)"),
-  slowly: z.boolean().optional().describe("Whether type one character at a time. Useful for triggering key handlers in the page. By default entire text is filled in at once."),
-  expectation: expectationSchema
+  submit: z.boolean().optional().describe("Press Enter after typing if true"),
+  slowly: z.boolean().optional().describe("Type slowly for auto-complete if true"),
+  expectation: expectationSchema.describe("Page state config. Use batch_execute for forms")
 });
 var type = defineTabTool({
   capability: "core",
   schema: {
     name: "browser_type",
     title: "Type text",
-    description: `Type text into editable element.FOR FORMS:Use batch_execute to fill multiple fields efficiently.slowly:true for auto-complete fields,submit:true to press Enter after.expectation:{includeSnapshot:false} when filling multiple fields(use batch),true for final verification.snapshotOptions:{selector:"form"} to focus on form only.diffOptions:{enabled:true} shows only what changed in form.`,
+    description: "Type text into editable element",
     inputSchema: typeSchema,
     type: "destructive"
   },
   handle: async (tab, params, response) => {
-    const locator = await tab.refLocator(params);
+    const { locator } = await resolveFirstElement(tab, params.selectors);
     await tab.waitForCompletion(async () => {
       if (params.slowly) {
         response.addCode(`await page.${await generateLocator(locator)}.pressSequentially(${quote(params.text)});`);
@@ -81,10 +82,7 @@ var type = defineTabTool({
         await locator.press("Enter");
       }
     });
-    if (params.expectation?.includeSnapshot) {
-      const newSnapshot = await tab.captureSnapshot();
-      response.setTabSnapshot(newSnapshot);
-    }
+    await handleSnapshotExpectation(tab, params.expectation, response);
   }
 });
 var keyboard_default = [pressKey, type];

package/lib/tools/mouse.js

@@ -54,11 +54,11 @@ var mouseClick = defineTabTool({
   schema: {
     name: "browser_mouse_click_xy",
     title: "Click",
-    description: "Click at specific coordinates.Requires --caps=vision.x,y:click position.expectation:{includeSnapshot:true} to verify result.PREFER browser_click with element ref over coordinates.USE batch_execute for coordinate-based workflows.",
+    description: "Click at specific coordinates",
     inputSchema: elementSchema.extend({
-      x: z.number().describe("X coordinate"),
-      y: z.number().describe("Y coordinate"),
-      expectation: expectationSchema
+      x: z.number().describe("X coordinate (requires --caps=vision)"),
+      y: z.number().describe("Y coordinate (requires --caps=vision)"),
+      expectation: expectationSchema.describe("Page state after click. Prefer element ref over coords")
     }),
     type: "destructive"
   },
@@ -81,13 +81,13 @@ var mouseDrag = defineTabTool({
   schema: {
     name: "browser_mouse_drag_xy",
     title: "Drag mouse",
-    description: `Drag from one coordinate to another.Requires --caps=vision.startX,startY→endX,endY.expectation:{includeSnapshot:true,snapshotOptions:{selector:".drop-zone"}} to verify.PREFER browser_drag with element refs over coordinates.`,
+    description: "Drag from one coordinate to another",
     inputSchema: elementSchema.extend({
-      startX: z.number().describe("Start X coordinate"),
-      startY: z.number().describe("Start Y coordinate"),
-      endX: z.number().describe("End X coordinate"),
-      endY: z.number().describe("End Y coordinate"),
-      expectation: expectationSchema
+      startX: z.number().describe("Start X (requires --caps=vision)"),
+      startY: z.number().describe("Start Y (requires --caps=vision)"),
+      endX: z.number().describe("End X"),
+      endY: z.number().describe("End Y"),
+      expectation: expectationSchema.describe("Page state after drag. Prefer element refs over coords")
     }),
     type: "destructive"
   },

package/lib/tools/navigate.js

@@ -31,10 +31,10 @@ var navigate = defineTool({
   schema: {
     name: "browser_navigate",
     title: "Navigate to a URL",
-    description: `Navigate to a URL.expectation:{includeSnapshot:true} to see what loaded,false if you know what to do next.snapshotOptions:{selector:"#content"} to focus on main content(saves 50% tokens).diffOptions:{enabled:true} when revisiting pages to see only changes.CONSIDER batch_execute for navigate→interact workflows.`,
+    description: "Navigate to a URL",
     inputSchema: z.object({
       url: z.string().describe("The URL to navigate to"),
-      expectation: expectationSchema
+      expectation: expectationSchema.describe("Page state after navigation")
     }),
     type: "destructive"
   },
@@ -48,10 +48,10 @@ var goBack = defineTabTool({
   capability: "core",
   schema: {
     name: "browser_navigate_back",
-    title: "Go back",
-    description: "Go back to previous page.expectation:{includeSnapshot:true} to see previous page,false if continuing workflow.diffOptions:{enabled:true} shows only what changed from forward page.USE batch_execute for back→interact sequences.",
+    title: "Go back to previous page",
+    description: "Go back to previous page",
     inputSchema: z.object({
-      expectation: expectationSchema
+      expectation: expectationSchema.describe("Page state after going back")
     }),
     type: "readOnly"
   },
@@ -64,10 +64,10 @@ var goForward = defineTabTool({
   capability: "core",
   schema: {
     name: "browser_navigate_forward",
-    title: "Go forward",
-    description: "Go forward to next page.expectation:{includeSnapshot:true} to see next page,false if continuing workflow.diffOptions:{enabled:true} shows only what changed from previous page.USE batch_execute for forward→interact sequences.",
+    title: "Go forward to next page",
+    description: "Go forward to next page",
     inputSchema: z.object({
-      expectation: expectationSchema
+      expectation: expectationSchema.describe("Page state after going forward")
     }),
     type: "readOnly"
   },

package/lib/tools/network.js

@@ -24,22 +24,22 @@ import {
 } from "../utils/network-filter.js";
 import { defineTabTool } from "./tool.js";
 var networkFilterSchema = z.object({
-  urlPatterns: z.array(z.string()).optional(),
-  excludeUrlPatterns: z.array(z.string()).optional(),
+  urlPatterns: z.array(z.string()).optional().describe("URL patterns to filter (supports regex)"),
+  excludeUrlPatterns: z.array(z.string()).optional().describe("URL patterns to exclude (takes precedence)"),
   statusRanges: z.array(z.object({
-    min: z.number(),
-    max: z.number()
-  })).optional(),
-  methods: z.array(z.string()).optional(),
-  maxRequests: z.number().default(20),
-  newestFirst: z.boolean().default(true)
+    min: z.number().describe("Minimum status code"),
+    max: z.number().describe("Maximum status code")
+  })).optional().describe("Status code ranges (e.g., [{min:200,max:299}])"),
+  methods: z.array(z.string()).optional().describe("HTTP methods to filter"),
+  maxRequests: z.number().default(20).describe("Max requests to return (default: 20)"),
+  newestFirst: z.boolean().default(true).describe("Order by timestamp (default: newest first)")
 });
 var requests = defineTabTool({
   capability: "core",
   schema: {
     name: "browser_network_requests",
     title: "List network requests",
-    description: 'Returns network requests since loading the page with optional filtering. urlPatterns:["api/users"] to filter by URL patterns. excludeUrlPatterns:["analytics"] to exclude specific patterns. statusRanges:[{min:200,max:299}] for success codes only. methods:["GET","POST"] to filter by HTTP method. maxRequests:10 to limit results. newestFirst:false for chronological order. Supports regex patterns for advanced filtering.',
+    description: "Returns network requests since loading the page with optional filtering",
     inputSchema: networkFilterSchema.partial(),
     type: "readOnly"
   },

package/lib/tools/screenshot.js

@@ -20,23 +20,19 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 // src/tools/screenshot.ts
 import { z } from "zod";
 import { expectationSchema } from "../schemas/expectation.js";
+import { elementSelectorSchema } from "../types/selectors.js";
 import { formatObject } from "../utils/codegen.js";
 import { defineTabTool } from "./tool.js";
 import { generateLocator } from "./utils.js";
+var selectorsSchema = z.array(elementSelectorSchema).min(1).max(5).describe("Array of element selectors (max 5) supporting ref, role, CSS, or text-based selection");
 var screenshotSchema = z.object({
   type: z.enum(["png", "jpeg"]).default("png").describe("Image format for the screenshot. Default is png."),
   filename: z.string().optional().describe("File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified."),
-  element: z.string().optional().describe("Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too."),
-  ref: z.string().optional().describe('System-generated element ID from previous tool results (e.g., "rNODE-45-1"). Never use custom values. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.'),
+  selectors: selectorsSchema.optional().describe("Optional element selectors for element screenshots. If not provided, viewport screenshot will be taken."),
   fullPage: z.boolean().optional().describe("When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Cannot be used with element screenshots."),
-  expectation: expectationSchema
+  expectation: expectationSchema.describe("Additional page state config")
 }).refine((data) => {
-  return !!data.element === !!data.ref;
-}, {
-  message: "Both element and ref must be provided or neither.",
-  path: ["ref", "element"]
-}).refine((data) => {
-  return !(data.fullPage && (data.element || data.ref));
+  return !(data.fullPage && data.selectors && data.selectors.length > 0);
 }, {
   message: "fullPage cannot be used with element screenshots.",
   path: ["fullPage"]
@@ -55,19 +51,25 @@ function createScreenshotOptions(fileType, fileName, fullPage) {
   };
 }
 function isElementScreenshotRequest(params) {
-  return !!(params.element && params.ref);
+  return !!(params.selectors && params.selectors.length > 0);
 }
 function getScreenshotTarget(params, isElementScreenshot) {
-  if (isElementScreenshot && params.element) {
-    return params.element;
+  if (isElementScreenshot) {
+    return "element";
   }
   return params.fullPage ? "full page" : "viewport";
 }
 async function getScreenshotLocator(tab, params, isElementScreenshot) {
-  if (!(isElementScreenshot && params.element && params.ref)) {
+  if (!(isElementScreenshot && params.selectors)) {
     return null;
   }
-  return await tab.refLocator({ element: params.element, ref: params.ref });
+  const resolutionResults = await tab.resolveElementLocators(params.selectors);
+  const successfulResults = resolutionResults.filter((r) => r.locator && !r.error);
+  if (successfulResults.length === 0) {
+    const errors = resolutionResults.map((r) => r.error || "Unknown error").join(", ");
+    throw new Error(`Failed to resolve element selectors for screenshot: ${errors}`);
+  }
+  return successfulResults[0].locator;
 }
 async function addScreenshotCode(response, locator, options) {
   if (locator) {
@@ -84,7 +86,7 @@ var screenshot = defineTabTool({
   schema: {
     name: "browser_take_screenshot",
     title: "Take a screenshot",
-    description: `Take a screenshot of current page.Returns image data.expectation:{includeSnapshot:false} to avoid redundant accessibility tree(screenshot≠snapshot).imageOptions:{quality:50,format:"jpeg"} for 70% size reduction.fullPage:true for entire page,element+ref for specific element.USE CASES:visual verification,documentation,error capture.`,
+    description: "Take a screenshot of current page and return image data",
     inputSchema: screenshotSchema,
     type: "readOnly"
   },

package/lib/tools/shared-element-utils.js

@@ -0,0 +1,60 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/tools/shared-element-utils.ts
+async function resolveFirstElement(tab, selectors, errorMessage = "Failed to resolve element selectors") {
+  const resolutionResults = await tab.resolveElementLocators(selectors);
+  const successfulResults = resolutionResults.filter((r) => r.locator && !r.error);
+  if (successfulResults.length === 0) {
+    const errors = resolutionResults.map((r) => r.error || "Unknown error").join(", ");
+    throw new Error(`${errorMessage}: ${errors}`);
+  }
+  return { locator: successfulResults[0].locator };
+}
+async function handleSnapshotExpectation(tab, expectation, response) {
+  if (expectation?.includeSnapshot) {
+    const newSnapshot = await tab.captureSnapshot();
+    response.setTabSnapshot(newSnapshot);
+  }
+}
+async function resolveDragElements(tab, startSelectors, endSelectors) {
+  const [startResults, endResults] = await Promise.all([
+    tab.resolveElementLocators(startSelectors),
+    tab.resolveElementLocators(endSelectors)
+  ]);
+  const startSuccessful = startResults.filter((r) => r.locator && !r.error);
+  const endSuccessful = endResults.filter((r) => r.locator && !r.error);
+  if (startSuccessful.length === 0) {
+    const errors = startResults.map((r) => r.error || "Unknown error").join(", ");
+    throw new Error(`Failed to resolve start element selectors: ${errors}`);
+  }
+  if (endSuccessful.length === 0) {
+    const errors = endResults.map((r) => r.error || "Unknown error").join(", ");
+    throw new Error(`Failed to resolve end element selectors: ${errors}`);
+  }
+  return {
+    startLocator: startSuccessful[0].locator,
+    endLocator: endSuccessful[0].locator
+  };
+}
+export {
+  resolveFirstElement,
+  resolveDragElements,
+  handleSnapshotExpectation
+};