chrometools-mcp 3.2.10 → 3.3.8

package/models/index.js

@@ -38,18 +38,32 @@ const MODEL_REGISTRY = [
   TextInputModel,  // Default fallback for text-like inputs
 ];
 
+/**
+ * Wrap operation with timeout to prevent hanging
+ */
+async function withTimeout(operation, timeoutMs, operationName) {
+  const timeoutPromise = new Promise((_, reject) =>
+    setTimeout(() => reject(new Error(`${operationName} timed out after ${timeoutMs}ms`)), timeoutMs)
+  );
+  return Promise.race([operation(), timeoutPromise]);
+}
+
 /**
  * Factory class for creating appropriate input models
  */
 export class InputModelFactory {
   /**
-   * Get element info (tagName, inputType)
+   * Get element info (tagName, inputType) with timeout
    */
-  static async getElementInfo(element) {
-    return await element.evaluate(el => ({
-      tagName: el.tagName.toLowerCase(),
-      inputType: el.type?.toLowerCase() || null,
-    }));
+  static async getElementInfo(element, timeoutMs = 5000) {
+    return await withTimeout(
+      () => element.evaluate(el => ({
+        tagName: el.tagName.toLowerCase(),
+        inputType: el.type?.toLowerCase() || null,
+      })),
+      timeoutMs,
+      'getElementInfo'
+    );
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrometools-mcp",
-  "version": "3.2.10",
+  "version": "3.3.8",
   "description": "MCP (Model Context Protocol) server for Chrome automation using Puppeteer. Persistent browser sessions, UI framework detection (MUI, Ant Design, etc.), Page Object support, visual testing, Figma comparison. Works seamlessly in WSL, Linux, macOS, and Windows.",
   "type": "module",
   "main": "index.js",

package/pom/apom-tree-converter.js

@@ -10,9 +10,10 @@
  * Runs in browser context via page.evaluate()
  *
  * @param {boolean} interactiveOnly - Only include interactive elements and their parents
+ * @param {boolean} viewportOnly - Only include elements visible in current viewport
  * @returns {Object} APOM tree structure
  */
-function buildAPOMTree(interactiveOnly = true) {
+function buildAPOMTree(interactiveOnly = true, viewportOnly = false) {
   const pageId = `page_${btoa(window.location.href).replace(/[^a-zA-Z0-9]/g, '').substring(0, 20)}_${Date.now()}`;
 
   const result = {
@@ -26,7 +27,14 @@ function buildAPOMTree(interactiveOnly = true) {
       interactiveCount: 0,
       formCount: 0,
       modalCount: 0,
-      maxDepth: 0
+      maxDepth: 0,
+      viewportOnly: viewportOnly || undefined,
+      viewport: viewportOnly ? {
+        width: window.innerWidth || document.documentElement.clientWidth,
+        height: window.innerHeight || document.documentElement.clientHeight,
+        scrollX: window.scrollX || window.pageXOffset,
+        scrollY: window.scrollY || window.pageYOffset
+      } : undefined
     }
   };
 
@@ -51,8 +59,122 @@ function buildAPOMTree(interactiveOnly = true) {
   // Collect radio and checkbox groups for easier agent access
   result.groups = collectInputGroups(result.tree);
 
+  // Detect page alerts, warnings, errors, and restrictions
+  result.alerts = detectPageAlerts();
+
   return result;
 
+  /**
+   * Detect page alerts, warnings, errors, toasts, and restrictions
+   * Uses heuristics to find notification elements
+   */
+  function detectPageAlerts() {
+    const alerts = [];
+    const seenTexts = new Set();
+    const MIN_TEXT_LENGTH = 10;  // Ignore very short texts like "19", "OK"
+
+    // Helper to add alert avoiding duplicates and substrings
+    function addAlert(type, text, source) {
+      text = text?.trim();
+      if (!text || text.length < MIN_TEXT_LENGTH || text.length > 300) return;
+
+      // Normalize text
+      const normalizedText = text.substring(0, 200);
+
+      // Skip if already seen or is substring of existing
+      if (seenTexts.has(normalizedText)) return;
+      for (const seen of seenTexts) {
+        if (seen.includes(normalizedText) || normalizedText.includes(seen)) return;
+      }
+
+      seenTexts.add(normalizedText);
+      alerts.push({ type, text: normalizedText, source });
+    }
+
+    // 1. Elements with role="alert" or aria-live (highest priority)
+    document.querySelectorAll('[role="alert"], [aria-live="assertive"]').forEach(el => {
+      const text = el.textContent?.trim();
+      addAlert('alert', text, 'aria');
+    });
+
+    // 2. Classes containing restriction keywords (high priority - affects functionality)
+    const restrictionSelector = '[class*="deactivat"], [class*="disabled"], [class*="blocked"], [class*="restrict"], [class*="suspend"], [class*="inactive"]';
+    document.querySelectorAll(restrictionSelector).forEach(el => {
+      if (!isVisibleForAlert(el)) return;
+      const text = el.textContent?.trim();
+      addAlert('restriction', text, 'class');
+    });
+
+    // 3. Error classes
+    document.querySelectorAll('[class*="error"], [class*="danger"], [class*="invalid"]').forEach(el => {
+      if (!isVisibleForAlert(el)) return;
+      const text = el.textContent?.trim();
+      addAlert('error', text, 'class');
+    });
+
+    // 4. Warning classes
+    document.querySelectorAll('[class*="warning"], [class*="warn"], [class*="caution"]').forEach(el => {
+      if (!isVisibleForAlert(el)) return;
+      const text = el.textContent?.trim();
+      addAlert('warning', text, 'class');
+    });
+
+    // 5. Toast/Snackbar notifications (usually important messages)
+    document.querySelectorAll('[class*="toast"], [class*="snackbar"], [class*="alert-banner"]').forEach(el => {
+      if (!isVisibleForAlert(el)) return;
+      const text = el.textContent?.trim();
+      addAlert('notification', text, 'toast');
+    });
+
+    // 6. SVG icons with warning colors - only for restriction/deactivated contexts
+    const warningColors = ['#FF3B30', '#FAB32F', '#FFCC00', '#FF9500', '#F44336'];
+    document.querySelectorAll('svg').forEach(svg => {
+      const svgHtml = svg.outerHTML.toLowerCase();
+      const hasWarningColor = warningColors.some(c => svgHtml.includes(c.toLowerCase()));
+      if (!hasWarningColor) return;
+
+      // Only consider if parent has restriction-related class or text
+      let parent = svg.parentElement;
+      let attempts = 0;
+      while (parent && attempts < 3) {
+        const className = parent.className?.toLowerCase() || '';
+        const text = parent.textContent?.trim() || '';
+
+        // Check if context suggests restriction/warning
+        const isRestrictionContext =
+          /deactivat|disabled|blocked|restrict|suspend|приостановлен|заблокирован/.test(className + ' ' + text.toLowerCase());
+
+        if (isRestrictionContext && text.length >= MIN_TEXT_LENGTH) {
+          addAlert('restriction', text, 'icon-color');
+          break;
+        }
+        parent = parent.parentElement;
+        attempts++;
+      }
+    });
+
+    // 7. Elements with semantic key/name attributes
+    document.querySelectorAll('[key*="error"], [key*="warning"], [key*="deactivat"], [key*="block"]').forEach(el => {
+      const parent = el.closest('div, span, p');
+      if (parent) {
+        const text = parent.textContent?.trim();
+        addAlert('warning', text, 'semantic-attr');
+      }
+    });
+
+    // Return only if there are meaningful alerts
+    return alerts.length > 0 ? alerts : undefined;
+  }
+
+  /**
+   * Check if element is visible (for alert detection)
+   */
+  function isVisibleForAlert(el) {
+    if (el.offsetWidth === 0 || el.offsetHeight === 0) return false;
+    const style = window.getComputedStyle(el);
+    return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+  }
+
   /**
    * Collect radio and checkbox groups from the tree
    */
@@ -148,6 +270,32 @@ function buildAPOMTree(interactiveOnly = true) {
     return node;
   }
 
+  /**
+   * Filter out null, undefined, and empty string values from object
+   * to reduce JSON output size
+   */
+  function filterNullValues(obj) {
+    if (!obj || typeof obj !== 'object') return obj;
+
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      // Skip null, undefined, and empty strings
+      if (value === null || value === undefined || value === '') continue;
+      // Skip false for boolean fields (keep true)
+      if (value === false) continue;
+      // Recursively filter nested objects (but not arrays)
+      if (typeof value === 'object' && !Array.isArray(value)) {
+        const filtered = filterNullValues(value);
+        if (Object.keys(filtered).length > 0) {
+          result[key] = filtered;
+        }
+      } else {
+        result[key] = value;
+      }
+    }
+    return result;
+  }
+
   /**
    * Check if cursor:pointer is explicitly set (not inherited)
    */
@@ -229,6 +377,23 @@ function buildAPOMTree(interactiveOnly = true) {
     interactiveElements.add(document.body);
   }
 
+  /**
+   * Check if element is in viewport
+   */
+  function isInViewport(el) {
+    const rect = el.getBoundingClientRect();
+    const viewportHeight = window.innerHeight || document.documentElement.clientHeight;
+    const viewportWidth = window.innerWidth || document.documentElement.clientWidth;
+
+    // Element is in viewport if any part of it is visible
+    return (
+      rect.bottom > 0 &&
+      rect.right > 0 &&
+      rect.top < viewportHeight &&
+      rect.left < viewportWidth
+    );
+  }
+
   /**
    * Check if element is visible
    * More reliable check that works with position:fixed elements (Angular Material, etc.)
@@ -248,6 +413,11 @@ function buildAPOMTree(interactiveOnly = true) {
     // For body element, always consider visible if dimensions > 0
     if (el === document.body) return true;
 
+    // Check viewport if viewportOnly mode is enabled
+    if (viewportOnly && !isInViewport(el)) {
+      return false;
+    }
+
     // Additional check: element should be in viewport or have offsetParent
     // This handles elements inside position:fixed containers (Angular Material)
     return el.offsetParent !== null || style.position === 'fixed' || style.position === 'sticky';
@@ -297,19 +467,23 @@ function buildAPOMTree(interactiveOnly = true) {
       node = {
         id,
         tag: element.tagName.toLowerCase(),
-        position,
         type: elementType.type,
         children: []
       };
 
+      // Only include position if not static (position is null for static)
+      if (position) {
+        node.position = position;
+      }
+
       // Add selector only in includeAll mode
       if (!interactiveOnly) {
         node.selector = selector;
       }
 
-      // Add metadata for interactive elements
+      // Add metadata for interactive elements, filtering out null/undefined values
       if (elementType.metadata) {
-        node.metadata = elementType.metadata;
+        node.metadata = filterNullValues(elementType.metadata);
       }
     } else {
       // Containers: compact format "tag_id": [children] when interactiveOnly
@@ -340,8 +514,8 @@ function buildAPOMTree(interactiveOnly = true) {
     if (elementType.type === 'form') {
       result.metadata.formCount++;
     }
-    if (position.type === 'fixed' || position.type === 'absolute') {
-      if (position.zIndex >= 100) {
+    if (position && (position.type === 'fixed' || position.type === 'absolute')) {
+      if (position.zIndex && position.zIndex >= 100) {
         result.metadata.modalCount++;
       }
     }
@@ -365,6 +539,11 @@ function buildAPOMTree(interactiveOnly = true) {
       return compactNode;
     }
 
+    // Remove empty children array to reduce output size
+    if (node.children && node.children.length === 0) {
+      delete node.children;
+    }
+
     return node;
   }
 
@@ -379,37 +558,30 @@ function buildAPOMTree(interactiveOnly = true) {
 
   /**
    * Get positioning information
+   * Returns null for static position (default) to reduce output size
    */
   function getPositionInfo(element) {
     const style = window.getComputedStyle(element);
     const position = style.position;
-    const zIndex = style.zIndex === 'auto' ? 'auto' : parseInt(style.zIndex, 10);
 
-    // Check if creates stacking context
-    const isStacking =
-      position === 'fixed' ||
-      position === 'sticky' ||
-      (position === 'absolute' && zIndex !== 'auto') ||
-      (position === 'relative' && zIndex !== 'auto') ||
-      parseFloat(style.opacity) < 1 ||
-      style.transform !== 'none' ||
-      style.filter !== 'none' ||
-      style.perspective !== 'none' ||
-      style.clipPath !== 'none' ||
-      style.mask !== 'none' ||
-      style.mixBlendMode !== 'normal' ||
-      style.isolation === 'isolate';
+    // Skip static position (default) - no need to include
+    if (position === 'static') {
+      return null;
+    }
 
-    return {
-      type: position,
-      zIndex: zIndex,
-      isStacking: isStacking,
-      // Additional positioning properties for modals/overlays detection
-      hasBackdrop: style.backgroundColor !== 'rgba(0, 0, 0, 0)' &&
-                   (position === 'fixed' || position === 'absolute'),
-      isFullscreen: element.offsetWidth >= window.innerWidth * 0.9 &&
-                    element.offsetHeight >= window.innerHeight * 0.9
+    const zIndex = style.zIndex === 'auto' ? 'auto' : parseInt(style.zIndex, 10);
+
+    // Only include non-default values
+    const result = {
+      type: position
     };
+
+    // Only include zIndex if it's not 'auto'
+    if (zIndex !== 'auto') {
+      result.zIndex = zIndex;
+    }
+
+    return result;
   }
 
   /**
@@ -446,6 +618,83 @@ function buildAPOMTree(interactiveOnly = true) {
     }
   }
 
+  /**
+   * Check if tag is a custom element (Web Component / Framework component)
+   */
+  function isCustomElement(tag) {
+    // Custom elements must contain a hyphen
+    return tag.includes('-');
+  }
+
+  /**
+   * Check if element has explicit click binding (framework attributes or addEventListener)
+   * Uses monkey-patched addEventListener tracker for framework detection (Angular, React, Vue)
+   */
+  function hasExplicitClickBinding(element) {
+    // Check for framework-specific click bindings (attributes)
+    const attrs = element.attributes;
+    for (let i = 0; i < attrs.length; i++) {
+      const name = attrs[i].name.toLowerCase();
+      // Angular: (click), Angular.js: ng-click
+      // Vue: @click, v-on:click
+      // React: onClick (but this is a property, not attribute)
+      if (name === '(click)' || name === 'ng-click' ||
+          name === '@click' || name === 'v-on:click' ||
+          name.startsWith('on') && name.includes('click')) {
+        return true;
+      }
+    }
+    // Check onclick property
+    if (element.onclick) return true;
+    // Check onclick attribute
+    if (element.hasAttribute('onclick')) return true;
+
+    // Check for click listeners added via addEventListener (framework detection)
+    // This is injected by page-manager.js via evaluateOnNewDocument
+    if (typeof window.__hasClickListener === 'function' && window.__hasClickListener(element)) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Find click handler for interactive elements (bubbling search)
+   * Searches UP from element to find ancestor with explicit click binding
+   * Returns "tag:id" format like "div:container_19" or null if not found
+   */
+  function findClickHandler(element) {
+    const tag = element.tagName.toLowerCase();
+
+    // Check self first - native interactive elements handle their own clicks
+    if (hasExplicitClickBinding(element) ||
+        ['button', 'a', 'input', 'select'].includes(tag) ||
+        element.getAttribute('role') === 'button') {
+      return null;  // element handles its own click, no need for clickTarget
+    }
+
+    // Search UP (like event bubbling) - find ancestor with explicit click handler
+    let parent = element.parentElement;
+    let depth = 0;
+    const maxDepth = 5;  // limit to prevent hanging
+
+    while (parent && depth < maxDepth) {
+      if (hasExplicitClickBinding(parent)) {
+        // Found real click handler
+        const parentId = elementIds.get(parent);
+        if (parentId) {
+          const parentTag = parent.tagName.toLowerCase();
+          return `${parentTag}:${parentId}`;
+        }
+      }
+      parent = parent.parentElement;
+      depth++;
+    }
+
+    // No click handler found - return null (no fallback!)
+    return null;
+  }
+
   /**
    * Check if element is interactive based on various signals
    */
@@ -680,12 +929,20 @@ function buildAPOMTree(interactiveOnly = true) {
 
     // Generic container - check for JavaScript interactivity
     const interactivityCheck = checkInteractivity(element);
+
+    // For ALL interactive elements, search for click handler (bubbling)
+    // Returns "tag:id" format or null if not found
+    const clickTarget = interactivityCheck.isInteractive
+      ? findClickHandler(element)
+      : null;
+
     return {
       type: 'container',
       isInteractive: interactivityCheck.isInteractive,
       metadata: interactivityCheck.isInteractive ? {
         text: element.textContent?.trim().substring(0, 100) || '',
-        interactivityReason: interactivityCheck.reason
+        interactivityReason: interactivityCheck.reason,
+        clickTarget: clickTarget || undefined
       } : null
     };
   }
@@ -711,12 +968,17 @@ function buildAPOMTree(interactiveOnly = true) {
     // Try to find stable class name (excluding framework-specific dynamic classes)
     const stableClass = getStableClassName(element);
     if (stableClass) {
-      const classSelector = `.${stableClass}`;
+      const escapedClass = CSS.escape(stableClass);
+      const classSelector = `.${escapedClass}`;
       // Verify it's unique within parent context
       if (element.parentElement) {
-        const matches = element.parentElement.querySelectorAll(classSelector);
-        if (matches.length === 1 && matches[0] === element) {
-          return classSelector;
+        try {
+          const matches = element.parentElement.querySelectorAll(classSelector);
+          if (matches.length === 1 && matches[0] === element) {
+            return classSelector;
+          }
+        } catch (e) {
+          // Invalid selector, continue to path-based approach
         }
       }
     }
@@ -728,10 +990,10 @@ function buildAPOMTree(interactiveOnly = true) {
     while (current && current !== document.body) {
       let selector = current.tagName.toLowerCase();
 
-      // Add stable class if available
+      // Add stable class if available (escaped for CSS selector safety)
       const stableClass = getStableClassName(current);
       if (stableClass) {
-        selector += `.${stableClass}`;
+        selector += `.${CSS.escape(stableClass)}`;
       }
 
       // Add nth-of-type if needed
@@ -754,6 +1016,7 @@ function buildAPOMTree(interactiveOnly = true) {
 
   /**
    * Get stable class name excluding framework-specific dynamic classes
+   * and Tailwind CSS utility classes with special characters
    * Returns first stable class or null
    */
   function getStableClassName(element) {
@@ -763,8 +1026,14 @@ function buildAPOMTree(interactiveOnly = true) {
 
     const classes = element.className.split(/\s+/).filter(c => c);
 
-    // Filter out framework-specific classes
+    // Filter out framework-specific classes and Tailwind utilities
     const stableClasses = classes.filter(className => {
+      // Tailwind CSS: classes with special characters that break CSS selectors
+      // Colons for variants (hover:, focus:, md:, etc.)
+      // Slashes for fractions (w-1/2)
+      // Brackets for arbitrary values (bg-[#1da1f2])
+      if (/[:\/\[\]]/.test(className)) return false;
+
       // React: CSS Modules, Styled Components, Emotion
       if (/^[a-zA-Z0-9_-]+-[a-zA-Z0-9_-]{5,}$/.test(className)) return false;
       if (/^css-[a-z0-9]+(-[a-z0-9]+)?$/i.test(className)) return false;

package/server/tool-definitions.js

@@ -477,7 +477,7 @@ export const toolDefinitions = [
       },
       {
         name: "analyzePage",
-        description: "PRIMARY tool for reading page state. Returns APOM tree: {tree, metadata, groups}. Compact format (default): containers as \"tag_id\":[children] keys, interactive elements as {id, tag, type, position, metadata} without selectors. Use element IDs (e.g., button_45, input_20) with click/type tools. Selectors registered internally for resolution. Use refresh:true after clicks. Efficient: 8-10k tokens vs screenshot 15-25k.",
+        description: "PRIMARY tool for reading page state. Returns APOM tree: {tree, metadata, groups}. Compact format (default): containers as \"tag_id\":[children] keys, interactive elements as {id, tag, type, position, metadata} without selectors. Use element IDs (e.g., button_45, input_20) with click/type tools. Selectors registered internally for resolution. Use refresh:true after clicks. Efficient: 8-10k tokens vs screenshot 15-25k. Legend: clickTarget format is \"tag:id\" (e.g., \"kp-chats-list-item:container_58\") - use the id part for clicking. No clickTarget = element handles its own click.",
         inputSchema: {
           type: "object",
           properties: {
@@ -486,6 +486,8 @@ export const toolDefinitions = [
             useLegacyFormat: { type: "boolean", description: "Return legacy format instead of APOM (default: false - APOM is now default)" },
             registerElements: { type: "boolean", description: "Auto-register elements in selector resolver (default: true)" },
             groupBy: { type: "string", description: "Group elements: 'type' or 'flat' (default: 'type')", enum: ["type", "flat"] },
+            viewportOnly: { type: "boolean", description: "Only analyze elements in current viewport (default: false). Reduces output for long pages." },
+            diff: { type: "boolean", description: "Return only changes since last analysis: {added, removed, changed} (default: false)." },
           },
         },
       },

package/server/tool-schemas.js

@@ -21,6 +21,8 @@ export const ClickSchema = z.object({
   waitAfter: z.number().optional().describe("Milliseconds to wait after click (default: 1500)"),
   screenshot: z.boolean().optional().describe("Capture screenshot after click (default: false for performance)"),
   timeout: z.number().optional().describe("Maximum time to wait for operation in ms (default: 30000)"),
+  skipNetworkWait: z.boolean().optional().describe("Skip waiting for network requests (default: false). Use for forms with long-polling/WebSockets to avoid timeouts."),
+  networkWaitTimeout: z.number().optional().describe("Maximum time to wait for network requests in ms (default: 3000). Only used if skipNetworkWait is false."),
 }).refine(data => (data.id && !data.selector) || (!data.id && data.selector), {
   message: "Either 'id' or 'selector' must be provided, but not both"
 });
@@ -31,6 +33,7 @@ export const TypeSchema = z.object({
   text: z.string().describe("Text to type"),
   delay: z.number().optional().describe("Delay between keystrokes in ms (default: 30)"),
   clearFirst: z.boolean().optional().describe("Clear field before typing (default: true)"),
+  timeout: z.number().optional().describe("Maximum time to wait for operation in ms (default: 30000)"),
 }).refine(data => (data.id && !data.selector) || (!data.id && data.selector), {
   message: "Either 'id' or 'selector' must be provided, but not both"
 });
@@ -260,6 +263,8 @@ export const AnalyzePageSchema = z.object({
   useLegacyFormat: z.boolean().optional().describe("Return legacy format instead of APOM (default: false - APOM is now the default format)"),
   registerElements: z.boolean().optional().describe("Automatically register elements in selector resolver (default: true)"),
   groupBy: z.enum(['type', 'flat']).optional().describe("Group elements by type or return flat structure (default: 'type')"),
+  viewportOnly: z.boolean().optional().describe("Only analyze elements visible in current viewport (default: false). Reduces output for long pages."),
+  diff: z.boolean().optional().describe("Return only changes since last analysis: {added, removed, changed} (default: false). Useful after clicks to see what changed."),
 });
 
 export const GetElementDetailsSchema = z.object({

package/utils/hints-generator.js

@@ -8,6 +8,20 @@
  */
 export function generateNavigationHints(page, url) {
   return page.evaluate(() => {
+    // Helper to get safe class selector (filters Tailwind special chars)
+    function getSafeClassSelector(element) {
+      if (!element.className || typeof element.className !== 'string') return null;
+      const classes = element.className.split(' ')
+        .filter(c => c && !/[:\/\[\]]/.test(c))
+        .slice(0, 1);
+      if (classes.length === 0) return null;
+      try {
+        return `.${CSS.escape(classes[0])}`;
+      } catch (e) {
+        return null;
+      }
+    }
+
     const hints = {
       pageType: 'unknown',
       availableActions: [],
@@ -64,7 +78,7 @@ export function generateNavigationHints(page, url) {
       hints.keyElements.push({
         type: 'primary-button',
         text: mainButton.textContent.trim(),
-        selector: mainButton.id ? `#${mainButton.id}` : `.${mainButton.className.split(' ')[0]}`,
+        selector: mainButton.id ? `#${CSS.escape(mainButton.id)}` : (getSafeClassSelector(mainButton) || 'button'),
       });
     }
 
@@ -74,7 +88,7 @@ export function generateNavigationHints(page, url) {
         hints.keyElements.push({
           type: 'notification',
           text: alert.textContent.trim().substring(0, 100),
-          selector: alert.className ? `.${alert.className.split(' ')[0]}` : 'notification',
+          selector: getSafeClassSelector(alert) || '[role="alert"]',
         });
       }
     });
@@ -91,6 +105,20 @@ export async function generateClickHints(page, selector) {
   await new Promise(resolve => setTimeout(resolve, 100));
 
   return page.evaluate((clickedSelector) => {
+    // Helper to get safe class selector (filters Tailwind special chars)
+    function getSafeClassSelector(element) {
+      if (!element.className || typeof element.className !== 'string') return null;
+      const classes = element.className.split(' ')
+        .filter(c => c && !/[:\/\[\]]/.test(c))
+        .slice(0, 1);
+      if (classes.length === 0) return null;
+      try {
+        return `.${CSS.escape(classes[0])}`;
+      } catch (e) {
+        return null;
+      }
+    }
+
     const hints = {
       pageChanged: false,
       newElements: [],
@@ -105,7 +133,7 @@ export async function generateClickHints(page, selector) {
         hints.modalOpened = true;
         hints.newElements.push({
           type: 'modal',
-          selector: modal.className ? `.${modal.className.split(' ')[0]}` : '[role="dialog"]',
+          selector: getSafeClassSelector(modal) || '[role="dialog"]',
         });
         hints.suggestedNext.push('Interact with modal or close it');
       }
@@ -145,6 +173,20 @@ export async function generateFormSubmitHints(page) {
   await new Promise(resolve => setTimeout(resolve, 500));
 
   return page.evaluate(() => {
+    // Helper to get safe class selector (filters Tailwind special chars)
+    function getSafeClassSelector(element) {
+      if (!element.className || typeof element.className !== 'string') return null;
+      const classes = element.className.split(' ')
+        .filter(c => c && !/[:\/\[\]]/.test(c))
+        .slice(0, 1);
+      if (classes.length === 0) return null;
+      try {
+        return `.${CSS.escape(classes[0])}`;
+      } catch (e) {
+        return null;
+      }
+    }
+
     const hints = {
       success: false,
       errors: [],
@@ -173,7 +215,7 @@ export async function generateFormSubmitHints(page) {
       if (el.offsetWidth > 0) {
         hints.errors.push({
           text: el.textContent.trim().substring(0, 100),
-          selector: el.className ? `.${el.className.split(' ')[0]}` : 'error-element',
+          selector: getSafeClassSelector(el) || '[aria-invalid="true"]',
         });
       }
     });