@tontoko/fast-playwright-mcp 0.1.0 → 0.1.2

package/lib/tools/snapshot.js

@@ -20,7 +20,13 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 // src/tools/snapshot.ts
 import { z } from "zod";
 import { expectationSchema } from "../schemas/expectation.js";
+import { elementSelectorSchema } from "../types/selectors.js";
 import { formatObject } from "../utils/codegen.js";
+import {
+  handleSnapshotExpectation,
+  resolveDragElements,
+  resolveFirstElement
+} from "./shared-element-utils.js";
 import { defineTabTool, defineTool } from "./tool.js";
 import { generateLocator } from "./utils.js";
 var snapshot = defineTool({
@@ -28,9 +34,9 @@ var snapshot = defineTool({
   schema: {
     name: "browser_snapshot",
     title: "Page snapshot",
-    description: `Capture accessibility snapshot of current page.AVOID calling directly - use expectation:{includeSnapshot:true} on other tools instead.USE CASES:Initial page inspection,debugging when other tools didn't capture needed info.snapshotOptions:{selector:"#content"} to focus on specific area.`,
+    description: "Capture accessibility snapshot of current page",
     inputSchema: z.object({
-      expectation: expectationSchema
+      expectation: expectationSchema.describe("Page state config")
     }),
     type: "readOnly"
   },
@@ -45,26 +51,24 @@ var snapshot = defineTool({
     }
   }
 });
-var elementSchema = z.object({
-  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 clickSchema = elementSchema.extend({
-  doubleClick: z.boolean().optional().describe("Whether to perform a double click instead of a single click"),
-  button: z.enum(["left", "right", "middle"]).optional().describe("Button to click, defaults to left"),
-  expectation: expectationSchema
+var selectorsSchema = z.array(elementSelectorSchema).min(1).max(5).describe("Array of element selectors (max 5). Selectors are tried in order until one succeeds (fallback mechanism). " + "Multiple matches trigger an error with candidate list. " + "Supports: ref (highest priority), CSS (#id, .class, tag), role (button, textbox, etc.), text content. " + 'Example: [{css: "#submit"}, {role: "button", text: "Submit"}] - tries ID first, falls back to role+text');
+var clickSchema = z.object({
+  selectors: selectorsSchema,
+  doubleClick: z.boolean().optional().describe("Double-click if true"),
+  button: z.enum(["left", "right", "middle"]).optional().describe("Mouse button (default: left)"),
+  expectation: expectationSchema.describe("Page state capture config. Use batch_execute for multi-clicks")
 });
 var click = defineTabTool({
   capability: "core",
   schema: {
     name: "browser_click",
-    title: "Click",
-    description: `Perform click on web page.USE batch_execute for multi-click workflows.expectation:{includeSnapshot:false} when next action follows immediately,true to verify result.diffOptions:{enabled:true,format:"minimal"} shows only changes(saves 80% tokens).snapshotOptions:{selector:".result"} to focus on result area.doubleClick:true for double-click,button:"right" for context menu.`,
+    title: "Perform click on web page",
+    description: "Perform click on web page",
     inputSchema: clickSchema,
     type: "destructive"
   },
   handle: async (tab, params, response) => {
-    const locator = await tab.refLocator(params);
+    const { locator } = await resolveFirstElement(tab, params.selectors, "Failed to resolve any element selectors");
     const button = params.button;
     const buttonAttr = button ? `{ button: '${button}' }` : "";
     if (params.doubleClick) {
@@ -79,10 +83,7 @@ var click = defineTabTool({
         await locator.click({ button });
       }
     });
-    if (params.expectation?.includeSnapshot) {
-      const newSnapshot = await tab.captureSnapshot();
-      response.setTabSnapshot(newSnapshot);
-    }
+    await handleSnapshotExpectation(tab, params.expectation, response);
   }
 });
 var drag = defineTabTool({
@@ -90,21 +91,16 @@ var drag = defineTabTool({
   schema: {
     name: "browser_drag",
     title: "Drag mouse",
-    description: `Perform drag and drop between two elements.expectation:{includeSnapshot:true,snapshotOptions:{selector:".drop-zone"}} to verify drop result.diffOptions:{enabled:true} shows only what moved.CONSIDER batch_execute if part of larger workflow.`,
+    description: "Perform drag and drop between two elements",
     inputSchema: z.object({
-      startElement: z.string().describe("Human-readable source element description used to obtain the permission to interact with the element"),
-      startRef: z.string().describe('System-generated source element ID from previous tool results (e.g., "rNODE-45-1"). Never use custom values.'),
-      endElement: z.string().describe("Human-readable target element description used to obtain the permission to interact with the element"),
-      endRef: z.string().describe('System-generated target element ID from previous tool results (e.g., "rNODE-45-1"). Never use custom values.'),
-      expectation: expectationSchema
+      startSelectors: selectorsSchema.describe("Source element selectors for drag start"),
+      endSelectors: selectorsSchema.describe("Target element selectors for drag end"),
+      expectation: expectationSchema.describe("Page state after drag. Use batch_execute for workflows")
     }),
     type: "destructive"
   },
   handle: async (tab, params, response) => {
-    const [startLocator, endLocator] = await tab.refLocators([
-      { ref: params.startRef, element: params.startElement },
-      { ref: params.endRef, element: params.endElement }
-    ]);
+    const { startLocator, endLocator } = await resolveDragElements(tab, params.startSelectors, params.endSelectors);
     await tab.waitForCompletion(async () => {
       await startLocator.dragTo(endLocator);
     });
@@ -116,35 +112,37 @@ var hover = defineTabTool({
   schema: {
     name: "browser_hover",
     title: "Hover mouse",
-    description: `Hover over element on page.expectation:{includeSnapshot:true} to capture tooltips/dropdown menus,false for simple hover.snapshotOptions:{selector:".tooltip"} to focus on tooltip area.Often followed by click - use batch_execute for hover→click sequences.`,
-    inputSchema: elementSchema.extend({
-      expectation: expectationSchema
+    description: "Hover over element on page",
+    inputSchema: z.object({
+      selectors: selectorsSchema,
+      expectation: expectationSchema.describe("Page state after hover. Use batch_execute for hover→click")
     }),
     type: "readOnly"
   },
   handle: async (tab, params, response) => {
-    const locator = await tab.refLocator(params);
+    const { locator } = await resolveFirstElement(tab, params.selectors);
     response.addCode(`await page.${await generateLocator(locator)}.hover();`);
     await tab.waitForCompletion(async () => {
       await locator.hover();
     });
   }
 });
-var selectOptionSchema = elementSchema.extend({
-  values: z.array(z.string()).describe("Array of values to select in the dropdown. This can be a single value or multiple values."),
-  expectation: expectationSchema
+var selectOptionSchema = z.object({
+  selectors: selectorsSchema,
+  values: z.array(z.string()).describe("Values to select (array)"),
+  expectation: expectationSchema.describe("Page state after selection. Use batch_execute for forms")
 });
 var selectOption = defineTabTool({
   capability: "core",
   schema: {
     name: "browser_select_option",
     title: "Select option",
-    description: `Select option in dropdown.values:["option1","option2"] for multi-select.expectation:{includeSnapshot:false} when part of form filling(use batch),true to verify selection.snapshotOptions:{selector:"form"} for form context.USE batch_execute for form workflows with multiple selects.`,
+    description: "Select option in dropdown",
     inputSchema: selectOptionSchema,
     type: "destructive"
   },
   handle: async (tab, params, response) => {
-    const locator = await tab.refLocator(params);
+    const { locator } = await resolveFirstElement(tab, params.selectors);
     response.addCode(`await page.${await generateLocator(locator)}.selectOption(${formatObject(params.values)});`);
     await tab.waitForCompletion(async () => {
       await locator.selectOption(params.values);
@@ -153,6 +151,6 @@ var selectOption = defineTabTool({
 });
 var snapshot_default = [snapshot, click, drag, hover, selectOption];
 export {
-  elementSchema,
+  selectorsSchema,
   snapshot_default as default
 };

package/lib/tools/tabs.js

@@ -26,9 +26,9 @@ var listTabs = defineTool({
   schema: {
     name: "browser_tab_list",
     title: "List tabs",
-    description: "List browser tabs.Always returns tab list with titles and URLs.expectation:{includeSnapshot:false} for just tab info,true to also see current tab content.USE before tab_select to find right tab.",
+    description: "List browser tabs with titles and URLs",
     inputSchema: z.object({
-      expectation: expectationSchema
+      expectation: expectationSchema.describe("Page state config")
     }),
     type: "readOnly"
   },
@@ -42,10 +42,10 @@ var selectTab = defineTool({
   schema: {
     name: "browser_tab_select",
     title: "Select a tab",
-    description: `Select a tab by index.expectation:{includeSnapshot:true} to see selected tab content,false if you know what's there.USE batch_execute for tab_select→interact workflows.`,
+    description: "Select a tab by index",
     inputSchema: z.object({
       index: z.number().describe("The index of the tab to select"),
-      expectation: expectationSchema
+      expectation: expectationSchema.describe("Page state after tab switch")
     }),
     type: "readOnly"
   },
@@ -59,10 +59,10 @@ var newTab = defineTool({
   schema: {
     name: "browser_tab_new",
     title: "Open a new tab",
-    description: `Open a new tab.url:"https://example.com" to navigate immediately,omit for blank tab.expectation:{includeSnapshot:true} to see new tab,false if opening for later use.CONSIDER batch_execute for new_tab→navigate→interact.`,
+    description: "Open a new tab",
     inputSchema: z.object({
-      url: z.string().optional().describe("The URL to navigate to in the new tab. If not provided, the new tab will be blank."),
-      expectation: expectationSchema
+      url: z.string().optional().describe("URL for new tab (optional)"),
+      expectation: expectationSchema.describe("Page state of new tab")
     }),
     type: "readOnly"
   },
@@ -79,10 +79,10 @@ var closeTab = defineTool({
   schema: {
     name: "browser_tab_close",
     title: "Close a tab",
-    description: "Close a tab.index:N to close specific tab,omit to close current.expectation:{includeSnapshot:false} usually sufficient,true to verify remaining tabs.USE batch_execute for multi-tab cleanup.",
+    description: "Close a tab by index or close current tab",
     inputSchema: z.object({
-      index: z.number().optional().describe("The index of the tab to close. Closes current tab if not provided."),
-      expectation: expectationSchema
+      index: z.number().optional().describe("Tab index to close (omit for current)"),
+      expectation: expectationSchema.describe("Page state after close")
     }),
     type: "destructive"
   },

package/lib/tools/wait.js

@@ -26,12 +26,12 @@ var wait = defineTool({
   schema: {
     name: "browser_wait_for",
     title: "Wait for",
-    description: `Wait for text to appear/disappear or time to pass.PREFER text-based wait over time for reliability.For loading states:wait for text:"Loading..." textGone:true.For dynamic content:wait for specific text to appear.expectation:{includeSnapshot:true,snapshotOptions:{selector:"#status"},diffOptions:{enabled:true}} shows only what changed.AVOID:fixed time waits unless necessary.`,
+    description: "Wait for text to appear or disappear or a specified time to pass",
     inputSchema: z.object({
-      time: z.number().optional().describe("The time to wait in seconds"),
-      text: z.string().optional().describe("The text to wait for"),
-      textGone: z.string().optional().describe("The text to wait for to disappear"),
-      expectation: expectationSchema
+      time: z.number().optional().describe("Wait time in seconds"),
+      text: z.string().optional(),
+      textGone: z.string().optional(),
+      expectation: expectationSchema.describe("Page state after wait")
     }),
     type: "readOnly"
   },

package/lib/tools.js

@@ -26,6 +26,7 @@ import dialogs from "./tools/dialogs.js";
 import evaluate from "./tools/evaluate.js";
 import files from "./tools/files.js";
 import { browserFindElements } from "./tools/find-elements.js";
+import inspectHtml from "./tools/inspect-html.js";
 import install from "./tools/install.js";
 import keyboard from "./tools/keyboard.js";
 import mouse from "./tools/mouse.js";
@@ -43,6 +44,7 @@ var allTools = [
   ...evaluate,
   ...files,
   ...install,
+  ...inspectHtml,
   ...keyboard,
   ...navigate,
   ...network,

package/lib/types/batch.js

@@ -37,9 +37,9 @@ var batchStepSchema = z.object({
   expectation: expectationSchema.describe("Expected output configuration for this step")
 });
 var batchExecuteSchema = z.object({
-  steps: z.array(batchStepSchema).min(1).describe("Array of steps to execute in sequence"),
+  steps: z.array(batchStepSchema).min(1).describe('Array of steps to execute in sequence. Recommended for form filling (multiple type→click), multi-step navigation, any workflow with 2+ known steps. Saves 90% tokens vs individual calls. Example: [{tool:"browser_navigate",arguments:{url:"https://example.com"}},{tool:"browser_type",arguments:{selectors:[{css:"#user"}],text:"john"}},{tool:"browser_click",arguments:{selectors:[{css:"#btn"}]}}]'),
   stopOnFirstError: z.boolean().optional().default(false).describe("Stop entire batch on first error"),
-  globalExpectation: z.preprocess(parseJsonString, expectationSchema).optional().describe("Default expectation for all steps")
+  globalExpectation: z.preprocess(parseJsonString, expectationSchema).optional().describe('Default expectation for all steps. Recommended: {includeSnapshot:false,snapshotOptions:{selector:"#app"},diffOptions:{enabled:true}}. Per-step override with steps[].expectation')
 });
 export {
   batchStepSchema,

package/lib/types/html-inspection.js

@@ -0,0 +1,106 @@
+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/types/html-inspection.ts
+import { z } from "zod";
+import { elementSelectorSchema } from "./selectors.js";
+var htmlInspectionOptionsSchema = z.object({
+  selectors: z.array(elementSelectorSchema).min(1).describe("Array of element selectors to inspect"),
+  depth: z.number().min(1).max(10).optional().default(2).describe("Maximum hierarchy depth to extract"),
+  includeStyles: z.boolean().optional().default(false).describe("Include computed CSS styles"),
+  maxSize: z.number().min(1024).max(500000).optional().default(50000).describe("Maximum size in bytes (1KB-500KB)"),
+  format: z.enum(["html", "aria", "text"]).optional().default("html").describe("Output format"),
+  includeAttributes: z.boolean().optional().default(true).describe("Include element attributes"),
+  preserveWhitespace: z.boolean().optional().default(false).describe("Preserve whitespace in content"),
+  excludeSelector: z.string().optional().describe("CSS selector to exclude elements")
+});
+var HTMLInspectionError = {
+  SELECTOR_NOT_FOUND: "SELECTOR_NOT_FOUND",
+  SIZE_LIMIT_EXCEEDED: "SIZE_LIMIT_EXCEEDED",
+  EXTRACTION_TIMEOUT: "EXTRACTION_TIMEOUT",
+  INVALID_SELECTOR: "INVALID_SELECTOR",
+  DOM_ACCESS_ERROR: "DOM_ACCESS_ERROR"
+};
+function calculateHtmlSize(html) {
+  return new TextEncoder().encode(html).length;
+}
+function truncateHtml(html, maxSize) {
+  if (calculateHtmlSize(html) <= maxSize) {
+    return { html, truncated: false };
+  }
+  const truncated = html.substring(0, maxSize - 100);
+  const lastTag = truncated.lastIndexOf("<");
+  const safeHtml = lastTag > truncated.lastIndexOf(">") ? truncated.substring(0, lastTag) : truncated;
+  return { html: `${safeHtml}<!-- TRUNCATED -->`, truncated: true };
+}
+function validateHTMLInspectionOptions(options) {
+  return htmlInspectionOptionsSchema.parse(options);
+}
+function generateHTMLInspectionSuggestions(result) {
+  const suggestions = [];
+  if (result.truncated) {
+    suggestions.push("Content was truncated. Consider reducing depth or using more specific selectors.");
+  }
+  if (result.stats.selectorsNotFound > 0) {
+    suggestions.push("Some selectors did not match elements. Try using more specific or alternative selectors.");
+  }
+  if (result.timing.totalMs > 5000) {
+    suggestions.push("Inspection took longer than expected. Consider reducing scope or depth.");
+  }
+  if (result.stats.averageDepth > 5) {
+    suggestions.push("Deep element extraction detected. Consider limiting depth for better performance.");
+  }
+  return suggestions;
+}
+var HTMLInspectionUtils = {
+  calculateHtmlSize,
+  truncateHtml,
+  validateOptions: validateHTMLInspectionOptions,
+  generateSuggestions: generateHTMLInspectionSuggestions
+};
+var HTMLInspectionConstants = {
+  DEFAULT_MAX_SIZE: 50000,
+  DEFAULT_DEPTH: 2,
+  MAX_DEPTH: 10,
+  DEFAULT_TIMEOUT_MS: 1e4,
+  SIZE_THRESHOLDS: {
+    WARNING: 30000,
+    CRITICAL: 45000
+  },
+  COMMON_ARIA_PROPERTIES: [
+    "aria-label",
+    "aria-describedby",
+    "aria-hidden",
+    "aria-expanded",
+    "aria-selected",
+    "aria-checked",
+    "aria-disabled",
+    "aria-required"
+  ]
+};
+export {
+  validateHTMLInspectionOptions,
+  truncateHtml,
+  htmlInspectionOptionsSchema,
+  generateHTMLInspectionSuggestions,
+  calculateHtmlSize,
+  HTMLInspectionUtils,
+  HTMLInspectionError,
+  HTMLInspectionConstants
+};

package/lib/types/selectors.js

@@ -0,0 +1,126 @@
+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/types/selectors.ts
+import { z } from "zod";
+var refSelectorSchema = z.object({
+  ref: z.string().describe("System-generated element ID from previous tool results")
+});
+var roleSelectorSchema = z.object({
+  role: z.string().describe("ARIA role to match (e.g., button, textbox, link)"),
+  text: z.string().optional().describe("Optional text content to match within the role")
+});
+var cssSelectorSchema = z.object({
+  css: z.string().describe('CSS selector string (e.g., "#id", ".class", "button[type=submit]")')
+});
+var textSelectorSchema = z.object({
+  text: z.string().describe("Text content to search for"),
+  tag: z.string().optional().describe("Optional HTML tag to limit search scope")
+});
+var elementSelectorSchema = z.union([
+  refSelectorSchema,
+  roleSelectorSchema,
+  cssSelectorSchema,
+  textSelectorSchema
+]).describe("Element selector supporting ref, role, CSS, or text-based selection");
+var SelectorConfidence = {
+  HIGH: 0.9,
+  MEDIUM: 0.7,
+  LOW: 0.5,
+  VERY_LOW: 0.3
+};
+var ResolutionStrategy = {
+  REF: "ref",
+  CSS_PARALLEL: "css_parallel",
+  ROLE_SEQUENTIAL: "role_sequential",
+  TEXT_FALLBACK: "text_fallback"
+};
+function isRefSelector(selector) {
+  return "ref" in selector;
+}
+function isRoleSelector(selector) {
+  return "role" in selector;
+}
+function isCSSSelector(selector) {
+  return "css" in selector;
+}
+function isTextSelector(selector) {
+  return "text" in selector && !("role" in selector);
+}
+function validateElementSelector(selector) {
+  return elementSelectorSchema.parse(selector);
+}
+function isValidSelector(selector) {
+  try {
+    elementSelectorSchema.parse(selector);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var SelectorValidator = {
+  validateElementSelector,
+  isValidSelector
+};
+var SelectorPatterns = {
+  ARIA_ROLES: [
+    "button",
+    "textbox",
+    "link",
+    "checkbox",
+    "radio",
+    "combobox",
+    "listbox",
+    "option",
+    "tab",
+    "tabpanel",
+    "dialog",
+    "alert",
+    "menu",
+    "menuitem",
+    "table",
+    "row",
+    "cell",
+    "heading"
+  ],
+  CSS_PATTERNS: {
+    byId: (id) => `#${id}`,
+    byClass: (className) => `.${className}`,
+    byAttribute: (attr, value) => value ? `[${attr}="${value}"]` : `[${attr}]`,
+    byDataTestId: (testId) => `[data-testid="${testId}"]`,
+    byRole: (role) => `[role="${role}"]`
+  }
+};
+export {
+  validateElementSelector,
+  textSelectorSchema,
+  roleSelectorSchema,
+  refSelectorSchema,
+  isValidSelector,
+  isTextSelector,
+  isRoleSelector,
+  isRefSelector,
+  isCSSSelector,
+  elementSelectorSchema,
+  cssSelectorSchema,
+  SelectorValidator,
+  SelectorPatterns,
+  SelectorConfidence,
+  ResolutionStrategy
+};