chrometools-mcp 3.5.5 → 3.6.0

package/index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import {Server} from "@modelcontextprotocol/sdk/server/index.js";
 import {StdioServerTransport} from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -37,7 +37,12 @@ import {
     getAllPages,
     switchToPage,
     connectToTabByUrl,
-    getNetworkCDPClient
+    getNetworkCDPClient,
+    getTargetFrame,
+    setActiveFrame,
+    clearActiveFrame,
+    getActiveFrameMatcher,
+    listFramesForPage
 } from './browser/page-manager.js';
 
 // Import image processing utilities
@@ -403,8 +408,13 @@ async function executeToolInternal(name, args) {
      * Quick element registration - runs APOM analysis and registers elements
      */
     async function quickRegisterElements(page) {
-      await page.evaluate((apomTreeConverterCode, selectorResolverCode) => {
-        // Inject utilities
+      await page.evaluate((apomTreeConverterCode, selectorResolverCode, modelsCode) => {
+        // Inject utilities. Models must be loaded BEFORE buildAPOMTree because
+        // initializeModelRegistry() inside it references window.ModelRegistry. After a
+        // navigation the browser window is wiped, so we always re-eval if missing.
+        if (typeof window.ModelRegistry === 'undefined') {
+          eval(modelsCode);
+        }
         if (typeof buildAPOMTree === 'undefined') {
           eval(apomTreeConverterCode);
         }
@@ -441,7 +451,7 @@ async function executeToolInternal(name, args) {
         if (typeof registerElements !== 'undefined') {
           registerElements(elementsArray);
         }
-      }, apomTreeConverter, selectorResolver);
+      }, apomTreeConverter, selectorResolver, elementModelBase + '\n' + elementModels + '\n' + modelRegistry);
     }
 
     /**
@@ -470,15 +480,56 @@ async function executeToolInternal(name, args) {
 
       let resolved = await Promise.race([tryResolve(), timeoutPromise]);
 
-      // Auto-refresh: if looks like APOM ID but not found, re-register elements and retry
+      // Auto-refresh: if looks like APOM ID but not found, re-register elements and retry.
+      // quickRegisterElements re-injects ModelRegistry — if that itself fails (e.g. ReferenceError
+      // from a partially-loaded browser context), surface a clear "call analyzePage" message
+      // instead of leaking the raw browser error.
       if (!resolved.found && isApomIdPattern(identifier)) {
-        await quickRegisterElements(page);
+        try {
+          await quickRegisterElements(page);
+        } catch (e) {
+          if (/ModelRegistry is not defined/.test(String(e?.message || e))) {
+            throw new Error(
+              `APOM registry stale after navigation/reload. Call analyzePage() to refresh element ids before reusing "${identifier}".`
+            );
+          }
+          throw e;
+        }
         resolved = await Promise.race([tryResolve(), timeoutPromise]);
       }
 
       return resolved;
     }
 
+    /**
+     * Snapshot of all APOM ids on the page → { id: { tag, type, text } }
+     * Used by click({ autoAnalyzeAfter: true }) to compute pre/post deltas.
+     */
+    async function getApomSnapshot(page) {
+      return await page.evaluate((apomCode, modelsCode) => {
+        if (typeof window.ModelRegistry === 'undefined') eval(modelsCode);
+        if (typeof buildAPOMTree === 'undefined') eval(apomCode);
+        const apom = buildAPOMTree(true);
+        const map = {};
+        function walk(node) {
+          if (!node || typeof node !== 'object') return;
+          if (node.id) {
+            map[node.id] = {
+              tag: node.tag,
+              type: node.type,
+              text: (node.metadata && node.metadata.text ? String(node.metadata.text).substring(0, 60) : null)
+            };
+          }
+          if (Array.isArray(node.children)) node.children.forEach(walk);
+          for (const k of Object.keys(node)) {
+            if (Array.isArray(node[k])) node[k].forEach(walk);
+          }
+        }
+        walk(apom.tree);
+        return map;
+      }, apomTreeConverter, elementModelBase + '\n' + elementModels + '\n' + modelRegistry);
+    }
+
     if (name === "click") {
       const validatedArgs = schemas.ClickSchema.parse(args);
       const page = await getLastOpenPage();
@@ -489,24 +540,79 @@ async function executeToolInternal(name, args) {
         // Get identifier (id or selector)
         const identifier = validatedArgs.id || validatedArgs.selector;
 
+        // Resolve/query inside the active frame (P0-1). The ElementHandle from
+        // ctx.$() runs in the frame's context, so element.click()/.evaluate()
+        // in executeClickAction operate inside the iframe. Page-level diagnostics
+        // (network/screenshot) stay on `page`.
+        const ctx = await getTargetFrame(page);
+
         // Resolve selector (supports both APOM ID and CSS selector)
-        const resolved = await resolveSelector(page, identifier);
+        const resolved = await resolveSelector(ctx, identifier);
         if (!resolved.found) {
           throw new Error(`Element not found: ${identifier}${resolved.isPageObjectId ? ' (APOM ID)' : ' (CSS selector)'}`);
         }
 
-        const element = await page.$(resolved.selector);
+        const element = await ctx.$(resolved.selector);
         if (!element) {
           throw new Error(`Element not found: ${identifier}`);
         }
 
+        // Pre-click APOM snapshot (only if delta is requested) — captures every id
+        // currently in the tree so we can diff the post-click state.
+        let preSnap = null;
+        if (validatedArgs.autoAnalyzeAfter) {
+          preSnap = await getApomSnapshot(ctx);
+        }
+
         // Use shared click action handler
-        return await executeClickAction(page, element, {
+        const clickResult = await executeClickAction(page, element, {
           identifier,
           screenshot: validatedArgs.screenshot,
           skipNetworkWait: validatedArgs.skipNetworkWait,
-          networkWaitTimeout: validatedArgs.networkWaitTimeout
+          networkWaitTimeout: validatedArgs.networkWaitTimeout,
+          waitForSelector: validatedArgs.waitForSelector,
+          waitTimeoutMs: validatedArgs.waitTimeoutMs,
+          waitForRouteChange: validatedArgs.waitForRouteChange
         });
+
+        // Post-click APOM delta: re-register new ids so callers can immediately
+        // use them in follow-up click/type calls without an extra analyzePage call.
+        if (validatedArgs.autoAnalyzeAfter && preSnap) {
+          try {
+            await quickRegisterElements(ctx);
+            const postSnap = await getApomSnapshot(ctx);
+            const added = Object.keys(postSnap).filter(id => !preSnap[id]);
+            const removed = Object.keys(preSnap).filter(id => !postSnap[id]);
+
+            let deltaText = '\n\n** APOM DELTA **';
+            if (added.length === 0 && removed.length === 0) {
+              deltaText += '\nNo APOM changes detected after click';
+            } else {
+              if (added.length > 0) {
+                const sample = added.slice(0, 15).map(id => {
+                  const m = postSnap[id] || {};
+                  const lab = m.text ? `"${m.text}"` : (m.type || m.tag || '?');
+                  return `${id}:${lab}`;
+                });
+                deltaText += `\n+${added.length} appeared: ${sample.join(', ')}${added.length > 15 ? `, ... (${added.length - 15} more)` : ''}`;
+              }
+              if (removed.length > 0) {
+                deltaText += `\n-${removed.length} disappeared`;
+              }
+            }
+
+            if (clickResult && Array.isArray(clickResult.content) && clickResult.content[0]) {
+              clickResult.content[0].text += deltaText;
+            }
+          } catch (e) {
+            // Delta is best-effort — never let it fail the actual click result
+            if (clickResult && Array.isArray(clickResult.content) && clickResult.content[0]) {
+              clickResult.content[0].text += `\n\n** APOM DELTA ** unavailable (${e.message})`;
+            }
+          }
+        }
+
+        return clickResult;
       };
 
       // Execute with timeout
@@ -527,13 +633,16 @@ async function executeToolInternal(name, args) {
         // Get identifier (id or selector)
         const identifier = validatedArgs.id || validatedArgs.selector;
 
+        // Resolve/query inside the active frame (P0-1)
+        const ctx = await getTargetFrame(page);
+
         // Resolve selector (supports both APOM ID and CSS selector)
-        const resolved = await resolveSelector(page, identifier);
+        const resolved = await resolveSelector(ctx, identifier);
         if (!resolved.found) {
           throw new Error(`Element not found: ${identifier}${resolved.isPageObjectId ? ' (APOM ID)' : ' (CSS selector)'}`);
         }
 
-        const element = await page.$(resolved.selector);
+        const element = await ctx.$(resolved.selector);
         if (!element) {
           throw new Error(`Element not found: ${identifier}`);
         }
@@ -786,6 +895,24 @@ async function executeToolInternal(name, args) {
       // Get identifier (id or selector)
       const identifier = validatedArgs.id || validatedArgs.selector;
 
+      // No identifier → full viewport screenshot. Mirrors processSceenshot pipeline used
+      // by element screenshots so the output (JPEG, scaled, base64) stays consistent.
+      if (!identifier) {
+        const buffer = await page.screenshot({ encoding: 'binary', fullPage: false });
+        const processed = await processScreenshot(buffer, {
+          maxWidth: validatedArgs.maxWidth !== undefined ? validatedArgs.maxWidth : 1024,
+          maxHeight: validatedArgs.maxHeight !== undefined ? validatedArgs.maxHeight : 8000,
+          quality: validatedArgs.quality || 40,
+          format: validatedArgs.format || 'jpeg',
+        });
+        return {
+          content: [
+            { type: 'text', text: 'Viewport screenshot' },
+            { type: 'image', data: processed.buffer.toString('base64'), mimeType: processed.mimeType }
+          ]
+        };
+      }
+
       // Resolve selector (supports both APOM ID and CSS selector)
       const resolved = await resolveSelector(page, identifier);
       if (!resolved.found) {
@@ -872,13 +999,16 @@ async function executeToolInternal(name, args) {
       // Get identifier (id or selector)
       const identifier = validatedArgs.id || validatedArgs.selector;
 
+      // Resolve/query inside the active frame (P0-1)
+      const ctx = await getTargetFrame(page);
+
       // Resolve selector (supports both APOM ID and CSS selector)
-      const resolved = await resolveSelector(page, identifier);
+      const resolved = await resolveSelector(ctx, identifier);
       if (!resolved.found) {
         throw new Error(`Element not found: ${identifier}${resolved.isPageObjectId ? ' (APOM ID)' : ' (CSS selector)'}`);
       }
 
-      const element = await page.$(resolved.selector);
+      const element = await ctx.$(resolved.selector);
       if (!element) {
         throw new Error(`Element not found: ${identifier}`);
       }
@@ -896,17 +1026,20 @@ async function executeToolInternal(name, args) {
       const timeout = validatedArgs.timeout || 5000;
       const waitForVisible = validatedArgs.visible !== false;
 
+      // Wait/query inside the active frame (P0-1)
+      const ctx = await getTargetFrame(page);
+
       try {
         if (waitForVisible) {
           // Wait for element to be visible
-          await page.waitForSelector(validatedArgs.selector, { timeout, visible: true });
+          await ctx.waitForSelector(validatedArgs.selector, { timeout, visible: true });
         } else {
           // Just wait for element to exist in DOM
-          await page.waitForSelector(validatedArgs.selector, { timeout });
+          await ctx.waitForSelector(validatedArgs.selector, { timeout });
         }
 
         // Get info about the element
-        const elementInfo = await page.evaluate((selector) => {
+        const elementInfo = await ctx.evaluate((selector) => {
           const el = document.querySelector(selector);
           if (!el) return null;
 
@@ -940,23 +1073,41 @@ async function executeToolInternal(name, args) {
       const page = await getLastOpenPage();
       const timeout = validatedArgs.timeout || 30000;
 
+      // Run in the active frame (P0-1) — defaults to main frame
+      const ctx = await getTargetFrame(page);
+      const scriptToRun = validatedArgs.script;
+
       // Wrap operation in timeout
       const executeOperation = async () => {
-        // Use page.evaluate with async support — if eval returns a Promise,
-        // await it so async IIFEs work correctly instead of returning {}
-        const result = await page.evaluate(async (code) => {
-          try {
+        // Two-pass eval (P1-4): first run the snippet as-is so bare expressions
+        // (`document.title`) keep returning their value. If that throws an
+        // "Illegal return statement" SyntaxError (top-level `return ...`), retry
+        // wrapped in an async IIFE. Robust, no fragile `^return`/`!function` heuristic.
+        const result = await ctx.evaluate(async (code) => {
+          const runEval = async (src) => {
             // eslint-disable-next-line no-eval
-            let evalResult = eval(code);
+            let evalResult = eval(src);
             // Await promises (async IIFE, fetch, etc.)
             if (evalResult && typeof evalResult === 'object' && typeof evalResult.then === 'function') {
               evalResult = await evalResult;
             }
-            return { success: true, result: evalResult };
+            return evalResult;
+          };
+          try {
+            return { success: true, result: await runEval(code) };
           } catch (error) {
+            const isIllegalReturn = error instanceof SyntaxError &&
+              /return/i.test(error.message) && /illegal|outside|unexpected/i.test(error.message);
+            if (isIllegalReturn) {
+              try {
+                return { success: true, result: await runEval(`(async () => { ${code} })()`) };
+              } catch (wrapErr) {
+                return { success: false, error: wrapErr.message };
+              }
+            }
             return { success: false, error: error.message };
           }
-        }, validatedArgs.script);
+        }, scriptToRun);
 
         await new Promise(resolve => setTimeout(resolve, validatedArgs.waitAfter || 500));
 
@@ -1217,13 +1368,16 @@ async function executeToolInternal(name, args) {
       // Get identifier (id or selector)
       const identifier = validatedArgs.id || validatedArgs.selector;
 
+      // Resolve/query inside the active frame (P0-1)
+      const ctx = await getTargetFrame(page);
+
       // Resolve selector (supports both APOM ID and CSS selector)
-      const resolved = await resolveSelector(page, identifier);
+      const resolved = await resolveSelector(ctx, identifier);
       if (!resolved.found) {
         throw new Error(`Element not found: ${identifier}${resolved.isPageObjectId ? ' (APOM ID)' : ' (CSS selector)'}`);
       }
 
-      const element = await page.$(resolved.selector);
+      const element = await ctx.$(resolved.selector);
       if (!element) {
         throw new Error(`Element not found: ${identifier}`);
       }
@@ -1240,13 +1394,16 @@ async function executeToolInternal(name, args) {
       let element = null;
 
       if (identifier) {
+        // Resolve/query inside the active frame (P0-1)
+        const ctx = await getTargetFrame(page);
+
         // Resolve selector (supports both APOM ID and CSS selector)
-        const resolved = await resolveSelector(page, identifier);
+        const resolved = await resolveSelector(ctx, identifier);
         if (!resolved.found) {
           throw new Error(`Element not found: ${identifier}${resolved.isPageObjectId ? ' (APOM ID)' : ' (CSS selector)'}`);
         }
 
-        element = await page.$(resolved.selector);
+        element = await ctx.$(resolved.selector);
         if (!element) {
           throw new Error(`Element not found: ${identifier}`);
         }
@@ -1267,13 +1424,16 @@ async function executeToolInternal(name, args) {
       // Get identifier (id or selector)
       const identifier = validatedArgs.id || validatedArgs.selector;
 
+      // Resolve/query inside the active frame (P0-1)
+      const ctx = await getTargetFrame(page);
+
       // Resolve selector (supports both APOM ID and CSS selector)
-      const resolved = await resolveSelector(page, identifier);
+      const resolved = await resolveSelector(ctx, identifier);
       if (!resolved.found) {
         throw new Error(`Element not found: ${identifier}${resolved.isPageObjectId ? ' (APOM ID)' : ' (CSS selector)'}`);
       }
 
-      const element = await page.$(resolved.selector);
+      const element = await ctx.$(resolved.selector);
       if (!element) {
         throw new Error(`Element not found: ${identifier}`);
       }
@@ -1649,6 +1809,10 @@ async function executeToolInternal(name, args) {
         await page.goto(validatedArgs.url, { waitUntil: validatedArgs.waitUntil || 'networkidle2' });
       }
 
+      // Top-level navigation invalidates any previously-selected iframe (P0-1).
+      // Reset to main frame so subsequent tools don't target a dead frame.
+      clearActiveFrame(page);
+
       const title = await page.title();
 
       // Run post-navigation diagnostics (same as post-click)
@@ -1688,6 +1852,70 @@ async function executeToolInternal(name, args) {
       };
     }
 
+    if (name === "listFrames") {
+      schemas.ListFramesSchema.parse(args);
+      const page = await getLastOpenPage();
+      const frames = listFramesForPage(page);
+      const matcher = getActiveFrameMatcher(page);
+
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            count: frames.length,
+            activeFrame: matcher || null, // null = main frame
+            frames,
+            hint: frames.length > 1
+              ? 'Use switchFrame({ frameUrl }) to target a child frame (e.g. a cross-origin iframe). switchFrame() with no args resets to main frame.'
+              : 'Only the main frame is present.'
+          }, null, 2)
+        }],
+      };
+    }
+
+    if (name === "switchFrame") {
+      const validatedArgs = schemas.SwitchFrameSchema.parse(args);
+      const page = await getLastOpenPage();
+
+      // No args → reset to main frame
+      if (!validatedArgs.frameUrl && !validatedArgs.frameSelector) {
+        clearActiveFrame(page);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ active: null, message: 'Reset to main frame.' }, null, 2)
+          }],
+        };
+      }
+
+      // Validate the matcher resolves before storing it, so switchFrame fails loudly
+      // instead of every later tool failing.
+      const matcher = validatedArgs.frameSelector
+        ? { frameSelector: validatedArgs.frameSelector }
+        : { frameUrl: validatedArgs.frameUrl };
+      setActiveFrame(page, matcher);
+
+      let frame;
+      try {
+        frame = await getTargetFrame(page);
+      } catch (e) {
+        clearActiveFrame(page); // don't leave a broken active frame set
+        throw e;
+      }
+
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            active: frame.url(),
+            matcher,
+            frames: listFramesForPage(page),
+            message: `Switched to frame: ${frame.url()}. Subsequent click/type/analyzePage/find/executeScript run inside it until switchFrame() resets.`
+          }, null, 2)
+        }],
+      };
+    }
+
     // Figma tools
     if (name === "getFigmaFrame") {
       const validatedArgs = schemas.GetFigmaFrameSchema.parse(args);
@@ -2260,10 +2488,12 @@ Start coding now.`;
     if (name === "smartFindElement") {
       const validatedArgs = schemas.SmartFindElementSchema.parse(args);
       const page = await getLastOpenPage();
+      const ctx = await getTargetFrame(page); // search inside active frame (P0-1)
       const maxResults = validatedArgs.maxResults || 5;
+      const minConfidence = validatedArgs.minConfidence != null ? validatedArgs.minConfidence : 0.6;
 
       // Execute smart search in page context
-      const results = await page.evaluate((description, maxResults, utilsCode, selectorResolverCode) => {
+      const results = await ctx.evaluate((description, maxResults, utilsCode, selectorResolverCode) => {
         // Inject utilities into page context
         eval(utilsCode);
         if (typeof registerElement === 'undefined') {
@@ -2273,25 +2503,38 @@ Start coding now.`;
         // Determine element type from description
         const elementType = determineElementType(description);
 
-        // Build candidate selectors based on element type
-        let candidates = [];
+        // Build candidate selectors based on element type.
+        // Dedup with a Set — broadened selectors overlap (a button can match
+        // several queries) and we don't want the same element scored twice.
+        const candidateSet = new Set();
+        const add = (sel) => { try { document.querySelectorAll(sel).forEach(el => candidateSet.add(el)); } catch (e) {} };
 
         if (elementType.type === 'input' || elementType.type === 'any') {
-          candidates.push(...document.querySelectorAll('input'));
-          candidates.push(...document.querySelectorAll('textarea'));
+          add('input');
+          add('textarea');
         }
 
         if (elementType.type === 'button' || elementType.type === 'any') {
-          candidates.push(...document.querySelectorAll('button'));
-          candidates.push(...document.querySelectorAll('input[type="submit"]'));
-          candidates.push(...document.querySelectorAll('input[type="button"]'));
-          candidates.push(...document.querySelectorAll('[role="button"]'));
+          add('button');
+          add('input[type="submit"]');
+          add('input[type="button"]');
+          add('[role="button"]');
+          // P1-3: broaden to non-semantic clickables that QA hit on real apps —
+          // menu items rendered as div/span[onclick], nav links, tabs.
+          add('[onclick]');
+          add('[role="menuitem"]');
+          add('[role="tab"]');
+          add('nav a');
+          add('[role="navigation"] a');
+          add('[role="menu"] [role="menuitem"]');
         }
 
         if (elementType.type === 'link' || elementType.type === 'any') {
-          candidates.push(...document.querySelectorAll('a'));
+          add('a');
         }
 
+        const candidates = Array.from(candidateSet);
+
         // Analyze each candidate
         const analyzed = candidates.map(el => {
           const context = analyzeButtonContextInPage(el);
@@ -2355,11 +2598,26 @@ Start coding now.`;
         hints
       };
 
-      // Execute action if provided
+      // Execute action if provided — but only when we're confident (P1-3).
+      // Previously results[0] was clicked unconditionally, so a high-scoring form
+      // submit could be auto-clicked when the user asked for something else.
+      // Guard on minConfidence AND a clear gap over the runner-up.
       if (validatedArgs.action && results.length > 0) {
         const bestMatch = results[0];
+        const runnerUp = results[1];
+        const gapOk = !runnerUp || (bestMatch.score - runnerUp.score) >= 10;
+        const confident = bestMatch.confidence >= minConfidence && gapOk;
+
+        if (!confident) {
+          response.actionSkipped = {
+            reason: bestMatch.confidence < minConfidence
+              ? `bestMatch confidence ${bestMatch.confidence.toFixed(2)} < minConfidence ${minConfidence}`
+              : `ambiguous: top-2 score gap (${bestMatch.score - runnerUp.score}) too small`,
+            hint: 'Refine the description, pass an explicit id/selector to click, or lower minConfidence.',
+          };
+        } else {
         try {
-          const actionResult = await executeElementAction(page, bestMatch.selector, validatedArgs.action);
+          const actionResult = await executeElementAction(page, bestMatch.selector, validatedArgs.action, ctx);
           response.actionExecuted = actionResult;
 
           // If screenshot was captured, add it to content
@@ -2374,6 +2632,7 @@ Start coding now.`;
         } catch (error) {
           response.actionError = error.message;
         }
+        }
       }
 
       return {
@@ -2392,10 +2651,14 @@ Start coding now.`;
     if (name === "analyzePage") {
       const validatedArgs = schemas.AnalyzePageSchema.parse(args);
       const page = await getLastOpenPage();
-      const pageUrl = page.url();
+      // Analyze the active frame (P0-1) — defaults to main frame. `frameList` is
+      // surfaced in the output so the agent can discover/switch frames.
+      const ctx = await getTargetFrame(page);
+      const frameList = listFramesForPage(page);
+      const pageUrl = ctx.url() || page.url();
 
       // Check for non-HTML pages (JSON, plain text, XML) — return raw content instead of empty tree
-      const contentType = await page.evaluate(() => document.contentType || '');
+      const contentType = await ctx.evaluate(() => document.contentType || '');
       if (contentType && !contentType.includes('html')) {
         const rawContent = await page.evaluate(() => {
           // For JSON/text pages, browser wraps content in <pre> inside <body>
@@ -2421,7 +2684,7 @@ Start coding now.`;
       }
 
       // APOM Tree format (default) - v2 with tree structure and positioning
-      const apomResult = await page.evaluate(async (apomTreeConverterCode, selectorResolverCode, modelsCode, shouldRegister, includeAll, viewportOnly) => {
+      const apomResult = await ctx.evaluate(async (apomTreeConverterCode, selectorResolverCode, modelsCode, shouldRegister, includeAll, viewportOnly, portalOpts) => {
         // Inject utilities if not already loaded
         if (typeof buildAPOMTree === 'undefined') {
           eval(apomTreeConverterCode);
@@ -2458,7 +2721,7 @@ Start coding now.`;
 
         // Build APOM tree
         // interactiveOnly = !includeAll (if includeAll is true, we want ALL elements)
-        const apomData = buildAPOMTree(!includeAll, viewportOnly);
+        const apomData = buildAPOMTree(!includeAll, viewportOnly, portalOpts);
 
         // Register elements in selector resolver if requested
         if (shouldRegister) {
@@ -2491,7 +2754,17 @@ Start coding now.`;
         }
 
         return apomData;
-      }, apomTreeConverter, selectorResolver, elementModelBase + '\n' + elementModels + '\n' + modelRegistry, validatedArgs.registerElements !== false, validatedArgs.includeAll || false, validatedArgs.viewportOnly || false);
+      }, apomTreeConverter, selectorResolver, elementModelBase + '\n' + elementModels + '\n' + modelRegistry, validatedArgs.registerElements !== false, validatedArgs.includeAll || false, validatedArgs.viewportOnly || false, {
+        include: validatedArgs.includePortals !== false,
+        selectors: validatedArgs.portalSelectors || undefined
+      });
+
+      // Surface frames so the agent can discover/switch into iframes (P0-1).
+      // Only when there's more than the main frame — keeps single-frame output lean.
+      if (frameList.length > 1) {
+        apomResult.frames = frameList;
+        apomResult.activeFrame = ctx === page.mainFrame() ? null : (ctx.url() || true);
+      }
 
       // Handle diff mode
       if (validatedArgs.diff) {
@@ -2515,7 +2788,8 @@ Start coding now.`;
                 previousTimestamp: previousAnalysis.timestamp,
                 diff,
                 metadata: apomResult.metadata,
-                alerts: apomResult.alerts
+                alerts: apomResult.alerts,
+                frames: frameList.length > 1 ? frameList : undefined
               })
             }]
           };
@@ -2763,8 +3037,9 @@ Start coding now.`;
     if (name === "findElementsByText") {
       const validatedArgs = schemas.FindElementsByTextSchema.parse(args);
       const page = await getLastOpenPage();
+      const ctx = await getTargetFrame(page); // search inside active frame (P0-1)
 
-      const elements = await page.evaluate((text, exact, caseSensitive, utilsCode, selectorResolverCode) => {
+      const elements = await ctx.evaluate((text, exact, caseSensitive, utilsCode, selectorResolverCode) => {
         eval(utilsCode);
         if (typeof registerElement === 'undefined') {
           eval(selectorResolverCode);
@@ -2830,11 +3105,14 @@ Start coding now.`;
         truncated: elements.length > 20
       };
 
-      // Execute action if provided and elements found
+      // Execute action if provided and elements found.
+      // Pass `ctx` so the raw selector resolves inside the active frame (P0-1) —
+      // the FIND ran in the frame, so the ACTION must too, otherwise page.$
+      // looks in the main frame and "Element not found for action".
       if (validatedArgs.action && elements.length > 0) {
         const firstMatch = elements[0];
         try {
-          const actionResult = await executeElementAction(page, firstMatch.selector, validatedArgs.action);
+          const actionResult = await executeElementAction(page, firstMatch.selector, validatedArgs.action, ctx);
           response.actionExecuted = actionResult;
 
           // If screenshot was captured, add it to content

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrometools-mcp",
-  "version": "3.5.5",
+  "version": "3.6.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",