chrometools-mcp 3.5.4 → 3.5.6

package/models/ModelRegistry.js

@@ -1,115 +1,115 @@
-/**
- * Model Registry - Strategy Pattern Implementation
- * Manages registration and selection of element models
- */
-
-class ModelRegistry {
-  constructor() {
-    this.models = [];
-    this.modelsMap = null; // Cached models -> actions map
-  }
-
-  /**
-   * Register a model class (not instance)
-   * @param {Class} ModelClass - Element model class
-   */
-  register(ModelClass) {
-    const instance = new ModelClass();
-    this.models.push(instance);
-
-    // Sort by priority (higher first)
-    this.models.sort((a, b) => b.getPriority() - a.getPriority());
-
-    // Invalidate cache
-    this.modelsMap = null;
-  }
-
-  /**
-   * Register multiple models at once
-   * @param {Array<Class>} modelClasses - Array of model classes
-   */
-  registerAll(modelClasses) {
-    for (const ModelClass of modelClasses) {
-      this.register(ModelClass);
-    }
-  }
-
-  /**
-   * Find matching model for element (Strategy Pattern)
-   * @param {HTMLElement} element - DOM element
-   * @param {Object} elementType - Result from determineElementType()
-   * @returns {ElementModel} Matching model instance
-   */
-  findModel(element, elementType) {
-    for (const model of this.models) {
-      if (model.matches(element, elementType)) {
-        return model;
-      }
-    }
-
-    // This should never happen if DefaultModel is registered
-    throw new Error('No matching model found (is DefaultModel registered?)');
-  }
-
-  /**
-   * Get models map for APOM output (cached)
-   * @returns {Object} Map of model names to actions
-   */
-  getModelsMap() {
-    if (this.modelsMap === null) {
-      this.modelsMap = {};
-      for (const model of this.models) {
-        this.modelsMap[model.getName()] = model.getActions();
-      }
-    }
-    return this.modelsMap;
-  }
-
-  /**
-   * Get model by name
-   * @param {string} modelName - Model name
-   * @returns {ElementModel|null} Model instance or null
-   */
-  getModelByName(modelName) {
-    return this.models.find(m => m.getName() === modelName) || null;
-  }
-
-  /**
-   * Get action handler name for element action
-   * @param {HTMLElement} element - Target element
-   * @param {Object} elementType - Element type info
-   * @param {string} actionName - Action to execute
-   * @returns {Object} { handlerName: string, modelName: string } or { error: string }
-   */
-  getActionHandler(element, elementType, actionName) {
-    const model = this.findModel(element, elementType);
-
-    // Check if action is available
-    const actions = model.getActions();
-    if (!actions.includes(actionName)) {
-      return {
-        error: `Action "${actionName}" not available for model "${model.getName()}". Available: ${actions.join(', ')}`
-      };
-    }
-
-    const handlerName = model.getActionHandler(actionName);
-    if (!handlerName) {
-      return {
-        error: `Action "${actionName}" has no handler in model "${model.getName()}"`
-      };
-    }
-
-    return {
-      handlerName,
-      modelName: model.getName()
-    };
-  }
-}
-
-// Export for both Node.js and browser
-if (typeof module !== 'undefined' && module.exports) {
-  module.exports = ModelRegistry;
-}
-if (typeof window !== 'undefined') {
-  window.ModelRegistry = ModelRegistry;
-}
+/**
+ * Model Registry - Strategy Pattern Implementation
+ * Manages registration and selection of element models
+ */
+
+class ModelRegistry {
+  constructor() {
+    this.models = [];
+    this.modelsMap = null; // Cached models -> actions map
+  }
+
+  /**
+   * Register a model class (not instance)
+   * @param {Class} ModelClass - Element model class
+   */
+  register(ModelClass) {
+    const instance = new ModelClass();
+    this.models.push(instance);
+
+    // Sort by priority (higher first)
+    this.models.sort((a, b) => b.getPriority() - a.getPriority());
+
+    // Invalidate cache
+    this.modelsMap = null;
+  }
+
+  /**
+   * Register multiple models at once
+   * @param {Array<Class>} modelClasses - Array of model classes
+   */
+  registerAll(modelClasses) {
+    for (const ModelClass of modelClasses) {
+      this.register(ModelClass);
+    }
+  }
+
+  /**
+   * Find matching model for element (Strategy Pattern)
+   * @param {HTMLElement} element - DOM element
+   * @param {Object} elementType - Result from determineElementType()
+   * @returns {ElementModel} Matching model instance
+   */
+  findModel(element, elementType) {
+    for (const model of this.models) {
+      if (model.matches(element, elementType)) {
+        return model;
+      }
+    }
+
+    // This should never happen if DefaultModel is registered
+    throw new Error('No matching model found (is DefaultModel registered?)');
+  }
+
+  /**
+   * Get models map for APOM output (cached)
+   * @returns {Object} Map of model names to actions
+   */
+  getModelsMap() {
+    if (this.modelsMap === null) {
+      this.modelsMap = {};
+      for (const model of this.models) {
+        this.modelsMap[model.getName()] = model.getActions();
+      }
+    }
+    return this.modelsMap;
+  }
+
+  /**
+   * Get model by name
+   * @param {string} modelName - Model name
+   * @returns {ElementModel|null} Model instance or null
+   */
+  getModelByName(modelName) {
+    return this.models.find(m => m.getName() === modelName) || null;
+  }
+
+  /**
+   * Get action handler name for element action
+   * @param {HTMLElement} element - Target element
+   * @param {Object} elementType - Element type info
+   * @param {string} actionName - Action to execute
+   * @returns {Object} { handlerName: string, modelName: string } or { error: string }
+   */
+  getActionHandler(element, elementType, actionName) {
+    const model = this.findModel(element, elementType);
+
+    // Check if action is available
+    const actions = model.getActions();
+    if (!actions.includes(actionName)) {
+      return {
+        error: `Action "${actionName}" not available for model "${model.getName()}". Available: ${actions.join(', ')}`
+      };
+    }
+
+    const handlerName = model.getActionHandler(actionName);
+    if (!handlerName) {
+      return {
+        error: `Action "${actionName}" has no handler in model "${model.getName()}"`
+      };
+    }
+
+    return {
+      handlerName,
+      modelName: model.getName()
+    };
+  }
+}
+
+// Export for both Node.js and browser
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = ModelRegistry;
+}
+if (typeof window !== 'undefined') {
+  window.ModelRegistry = ModelRegistry;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrometools-mcp",
-  "version": "3.5.4",
+  "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"],
         },
       },
       {
@@ -150,7 +153,7 @@ export const toolDefinitions = [
       },
       {
         name: "executeScript",
-        description: "⚠️ LAST RESORT tool - use ONLY when ALL specialized tools failed. NEVER use for: clicking (use click), typing (use type), reading page (use analyzePage), finding elements (use findElementsByText). May break React/Vue/Angular synthetic events. ALWAYS try specialized tools first.",
+        description: "⚠️ LAST RESORT tool - use ONLY when ALL specialized tools failed. NEVER use for: clicking (use click), typing (use type), scrolling (use scrollTo), reading page elements (use analyzePage), finding elements (use findElementsByText), fetching API data (use listNetworkRequests + getNetworkRequest). May break React/Vue/Angular synthetic events. ALWAYS try specialized tools first.",
         inputSchema: {
           type: "object",
           properties: {
@@ -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.