chrometools-mcp 3.3.9 → 3.4.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.4.0] - 2026-02-08
+
+### Added
+- **Adaptive click strategy with elementFromPoint pre-check** — Before each click, verifies the target element is topmost via `document.elementFromPoint()`. If covered by another element (e.g. small button under `<a routerLink>`), uses DOM dispatch to bypass coordinate hit-testing. Fixes clicks on absolutely-positioned elements over links.
+- **Auth redirect detection** — `navigateTo`, `openBrowser`, and `click` now warn when landing on a login page with returnUrl parameter. Broad login detection: password forms, phone/OTP forms, URL path (`/login`, `/signin`, `/auth`), CSS class matching.
+- **Post-click element detachment detection** — Detects when clicked element is removed from DOM during click (Angular `*ngFor` + Zone.js pattern). Shows actionable hint with app fix (trackBy) and executeScript workaround.
+- **Auth redirect in post-click diagnostics** — `formatDiagnosticsForAI` detects navigation to login pages with returnUrl and shows targeted warning.
+
+### Performance
+- **findElementsByText early exit** — Stops DOM traversal at 40 results, preventing 120s timeout on heavy Angular Material pages with CDK overlay.
+
 ## [3.3.9] - 2026-02-08
 
 ### Added

package/README.md

@@ -500,6 +500,10 @@ Click an element with optional result screenshot. **PREFERRED**: Use APOM ID fro
 - **Use case**: Buttons, links, form submissions, Django admin forms
 - **Returns**: Confirmation text + optional screenshot + network diagnostics
 - **Performance**: 2-10x faster without screenshot, instant with skipNetworkWait
+- **Click strategy**: Three-tier fallback for maximum compatibility:
+  1. Puppeteer native click (trusted CDP events)
+  2. CDP coordinate click at element center (trusted, bypasses interception check)
+  3. JavaScript `element.click()` (untrusted, last resort)
 - **Example**:
   ```javascript
   // PREFERRED: Using APOM ID
@@ -1922,6 +1926,32 @@ npx chrometools-mcp --install-bridge
 - Close and reopen Chrome
 - Check Extension Service Worker console for errors
 
+## Known Limitations
+
+### Angular *ngFor with Dynamic Bindings
+
+In Angular apps using Zone.js, **any** programmatic click (including CDP trusted events) can trigger change detection **between** event listener callbacks. If `*ngFor` iterates over a getter that returns a new array reference each time (e.g., `[options]="getOptions()"`), Angular destroys and recreates all child elements mid-dispatch, causing `@HostListener('click')` on the target element to never fire. Only real hardware mouse events (physical mouse) are immune — CDP events, despite being `isTrusted: true`, are not dispatched through the OS event queue.
+
+ChromeTools **automatically detects** this: after each click, it checks if the target element was removed from DOM. If so, the `ELEMENT DETACHED` hint is shown with a workaround guide.
+
+**App fix** (recommended): add `trackBy` to `*ngFor`, or cache the array reference instead of returning a new one each time.
+
+**Workaround** when app fix is not possible — use `executeScript` to call the Angular component API directly:
+```javascript
+// 1. Find the component instance
+executeScript({ script: `
+  const comp = ng.getComponent(document.querySelector('my-component'));
+  // 2. Explore available events
+  Object.keys(comp).filter(k => k.includes('Event'));
+` })
+
+// 3. Emit the event directly (bypasses DOM click entirely)
+executeScript({ script: `
+  const comp = ng.getComponent(document.querySelector('my-component'));
+  comp.selectedOptionChangeEvent.emit(comp.options.find(o => o.name === 'Delete'));
+` })
+```
+
 ## Architecture
 
 - **Puppeteer** for Chrome automation

package/index.js

@@ -352,6 +352,10 @@ async function executeToolInternal(name, args) {
       if (hints.heading) {
         hintsText += `\nPage heading: "${hints.heading}"`;
       }
+      if (hints.authRedirect) {
+        hintsText += `\n⚠️ AUTH REDIRECT: Page redirected to login (intended: ${hints.authRedirect.returnUrl || 'unknown'})`;
+        hintsText += `\n  → Session/cookies not established. Login first, then retry navigation.`;
+      }
       if (hints.availableActions.length > 0) {
         hintsText += `\nAvailable actions: ${hints.availableActions.join(', ')}`;
       }
@@ -484,23 +488,74 @@ async function executeToolInternal(name, args) {
         // ALWAYS scroll to element first to ensure it's in viewport
         await element.evaluate(el => el.scrollIntoView({ behavior: 'instant', block: 'center' }));
 
-        // Click with timeout to prevent hanging on navigation
+        // Click with adaptive fallback strategy:
+        //
+        // Pre-check: elementFromPoint() determines if element is the topmost at its center.
+        // This decides the click path — Puppeteer's click() doesn't always throw on interception.
+        //
+        // Path A (element covered by another, e.g. small button under <a routerLink>):
+        //   → JS element.click() — DOM dispatch bypasses coordinate hit-testing
+        //
+        // Path B (element is topmost — normal case):
+        //   Tier 1: Puppeteer native click (trusted CDP events)
+        //   Tier 2: page.mouse.click at coordinates (trusted CDP, no interception check)
+        //   Tier 3: JS element.click() (untrusted, last resort)
+        //   Trusted CDP events (Tier 1 & 2) are critical for Angular/Zone.js apps where
+        //   untrusted .click() triggers change detection mid-dispatch, destroying *ngFor elements.
         const clickWithTimeout = async (timeoutMs = 5000) => {
-          const clickPromise = element.click().catch(() => {
-            // If Puppeteer click fails, fallback to JS click
-            return element.evaluate(el => el.click());
-          });
-          const timeoutPromise = new Promise((_, reject) =>
-            setTimeout(() => reject(new Error('click timeout')), timeoutMs)
-          );
-          return Promise.race([clickPromise, timeoutPromise]).catch(() => {
-            // If click times out, try JS click as last resort
-            return element.evaluate(el => el.click());
+          const withTimeout = (promise) => Promise.race([
+            promise,
+            new Promise((_, reject) => setTimeout(() => reject(new Error('click timeout')), timeoutMs))
+          ]);
+
+          // Pre-check: is another element covering our target at its center coordinates?
+          const intercepted = await element.evaluate(el => {
+            const rect = el.getBoundingClientRect();
+            if (rect.width === 0 || rect.height === 0) return false;
+            const cx = rect.left + rect.width / 2;
+            const cy = rect.top + rect.height / 2;
+            const topEl = document.elementFromPoint(cx, cy);
+            // topEl is our element or a child of it — not intercepted
+            return topEl !== el && !el.contains(topEl);
           });
+
+          if (intercepted) {
+            // Path A: Element is covered (e.g., small button under <a routerLink>)
+            // Coordinate clicks would hit the covering element — use DOM dispatch
+            await element.evaluate(el => el.click());
+            return;
+          }
+
+          // Path B: Element is topmost — use trusted CDP events
+          // Tier 1: Puppeteer native click
+          try {
+            await withTimeout(element.click());
+            return;
+          } catch (e) { /* fall through to Tier 2 */ }
+
+          // Tier 2: CDP coordinate click — trusted events, bypasses Puppeteer's own checks
+          try {
+            const box = await element.boundingBox();
+            if (box) {
+              await withTimeout(page.mouse.click(box.x + box.width / 2, box.y + box.height / 2));
+              return;
+            }
+          } catch (e) { /* fall through to Tier 3 */ }
+
+          // Tier 3: JS click — untrusted, last resort
+          await element.evaluate(el => el.click());
         };
 
         await clickWithTimeout();
 
+        // Check if element was detached from DOM during click (Angular *ngFor + Zone.js pattern)
+        let elementDetached = false;
+        try {
+          elementDetached = await element.evaluate(el => !el.parentNode);
+        } catch (e) {
+          // Element handle may be invalid if page navigated — not a detachment issue
+        }
+
         // NEW POST-CLICK PATTERN:
         // 1. Run post-click diagnostics (waits for network requests within 200ms, max 10s timeout)
         let diagnostics;
@@ -556,6 +611,22 @@ async function executeToolInternal(name, args) {
           hintsText += `\nNew elements appeared: ${otherElements.map(e => e.text ? `${e.type}: ${e.text}` : e.type).join(', ')}`;
         }
 
+        // Auth redirect after click (session expired, protected route)
+        if (hints.authRedirect) {
+          hintsText += '\n⚠️ AUTH REDIRECT: Landed on login page. Session may have expired.';
+        }
+
+        // Element detached during click (Angular *ngFor + Zone.js)
+        if (elementDetached) {
+          hintsText += '\n⚠️ ELEMENT DETACHED: Element was removed from DOM during click — handler did NOT fire.';
+          hintsText += '\n   Cause: Angular Zone.js triggers change detection mid-click, *ngFor recreates elements.';
+          hintsText += '\n   App fix: add trackBy to *ngFor, or cache array reference instead of returning new one.';
+          hintsText += '\n   Workaround via executeScript:';
+          hintsText += "\n   1. Find component: ng.getComponent(document.querySelector('component-tag'))";
+          hintsText += "\n   2. Explore API: Object.keys(comp).filter(k => k.includes('Event'))";
+          hintsText += '\n   3. Emit: comp.someChangeEvent.emit(selectedOption)';
+        }
+
         if (hints.suggestedNext.length > 0) {
           hintsText += `\nSuggested next: ${hints.suggestedNext.join('; ')}`;
         }
@@ -1654,6 +1725,10 @@ async function executeToolInternal(name, args) {
       if (hints.heading) {
         hintsText += `\nPage heading: "${hints.heading}"`;
       }
+      if (hints.authRedirect) {
+        hintsText += `\n⚠️ AUTH REDIRECT: Page redirected to login (intended: ${hints.authRedirect.returnUrl || 'unknown'})`;
+        hintsText += `\n  → Session/cookies not established. Login first, then retry navigation.`;
+      }
       if (hints.availableActions.length > 0) {
         hintsText += `\nAvailable actions: ${hints.availableActions.join(', ')}`;
       }
@@ -2696,9 +2771,11 @@ Start coding now.`;
         }
 
         const results = [];
+        const MAX_RESULTS = 40; // Collect up to 40 to allow visible/hidden sorting, cap expensive selector generation
         const searchText = caseSensitive ? text : text.toLowerCase();
 
         document.querySelectorAll('*').forEach(el => {
+          if (results.length >= MAX_RESULTS) return; // Stop expensive selector generation after enough results
           // Skip script, style, etc
           if (['SCRIPT', 'STYLE', 'NOSCRIPT', 'BR', 'HR'].includes(el.tagName)) return;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrometools-mcp",
-  "version": "3.3.9",
+  "version": "3.4.0",
   "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/utils/hints-generator.js

@@ -55,11 +55,28 @@ export async function generateNavigationHints(page, url) {
       }
     }
 
+    // Helper: detect login/auth page (broad detection)
+    function isLoginPage() {
+      // Classic password form
+      if (document.querySelector('form input[type="password"]')) return true;
+      // Phone/OTP login (input[type="tel"] inside a form with few fields)
+      const telInput = document.querySelector('form input[type="tel"]');
+      if (telInput) {
+        const form = telInput.closest('form');
+        if (form && form.querySelectorAll('input:not([type="hidden"])').length <= 3) return true;
+      }
+      // URL-based detection (/login, /signin, /auth in path)
+      if (/\/(login|signin|sign-in|auth|authenticate)(\/|$|\?)/i.test(window.location.pathname)) return true;
+      // Class/ID-based detection
+      if (document.querySelector('[class*="login-form"], [class*="signin-form"], [class*="auth-form"], [id*="login-form"], [id*="signin-form"]')) return true;
+      return false;
+    }
+
     // Detect page type
-    if (document.querySelector('form input[type="password"]')) {
+    if (isLoginPage()) {
       hints.pageType = 'login';
       hints.suggestedNext.push('Fill login credentials and submit');
-      hints.commonSelectors.usernameField = 'input[type="email"], input[name*="user"], input[name*="email"]';
+      hints.commonSelectors.usernameField = 'input[type="email"], input[type="tel"], input[name*="user"], input[name*="email"], input[name*="phone"]';
       hints.commonSelectors.passwordField = 'input[type="password"]';
       hints.commonSelectors.submitButton = 'button[type="submit"], input[type="submit"]';
     } else if (document.querySelector('form') && document.querySelectorAll('form input').length > 3) {
@@ -76,6 +93,18 @@ export async function generateNavigationHints(page, url) {
       hints.suggestedNext.push('Browse items or use filters');
     }
 
+    // Detect auth redirect (landed on login page with returnUrl param)
+    const returnUrlPatterns = ['returnUrl', 'return_url', 'redirect', 'redirect_uri', 'next', 'return_to', 'RelayState'];
+    const urlParams = new URL(window.location.href).searchParams;
+    const returnParam = returnUrlPatterns.find(p => urlParams.has(p));
+    if (hints.pageType === 'login' && returnParam) {
+      hints.authRedirect = {
+        detected: true,
+        returnUrl: urlParams.get(returnParam),
+      };
+      hints.suggestedNext = ['⚠️ Auth redirect detected — complete login first, then navigate to intended page'];
+    }
+
     // Available actions
     const forms = document.querySelectorAll('form');
     if (forms.length > 0) {
@@ -257,6 +286,17 @@ export async function generateClickHints(page, selector) {
       hints.suggestedNext.push(type === 'menu' ? 'Select menu item' : 'Select option from dropdown');
     });
 
+    // Detect auth redirect after click (session expired, protected route)
+    const clickUrl = window.location.href;
+    const isLoginLike = document.querySelector('form input[type="password"]')
+      || (document.querySelector('form input[type="tel"]') && document.querySelectorAll('form input:not([type="hidden"])').length <= 3)
+      || /\/(login|signin|sign-in|auth|authenticate)(\/|$|\?)/i.test(window.location.pathname)
+      || document.querySelector('[class*="login-form"], [class*="signin-form"], [class*="auth-form"]');
+    if (/[?&](returnUrl|return_url|redirect|redirect_uri|next|return_to)=/i.test(clickUrl) && isLoginLike) {
+      hints.authRedirect = true;
+      hints.suggestedNext.push('⚠️ Auth redirect — landed on login page. Session may not be established.');
+    }
+
     return hints;
   }, selector);
 }
@@ -383,10 +423,10 @@ export async function generatePageHints(page) {
     };
 
     // Common patterns
-    const loginForm = document.querySelector('form input[type="password"]');
-    if (loginForm) {
-      const form = loginForm.closest('form');
-      hints.commonPatterns.loginForm = form && form.id ? `#${form.id}` : 'form:has(input[type="password"])';
+    const loginInput = document.querySelector('form input[type="password"]') || document.querySelector('form input[type="tel"]');
+    if (loginInput) {
+      const form = loginInput.closest('form');
+      hints.commonPatterns.loginForm = form && form.id ? `#${form.id}` : 'form';
     }
 
     const searchInput = document.querySelector('input[type="search"], input[placeholder*="search" i]');

package/utils/post-click-diagnostics.js

@@ -278,10 +278,20 @@ export function formatDiagnosticsForAI(diagnostics) {
 
   // Page navigation detection (form submit in non-SPA apps)
   if (diagnostics.navigation) {
-    output += `\n\n🔄 Page navigation detected (form submit):`;
-    output += `\n   From: ${diagnostics.navigation.from}`;
-    output += `\n   To: ${diagnostics.navigation.to}`;
-    output += `\n   → This indicates a successful form POST with page reload`;
+    const to = diagnostics.navigation.to || '';
+    const isAuthRedirect = /login|signin|auth/i.test(to)
+      && /[?&](returnUrl|return_url|redirect|next)/i.test(to);
+    if (isAuthRedirect) {
+      output += `\n\n⚠️ AUTH REDIRECT detected:`;
+      output += `\n   From: ${diagnostics.navigation.from}`;
+      output += `\n   To: ${diagnostics.navigation.to}`;
+      output += `\n   → Session not established. Ensure login completes and cookies are set before navigating to protected routes.`;
+    } else {
+      output += `\n\n🔄 Page navigation detected (form submit):`;
+      output += `\n   From: ${diagnostics.navigation.from}`;
+      output += `\n   To: ${diagnostics.navigation.to}`;
+      output += `\n   → This indicates a successful form POST with page reload`;
+    }
   }
 
   // Network activity - show all tracked requests (GET/POST/PUT/PATCH/DELETE)