chrometools-mcp 3.5.5 → 3.5.6

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.5.6] - 2026-05-28
+
+### Added
+- **`analyzePage({ includePortals, portalSelectors })`** — Generic React Portal scan beyond framework modals. Default selectors `['#modal-root', '#menu-popup-root', '#tooltip-root', '#popover-root', '[data-portal]']`, opt-out via `includePortals: false`. Without this, action menus / tooltips / popovers rendered outside `#root` are invisible to APOM
+- **In-tree popup detection** — `analyzePage` now also force-includes Popper/Tippy/FloatingUI-style popups: positioned (absolute/fixed) descendants inside a 0-height inline wrapper. Same opt-out flag (`includePortals`). Covers custom contextMenu implementations that don't use real React Portals
+- **`click({ waitForSelector, waitTimeoutMs })`** — Atomic click + wait. After click, waits for a CSS selector to appear (visible). On timeout the click still succeeds but the result text reports `⚠️ WAIT_TIMEOUT`. Designed for dropdowns/popups that race against the next MCP call
+- **`click({ autoAnalyzeAfter })`** — After click, diffs APOM state and appends `+N appeared: id:"text"` / `-N disappeared` delta. New element ids are pre-registered for follow-up `click`/`type` calls — opens a dropdown and clicks one of its items in two MCP calls instead of three
+- **`screenshot()` viewport mode** — Both `id` and `selector` are now optional; without either, captures the viewport (same compression pipeline as element screenshots)
+- **`executeScript` auto-IIFE** — Snippets starting with `return ...` are now auto-wrapped in `(async () => { ... })()`. Skipped when the snippet declares a `function`, to preserve implicit-return behavior
+
+### Fixed
+- **`ModelRegistry is not defined` after navigation** — Root cause: `quickRegisterElements` (called from `resolveSelector` auto-refresh) didn't inject models code, so `buildAPOMTree` inside it failed with `ReferenceError` when the browser context had been wiped. Models are now always re-injected. If the error still surfaces, it's mapped to a clear `APOM registry stale, call analyzePage()` message instead of leaking the raw ReferenceError
+
 ## [3.5.5] - 2026-03-27
 
 ### Added

package/README.md

@@ -403,7 +403,10 @@ executeScenario({ name: "login_flow", parameters: { email: "user@test.com" } })
   - `refresh` (optional): Force refresh cache to get CURRENT state after changes (default: false)
   - `includeAll` (optional): Include ALL page elements, not just interactive ones (default: false). Useful for layout work - find any element, get its selector, then use `getComputedCss` or `setStyles` on it.
   - `useLegacyFormat` (optional): Return legacy format instead of APOM (default: false - APOM is the default)
-  - `registerElements` (optional): Auto-register elements for ID-based usage (default: true)   - `groupBy` (optional): 'type' or 'flat' - how to group elements (default: 'type') - **Why better than screenshot**:
+  - `registerElements` (optional): Auto-register elements for ID-based usage (default: true)   - `groupBy` (optional): 'type' or 'flat' - how to group elements (default: 'type')
+  - `includePortals` (optional): Include contents of React Portal containers — menus, tooltips, popovers rendered outside the main React root (default: `true`). Without this, items inside dropdown popups (e.g. action menus in MTS-like apps) are invisible to `analyzePage`.
+  - `portalSelectors` (optional): Array of CSS selectors for portal root containers. Default: `['#modal-root', '#menu-popup-root', '#tooltip-root', '#popover-root', '[data-portal]']`. Override when the app uses different portal element ids.
+  - **In-tree popup heuristic**: when `includePortals` is enabled (default), `analyzePage` also detects "in-tree portal" patterns — popups rendered inside a 0-height inline wrapper and absolute-positioned out of it (Popper, Tippy, FloatingUI, custom contextMenu implementations). Without this, popup items live inside an `offsetHeight: 0` wrapper that `isVisible` drops, making the whole popup subtree invisible to `analyzePage`. - **Why better than screenshot**:
   - Shows actual data (form values, validation errors) not just visual
   - Uses 2-5k tokens vs screenshot 5-10k tokens
   - Returns structured data with **unique element IDs** for easy interaction
@@ -514,6 +517,9 @@ Click an element with optional result screenshot. **PREFERRED**: Use APOM ID fro
   - `timeout` (optional): Max operation time in ms (default: 30000)
   - `skipNetworkWait` (optional): Skip waiting for network requests (default: false). **Use for pages with continuous long-polling to get instant response.**
   - `networkWaitTimeout` (optional): Custom network wait timeout in ms (default: 10000). Only used if skipNetworkWait is false.
+  - `waitForSelector` (optional): CSS selector to wait for **after** the click — atomic click+wait. Use for dropdowns/popups that render into a React Portal and otherwise race with the next MCP call. Example: `click({ id: 'button_47', waitForSelector: '#menu-popup-root > div' })`.
+  - `waitTimeoutMs` (optional): Timeout for `waitForSelector` in ms (default: 2000). On timeout the click still succeeds but the result text reports `⚠️ WAIT_TIMEOUT`.
+  - `autoAnalyzeAfter` (optional): After click, automatically diff APOM and append the delta to the result text (e.g. `+3 appeared: button_42:"Статистика", button_43:"Настройки", link_44:"Удалить"`). New element ids are pre-registered so the next `click({ id })`/`type({ id })` call works **without an extra `analyzePage`**. Designed for the dropdown/menu pattern: one MCP call instead of three.
 - **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
@@ -676,10 +682,12 @@ Get precise dimensions, positioning, margins, padding, and borders.
 - **Returns**: Box model data + metrics
 
 #### screenshot
-Capture optimized screenshot of specific element with smart compression and automatic 3 MB limit.
+Capture optimized screenshot of a specific element, or the full viewport when no `id`/`selector` is given. Smart compression with a 3 MB hard limit.
 - **Parameters**:
-  - `selector` (required)
-  - `padding` (optional): Padding in pixels (default: 0)
+  - `id` (optional): APOM element ID from `analyzePage`. Mutually exclusive with `selector`.
+  - `selector` (optional): CSS selector. Mutually exclusive with `id`.
+  - Omit both `id` and `selector` to capture the **full viewport** (no element resolution needed).
+  - `padding` (optional): Padding in pixels (default: 0). Ignored for viewport screenshots.
   - `maxWidth` (optional): Max width for auto-scaling (default: 1024, null for original size)
   - `maxHeight` (optional): Max height for auto-scaling (default: 8000, null for original size)
   - `quality` (optional): JPEG quality 1-100 (default: 40)
@@ -717,6 +725,7 @@ Execute arbitrary JavaScript in page context with optional screenshot.
 - **Use case**: Complex interactions, custom manipulations
 - **Returns**: Execution result + optional screenshot
 - **Performance**: 2-10x faster without screenshot
+- **Top-level `return`**: snippets that start with `return ...` (e.g. `return document.title`) are auto-wrapped in an async IIFE — no need to manually wrap in `(() => { ... })()`. Scripts that declare a `function` are left unmodified so implicit-return patterns keep working.
 
 #### getConsoleLogs
 Retrieve browser console logs (log, warn, error, etc.).

package/index.js

@@ -403,8 +403,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 +446,7 @@ async function executeToolInternal(name, args) {
         if (typeof registerElements !== 'undefined') {
           registerElements(elementsArray);
         }
-      }, apomTreeConverter, selectorResolver);
+      }, apomTreeConverter, selectorResolver, elementModelBase + '\n' + elementModels + '\n' + modelRegistry);
     }
 
     /**
@@ -470,15 +475,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();
@@ -500,13 +546,61 @@ async function executeToolInternal(name, args) {
           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(page);
+        }
+
         // 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
         });
+
+        // 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(page);
+            const postSnap = await getApomSnapshot(page);
+            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
@@ -786,6 +880,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) {
@@ -940,6 +1052,17 @@ async function executeToolInternal(name, args) {
       const page = await getLastOpenPage();
       const timeout = validatedArgs.timeout || 30000;
 
+      // Auto-wrap top-level `return` into an async IIFE: `eval('return X')` is an
+      // Illegal return statement in script context, so users had to wrap manually.
+      // Heuristic: rewrite only when the snippet starts with `return ...` (most common
+      // case from QA reports). Skip when the snippet declares a function — that signals
+      // an explicit user-defined scope and an implicit-return result is likely intended.
+      let scriptToRun = validatedArgs.script;
+      const trimmedHead = scriptToRun.replace(/^\s+/, '');
+      if (/^return[\s;]/.test(trimmedHead) && !/\bfunction\s*[\w*(]/.test(scriptToRun)) {
+        scriptToRun = `(async () => { ${scriptToRun} })()`;
+      }
+
       // Wrap operation in timeout
       const executeOperation = async () => {
         // Use page.evaluate with async support — if eval returns a Promise,
@@ -956,7 +1079,7 @@ async function executeToolInternal(name, args) {
           } catch (error) {
             return { success: false, error: error.message };
           }
-        }, validatedArgs.script);
+        }, scriptToRun);
 
         await new Promise(resolve => setTimeout(resolve, validatedArgs.waitAfter || 500));
 
@@ -2421,7 +2544,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 page.evaluate(async (apomTreeConverterCode, selectorResolverCode, modelsCode, shouldRegister, includeAll, viewportOnly, portalOpts) => {
         // Inject utilities if not already loaded
         if (typeof buildAPOMTree === 'undefined') {
           eval(apomTreeConverterCode);
@@ -2458,7 +2581,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 +2614,10 @@ 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
+      });
 
       // Handle diff mode
       if (validatedArgs.diff) {

package/package.json

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

@@ -37,9 +37,16 @@ function initializeModelRegistry() {
  *
  * @param {boolean} interactiveOnly - Only include interactive elements and their parents
  * @param {boolean} viewportOnly - Only include elements visible in current viewport
+ * @param {Object} portalOpts - Portal scan options: { include: boolean, selectors: string[] }
+ *                              When include=true, force-includes contents of React Portal containers
+ *                              (e.g. #menu-popup-root, #tooltip-root) that live outside main React root.
  * @returns {Object} APOM tree structure
  */
-function buildAPOMTree(interactiveOnly = true, viewportOnly = false) {
+function buildAPOMTree(interactiveOnly = true, viewportOnly = false, portalOpts = undefined) {
+  const portalInclude = portalOpts ? portalOpts.include !== false : true;
+  const portalSelectors = (portalOpts && Array.isArray(portalOpts.selectors) && portalOpts.selectors.length > 0)
+    ? portalOpts.selectors
+    : ['#modal-root', '#menu-popup-root', '#tooltip-root', '#popover-root', '[data-portal]'];
   const pageId = `page_${btoa(window.location.href).replace(/[^a-zA-Z0-9]/g, '').substring(0, 20)}_${Date.now()}`;
 
   // Initialize model registry (Strategy Pattern setup)
@@ -116,6 +123,54 @@ function buildAPOMTree(interactiveOnly = true, viewportOnly = false) {
         forceMarkModalTree(el);
       }
     });
+
+    // Generic portal containers (menus, tooltips, popovers) — opt-in by selector list.
+    // Unlike framework modals, these are app-defined wrappers (e.g. #menu-popup-root from
+    // client/index.html). When non-empty, force-include their subtree.
+    if (portalInclude && portalSelectors.length > 0) {
+      try {
+        document.querySelectorAll(portalSelectors.join(',')).forEach(container => {
+          if (!container.children || container.children.length === 0) return;
+          for (const child of container.children) {
+            if (!modalElements.has(child)) {
+              forceMarkModalTree(child);
+            }
+          }
+        });
+      } catch (e) {
+        // Invalid selector in portalSelectors — skip silently, do not break analyzePage
+      }
+    }
+
+    // In-tree popups (Popper/Tippy/FloatingUI/custom contextMenu pattern). Some libs
+    // render the popup inside a 0-height inline wrapper and then absolute-position it
+    // out of the wrapper's box. Default isVisible() drops the wrapper (height: 0) and
+    // every popup descendant is lost. Detect: a 0×0 wrapper whose subtree contains a
+    // positioned (absolute/fixed) child with real bounds — force-mark that child.
+    if (portalInclude) {
+      function findPositionedPopup(el, maxDepth) {
+        if (maxDepth <= 0) return null;
+        for (const child of el.children) {
+          if (modalElements.has(child)) continue;
+          const cs = window.getComputedStyle(child);
+          if ((cs.position === 'absolute' || cs.position === 'fixed') &&
+              child.offsetWidth > 0 && child.offsetHeight > 0) {
+            return child;
+          }
+          const deeper = findPositionedPopup(child, maxDepth - 1);
+          if (deeper) return deeper;
+        }
+        return null;
+      }
+
+      const allEls = document.body.querySelectorAll('*');
+      for (const el of allEls) {
+        // Only zero-sized wrappers with children are candidates — cheap filter
+        if ((el.offsetHeight !== 0 && el.offsetWidth !== 0) || el.children.length === 0) continue;
+        const popup = findPositionedPopup(el, 3);
+        if (popup) forceMarkModalTree(popup);
+      }
+    }
   }
 
   // Build tree from body

package/server/tool-definitions.js

@@ -37,6 +37,9 @@ export const toolDefinitions = [
             waitAfter: { type: "number", description: "Wait ms (default: 1500)" },
             screenshot: { type: "boolean", description: "Screenshot (default: false)" },
             timeout: { type: "number", description: "Max wait ms (default: 30000)" },
+            waitForSelector: { type: "string", description: "CSS selector to wait for after click (atomic click+wait). Use for dropdowns/popups that render into portals." },
+            waitTimeoutMs: { type: "number", description: "Timeout for waitForSelector in ms (default: 2000)." },
+            autoAnalyzeAfter: { type: "boolean", description: "After click, diff APOM and append '+N appeared: id:\"text\"' delta to result. New ids are pre-registered for follow-up clicks. Use for dropdowns/menus opening with new options." },
           },
         },
       },
@@ -92,18 +95,18 @@ export const toolDefinitions = [
       },
       {
         name: "screenshot",
-        description: "Capture element image (5-10k tokens). Use analyzePage for form data/validation (8-10k tokens).",
+        description: "Capture element image (5-10k tokens), or full viewport when no id/selector is given. Use analyzePage for form data/validation (8-10k tokens).",
         inputSchema: {
           type: "object",
           properties: {
-            selector: { type: "string", description: "CSS selector" },
-            padding: { type: "number", description: "Padding px (default: 0)" },
+            id: { type: "string", description: "APOM element ID. Mutually exclusive with selector. Omit both for viewport screenshot." },
+            selector: { type: "string", description: "CSS selector. Mutually exclusive with id. Omit both for viewport screenshot." },
+            padding: { type: "number", description: "Padding px (default: 0). Ignored for viewport." },
             maxWidth: { type: "number", description: "Max width px (default: 1024, null=original)" },
             maxHeight: { type: "number", description: "Max height px (default: 8000, null=original)" },
             quality: { type: "number", minimum: 1, maximum: 100, description: "JPEG quality (default: 40)" },
             format: { type: "string", enum: ["png", "jpeg", "auto"], description: "Format (default: jpeg)" },
           },
-          required: ["selector"],
         },
       },
       {
@@ -532,6 +535,8 @@ Examples:
             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)." },
+            includePortals: { type: "boolean", description: "Include React Portal contents — menus, tooltips, popovers outside main root (default: true). Without this, dropdown items are invisible." },
+            portalSelectors: { type: "array", items: { type: "string" }, description: "Custom portal root CSS selectors. Default: ['#modal-root', '#menu-popup-root', '#tooltip-root', '#popover-root', '[data-portal]']." },
           },
         },
       },

package/server/tool-schemas.js

@@ -23,6 +23,9 @@ export const ClickSchema = z.object({
   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."),
+  waitForSelector: z.string().optional().describe("CSS selector to wait for after click — atomic click+wait. Useful for dropdowns/popups in portals (e.g. '#menu-popup-root > div') that otherwise race against the next MCP call."),
+  waitTimeoutMs: z.number().optional().describe("Timeout for waitForSelector in ms (default: 2000)."),
+  autoAnalyzeAfter: z.boolean().optional().describe("After click, automatically diff APOM state and append a delta to the result: '+N appeared: id1:\"text\", id2:\"text\"'. New ids are re-registered so callers can use them directly in the next click/type call without an extra analyzePage. Use for dropdowns and menus that reveal new options on click."),
 }).refine(data => (data.id && !data.selector) || (!data.id && data.selector), {
   message: "Either 'id' or 'selector' must be provided, but not both"
 });
@@ -110,15 +113,15 @@ export const SetStylesSchema = z.object({
 
 // Screenshot tools
 export const ScreenshotSchema = z.object({
-  id: z.string().optional().describe("APOM element ID from analyzePage (e.g., 'div_20'). Mutually exclusive with selector."),
-  selector: z.string().optional().describe("CSS selector for element to screenshot. Mutually exclusive with id."),
-  padding: z.number().optional().describe("Padding around element in pixels (default: 0)"),
+  id: z.string().optional().describe("APOM element ID from analyzePage (e.g., 'div_20'). Mutually exclusive with selector. If neither id nor selector is provided, captures full viewport."),
+  selector: z.string().optional().describe("CSS selector for element to screenshot. Mutually exclusive with id. If neither id nor selector is provided, captures full viewport."),
+  padding: z.number().optional().describe("Padding around element in pixels (default: 0). Ignored for viewport screenshot."),
   maxWidth: z.number().nullable().optional().describe("Maximum width in pixels, auto-scales if larger (default: 1024, set to null for original size)"),
   maxHeight: z.number().nullable().optional().describe("Maximum height in pixels, auto-scales if larger (default: 8000 for API limit, set to null for original size)"),
   quality: z.number().min(1).max(100).optional().describe("JPEG quality 1-100 (default: 40)"),
   format: z.enum(['png', 'jpeg', 'auto']).optional().describe("Image format (default: 'jpeg')"),
-}).refine(data => (data.id && !data.selector) || (!data.id && data.selector), {
-  message: "Either 'id' or 'selector' must be provided, but not both"
+}).refine(data => !(data.id && data.selector), {
+  message: "Provide only one of 'id' or 'selector' (or neither for a viewport screenshot)"
 });
 
 export const SaveScreenshotSchema = z.object({
@@ -289,6 +292,8 @@ export const AnalyzePageSchema = z.object({
   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."),
+  includePortals: z.boolean().optional().describe("Include contents of React Portal containers that live outside main React root (default: true). Covers menus, tooltips, popovers rendered via portals — without this, dropdown contents are invisible to analyzePage."),
+  portalSelectors: z.array(z.string()).optional().describe("CSS selectors of portal root containers to scan (default: ['#modal-root', '#menu-popup-root', '#tooltip-root', '#popover-root', '[data-portal]']). Provide custom list when the app uses different portal element ids."),
 });
 
 export const GetElementDetailsSchema = z.object({

package/specs/SEGM-537-UNBLOCKERS_PROGRESS.md

@@ -0,0 +1,94 @@
+# Progress: SEGM-537 QA Unblockers
+
+**Status**: NEEDS APPROVAL
+**Spec**: [SEGM-537-UNBLOCKERS_SPEC.md](./SEGM-537-UNBLOCKERS_SPEC.md)
+**Created**: 2026-05-28
+
+## Phase 0 — Approval & alignment
+
+- [ ] Пользователь одобрил scope (все 5 блокеров)
+- [ ] Пользователь одобрил дизайн API (имена параметров, дефолты)
+- [ ] Дать команду «погнали, начни с Phase 1»
+
+## Phase 1 — Блокер #1: portal scan расширение
+
+- [x] Расширить `pom/apom-tree-converter.js` — добавить `portalSelectors` параметр + третий проход (~120)
+- [x] ~~Переименовать `forceMarkModalTree`~~ — переиспользована as-is, переименование избыточно
+- [x] Прокинуть `includePortals` / `portalSelectors` через `page.evaluate` в `index.js`
+- [x] Обновить `server/tool-schemas.js` + `server/tool-definitions.js` для `analyzePage`
+- [x] `npm run build` — Syntax validation passed
+- [ ] Verification: бенчмарк Google (требует запуска MCP — пользователь должен перезапустить и прогнать)
+- [ ] Verification: ручной тест на QA-стенде (требует доступа QA — отдаём после рестарта MCP)
+- [x] Обновить `README.md` — секция `analyzePage`
+
+## Phase 2 — Блокер #2: click + waitForSelector
+
+- [x] Добавить `waitForSelector` / `waitTimeoutMs` в `executeClickAction` + `click` handler
+- [x] Возвращать `appearedInMs` в результате (или `⚠️ WAIT_TIMEOUT` сообщение)
+- [x] Обновить `server/tool-schemas.js` + `server/tool-definitions.js` для `click`
+- [x] `npm run build` — Syntax validation passed
+- [ ] Verification: на стенде клик «три точки» с `waitForSelector` (требует рестарта MCP)
+- [ ] Verification: несуществующий селектор → таймаут (требует рестарта MCP)
+- [x] Обновить `README.md` — секция `click`
+
+## Phase 3 — Блокер #4: ModelRegistry stale error
+
+- [x] **Root cause fix**: `quickRegisterElements` теперь инжектит models code (раньше не делал → ReferenceError при auto-refresh после navigation)
+- [x] User-friendly fallback: catch на `ReferenceError: ModelRegistry is not defined` в `resolveSelector` → сообщение «APOM registry stale, call analyzePage()»
+- [x] `npm run build` — Syntax validation passed
+- [ ] Verification: воспроизвести (analyzePage → navigate → click) — требует рестарта MCP
+
+## Phase 4 — Блокер #3: screenshot без selector
+
+- [x] Ослабить `.refine` в `ScreenshotSchema` (запрещаем только конфликт, не отсутствие)
+- [x] Без id/selector — viewport screenshot через `processScreenshot`
+- [x] Обновить `server/tool-schemas.js` + `server/tool-definitions.js`
+- [x] `npm run build` — Syntax validation passed
+- [ ] Verification: `screenshot()` без аргументов возвращает viewport — требует рестарта MCP
+- [x] Обновить `README.md` — секция `screenshot`
+
+## Phase 5 — Блокер #5: executeScript auto-IIFE
+
+- [x] Препроцессор скрипта в `executeScript` handler (index.js)
+- [x] Regex: оборачивает только если `^return[\s;]` И код не содержит `function ...`
+- [x] `npm run build` — Syntax validation passed
+- [x] Verification (offline): 5 канонических случаев работают корректно (`return document.title`, `   return 42;`, IIFE, plain expr, `function ... return`)
+- [x] Обновить `README.md` — секция `executeScript`
+
+## Phase 7 — click autoAnalyzeAfter
+
+- [x] Helper `getApomSnapshot(page)` в index.js
+- [x] Pre/post snapshot в click handler с регистрацией новых id через `quickRegisterElements`
+- [x] Дельта `+N appeared: id:"text"` / `-N disappeared` / `No APOM changes` в результате click
+- [x] Schema + tool-definitions + README
+- [x] `npm run build` — passed
+- [x] Verified на стенде: Phase 7 механика работает (snapshots + diff + content append). На SEGM-стенде дельта пустая из-за Phase 8 проблемы (popup не попадает в дерево).
+
+## Phase 8 — In-tree popup detection
+
+Открыт **при e2e-тесте Phase 7**: popup-меню стенда (Popper-style) рендерится внутри 0-height wrapper и не попадает в APOM tree, потому что `isVisible` отбрасывает wrapper.
+
+- [x] Расширение portal-scan в `pom/apom-tree-converter.js` — новый блок после id-portalSelectors
+- [x] `findPositionedPopup(el, depth=3)` — рекурсивный поиск absolute/fixed-positioned child с реальными bounds внутри 0×0 wrapper
+- [x] force-mark найденного popup через существующий `forceMarkModalTree`
+- [x] Используется тот же flag `portalInclude` (default `true`) — opt-out возможен через `includePortals: false`
+- [x] README обновлён
+- [x] `npm run build` — passed
+- [ ] Verification на SEGM-стенде — требует рестарта MCP
+
+## Phase 6 — Финализация сессии
+
+- [ ] Прогон всех verification на реальном QA-стенде SEGM-537 (если доступ есть)
+- [ ] Спросить пользователя: bump version + CHANGELOG entry?
+- [ ] Если YES — single CHANGELOG entry для всей сессии, версия += patch (3.5.4 → 3.5.5)
+- [ ] Отдать QA на повтор сценария из отчёта
+
+## Verification status: per-phase checks
+
+Каждая phase имеет свои verification-шаги выше. Не двигаться к следующей пока текущая не зелёная.
+
+## Открытые вопросы (повторяю из spec)
+
+1. Дефолтные id-портал-селекторы (`#menu-popup-root`, `#modal-root`, `#tooltip-root`, `#popover-root`) — норм или хотите другой набор?
+2. `keepOpen: true` для `click` — пропускаем, делаем только `waitForSelector`. Если QA увидит что попап всё равно закрывается — добавим в Phase 2.5.
+3. Авто-IIFE для `executeScript` — допустимый риск перехвата `return` в случаях, где `return` намеренно внутри функции? Митигируем regex'ом на top-level.