@tontoko/fast-playwright-mcp 0.1.0 → 0.1.2

package/lib/services/selector-resolver.js

@@ -0,0 +1,541 @@
+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/services/selector-resolver.ts
+import {
+  isCSSSelector,
+  isRefSelector,
+  isRoleSelector,
+  isTextSelector,
+  ResolutionStrategy,
+  SelectorConfidence,
+  validateElementSelector
+} from "../types/selectors.js";
+import { tabDebug } from "../utils/log.js";
+var GENERIC_TAG_SELECTOR = /^[a-z]+$/;
+
+class SelectorResolver {
+  page;
+  defaultTimeoutMs = 3000;
+  constructor(page) {
+    this.page = page;
+  }
+  async resolveSelectors(selectors, options = {}) {
+    const startTime = Date.now();
+    const {
+      timeoutMs = this.defaultTimeoutMs,
+      continueOnError = true,
+      executionStrategy = "hybrid"
+    } = options;
+    tabDebug(`Resolving ${selectors.length} selectors using ${executionStrategy} strategy`);
+    const validatedSelectors = this._validateSelectors(selectors);
+    const categorized = this._categorizeSelectors(validatedSelectors);
+    try {
+      switch (executionStrategy) {
+        case "parallel":
+          return await this._resolveParallel(categorized, timeoutMs, continueOnError);
+        case "sequential":
+          return await this._resolveSequential(categorized, timeoutMs, continueOnError);
+        default:
+          return await this._resolveHybrid(categorized, timeoutMs, continueOnError);
+      }
+    } catch (error) {
+      tabDebug(`Selector resolution failed after ${Date.now() - startTime}ms:`, error);
+      throw error;
+    }
+  }
+  async resolveSingleSelector(selector, options = {}) {
+    const { timeoutMs = this.defaultTimeoutMs } = options;
+    const startTime = Date.now();
+    try {
+      validateElementSelector(selector);
+      const result = await this._resolveSelectorWithTimeout(selector, timeoutMs);
+      if (result.locator && !result.error) {
+        const metadata = await this._extractElementMetadata(result.locator);
+        const suggestions = this._generateSuggestions(selector, metadata);
+        return {
+          ...result,
+          metadata,
+          suggestions
+        };
+      }
+      return result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      tabDebug(`Single selector resolution failed: ${errorMessage}`);
+      return {
+        locator: this.page.locator("not-found"),
+        selector,
+        confidence: 0,
+        strategy: this._getStrategyForSelector(selector),
+        resolutionTimeMs: Date.now() - startTime,
+        error: errorMessage
+      };
+    }
+  }
+  _validateSelectors(selectors) {
+    return selectors.map((selector, index) => {
+      try {
+        return validateElementSelector(selector);
+      } catch (error) {
+        throw new Error(`Invalid selector at index ${index}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    });
+  }
+  _categorizeSelectors(selectors) {
+    const categorized = {
+      refs: [],
+      css: [],
+      roles: [],
+      text: []
+    };
+    for (const selector of selectors) {
+      if (isRefSelector(selector)) {
+        categorized.refs.push(selector);
+      } else if (isCSSSelector(selector)) {
+        categorized.css.push(selector);
+      } else if (isRoleSelector(selector)) {
+        categorized.roles.push(selector);
+      } else if (isTextSelector(selector)) {
+        categorized.text.push(selector);
+      }
+    }
+    return categorized;
+  }
+  async _resolveParallel(categorized, timeoutMs, continueOnError) {
+    const allSelectors = [
+      ...categorized.refs,
+      ...categorized.css,
+      ...categorized.roles,
+      ...categorized.text
+    ];
+    const promises = allSelectors.map(async (selector) => {
+      try {
+        return await this._resolveSelectorWithTimeout(selector, timeoutMs);
+      } catch (error) {
+        if (!continueOnError) {
+          throw error;
+        }
+        return this._createErrorResult(selector, error);
+      }
+    });
+    return await Promise.all(promises);
+  }
+  async _resolveSequential(categorized, timeoutMs, continueOnError) {
+    const allSelectors = [
+      ...categorized.refs,
+      ...categorized.css,
+      ...categorized.roles,
+      ...categorized.text
+    ];
+    const promises = allSelectors.map(async (selector, index) => {
+      await new Promise((resolve) => setTimeout(resolve, index * 10));
+      try {
+        return await this._resolveSelectorWithTimeout(selector, timeoutMs);
+      } catch (error) {
+        if (!continueOnError) {
+          throw error;
+        }
+        return this._createErrorResult(selector, error);
+      }
+    });
+    return await Promise.all(promises);
+  }
+  async _resolveHybrid(categorized, timeoutMs, continueOnError) {
+    const results = [];
+    if (categorized.refs.length > 0) {
+      const refPromises = categorized.refs.map(async (selector) => {
+        try {
+          return await this._resolveSelectorWithTimeout(selector, timeoutMs);
+        } catch (error) {
+          if (!continueOnError) {
+            throw error;
+          }
+          return this._createErrorResult(selector, error);
+        }
+      });
+      const refResults = await Promise.all(refPromises);
+      results.push(...refResults);
+    }
+    const otherSelectors = [
+      ...categorized.css,
+      ...categorized.roles,
+      ...categorized.text
+    ];
+    const otherPromises = otherSelectors.map(async (selector, index) => {
+      await new Promise((resolve) => setTimeout(resolve, index * 10));
+      try {
+        return await this._resolveSelectorWithTimeout(selector, timeoutMs);
+      } catch (error) {
+        if (!continueOnError) {
+          throw error;
+        }
+        return this._createErrorResult(selector, error);
+      }
+    });
+    const otherResults = await Promise.all(otherPromises);
+    results.push(...otherResults);
+    return results;
+  }
+  async _resolveSelectorWithTimeout(selector, timeoutMs) {
+    const startTime = Date.now();
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new Error(`Selector resolution timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+    });
+    try {
+      const result = await Promise.race([
+        this._resolveSingleSelectorInternal(selector),
+        timeoutPromise
+      ]);
+      return {
+        ...result,
+        resolutionTimeMs: Date.now() - startTime
+      };
+    } catch (error) {
+      return this._createErrorResult(selector, error, Date.now() - startTime);
+    }
+  }
+  async _resolveSingleSelectorInternal(selector) {
+    if (isRefSelector(selector)) {
+      return await this._resolveRefSelector(selector);
+    }
+    if (isRoleSelector(selector)) {
+      return await this._resolveRoleSelector(selector);
+    }
+    if (isCSSSelector(selector)) {
+      return await this._resolveCSSSelector(selector);
+    }
+    if (isTextSelector(selector)) {
+      return await this._resolveTextSelector(selector);
+    }
+    throw new Error("Unknown selector type");
+  }
+  async _resolveRefSelector(selector) {
+    try {
+      const locator = this.page.locator(`aria-ref=${selector.ref}`);
+      const count = await locator.count();
+      if (count === 0) {
+        return {
+          locator: this.page.locator("not-found"),
+          selector,
+          confidence: 0,
+          strategy: ResolutionStrategy.REF,
+          error: `Ref ${selector.ref} not found in current page state`
+        };
+      }
+      return {
+        locator,
+        selector,
+        confidence: SelectorConfidence.HIGH,
+        strategy: ResolutionStrategy.REF
+      };
+    } catch (error) {
+      throw new Error(`Failed to resolve ref selector: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  async _resolveRoleSelector(selector) {
+    try {
+      let locator = this.page.getByRole(selector.role);
+      let confidence = SelectorConfidence.MEDIUM;
+      if (selector.text) {
+        locator = locator.filter({ hasText: selector.text });
+        confidence = SelectorConfidence.HIGH;
+      }
+      const count = await locator.count();
+      if (count === 0) {
+        const alternatives = await this._findRoleAlternatives(selector.role, selector.text);
+        return {
+          locator: this.page.locator("not-found"),
+          selector,
+          confidence: 0,
+          strategy: ResolutionStrategy.ROLE_SEQUENTIAL,
+          alternatives,
+          error: selector.text ? `No elements found with role "${selector.role}" and text "${selector.text}"` : `No elements found with role "${selector.role}"`
+        };
+      }
+      if (count > 1 && !selector.text) {
+        const candidates = await this._getMatchCandidates(locator);
+        const candidateDescriptions = candidates.map((c, i) => {
+          const attrs = Object.entries(c.attributes).filter(([key]) => ["id", "name", "data-testid", "aria-label"].includes(key)).map(([key, value]) => `${key}="${value}"`).join(" ");
+          const prefix = attrs ? `[${attrs}] ` : "";
+          const truncatedText = c.text.length > 50 ? `${c.text.substring(0, 50)}...` : c.text;
+          return `  ${i + 1}) ${prefix}text: "${truncatedText}"`;
+        }).join(`
+`);
+        return {
+          locator: this.page.locator("not-found"),
+          selector,
+          confidence: 0,
+          strategy: ResolutionStrategy.ROLE_SEQUENTIAL,
+          error: `Multiple elements (${count}) found with role "${selector.role}". Please be more specific:
+${candidateDescriptions}
+Consider adding text filter or using a more specific selector.`
+        };
+      }
+      return {
+        locator,
+        selector,
+        confidence,
+        strategy: ResolutionStrategy.ROLE_SEQUENTIAL
+      };
+    } catch (error) {
+      throw new Error(`Failed to resolve role selector: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  async _resolveCSSSelector(selector) {
+    try {
+      const locator = this.page.locator(selector.css);
+      const count = await locator.count();
+      if (count === 0) {
+        return {
+          locator: this.page.locator("not-found"),
+          selector,
+          confidence: 0,
+          strategy: ResolutionStrategy.CSS_PARALLEL,
+          error: `No elements found matching CSS selector "${selector.css}"`
+        };
+      }
+      let confidence = SelectorConfidence.MEDIUM;
+      if (selector.css.startsWith("#")) {
+        confidence = SelectorConfidence.HIGH;
+      } else if (count > 1 && GENERIC_TAG_SELECTOR.test(selector.css)) {
+        const candidates = await this._getMatchCandidates(locator);
+        const candidateDescriptions = candidates.map((c, i) => {
+          const attrs = Object.entries(c.attributes).filter(([key]) => ["id", "class", "name", "data-testid"].includes(key)).map(([key, value]) => `${key}="${value}"`).join(" ");
+          const prefix = attrs ? `[${attrs}] ` : "";
+          const truncatedText = c.text.length > 50 ? `${c.text.substring(0, 50)}...` : c.text;
+          return `  ${i + 1}) ${prefix}text: "${truncatedText}"`;
+        }).join(`
+`);
+        return {
+          locator: this.page.locator("not-found"),
+          selector,
+          confidence: 0,
+          strategy: ResolutionStrategy.CSS_PARALLEL,
+          error: `Multiple elements (${count}) found with CSS selector "${selector.css}". Please be more specific:
+${candidateDescriptions}
+Consider using a more specific selector like ID or adding :nth-child().`
+        };
+      }
+      return {
+        locator,
+        selector,
+        confidence,
+        strategy: ResolutionStrategy.CSS_PARALLEL
+      };
+    } catch (error) {
+      throw new Error(`Failed to resolve CSS selector: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  async _resolveTextSelector(selector) {
+    try {
+      let locator = this.page.getByText(selector.text);
+      if (selector.tag) {
+        locator = this.page.locator(selector.tag).filter({ hasText: selector.text });
+      }
+      const count = await locator.count();
+      if (count === 0) {
+        const alternatives = await this._findTextAlternatives(selector.text);
+        return {
+          locator: this.page.locator("not-found"),
+          selector,
+          confidence: 0,
+          strategy: ResolutionStrategy.TEXT_FALLBACK,
+          alternatives,
+          error: selector.tag ? `No elements found with text "${selector.text}" in ${selector.tag} tags` : `No elements found with text "${selector.text}"`
+        };
+      }
+      let confidence = SelectorConfidence.MEDIUM;
+      if (selector.tag) {
+        confidence = SelectorConfidence.HIGH;
+      } else if (count > 3) {
+        const candidates = await this._getMatchCandidates(locator);
+        const candidateDescriptions = candidates.map((c, i) => {
+          const attrs = Object.entries(c.attributes).filter(([key]) => ["id", "class", "role", "data-testid"].includes(key)).map(([key, value]) => `${key}="${value}"`).join(" ");
+          const tagName = c.attributes.tagName || "element";
+          const attrString = attrs ? ` ${attrs}` : "";
+          const truncatedText = c.text.length > 50 ? `${c.text.substring(0, 50)}...` : c.text;
+          return `  ${i + 1}) <${tagName}${attrString}> text: "${truncatedText}"`;
+        }).join(`
+`);
+        return {
+          locator: this.page.locator("not-found"),
+          selector,
+          confidence: 0,
+          strategy: ResolutionStrategy.TEXT_FALLBACK,
+          error: `Multiple elements (${count}) found with text "${selector.text}". Please be more specific:
+${candidateDescriptions}
+Consider using CSS selector or role with text filter.`
+        };
+      }
+      return {
+        locator,
+        selector,
+        confidence,
+        strategy: ResolutionStrategy.TEXT_FALLBACK
+      };
+    } catch (error) {
+      throw new Error(`Failed to resolve text selector: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  async _getMatchCandidates(locator, limit = 5) {
+    const count = await locator.count();
+    const maxCount = Math.min(count, limit);
+    const promises = [];
+    for (let i = 0;i < maxCount; i++) {
+      const element = locator.nth(i);
+      promises.push(Promise.all([
+        element.textContent(),
+        element.evaluate((el) => {
+          const attrs = {};
+          for (const attr of el.attributes) {
+            attrs[attr.name] = attr.value;
+          }
+          return attrs;
+        })
+      ]).then(([text, attributes]) => ({
+        index: i,
+        text: text?.trim() || "",
+        attributes
+      })).catch(() => null));
+    }
+    const results = await Promise.all(promises);
+    return results.filter((result) => result !== null);
+  }
+  async _findRoleAlternatives(role, text) {
+    const alternatives = [];
+    const commonRoleAlternatives = {
+      button: ["link", "menuitem"],
+      link: ["button", "menuitem"],
+      textbox: ["searchbox", "combobox"],
+      checkbox: ["radio", "switch"]
+    };
+    const roleAlts = commonRoleAlternatives[role] || [];
+    const rolePromises = roleAlts.map(async (altRole) => {
+      try {
+        const locator = text ? this.page.getByRole(altRole).filter({ hasText: text }) : this.page.getByRole(altRole);
+        const count = await locator.count();
+        if (count > 0) {
+          return { role: altRole, text };
+        }
+        return null;
+      } catch {
+        return null;
+      }
+    });
+    const results = await Promise.all(rolePromises);
+    const validAlternatives = results.filter((alt) => alt !== null);
+    alternatives.push(...validAlternatives);
+    return alternatives.slice(0, 3);
+  }
+  async _findTextAlternatives(text) {
+    const alternatives = [];
+    const partialText = text.substring(0, Math.floor(text.length / 2));
+    if (partialText.length > 3) {
+      try {
+        const count = await this.page.getByText(partialText, { exact: false }).count();
+        if (count > 0) {
+          alternatives.push({ text: partialText });
+        }
+      } catch {}
+    }
+    return alternatives.slice(0, 2);
+  }
+  async _extractElementMetadata(locator) {
+    try {
+      const element = locator.first();
+      const [
+        tagName,
+        attributes,
+        textContent,
+        boundingBox,
+        isVisible,
+        isEnabled
+      ] = await Promise.all([
+        element.evaluate((el) => el.tagName.toLowerCase()),
+        element.evaluate((el) => {
+          const attrs = {};
+          for (const attr of el.attributes) {
+            attrs[attr.name] = attr.value;
+          }
+          return attrs;
+        }),
+        element.textContent() || "",
+        element.boundingBox().catch(() => null),
+        element.isVisible().catch(() => false),
+        element.isEnabled().catch(() => false)
+      ]);
+      return {
+        tagName,
+        attributes,
+        textContent: textContent || "",
+        boundingBox: boundingBox || undefined,
+        isVisible,
+        isEnabled
+      };
+    } catch (error) {
+      tabDebug("Failed to extract element metadata:", error);
+      return;
+    }
+  }
+  _generateSuggestions(selector, metadata) {
+    const suggestions = [];
+    if (!metadata) {
+      return suggestions;
+    }
+    if (metadata.attributes["data-testid"] && !isCSSSelector(selector)) {
+      suggestions.push(`Consider using CSS selector with data-testid: [data-testid="${metadata.attributes["data-testid"]}"]`);
+    }
+    if (metadata.attributes.id && !isCSSSelector(selector)) {
+      suggestions.push(`Consider using CSS selector with ID: #${metadata.attributes.id}`);
+    }
+    if (metadata.attributes.role && !isRoleSelector(selector)) {
+      suggestions.push(`Consider using role selector: role="${metadata.attributes.role}"`);
+    }
+    return suggestions;
+  }
+  _createErrorResult(selector, error, resolutionTimeMs = 0) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return {
+      locator: this.page.locator("not-found"),
+      selector,
+      confidence: 0,
+      strategy: this._getStrategyForSelector(selector),
+      resolutionTimeMs,
+      error: errorMessage
+    };
+  }
+  _getStrategyForSelector(selector) {
+    if (isRefSelector(selector)) {
+      return ResolutionStrategy.REF;
+    }
+    if (isCSSSelector(selector)) {
+      return ResolutionStrategy.CSS_PARALLEL;
+    }
+    if (isRoleSelector(selector)) {
+      return ResolutionStrategy.ROLE_SEQUENTIAL;
+    }
+    return ResolutionStrategy.TEXT_FALLBACK;
+  }
+}
+export {
+  SelectorResolver
+};

package/lib/tab.js

@@ -21,10 +21,10 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 import { EventEmitter } from "node:events";
 import { TIMEOUTS } from "./config/constants.js";
 import { ManualPromise } from "./manual-promise.js";
+import { SelectorResolver } from "./services/selector-resolver.js";
 import { callOnPageNoTrace, waitForCompletion } from "./tools/utils.js";
 import { logUnhandledError } from "./utils/log.js";
 import { snapshotDebug, tabDebug } from "./utils/log.js";
-var REF_VALUE_REGEX = /\[ref=([^\]]+)\]/;
 var TabEvents = {
   modalState: "modalState"
 };
@@ -41,6 +41,7 @@ class Tab extends EventEmitter {
   _downloads = [];
   _customRefMappings = new Map;
   _customRefCounter = 0;
+  _selectorResolver;
   _navigationState = {
     isNavigating: false,
     lastNavigationStart: 0
@@ -50,6 +51,7 @@ class Tab extends EventEmitter {
     this.context = context;
     this.page = page;
     this._onPageClose = onPageClose;
+    this._selectorResolver = new SelectorResolver(page);
     page.on("console", (event) => this._handleConsoleMessage(messageToConsoleMessage(event)));
     page.on("pageerror", (error) => this._handleConsoleMessage(pageErrorToConsoleMessage(error)));
     page.on("request", (request) => this._requests.set(request, null));
@@ -368,24 +370,55 @@ class Tab extends EventEmitter {
     }
     return `element_${this._customRefCounter}`;
   }
+  async resolveElementLocators(selectors, options) {
+    tabDebug(`Resolving ${selectors.length} element locators`);
+    try {
+      return await this._selectorResolver.resolveSelectors(selectors, options);
+    } catch (error) {
+      tabDebug("Failed to resolve element locators:", error);
+      throw error;
+    }
+  }
+  async resolveSingleElementLocator(selector, options) {
+    tabDebug("Resolving single element locator:", selector);
+    try {
+      return await this._selectorResolver.resolveSingleSelector(selector, options);
+    } catch (error) {
+      tabDebug("Failed to resolve single element locator:", error);
+      throw error;
+    }
+  }
   async refLocator(params) {
-    return (await this.refLocators([params]))[0];
+    const { selector } = params;
+    tabDebug("Using selector system for element:", params.element);
+    const result = await this._selectorResolver.resolveSingleSelector(selector);
+    if (result.error || !result.locator) {
+      const errorMessage = `Failed to resolve selector for element "${params.element}": ${result.error || "Unknown error"}`;
+      const alternativesMessage = result.alternatives ? `. Alternatives: ${JSON.stringify(result.alternatives)}` : "";
+      throw new Error(errorMessage + alternativesMessage);
+    }
+    return result.locator.describe(params.element);
   }
   async refLocators(params) {
-    const snapshot = await this.page._snapshotForAI();
-    return params.map((param) => {
-      if (this._customRefMappings.has(param.ref)) {
-        const selector = this._customRefMappings.get(param.ref);
-        if (selector) {
-          return this.page.locator(selector).describe(param.element);
-        }
-      }
-      if (!snapshot.includes(`[ref=${param.ref}]`)) {
-        const availableRefs = this._getAvailableRefs(snapshot);
-        throw new Error(`Ref ${param.ref} not found. Available refs: [${availableRefs.join(", ")}]. Element: ${param.element}. Consider capturing a new snapshot if the page has changed.`);
+    const selectors = params.map((p) => {
+      if (!p.selector) {
+        throw new Error(`Missing selector for element: ${p.element}`);
       }
-      return this.page.locator(`aria-ref=${param.ref}`).describe(param.element);
+      return p.selector;
     });
+    const resolutionResults = await this._selectorResolver.resolveSelectors(selectors);
+    const results = [];
+    for (let i = 0;i < resolutionResults.length; i++) {
+      const result = resolutionResults[i];
+      const param = params[i];
+      if (result.error || !result.locator) {
+        const errorMessage = `Failed to resolve selector for element "${param.element}": ${result.error || "Unknown error"}`;
+        const alternativesMessage = result.alternatives ? `. Alternatives: ${JSON.stringify(result.alternatives)}` : "";
+        throw new Error(errorMessage + alternativesMessage);
+      }
+      results.push(result.locator.describe(param.element));
+    }
+    return results;
   }
   async waitForTimeout(time) {
     if (this._javaScriptBlocked()) {
@@ -396,16 +429,6 @@ class Tab extends EventEmitter {
       return page.evaluate((timeout) => new Promise((f) => setTimeout(f, timeout)), time);
     });
   }
-  _getAvailableRefs(snapshot) {
-    const refMatches = snapshot.match(/\[ref=([^\]]+)\]/g);
-    if (!refMatches) {
-      return [];
-    }
-    return refMatches.map((match) => {
-      const refValue = REF_VALUE_REGEX.exec(match);
-      return refValue ? refValue[1] : "";
-    }).filter(Boolean);
-  }
 }
 function messageToConsoleMessage(message) {
   return {

package/lib/tools/base-tool-handler.js

@@ -79,28 +79,12 @@ class BaseToolHandler {
 }
 
 class BaseElementToolHandler extends BaseToolHandler {
-  async resolveElementLocator(tab, params) {
-    if (params.ref && params.element) {
-      return await tab.refLocator({
-        ref: params.ref,
-        element: params.element
-      });
-    }
-  }
-  validateElementParams(params) {
-    if (params.ref && !params.element) {
-      throw new Error("Element description is required when ref is provided");
-    }
-    if (params.element && !params.ref) {
-      throw new Error("Element ref is required when element description is provided");
-    }
+  resolveElementLocator(_tab, _params) {
+    return Promise.resolve(undefined);
   }
+  validateElementParams(_params) {}
   handleToolError(error, response, params) {
     super.handleToolError(error, response, params);
-    if (params.element && params.ref) {
-      response.addResult("Suggestion: Verify element selector is still valid");
-      response.addResult("Suggestion: Check if element is visible and interactable");
-    }
   }
 }
 function createToolWithBaseHandler(config, handlerClass) {

package/lib/tools/batch-execute.js

@@ -26,7 +26,7 @@ var batchExecuteTool = defineTool({
   schema: {
     name: "browser_batch_execute",
     title: "Batch Execute Browser Actions",
-    description: `Execute multiple browser actions in sequence with optimized response handling.RECOMMENDED:Use this tool instead of individual actions when performing multiple operations to significantly reduce token usage and improve performance.BY DEFAULT use for:form filling(multiple type→click),multi-step navigation,any workflow with 2+ known steps.Saves 90% tokens vs individual calls.globalExpectation:{includeSnapshot:false,snapshotOptions:{selector:"#app"},diffOptions:{enabled:true}}.Per-step override:steps[].expectation.Example:[{tool:"browser_navigate",arguments:{url:"https://example.com"}},{tool:"browser_type",arguments:{element:"username",ref:"#user",text:"john"}},{tool:"browser_click",arguments:{element:"submit",ref:"#btn"}}].Tool names must match exactly(e.g.browser_navigate,browser_click,browser_type).`,
+    description: "Execute multiple browser actions in sequence. PREFER over individual tools for 2+ operations.",
     inputSchema: batchExecuteSchema,
     type: "destructive"
   },