chrometools-mcp 3.3.6 → 3.3.8

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.3.8] - 2026-02-03
+
+### Added
+- **analyzePage: addEventListener tracking for Angular/React/Vue** — Monkey-patch detection
+  - Injects tracker via `evaluateOnNewDocument` before page load
+  - Catches `addEventListener('click', ...)` calls from any framework
+  - Solves Angular detection (compiled `(click)` bindings now visible)
+  - WeakMap storage prevents memory leaks
+  - `hasExplicitClickBinding()` now checks `window.__hasClickListener()`
+
+- **analyzePage: viewportOnly flag** — Filter to visible elements only
+  - Reduces output by 30-56% on large pages
+  - Useful for data-heavy pages with content below fold
+
+- **analyzePage: diff mode** — Show only changes since last analysis
+  - Returns `{added, removed, changed}` structure
+  - ~80-90% size reduction for incremental updates
+
+- **analyzePage: clickTarget legend** — Clarified in tool description
+  - Format: `"tag:id"` (e.g., `"div:container_19"`)
+  - No clickTarget = element handles its own click
+
+## [3.3.7] - 2026-02-03
+
+### Performance
+- **analyzePage: 26% output size reduction** — Optimized JSON structure
+  - Removed `position` for static elements (default, no need to include)
+  - Removed `zIndex: "auto"` (default value)
+  - Removed `isStacking`, `hasBackdrop`, `isFullscreen` from position object
+  - Removed empty `children: []` arrays
+  - Filtered out `null`, `undefined`, empty string, and `false` values from metadata
+  - Google Search benchmark: ~38 KB → ~28 KB
+
+### Added
+- **CLAUDE.md: analyzePage benchmark requirement** — Mandatory performance check
+  - Test URL: `https://www.google.com/search?q=puppeteer+mcp+server`
+  - Baseline: ~28 KB, threshold: < 40 KB
+  - Must run after any changes to analyzePage tool
+
+## [3.3.6] - 2026-02-03
+
+### Added
+- **Chrome Extension: POST request tracking** — Track POST requests via webRequest API
+  - Extension now captures POST/PUT/PATCH requests that Puppeteer may miss
+  - Shows in "Browser-level requests (via Extension)" section
+  - Useful for SPA apps with complex async request patterns
+
 ## [3.3.5] - 2026-01-30
 
 ### Fixed

package/browser/page-manager.js

@@ -7,6 +7,59 @@
 import { getBrowser } from './browser-manager.js';
 // Note: injectRecorder removed - now using Chrome Extension for recording
 
+/**
+ * Click listener tracking script - injected via evaluateOnNewDocument
+ * Monkey-patches addEventListener to track which elements have click listeners
+ * This enables detection of click handlers added by frameworks like Angular
+ */
+const CLICK_LISTENER_TRACKER_SCRIPT = `
+(function() {
+  // Only inject once
+  if (window.__clickListenerTracker) return;
+  window.__clickListenerTracker = true;
+
+  // WeakMap to track elements with click listeners (prevents memory leaks)
+  const clickListeners = new WeakMap();
+
+  // Store original methods
+  const originalAddEventListener = EventTarget.prototype.addEventListener;
+  const originalRemoveEventListener = EventTarget.prototype.removeEventListener;
+
+  // Patch addEventListener
+  EventTarget.prototype.addEventListener = function(type, listener, options) {
+    if (type === 'click' && this instanceof Element) {
+      // Track this element has click listener
+      const count = clickListeners.get(this) || 0;
+      clickListeners.set(this, count + 1);
+    }
+    return originalAddEventListener.call(this, type, listener, options);
+  };
+
+  // Patch removeEventListener for accuracy
+  EventTarget.prototype.removeEventListener = function(type, listener, options) {
+    if (type === 'click' && this instanceof Element) {
+      const count = clickListeners.get(this) || 0;
+      if (count > 0) {
+        clickListeners.set(this, count - 1);
+      }
+    }
+    return originalRemoveEventListener.call(this, type, listener, options);
+  };
+
+  // Global function to check if element has click listener
+  window.__hasClickListener = function(element) {
+    if (!element) return false;
+    const count = clickListeners.get(element);
+    return count && count > 0;
+  };
+
+  // Also expose for debugging
+  window.__getClickListenerCount = function(element) {
+    return clickListeners.get(element) || 0;
+  };
+})();
+`;
+
 /**
  * Debug log helper (only logs to stderr when DEBUG=1)
  * @param {...any} args - Arguments to log
@@ -159,6 +212,20 @@ export async function setupNetworkMonitoring(page) {
 
 // Note: setupRecorderAutoReinjection removed - Chrome Extension handles recording now
 
+/**
+ * Inject click listener tracker into page
+ * Must be called BEFORE page.goto() to catch all listeners
+ * @param {Page} page - Puppeteer page instance
+ */
+async function injectClickListenerTracker(page) {
+  try {
+    await page.evaluateOnNewDocument(CLICK_LISTENER_TRACKER_SCRIPT);
+    debugLog('Click listener tracker injected');
+  } catch (error) {
+    debugLog('Failed to inject click listener tracker:', error.message);
+  }
+}
+
 /**
  * Get or create page for URL
  * @param {string} url - URL to navigate to
@@ -180,6 +247,9 @@ export async function getOrCreatePage(url) {
   // Create new page
   const page = await browser.newPage();
 
+  // Inject click listener tracker BEFORE navigation
+  await injectClickListenerTracker(page);
+
   // Set up console log capture
   const client = await page.target().createCDPSession();
   await client.send('Runtime.enable');
@@ -277,6 +347,19 @@ export function setLastPage(page) {
  * @returns {Promise<void>}
  */
 export async function setupNewPage(page, source = 'manual') {
+  // Inject click listener tracker
+  // For new tabs, we need both:
+  // 1. evaluateOnNewDocument for future navigations
+  // 2. evaluate for already-loaded content (won't catch existing listeners, but will catch new ones)
+  try {
+    await page.evaluateOnNewDocument(CLICK_LISTENER_TRACKER_SCRIPT);
+    // Also inject immediately for current page (in case content already loaded)
+    await page.evaluate(CLICK_LISTENER_TRACKER_SCRIPT);
+    debugLog(`Click listener tracker injected for ${source} page`);
+  } catch (error) {
+    debugLog('Failed to inject click listener tracker:', error.message);
+  }
+
   // Set up console log capture
   try {
     const client = await page.target().createCDPSession();

package/index.js

@@ -2212,20 +2212,25 @@ Start coding now.`;
       };
     }
 
+    // Store previous analysis for diff calculation
+    if (!global.previousApomAnalysis) {
+      global.previousApomAnalysis = new Map(); // pageUrl -> analysis data
+    }
+
     if (name === "analyzePage") {
       const validatedArgs = schemas.AnalyzePageSchema.parse(args);
       const page = await getLastOpenPage();
       const pageUrl = page.url();
 
       // APOM Tree format (default) - v2 with tree structure and positioning
-      const apomResult = await page.evaluate((apomTreeConverterCode, selectorResolverCode, shouldRegister, includeAll) => {
+      const apomResult = await page.evaluate((apomTreeConverterCode, selectorResolverCode, shouldRegister, includeAll, viewportOnly) => {
         // Inject utilities
         eval(apomTreeConverterCode);
         eval(selectorResolverCode);
 
         // Build APOM tree
         // interactiveOnly = !includeAll (if includeAll is true, we want ALL elements)
-        const apomData = buildAPOMTree(!includeAll);
+        const apomData = buildAPOMTree(!includeAll, viewportOnly);
 
         // Register elements in selector resolver if requested
         if (shouldRegister) {
@@ -2258,7 +2263,43 @@ Start coding now.`;
         }
 
         return apomData;
-      }, apomTreeConverter, selectorResolver, validatedArgs.registerElements !== false, validatedArgs.includeAll || false);
+      }, apomTreeConverter, selectorResolver, validatedArgs.registerElements !== false, validatedArgs.includeAll || false, validatedArgs.viewportOnly || false);
+
+      // Handle diff mode
+      if (validatedArgs.diff) {
+        const previousAnalysis = global.previousApomAnalysis.get(pageUrl);
+
+        if (previousAnalysis) {
+          // Calculate diff
+          const diff = calculateApomDiff(previousAnalysis, apomResult);
+
+          // Store current analysis for next diff
+          global.previousApomAnalysis.set(pageUrl, apomResult);
+
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                mode: 'diff',
+                pageId: apomResult.pageId,
+                url: apomResult.url,
+                timestamp: apomResult.timestamp,
+                previousTimestamp: previousAnalysis.timestamp,
+                diff,
+                metadata: apomResult.metadata,
+                alerts: apomResult.alerts
+              })
+            }]
+          };
+        } else {
+          // No previous analysis, return full result with note
+          global.previousApomAnalysis.set(pageUrl, apomResult);
+          apomResult._note = 'First analysis for this page, no diff available';
+        }
+      } else {
+        // Store for future diff
+        global.previousApomAnalysis.set(pageUrl, apomResult);
+      }
 
       return {
         content: [{
@@ -2268,6 +2309,82 @@ Start coding now.`;
       };
     }
 
+    /**
+     * Calculate diff between two APOM analyses
+     */
+    function calculateApomDiff(previous, current) {
+      const previousElements = flattenApomTree(previous.tree);
+      const currentElements = flattenApomTree(current.tree);
+
+      const previousIds = new Set(previousElements.map(e => e.id));
+      const currentIds = new Set(currentElements.map(e => e.id));
+
+      const added = currentElements.filter(e => !previousIds.has(e.id));
+      const removed = previousElements.filter(e => !currentIds.has(e.id));
+
+      // Find changed elements (same ID but different content)
+      const changed = [];
+      for (const curr of currentElements) {
+        if (previousIds.has(curr.id)) {
+          const prev = previousElements.find(e => e.id === curr.id);
+          if (prev && JSON.stringify(prev.metadata) !== JSON.stringify(curr.metadata)) {
+            changed.push({
+              id: curr.id,
+              type: curr.type,
+              before: prev.metadata,
+              after: curr.metadata
+            });
+          }
+        }
+      }
+
+      return {
+        added: added.length > 0 ? added : undefined,
+        removed: removed.length > 0 ? removed : undefined,
+        changed: changed.length > 0 ? changed : undefined,
+        summary: {
+          addedCount: added.length,
+          removedCount: removed.length,
+          changedCount: changed.length
+        }
+      };
+    }
+
+    /**
+     * Flatten APOM tree to array of elements
+     */
+    function flattenApomTree(node, result = []) {
+      if (!node) return result;
+
+      // Handle compact format: { "tag_id": [children] }
+      if (typeof node === 'object' && !node.id && !node.tag) {
+        const keys = Object.keys(node);
+        for (const key of keys) {
+          if (Array.isArray(node[key])) {
+            node[key].forEach(child => flattenApomTree(child, result));
+          }
+        }
+        return result;
+      }
+
+      // Interactive element with id
+      if (node.id) {
+        result.push({
+          id: node.id,
+          tag: node.tag,
+          type: node.type,
+          metadata: node.metadata
+        });
+      }
+
+      // Process children
+      if (node.children) {
+        node.children.forEach(child => flattenApomTree(child, result));
+      }
+
+      return result;
+    }
+
     if (name === "getElementDetails") {
       const validatedArgs = schemas.GetElementDetailsSchema.parse(args);
       const page = await getLastOpenPage();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrometools-mcp",
-  "version": "3.3.6",
+  "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
     };
   }

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

@@ -263,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({