chrometools-mcp 3.5.6 → 3.6.0

package/utils/element-actions.js

@@ -20,13 +20,16 @@ async function takeActionScreenshot(page, clip) {
   };
 }
 
-// Helper function to execute actions on elements
-export async function executeElementAction(page, selector, action) {
+// Helper function to execute actions on elements.
+// `frame` (P0-1) is the DOM context used for element resolution/evaluation —
+// pass the active iframe's Frame to act inside it. Defaults to `page` (main frame).
+// Page-level operations (keyboard, screenshot) always use `page`.
+export async function executeElementAction(page, selector, action, frame = page) {
   if (!action || !action.type) {
     return null;
   }
 
-  const element = await page.$(selector);
+  const element = await frame.$(selector);
   if (!element) {
     throw new Error(`Element not found for action: ${selector}`);
   }
@@ -83,7 +86,7 @@ export async function executeElementAction(page, selector, action) {
     case 'scrollTo':
       await element.scrollIntoView({ behavior: 'auto' });
       await new Promise(resolve => setTimeout(resolve, action.waitAfter || 300));
-      const position = await page.evaluate(() => ({
+      const position = await frame.evaluate(() => ({
         x: window.scrollX,
         y: window.scrollY
       }));
@@ -128,7 +131,7 @@ export async function executeElementAction(page, selector, action) {
       for (const style of action.styles) {
         stylesObject[style.name] = style.value;
       }
-      await page.evaluate((sel, styles) => {
+      await frame.evaluate((sel, styles) => {
         const el = document.querySelector(sel);
         if (el) {
           Object.entries(styles).forEach(([key, value]) => {

package/utils/platform-utils.js

@@ -30,6 +30,10 @@ export const isWindows = process.platform === 'win32' || isWSL;
  * @returns {string} - Path to Chrome executable
  */
 export function getChromePath() {
+  // Explicit override wins on every platform
+  if (process.env.CHROMETOOLS_CHROME_PATH) {
+    return process.env.CHROMETOOLS_CHROME_PATH;
+  }
   if (process.platform === 'win32') {
     // Native Windows
     return 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe';
@@ -57,6 +61,17 @@ export function getTempDir() {
 }
 
 /**
- * Chrome remote debugging port
+ * Get the Chrome user-data-dir used when launching a new instance.
+ * Override with CHROMETOOLS_USER_DATA_DIR to point at a real/cloned profile
+ * that already holds the user's login session/cookies.
+ * @returns {string} - Path to Chrome user data directory
+ */
+export function getUserDataDir() {
+  return process.env.CHROMETOOLS_USER_DATA_DIR || `${getTempDir()}/chrome-mcp-profile`;
+}
+
+/**
+ * Chrome remote debugging port.
+ * Override with CHROMETOOLS_DEBUG_PORT (defaults to 9222).
  */
-export const CHROME_DEBUG_PORT = 9222;
+export const CHROME_DEBUG_PORT = parseInt(process.env.CHROMETOOLS_DEBUG_PORT, 10) || 9222;

package/utils/post-click-diagnostics.js

@@ -298,21 +298,38 @@ export function formatDiagnosticsForAI(diagnostics) {
   const netActivity = diagnostics.networkActivity;
   const trackedRequests = netActivity.trackedRequests || [];
 
-  // Show requests detected within 200ms after action
-  if (trackedRequests.length > 0) {
-    output += `\n\n📡 Network requests (${trackedRequests.length}):`;
-    trackedRequests.forEach((req, idx) => {
+  // Show requests detected within 200ms after action.
+  // P1-6: filter to data requests (XHR/Fetch) and drop static assets — a single
+  // SPA navigation pulls dozens of JS chunks/CSS/fonts that drown the signal.
+  // Cap the printed list and summarize the rest.
+  const STATIC_TYPES = new Set(['Script', 'Stylesheet', 'Font', 'Image', 'Media', 'Manifest', 'Other']);
+  const MAX_SHOWN = 12;
+  const dataRequests = trackedRequests.filter(req => {
+    if (!req.type) return true; // no type info → keep (bridge/legacy)
+    return !STATIC_TYPES.has(req.type);
+  });
+  const staticDropped = trackedRequests.length - dataRequests.length;
+
+  if (dataRequests.length > 0) {
+    const shown = dataRequests.slice(0, MAX_SHOWN);
+    output += `\n\n📡 Network requests (XHR/Fetch: ${dataRequests.length}${staticDropped > 0 ? `, ${staticDropped} static asset(s) hidden` : ''}):`;
+    shown.forEach((req, idx) => {
       const statusIcon = req.status === 'pending' ? '⏳' :
                         (req.status === 'completed' || (typeof req.status === 'number' && req.status < 400) ? '✓' : '✗');
       const statusText = req.statusText || req.status || 'pending';
       output += `\n  ${idx + 1}. ${statusIcon} ${req.method} ${req.url}`;
       output += `\n     → Status: ${statusText}`;
     });
+    if (dataRequests.length > MAX_SHOWN) {
+      output += `\n  … ${dataRequests.length - MAX_SHOWN} more`;
+    }
 
     // Show if some requests are still pending after timeout
     if (netActivity.stillPending > 0) {
       output += `\n\n⏳ ${netActivity.stillPending} request(s) still pending after ${Math.round(netActivity.waitedMs)}ms timeout`;
     }
+  } else if (staticDropped > 0) {
+    output += `\n\n📡 No XHR/Fetch requests detected within 200ms (${staticDropped} static asset(s) hidden)`;
   } else {
     output += '\n\n📡 No network requests detected within 200ms';
   }

package/specs/SEGM-537-UNBLOCKERS_PROGRESS.md

@@ -1,94 +0,0 @@
-# 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.

package/specs/SEGM-537-UNBLOCKERS_SPEC.md

@@ -1,187 +0,0 @@
-# Spec: SEGM-537 QA Unblockers
-
-**Status**: DRAFT — waiting for user approval
-**Created**: 2026-05-28
-**Triggered by**: QA-отчёт SEGM-537 (Bulk Creatives Upload) — пять блокеров ChromeTools MCP не дали довести QA до фичи
-
-## Motivation
-
-При прогоне QA SEGM-537 на стенде `selfservice.segmento.mts-corp.ru` ChromeTools MCP заблокировал прогресс на шаге «открыть меню действий → Настройки». QA довёл до этапа 1 из 7 и зафиксировал пять конкретных проблем в инструменте. Фича сама не проверена — нужно разблокировать инструмент.
-
-## Goals
-
-Разблокировать сценарий: открыть React Portal попап (`#menu-popup-root`), дождаться его появления после клика, кликнуть пункт меню, продолжить QA-сценарий. Попутно убрать раздражающие шероховатости (`screenshot` без аргументов, понятная ошибка про устаревший APOM `id`, поведение `executeScript` с top-level `return`).
-
-## Non-goals
-
-- Не переписываем `analyzePage` целиком — расширяем существующую portal-логику в `pom/apom-tree-converter.js:88-115`.
-- Не делаем «универсальный» wait для произвольных DOM-изменений — добавляем только `waitForSelector` как опцию к `click`.
-- Не лезем в код QA-стенда (Замечание #6 из отчёта — про прямые URL `/app/campaign/settings/77130` — не наша зона).
-
----
-
-## Блокер #1 — analyzePage не видит React Portals (menu/tooltip)
-
-### Текущее поведение
-
-`pom/apom-tree-converter.js:88-115` сканирует прямых детей `<body>` по жёсткому списку CSS-классов framework-портал-контейнеров (`ant-modal-root`, `MuiDialog-root`, `mantine-Modal-root` и т.п.) — это про **модальные диалоги**. Меню/dropdown/tooltip-порталы у проектов часто рендерятся в `<div id="menu-popup-root">` / `<div id="tooltip-root">` (см. `client/index.html` стенда SEGM-537) — эти контейнеры детектор пропускает.
-
-### Целевое поведение
-
-`analyzePage` принимает опциональный параметр `includePortals` (default `true`):
-
-```js
-analyzePage({ url?, includePortals?: boolean = true, portalSelectors?: string[] })
-```
-
-- `includePortals: true` — по умолчанию включаем порталы.
-- `portalSelectors` — массив CSS-селекторов (default: `['#modal-root', '#menu-popup-root', '#tooltip-root', '#popover-root', '[data-portal]']`), любые `body > selector` контейнеры force-включаются в APOM tree с compact-форматом, как уже делается для модалок.
-- Существующая логика модалок-фреймворков сохраняется без изменений (не ломаем уже работающий ant/MUI detection).
-
-### Реализация
-
-1. В `pom/apom-tree-converter.js` рядом с `portalPatterns` (~89) добавить `idPortalSelectors` — массив дефолтов, мерж с user-провайдеными.
-2. В пасс «scan body direct children» (~107) добавить второй проход: `document.querySelectorAll(idPortalSelectors.join(','))` → force-include через существующую `forceIncludeModalSubtree()` (или вынести в `forceIncludePortalSubtree`, более широкое имя).
-3. Прокинуть `includePortals` / `portalSelectors` через `page.evaluate` в `index.js:~2400`.
-4. В `tool-schemas.js` добавить два параметра с описанием и дефолтами.
-
-### Verification
-
-- На стенде с открытым меню действий (`document.querySelector('#menu-popup-root').children.length > 0`) `analyzePage` возвращает элементы попапа в дереве.
-- Бенчмарк из CLAUDE.md (Google Search) — размер вывода не вырастает на > 5KB при отсутствии порталов (контейнеры пустые → ничего не добавляется).
-- `findElementsByText` — проверить что на тексте «Настройки» внутри открытого попапа возвращает > 0 (по отчёту QA там может быть отдельный баг, верифицировать).
-
----
-
-## Блокер #2 — атомарный click + ожидание появления попапа
-
-### Текущее поведение
-
-`click({ id })` отправляет `mousePressed` + `mouseReleased` и возвращает управление. Попап-меню часто закрывается по `mousedown` outside (focus-out) при следующем действии MCP, поэтому к моменту `analyzePage`/`executeScript` контента в `#menu-popup-root` уже нет (см. отчёт: `childCount: 0`).
-
-### Целевое поведение
-
-```js
-click({
-  id | selector,
-  waitForSelector?: string,          // дождаться появления селектора после клика
-  waitTimeoutMs?: number = 2000,     // таймаут ожидания
-})
-```
-
-- После `mouseReleased` запускается `page.waitForSelector(waitForSelector, { timeout: waitTimeoutMs, visible: true })`.
-- Возвращает `{ clicked: true, appearedAfter?: 'selector', appearedInMs: number }` либо понятную ошибку `WAIT_TIMEOUT: selector did not appear within Xms after click`.
-- Не двигаем курсор после клика (это уже так, но проверить — отчёт упоминает «фокус-аут» как причину закрытия).
-
-### NOT добавляем
-
-`keepOpen: true` (из отчёта) — не понятно как это реализовать без хака на уровне страницы. Если `waitForSelector` решает проблему — `keepOpen` не нужен. Если QA увидит, что попап всё равно закрывается — вернёмся к вопросу.
-
-### Реализация
-
-1. В `index.js` (`click` handler ~) после `await page.mouse.click(...)` — условное `await page.waitForSelector(opts.waitForSelector, ...)`.
-2. Замерить время `Date.now() - start` для `appearedInMs`.
-3. В `tool-schemas.js` добавить `waitForSelector`, `waitTimeoutMs`.
-
-### Verification
-
-- На стенде кликнуть «три точки» с `waitForSelector: '#menu-popup-root > div'` → попап остаётся открытым, селектор найден.
-- Кликнуть с заведомо несуществующим селектором → понятная ошибка с таймаутом.
-
----
-
-## Блокер #3 — screenshot без selector
-
-### Текущее поведение
-
-```
-Either 'id' or 'selector' must be provided, but not both
-```
-
-Обязателен один из двух параметров.
-
-### Целевое поведение
-
-Оба параметра опциональны. Если ни `id`, ни `selector` не переданы — делается **viewport screenshot** (как `saveScreenshot('viewport')`).
-
-### Реализация
-
-В `index.js` (`screenshot` handler) ослабить валидацию, в дефолтной ветке использовать `page.screenshot({ fullPage: false })` (либо `fullPage: true` если будет отдельный параметр).
-
-### Verification
-
-`screenshot()` без аргументов возвращает viewport-картинку.
-
----
-
-## Блокер #4 — `ModelRegistry is not defined` после навигации
-
-### Текущее поведение
-
-После навигации/перерисовки страницы повторный `click({ id: 'button_47' })` иногда падает с `ModelRegistry is not defined` (browser-side глобал сбрасывается, id из старого `analyzePage` устарел).
-
-### Целевое поведение
-
-`click` (и `executeModelAction`) ловят `ReferenceError: ModelRegistry is not defined` и возвращают понятную ошибку:
-
-```
-APOM registry stale (navigation/reload occurred). Call analyzePage() to refresh element ids.
-```
-
-### Реализация
-
-В `index.js` (action handlers ~672) обернуть `page.evaluate` в try/catch, маппить `ReferenceError` на бизнес-сообщение.
-
-### NOT делаем
-
-Авто-вызов `analyzePage` — потенциально дорого, плюс пользователь может не ожидать перерасчёт состояния.
-
-### Verification
-
-Воспроизвести: `analyzePage` → `navigateTo(другая страница)` → `click({ id: 'button_47' })` → получить новое сообщение, не `ReferenceError`.
-
----
-
-## Блокер #5 — executeScript падает на top-level `return`
-
-### Текущее поведение
-
-```js
-executeScript({ script: 'return 42;' })  // Illegal return statement
-```
-
-Юзеру приходится оборачивать в IIFE: `(() => { return 42; })();`.
-
-### Целевое поведение
-
-Авто-оборачивание: если переданный `script` содержит top-level `return` (regex `/^\s*return\s|;\s*return\s/`), оборачиваем в `(async () => { <script> })()` перед `page.evaluate`.
-
-### Реализация
-
-В `index.js` (`executeScript` handler) — препроцессор кода.
-
-### Verification
-
-- `executeScript({ script: 'return document.title' })` → возвращает title.
-- `executeScript({ script: '(() => { return 42; })()' })` — продолжает работать (уже завёрнут).
-- `executeScript({ script: 'document.title' })` — продолжает работать.
-
----
-
-## Affected files
-
-- `pom/apom-tree-converter.js` — Блокер #1 (portal scan расширение)
-- `index.js` — Блокеры #1, #2, #3, #4, #5 (handler-ы + page.evaluate args)
-- `tool-schemas.js` — Блокеры #1, #2, #3 (новые параметры в JSON Schema)
-- `README.md` — документация новых параметров (обязательно по CLAUDE.md)
-- `CHANGELOG.md` — одна запись в конце сессии (только по запросу пользователя)
-
-## Out of scope / открытые вопросы
-
-1. **#1**: список дефолтных id-портал-селекторов — взят с потолка по практике (`#menu-popup-root` есть у QA-стенда, `#modal-root`/`#tooltip-root`/`#popover-root` — типовые имена). Возможно, стоит сделать без дефолтов и требовать явный массив? Решение: оставить дефолты, чтобы не ломать существующих юзеров.
-2. **#2**: нужен ли `waitForSelector` отдельным параметром или интегрировать в существующий `waitForElement`-pattern? Решение: отдельный параметр для атомарности (одна MCP-вызов вместо двух).
-3. **#5**: авто-IIFE может сломать скрипты, где `return` намеренно внутри функции. Митигируем regex'ом который ищет именно top-level (не внутри `function (){ return }`). Если окажется хрупким — откатимся к документации.
-
-## Verification (end-to-end на QA-стенде)
-
-После реализации QA повторяет сценарий из отчёта начиная с шага 1 плана продолжения. Успех = пройти до шага 7 (загрузка ZIP) без воркараундов через `executeScript`.