@tontoko/fast-playwright-mcp 0.1.1 → 0.1.3

package/lib/utilities/html-inspector.js

@@ -0,0 +1,514 @@
+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/utilities/html-inspector.ts
+import { SelectorResolver } from "../services/selector-resolver.js";
+import {
+  generateHTMLInspectionSuggestions,
+  HTMLInspectionConstants,
+  HTMLInspectionUtils,
+  validateHTMLInspectionOptions
+} from "../types/html-inspection.js";
+import { tabDebug } from "../utils/log.js";
+
+class HTMLInspector {
+  selectorResolver;
+  defaultOptions = {
+    depth: HTMLInspectionConstants.DEFAULT_DEPTH,
+    maxSize: HTMLInspectionConstants.DEFAULT_MAX_SIZE,
+    format: "html",
+    includeAttributes: true,
+    includeStyles: false,
+    preserveWhitespace: false
+  };
+  constructor(page) {
+    this.selectorResolver = new SelectorResolver(page);
+  }
+  async _processSelectorResult(index, selectorResult, selector, options, remainingSize) {
+    if (selectorResult.error || selectorResult.confidence === 0) {
+      tabDebug(`Selector ${index} failed to resolve: ${selectorResult.error}`);
+      return { error: true };
+    }
+    try {
+      const elementResult = await this._extractElementHTML(selectorResult.locator, selector, options, remainingSize);
+      return { element: elementResult ?? undefined };
+    } catch (error) {
+      tabDebug(`Failed to extract HTML for selector ${index}:`, error);
+      return { error: true };
+    }
+  }
+  async _processAllSelectors(selectorResults, selectors, options) {
+    const elements = {};
+    let totalSizeBytes = 0;
+    let truncated = false;
+    let elementsFound = 0;
+    let selectorsNotFound = 0;
+    let totalDepth = 0;
+    const maxSize = options.maxSize ?? 50000;
+    const allResults = await Promise.all(selectorResults.map((selectorResult, i) => this._processSelectorResult(i, selectorResult, selectors[i], options, maxSize).then((result) => ({ index: i, result }))));
+    for (const { index, result } of allResults) {
+      if (result.error) {
+        selectorsNotFound++;
+        continue;
+      }
+      if (result.element && totalSizeBytes + result.element.metadata.sizeBytes <= maxSize) {
+        elements[index] = result.element;
+        totalSizeBytes += result.element.metadata.sizeBytes;
+        elementsFound++;
+        totalDepth += this._calculateElementDepth(result.element);
+        if (result.element.html.includes("<!-- TRUNCATED -->")) {
+          truncated = true;
+        }
+      } else if (result.element) {
+        truncated = true;
+        tabDebug("Size limit reached, skipping remaining elements");
+        break;
+      }
+    }
+    return {
+      elements,
+      stats: {
+        elementsFound,
+        selectorsNotFound,
+        totalDepth,
+        totalSizeBytes,
+        truncated
+      }
+    };
+  }
+  async extractHTML(options) {
+    const startTime = Date.now();
+    const validatedOptions = validateHTMLInspectionOptions(options);
+    const mergedOptions = { ...this.defaultOptions, ...validatedOptions };
+    tabDebug(`Starting HTML extraction for ${mergedOptions.selectors.length} selectors`);
+    try {
+      const selectorStartTime = Date.now();
+      const selectorResults = await this.selectorResolver.resolveSelectors(mergedOptions.selectors, { continueOnError: true });
+      const selectorResolutionMs = Date.now() - selectorStartTime;
+      const extractionStartTime = Date.now();
+      const { elements, stats } = await this._processAllSelectors(selectorResults, mergedOptions.selectors, mergedOptions);
+      const extractionMs = Date.now() - extractionStartTime;
+      const totalMs = Date.now() - startTime;
+      const result = {
+        elements,
+        totalSizeBytes: stats.totalSizeBytes,
+        truncated: stats.truncated,
+        timing: {
+          totalMs,
+          selectorResolutionMs,
+          extractionMs
+        },
+        stats: {
+          elementsFound: stats.elementsFound,
+          selectorsNotFound: stats.selectorsNotFound,
+          averageDepth: stats.elementsFound > 0 ? stats.totalDepth / stats.elementsFound : 0
+        }
+      };
+      result.suggestions = generateHTMLInspectionSuggestions(result);
+      if (result.timing.totalMs > 5000) {
+        result.suggestions?.push("Extraction took longer than expected. Consider reducing scope or depth.");
+      }
+      if (result.totalSizeBytes > HTMLInspectionConstants.SIZE_THRESHOLDS.WARNING) {
+        result.suggestions?.push("Large content detected. Consider reducing depth or using more specific selectors.");
+      }
+      tabDebug(`HTML extraction completed in ${result.timing.totalMs}ms: ${result.stats.elementsFound} elements, ${result.totalSizeBytes} bytes`);
+      return result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      tabDebug("HTML extraction failed:", errorMessage);
+      return {
+        elements: {},
+        totalSizeBytes: 0,
+        truncated: false,
+        suggestions: [`Extraction failed: ${errorMessage}`],
+        timing: {
+          totalMs: Date.now() - startTime,
+          selectorResolutionMs: 0,
+          extractionMs: 0
+        },
+        stats: {
+          elementsFound: 0,
+          selectorsNotFound: options.selectors.length,
+          averageDepth: 0
+        }
+      };
+    }
+  }
+  suggestCSSSelectors(inspectionResult) {
+    const suggestions = [];
+    for (const elementResult of Object.values(inspectionResult.elements)) {
+      const elementSuggestions = this._generateSelectorsForElement(elementResult);
+      suggestions.push(...elementSuggestions);
+    }
+    return [...suggestions].sort((a, b) => b.confidence - a.confidence).slice(0, 20);
+  }
+  async optimizeForLLM(inspectionResult) {
+    const optimizedElements = {};
+    let totalSizeBytes = 0;
+    const entries = Object.entries(inspectionResult.elements);
+    const optimizedResults = await Promise.all(entries.map(async ([index, element]) => ({
+      index: Number.parseInt(index, 10),
+      element: await this._optimizeElementForLLM(element)
+    })));
+    for (const { index, element } of optimizedResults) {
+      optimizedElements[index] = element;
+      totalSizeBytes += element.metadata.sizeBytes;
+    }
+    return {
+      ...inspectionResult,
+      elements: optimizedElements,
+      totalSizeBytes
+    };
+  }
+  async _extractElementHTML(locator, selector, options, remainingSizeBytes) {
+    try {
+      const count = await locator.count();
+      if (count === 0) {
+        return null;
+      }
+      const element = locator.first();
+      const metadata = await this._extractElementMetadata(element);
+      let html;
+      switch (options.format) {
+        case "text":
+          html = await this._extractTextContent(element);
+          break;
+        case "aria":
+          html = await this._extractAriaContent(element);
+          break;
+        default:
+          html = await this._extractHTMLContent(element, options);
+          break;
+      }
+      const sizeBytes = HTMLInspectionUtils.calculateHtmlSize(html);
+      if (sizeBytes > remainingSizeBytes && remainingSizeBytes > 0) {
+        const truncationResult = HTMLInspectionUtils.truncateHtml(html, remainingSizeBytes);
+        html = truncationResult.html;
+        metadata.sizeBytes = HTMLInspectionUtils.calculateHtmlSize(html);
+      } else {
+        metadata.sizeBytes = sizeBytes;
+      }
+      const result = {
+        html,
+        metadata,
+        matchedSelector: selector
+      };
+      if (options.depth && options.depth > 1) {
+        result.children = await this._extractChildElements(element, options, remainingSizeBytes - metadata.sizeBytes);
+      }
+      return result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return {
+        html: "",
+        metadata: {
+          tagName: "unknown",
+          attributes: {},
+          textContent: "",
+          sizeBytes: 0
+        },
+        matchedSelector: selector,
+        error: errorMessage
+      };
+    }
+  }
+  async _extractElementMetadata(locator) {
+    try {
+      const [
+        tagName,
+        attributes,
+        textContent,
+        boundingBox,
+        computedStyles,
+        ariaRole,
+        ariaProperties
+      ] = await Promise.all([
+        locator.evaluate((el) => el.tagName.toLowerCase()),
+        locator.evaluate((el) => {
+          const attrs = {};
+          for (const attr of el.attributes) {
+            attrs[attr.name] = attr.value;
+          }
+          return attrs;
+        }),
+        locator.textContent() || "",
+        locator.boundingBox().catch(() => null),
+        this._extractComputedStyles(locator),
+        locator.evaluate((el) => el.getAttribute("role")),
+        this._extractAriaProperties(locator)
+      ]);
+      return {
+        tagName,
+        attributes,
+        textContent: textContent || "",
+        sizeBytes: 0,
+        boundingBox: boundingBox || undefined,
+        computedStyles,
+        ariaRole: ariaRole || undefined,
+        ariaProperties
+      };
+    } catch (error) {
+      tabDebug("Failed to extract element metadata:", error);
+      return {
+        tagName: "unknown",
+        attributes: {},
+        textContent: "",
+        sizeBytes: 0
+      };
+    }
+  }
+  async _extractHTMLContent(locator, options) {
+    return await locator.evaluate((el, opts) => {
+      const removeExcludedElements = (element, selector) => {
+        if (!selector) {
+          return;
+        }
+        const excluded = element.querySelectorAll(selector);
+        for (const elem of excluded) {
+          elem.remove();
+        }
+      };
+      const cleanAttributes = (element) => {
+        const walker = document.createTreeWalker(element, NodeFilter.SHOW_ELEMENT, null);
+        const elements = [];
+        let node = walker.nextNode();
+        while (node) {
+          elements.push(node);
+          node = walker.nextNode();
+        }
+        const keepAttrs = [
+          "id",
+          "class",
+          "role",
+          "data-testid",
+          "href",
+          "src",
+          "alt",
+          "title"
+        ];
+        for (const elem of elements) {
+          const toRemove = Array.from(elem.attributes).filter((attr) => !keepAttrs.includes(attr.name)).map((attr) => attr.name);
+          for (const name of toRemove) {
+            elem.removeAttribute(name);
+          }
+        }
+      };
+      const normalizeWhitespace = (element) => {
+        const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT, null);
+        const textNodes = [];
+        let node = walker.nextNode();
+        while (node) {
+          textNodes.push(node);
+          node = walker.nextNode();
+        }
+        for (const textNode of textNodes) {
+          textNode.nodeValue = (textNode.nodeValue || "").replace(/\s+/g, " ").trim();
+        }
+      };
+      const clone = el.cloneNode(true);
+      removeExcludedElements(clone, opts.excludeSelector);
+      removeExcludedElements(clone, "script, style");
+      if (!opts.includeAttributes) {
+        cleanAttributes(clone);
+      }
+      if (!opts.preserveWhitespace) {
+        normalizeWhitespace(clone);
+      }
+      return clone.outerHTML;
+    }, options);
+  }
+  async _extractTextContent(locator) {
+    const textContent = await locator.textContent();
+    return textContent || "";
+  }
+  async _extractAriaContent(locator) {
+    return await locator.evaluate((el) => {
+      const role = el.getAttribute("role") || el.tagName.toLowerCase();
+      const label = el.getAttribute("aria-label") || el.textContent?.trim() || "";
+      return `${role}: ${label}`;
+    });
+  }
+  async _processBatch(childElements, tagNames, startIdx, endIdx, childOptions, maxBytes) {
+    const promises = [];
+    for (let i = startIdx;i < endIdx && maxBytes > 0; i++) {
+      const childSelector = { css: tagNames[i] };
+      promises.push(this._extractElementHTML(childElements[i], childSelector, childOptions, maxBytes).then((result) => result ?? undefined));
+    }
+    const results = await Promise.all(promises);
+    return results.filter((r) => r !== undefined);
+  }
+  async _extractChildElements(parentLocator, options, remainingSizeBytes) {
+    try {
+      const children = [];
+      const childOptions = { ...options, depth: (options.depth || 1) - 1 };
+      const childElements = await parentLocator.locator("> *").all();
+      if (childElements.length === 0) {
+        return children;
+      }
+      const tagNames = await Promise.all(childElements.map((child) => child.evaluate((el) => el.tagName.toLowerCase())));
+      const allResults = await this._processBatch(childElements, tagNames, 0, childElements.length, childOptions, remainingSizeBytes);
+      let currentRemainingBytes = remainingSizeBytes;
+      for (const childResult of allResults) {
+        if (currentRemainingBytes <= 0) {
+          break;
+        }
+        if (childResult.metadata.sizeBytes <= currentRemainingBytes) {
+          children.push(childResult);
+          currentRemainingBytes -= childResult.metadata.sizeBytes;
+        }
+      }
+      return children;
+    } catch (error) {
+      tabDebug("Failed to extract child elements:", error);
+      return [];
+    }
+  }
+  _calculateElementDepth(element) {
+    if (!element.children || element.children.length === 0) {
+      return 1;
+    }
+    const maxChildDepth = Math.max(...element.children.map((child) => this._calculateElementDepth(child)));
+    return 1 + maxChildDepth;
+  }
+  _generateSelectorsForElement(element) {
+    const suggestions = [];
+    const { tagName, attributes } = element.metadata;
+    if (attributes.id) {
+      suggestions.push({
+        selector: `#${attributes.id}`,
+        confidence: 0.95,
+        element: `${tagName}#${attributes.id}`,
+        description: "Unique ID selector (most reliable)"
+      });
+    }
+    if (attributes["data-testid"]) {
+      suggestions.push({
+        selector: `[data-testid="${attributes["data-testid"]}"]`,
+        confidence: 0.9,
+        element: `${tagName}[data-testid="${attributes["data-testid"]}"]`,
+        description: "Test ID selector (very reliable)"
+      });
+    }
+    if (attributes.class) {
+      const classes = attributes.class.split(" ").filter(Boolean);
+      for (const className of classes) {
+        suggestions.push({
+          selector: `.${className}`,
+          confidence: 0.7,
+          element: `${tagName}.${className}`,
+          description: "Class selector (moderate reliability)"
+        });
+      }
+    }
+    if (attributes.role) {
+      suggestions.push({
+        selector: `[role="${attributes.role}"]`,
+        confidence: 0.8,
+        element: `${tagName}[role="${attributes.role}"]`,
+        description: "ARIA role selector (good for accessibility)"
+      });
+    }
+    for (const [attrName, attrValue] of Object.entries(attributes)) {
+      if (!["id", "class", "role", "data-testid"].includes(attrName) && attrValue) {
+        suggestions.push({
+          selector: `${tagName}[${attrName}="${attrValue}"]`,
+          confidence: 0.6,
+          element: `${tagName}[${attrName}="${attrValue}"]`,
+          description: `Attribute selector (${attrName})`
+        });
+      }
+    }
+    return suggestions;
+  }
+  async _optimizeElementForLLM(element) {
+    let optimizedHtml = element.html;
+    const noiseAttributes = ["style", "onclick", "onload", "onchange"];
+    for (const attr of noiseAttributes) {
+      optimizedHtml = optimizedHtml.replace(new RegExp(`\\s+${attr}="[^"]*"`, "g"), "");
+    }
+    optimizedHtml = optimizedHtml.replace(/\s+/g, " ").trim();
+    optimizedHtml = optimizedHtml.replace(/<(\w+)[^>]*>\s*<\/\1>/g, "");
+    const optimizedElement = {
+      ...element,
+      html: optimizedHtml,
+      metadata: {
+        ...element.metadata,
+        sizeBytes: HTMLInspectionUtils.calculateHtmlSize(optimizedHtml)
+      }
+    };
+    if (element.children) {
+      optimizedElement.children = await Promise.all(element.children.map((child) => this._optimizeElementForLLM(child)));
+    }
+    return optimizedElement;
+  }
+  async _extractComputedStyles(locator) {
+    try {
+      return await locator.evaluate((el) => {
+        const computed = window.getComputedStyle(el);
+        const styles = {};
+        const importantProps = [
+          "display",
+          "visibility",
+          "position",
+          "width",
+          "height",
+          "color",
+          "background-color",
+          "font-size",
+          "font-weight"
+        ];
+        for (const prop of importantProps) {
+          styles[prop] = computed.getPropertyValue(prop);
+        }
+        return styles;
+      });
+    } catch {
+      return;
+    }
+  }
+  async _extractAriaProperties(locator) {
+    try {
+      return await locator.evaluate((el) => {
+        const ariaProps = {};
+        const commonAriaProps = [
+          "aria-label",
+          "aria-describedby",
+          "aria-hidden",
+          "aria-expanded",
+          "aria-selected",
+          "aria-checked",
+          "aria-disabled",
+          "aria-required"
+        ];
+        for (const prop of commonAriaProps) {
+          const value = el.getAttribute(prop);
+          if (value) {
+            ariaProps[prop] = value;
+          }
+        }
+        return Object.keys(ariaProps).length > 0 ? ariaProps : undefined;
+      });
+    } catch {
+      return;
+    }
+  }
+}
+export {
+  HTMLInspector
+};

package/lib/utilities/index.js

@@ -0,0 +1,24 @@
+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/utilities/index.ts
+import { HTMLInspector } from "./html-inspector.js";
+export {
+  HTMLInspector
+};

package/lib/utils/tool-patterns.js

@@ -18,38 +18,11 @@ var __toESM = (mod, isNodeMode, target) => {
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/utils/tool-patterns.ts
-import { BaseElementToolHandler } from "../tools/base-tool-handler.js";
 import { getErrorMessage } from "./common-formatters.js";
-var resolveElementLocator = async (tab, params) => {
-
-  class TempHandler extends BaseElementToolHandler {
-    constructor() {
-      super("temp");
-    }
-    executeToolLogic() {
-      return Promise.resolve();
-    }
-    resolveLocator(tabInstance, locatorParams) {
-      return this.resolveElementLocator(tabInstance, locatorParams);
-    }
-  }
-  return await new TempHandler().resolveLocator(tab, params);
-};
-var validateElementParams = (params) => {
-
-  class TempHandler extends BaseElementToolHandler {
-    constructor() {
-      super("temp");
-    }
-    executeToolLogic() {
-      return Promise.resolve();
-    }
-    validateParams(validationParams) {
-      this.validateElementParams(validationParams);
-    }
-  }
-  new TempHandler().validateParams(params);
+var resolveElementLocator = (_tab, _params) => {
+  return Promise.resolve(undefined);
 };
+var validateElementParams = (_params) => {};
 function addToolErrorContext(response, error, toolName, params) {
   const errorMessage = getErrorMessage(error);
   response.addError(`Error in ${toolName}: ${errorMessage}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tontoko/fast-playwright-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "publishConfig": {
     "access": "public"
   },
@@ -51,8 +51,8 @@
     "dotenv": "^17.2.0",
     "fast-diff": "^1.3.0",
     "mime": "^4.0.7",
-    "playwright": "1.55.0-alpha-2025-08-07",
-    "playwright-core": "1.55.0-alpha-2025-08-07",
+    "playwright": "1.58.0-alpha-1766189059000",
+    "playwright-core": "1.58.0-alpha-1766189059000",
     "sharp": "^0.34.3",
     "ws": "^8.18.1",
     "zod": "^3.24.1",
@@ -61,7 +61,7 @@
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.57.0",
     "@biomejs/biome": "2.1.2",
-    "@playwright/test": "1.55.0-alpha-2025-08-07",
+    "@playwright/test": "1.58.0-alpha-1766189059000",
     "@types/debug": "^4.1.12",
     "@types/node": "^22.13.10",
     "@types/ws": "^8.18.1",