chrome-bridge-mcp 1.18.0 → 1.19.0

package/README.md

@@ -180,7 +180,11 @@ paste into a chat.
 | `Port N is held by a process that is not chrome-bridge` | Something else owns the port. Free it or change `CHROME_BRIDGE_PORT`. |
 | `execute_js` fails | Enable **Allow user scripts** in `chrome://extensions` → Chrome Bridge → Details (Chrome 138+; on 135-137 enable Developer Mode). |
 | `read_console` returns `note=Instrumentation not loaded` | The page was opened before the extension, "Capture console & metrics" is off, or the page isn't injectable (`chrome://`). Reload it. |
-| Screenshot times out | On ChromeOS a fully occluded window stops producing frames; captures fail after 10s. Bring the window forward. |
+| Screenshot times out, or `image readback failed` | A minimized or fully covered window stops producing frames; captures fail after 10 s. Bring the window forward. |
+| `wait_for`/`scroll` return `page_hidden: true`, pages stop updating | Same cause: Chrome does not render a hidden page and slows its timers (after a few minutes, to one wake-up per minute). `get_page_info` reports `visibility`. Bring the window on screen, or `create_tab` with `new_window` and bounds. |
+| `screenshot presets` says `NOT APPLIED` | Presets resize the window; they do not emulate a phone (no device pixel ratio, UA or touch). The window manager enforces a minimum width, and no window exceeds the screen (e.g. at most a 1536×686 viewport on a 1536×864 ChromeOS screen). For phone emulation or larger viewports use a headless browser. |
+| `type_text` returns `mismatch: true` | The field rejected the value. Events from an extension have `isTrusted: false`, and some widgets (date pickers, search boxes with tokenizers) discard them. Try `mode: 'keys'`, then the site's own controls (the calendar buttons), or `handoff`. |
+| `[media removed: request limit]` instead of a screenshot | Written by the MCP client, not by the bridge: too many images in one request. Use `save_to`, or `element_screenshot` with `region` and a small `scale`. |
 | Commands work, then stop | The MV3 service worker restarted and in-memory state (network log, diff baselines, HTTP auth) was reset. Re-run the monitoring call. |
 | Extension dropped on every ChromeOS reboot | Install from the Web Store instead of Load unpacked. |
 | Tool missing from the list | It's in an opt-in group. Check `get_status` → `caps_available`, then set `CHROME_BRIDGE_CAPS=all`. |

package/extension/lib/find-text.js

@@ -0,0 +1,97 @@
+/**
+ * findTextInPage gira nella pagina: chrome.scripting ne serializza il
+ * sorgente, quindi è autocontenuta (niente import, niente chiusure).
+ *
+ * Cerca sul testo degli elementi, non dei singoli nodi di testo: un'etichetta
+ * spezzata in più nodi («<span>Prestazioni</span> e <b>clic</b>», o con
+ * &nbsp;) prima non veniva mai trovata, ed è la forma normale dei menu di
+ * Meta. Fra le parole dell'ago vale qualunque sequenza di spazi o &nbsp;.
+ * Ogni occorrenza è riportata una volta, dall'elemento più interno che la
+ * contiene tutta; si entra anche negli shadow root aperti.
+ *
+ * Il costo resta basso sulle pagine grandi: si scende solo nei rami il cui
+ * testo contiene l'ago.
+ */
+export function findTextInPage(needleRaw, caseSensitive, maxResults, doc = document, win = window) {
+  const words = String(needleRaw || '').split(/[\s ]+/).filter(Boolean);
+  if (!words.length) return { count: 0, matches: [] };
+  const pattern = words.map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('[\\s\\u00a0]+');
+  const flags = caseSensitive ? 'g' : 'gi';
+  const SKIP = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE']);
+
+  const textOf = (node) => {
+    if (node.nodeType === 3) return node.textContent || '';
+    if (node.nodeType !== 1 || SKIP.has(node.tagName)) return '';
+    let out = '';
+    for (const c of node.childNodes) out += textOf(c);
+    return out;
+  };
+  const ranges = (text) => {
+    const re = new RegExp(pattern, flags);
+    const out = [];
+    let m;
+    while ((m = re.exec(text))) out.push([m.index, m.index + m[0].length]);
+    return out;
+  };
+  const selectorFor = (el) => {
+    if (el.id) return `#${el.id}`;
+    const tag = el.tagName.toLowerCase();
+    const cls = el.classList && el.classList.length ? `.${[...el.classList].slice(0, 2).join('.')}` : '';
+    return `${tag}${cls}`;
+  };
+
+  const matches = [];
+  const visit = (el, inShadow) => {
+    if (matches.length >= maxResults || SKIP.has(el.tagName)) return;
+    const text = textOf(el);
+    const found = ranges(text);
+    if (!found.length) return;
+    // Intervalli dei figli elemento nel testo di el: textOf concatena i figli
+    // in ordine, quindi gli offset coincidono.
+    const kids = [];
+    let off = 0;
+    for (const c of el.childNodes) {
+      const len = textOf(c).length;
+      if (c.nodeType === 1) kids.push({ el: c, from: off, to: off + len });
+      off += len;
+    }
+    const owned = found.filter(([a, b]) => !kids.some((k) => a >= k.from && b <= k.to));
+    if (owned.length) {
+      const rect = el.getBoundingClientRect();
+      const flat = text.replace(/[\s ]/g, ' ');
+      for (const [a, b] of owned) {
+        if (matches.length >= maxResults) break;
+        matches.push({
+          selector: selectorFor(el),
+          context: flat.substring(Math.max(0, a - 40), b + 40).replace(/ +/g, ' ').trim(),
+          visible: rect.width > 0 && rect.height > 0,
+          position: { x: Math.round(rect.x + win.scrollX), y: Math.round(rect.y + win.scrollY) },
+          ...(inShadow ? { in_shadow: true } : {}),
+        });
+      }
+    }
+    for (const k of kids) {
+      if (found.some(([a, b]) => a >= k.from && b <= k.to)) visit(k.el, inShadow);
+    }
+  };
+
+  // Gli shadow root non compaiono nel testo dell'ospite: si cercano a parte,
+  // anche annidati, dopo il documento.
+  const roots = [];
+  const collectShadows = (root) => {
+    for (const el of root.querySelectorAll('*')) {
+      if (el.shadowRoot) {
+        roots.push(el.shadowRoot);
+        collectShadows(el.shadowRoot);
+      }
+    }
+  };
+  if (doc.body) {
+    visit(doc.body, false);
+    collectShadows(doc.body);
+  }
+  for (const root of roots) {
+    for (const c of root.children) visit(c, true);
+  }
+  return { count: matches.length, matches };
+}

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Chrome Bridge for Claude Code",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Bridge your browser to Claude Code: 59 token-efficient web-dev automation tools over a local WebSocket. ChromeOS included.",
   "homepage_url": "https://github.com/frsorrentino/chrome-bridge",
   "minimum_chrome_version": "135",

package/extension/service-worker.js

@@ -11,6 +11,7 @@ import { pageFingerprint } from './lib/page-fingerprint.js';
 import { createPacer } from './lib/capture-pacing.js';
 import { computeTiles } from './lib/tile-layout.js';
 import { classifyDownload } from './lib/download-state.js';
+import { findTextInPage } from './lib/find-text.js';
 const { pushError } = globalThis.__cbTelemetry;
 
 const DEFAULT_PORT = 8765;
@@ -603,11 +604,60 @@ async function captureVisible(windowId, options = { format: 'png' }) {
     }, 10000);
     chrome.tabs.captureVisibleTab(windowId, options).then(
       (dataUrl) => { clearTimeout(timer); resolve(dataUrl); },
-      (err) => { clearTimeout(timer); reject(err); },
+      (err) => {
+        clearTimeout(timer);
+        // «image readback failed» è lo stesso guasto della finestra che non
+        // disegna, detto dal compositor: stesso messaggio, stesso rimedio.
+        if (/readback failed/i.test(err?.message || '')) {
+          reject(new Error(`Capture failed (${err.message}): the window is not rendering frames (fully occluded, minimized, or frozen). Bring the Chrome window at least partially on screen and retry.`));
+        } else {
+          reject(err);
+        }
+      },
     );
   });
 }
 
+// --- Utility: scadenze tenute dal service worker ---
+// Le attese che girano nella pagina usano setTimeout, e Chrome raggruppa i
+// timer delle pagine nascoste fino a un risveglio al minuto: il controllo
+// della scadenza scattava tardi e vinceva il timeout di trasporto (60 s per
+// un'attesa da 25, osservato su Meta Ads Manager il 23/09/2026). Il service
+// worker non è rallentato: la scadenza la tiene lui.
+const HIDDEN_HINT = 'The page is hidden (window minimized, covered or in the background): Chrome slows its timers and stops rendering. Bring the window on screen, or create_tab new_window with bounds, then retry.';
+
+async function pageHidden(tabId) {
+  try {
+    const q = chrome.scripting.executeScript({ target: { tabId }, func: () => document.visibilityState === 'hidden' });
+    const r = await Promise.race([q, new Promise((res) => setTimeout(() => res(null), 1000))]);
+    return r?.[0]?.result === true;
+  } catch {
+    return false;
+  }
+}
+
+// Esegue run(); se non risponde entro deadlineMs restituisce onTimeout. In
+// entrambi i casi un esito negativo su pagina nascosta porta page_hidden e il
+// suggerimento, così chi chiama non ritenta tre volte la stessa attesa.
+async function withDeadline(tabId, deadlineMs, run, onTimeout, isNegative) {
+  const DEADLINE = Symbol('deadline');
+  let timer;
+  let result;
+  try {
+    result = await Promise.race([
+      run(),
+      new Promise((res) => { timer = setTimeout(() => res(DEADLINE), deadlineMs); }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+  if (result === DEADLINE) result = { ...onTimeout };
+  if (result && isNegative(result) && await pageHidden(tabId)) {
+    return { ...result, page_hidden: true, hint: HIDDEN_HINT };
+  }
+  return result;
+}
+
 // --- Utility: rendi visibile un tab per la cattura SENZA rubare il focus OS ---
 // captureVisibleTab richiede solo che il tab sia attivo nella sua finestra,
 // non che la finestra sia in primo piano. Al termine ripristina il tab che
@@ -1170,7 +1220,14 @@ async function cmdMoveTab({ tab_id, window_id, new_window = false, window_type,
       if (typeof v === 'number') winOpts[k] = v;
     }
     const win = await chrome.windows.create(winOpts);
+    // La finestra nuova può nascere dietro un'altra (lo decide il window
+    // manager): allora la pagina resta hidden e non disegna. Lo si dice qui,
+    // non dopo tre attese scadute.
+    await new Promise((r) => setTimeout(r, 300));
+    const hidden = await pageHidden(tab_id);
     return {
+      visibility: hidden ? 'hidden' : 'visible',
+      ...(hidden ? { hint: HIDDEN_HINT } : {}),
       moved: tab_id,
       url: before.url,
       from_window: before.windowId,
@@ -1344,6 +1401,9 @@ async function cmdGetPageInfo({ tab_id, frame_id }) {
         url: location.href,
         doctype: document.doctype ? document.doctype.name : null,
         charset: document.characterSet,
+        // hidden = finestra minimizzata, coperta o in secondo piano: la pagina
+        // non disegna e i suoi timer rallentano. Va saputo prima di attendere.
+        visibility: document.visibilityState,
         metas,
         scripts,
         stylesheets,
@@ -1754,7 +1814,7 @@ async function cmdWaitForElement({ selector, timeout = 10000, interval = 200, vi
   const tabId = await resolveTabId(tab_id);
   const clampedInterval = Math.max(interval, 50);
 
-  const results = await chrome.scripting.executeScript({
+  const run = () => chrome.scripting.executeScript({
     target: scriptTarget(tabId, frame_id),
     func: (sel, tout, intv, vis) => {
       function deepQuery(sel) {
@@ -1806,8 +1866,9 @@ async function cmdWaitForElement({ selector, timeout = 10000, interval = 200, vi
     },
     args: [selector, timeout, clampedInterval, visible],
     world: 'MAIN',
-  });
-  return results?.[0]?.result ?? { found: false, error: 'No result' };
+  }).then((results) => results?.[0]?.result ?? { found: false, error: 'No result' });
+  return withDeadline(tabId, timeout + 1000, run,
+    { found: false, error: `Element not found within ${timeout}ms: ${selector}` }, (r) => r.found === false);
 }
 
 // --- scroll_to ---
@@ -2058,11 +2119,16 @@ async function cmdViewportResize({ preset, width, height, left, top, state, read
   }
   const winNow = await chrome.windows.get(tab.windowId);
   const geometry = { left: winNow.left, top: winNow.top, width: winNow.width, height: winNow.height, state: winNow.state };
-  if (read_only) return { actual, window: geometry, viewport_error };
+  // Uno zoom sotto il 100% allarga il viewport in CSS px oltre lo schermo:
+  // senza questo numero un 2226 px su uno schermo da 1536 non si spiega.
+  let zoom = null;
+  try { zoom = await chrome.tabs.getZoom(tabId); } catch { /* scheda senza zoom (chrome://) */ }
+  if (read_only) return { actual, window: geometry, zoom, viewport_error };
   const win = winNow;
   return {
     requested: { width: targetW, height: targetH, preset: preset || null, left, top, state },
     actual,
+    zoom,
     viewport_error,
     // Il window manager può accettare e ignorare: senza il confronto una
     // finestra rimasta ferma passerebbe per spostata.
@@ -3536,41 +3602,7 @@ async function cmdFindText({ text, case_sensitive = false, max_results = 20, tab
   const tabId = await resolveTabId(tab_id);
   const results = await chrome.scripting.executeScript({
     target: { tabId },
-    func: (needleRaw, caseSensitive, maxResults) => {
-      const needle = caseSensitive ? needleRaw : needleRaw.toLowerCase();
-      const matches = [];
-      const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, {
-        acceptNode: (n) => {
-          const p = n.parentElement;
-          if (!p || ['SCRIPT', 'STYLE', 'NOSCRIPT'].includes(p.tagName)) return NodeFilter.FILTER_REJECT;
-          return NodeFilter.FILTER_ACCEPT;
-        },
-      });
-      const selectorFor = (el) => {
-        if (el.id) return `#${el.id}`;
-        const tag = el.tagName.toLowerCase();
-        const cls = el.classList.length ? `.${[...el.classList].slice(0, 2).join('.')}` : '';
-        return `${tag}${cls}`;
-      };
-      let node;
-      while ((node = walker.nextNode()) && matches.length < maxResults) {
-        const hay = caseSensitive ? node.textContent : node.textContent.toLowerCase();
-        let idx = hay.indexOf(needle);
-        while (idx !== -1 && matches.length < maxResults) {
-          const parent = node.parentElement;
-          const rect = parent.getBoundingClientRect();
-          const ctx = node.textContent.substring(Math.max(0, idx - 40), idx + needleRaw.length + 40);
-          matches.push({
-            selector: selectorFor(parent),
-            context: ctx.trim(),
-            visible: rect.width > 0 && rect.height > 0,
-            position: { x: Math.round(rect.x + window.scrollX), y: Math.round(rect.y + window.scrollY) },
-          });
-          idx = hay.indexOf(needle, idx + 1);
-        }
-      }
-      return { count: matches.length, matches };
-    },
+    func: findTextInPage,
     args: [text, case_sensitive, max_results],
     world: 'MAIN',
   });
@@ -4448,7 +4480,7 @@ async function cmdWaitForText({ text, selector, timeout = 10000, interval = 200,
   if (!text) throw new Error('Missing required parameter: text');
   const tabId = await resolveTabId(tab_id);
 
-  const results = await chrome.scripting.executeScript({
+  const run = () => chrome.scripting.executeScript({
     target: scriptTarget(tabId, frame_id),
     func: (needle, scopeSel, tout, intv) => new Promise((resolve) => {
       const started = Date.now();
@@ -4477,9 +4509,10 @@ async function cmdWaitForText({ text, selector, timeout = 10000, interval = 200,
     }),
     args: [text, selector || null, timeout, Math.max(50, interval)],
     world: 'MAIN',
-  });
+  }).then((results) => results?.[0]?.result ?? { found: false, error: 'No result' });
 
-  return results?.[0]?.result ?? { found: false, error: 'No result' };
+  return withDeadline(tabId, timeout + 1000, run,
+    { found: false, error: `Text not found within ${timeout}ms: ${text}` }, (r) => r.found === false);
 }
 
 async function cmdSavePage({ tab_id }) {
@@ -4707,52 +4740,92 @@ async function cmdWaitForFunction({ expression, timeout = 10000, polling_ms = 10
 
 // --- scroll_until ---
 
-async function cmdScrollUntil({ until = 'no_new_content', selector, max_scrolls = 20, step_px, settle_ms = 400, tab_id }) {
+async function cmdScrollUntil({ until = 'no_new_content', selector, container, max_scrolls = 20, step_px, settle_ms = 400, tab_id }) {
   const tabId = await resolveTabId(tab_id);
   if (until === 'network_idle') await ensureNetworkHook(tabId);
-  const results = await chrome.scripting.executeScript({
+  const run = () => chrome.scripting.executeScript({
     target: { tabId },
-    func: (mode, sel, maxScrolls, stepPx, settleMs) => new Promise((resolve) => {
+    func: (mode, sel, containerSel, maxScrolls, stepPx, settleMs) => new Promise((resolve) => {
       const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+      const docEl = document.scrollingElement || document.documentElement;
+      const scrollable = (el) => {
+        if (el.scrollHeight <= el.clientHeight + 2) return false;
+        const oy = getComputedStyle(el).overflowY;
+        return oy === 'auto' || oy === 'scroll' || oy === 'overlay';
+      };
+      const describe = (el) => {
+        if (el.id) return `#${el.id}`;
+        const cls = typeof el.className === 'string' && el.className.trim() ? `.${el.className.trim().split(/\s+/).slice(0, 2).join('.')}` : '';
+        return el.tagName.toLowerCase() + cls;
+      };
+      // Le app come Ads Manager bloccano il documento e scorrono in un div
+      // interno: scorrendo solo window la condizione «bottom» era vera al
+      // primo giro. Senza container esplicito si prende il contenitore
+      // scorrevole più grande, ma solo se il documento non scorre.
+      let box = null;
+      if (containerSel) {
+        box = document.querySelector(containerSel);
+        if (!box) { resolve({ stopped_reason: 'error', error: `Container not found: ${containerSel}`, scrolls: 0 }); return; }
+      } else if (docEl.scrollHeight <= innerHeight + 2
+        // overflow hidden su html o body: l'utente non può scorrere il
+        // documento anche se è più alto della finestra (e scrollBy sì).
+        || [document.documentElement, document.body].some((e) => e && getComputedStyle(e).overflowY === 'hidden')) {
+        let best = null;
+        let bestArea = 0;
+        for (const el of document.querySelectorAll('body *')) {
+          if (el.clientHeight < 50 || !scrollable(el)) continue;
+          const area = el.clientWidth * el.clientHeight;
+          if (area > bestArea) { best = el; bestArea = area; }
+        }
+        box = best;
+      }
+      const s = box
+        ? { by: (d) => box.scrollBy(0, d), pos: () => box.scrollTop, height: () => box.scrollHeight, view: () => box.clientHeight, name: describe(box) }
+        : { by: (d) => window.scrollBy(0, d), pos: () => window.scrollY, height: () => docEl.scrollHeight, view: () => innerHeight, name: 'document' };
+      const done = (stopped_reason, scrolls) => resolve({ stopped_reason, scrolls, finalScrollY: Math.round(s.pos()), container: s.name });
       (async () => {
         let scrolls = 0;
-        let lastHeight = document.documentElement.scrollHeight;
+        let lastHeight = s.height();
         let stableCount = 0;
-        const step = stepPx || window.innerHeight;
+        const step = stepPx || s.view();
         for (scrolls = 0; scrolls < maxScrolls; scrolls++) {
           if (mode === 'element' && sel) {
             const el = document.querySelector(sel);
             if (el) {
               const r = el.getBoundingClientRect();
               const vis = r.width > 0 && r.height > 0 && getComputedStyle(el).visibility !== 'hidden';
-              if (vis) { resolve({ stopped_reason: 'element_found', scrolls, finalScrollY: Math.round(window.scrollY) }); return; }
+              if (vis) { done('element_found', scrolls); return; }
             }
           }
-          window.scrollBy(0, step);
+          s.by(step);
           await sleep(settleMs);
 
           if (mode === 'network_idle') {
             const inflight = window.__chromeBridge_inflight || 0;
             const last = window.__chromeBridge_lastNetActivity || Date.now();
-            if (inflight === 0 && Date.now() - last >= settleMs) { resolve({ stopped_reason: 'network_idle', scrolls: scrolls + 1, finalScrollY: Math.round(window.scrollY) }); return; }
+            if (inflight === 0 && Date.now() - last >= settleMs) { done('network_idle', scrolls + 1); return; }
           }
 
-          const h = document.documentElement.scrollHeight;
+          const h = s.height();
           if (h === lastHeight) {
             stableCount++;
-            if (mode === 'no_new_content' && stableCount >= 2) { resolve({ stopped_reason: 'no_new_content', scrolls: scrolls + 1, finalScrollY: Math.round(window.scrollY) }); return; }
+            if (mode === 'no_new_content' && stableCount >= 2) { done('no_new_content', scrolls + 1); return; }
           } else { stableCount = 0; lastHeight = h; }
 
           // bottom reached
-          if (window.innerHeight + window.scrollY >= h - 2) { resolve({ stopped_reason: 'bottom', scrolls: scrolls + 1, finalScrollY: Math.round(window.scrollY) }); return; }
+          if (s.view() + s.pos() >= h - 2) { done('bottom', scrolls + 1); return; }
         }
-        resolve({ stopped_reason: 'max_scrolls', scrolls, finalScrollY: Math.round(window.scrollY) });
+        done('max_scrolls', scrolls);
       })();
     }),
-    args: [until, selector || null, max_scrolls, step_px || null, settle_ms],
+    args: [until, selector || null, container || null, max_scrolls, step_px || null, settle_ms],
     world: 'MAIN',
-  });
-  return results?.[0]?.result ?? { stopped_reason: 'error', scrolls: 0 };
+  }).then((results) => results?.[0]?.result ?? { stopped_reason: 'error', scrolls: 0 });
+  // Stesse sleep in pagina delle attese: su una scheda nascosta rallentano.
+  const deadline = Math.min(55000, max_scrolls * (settle_ms + 250) + 5000);
+  return withDeadline(tabId, deadline, run,
+    { stopped_reason: 'deadline', error: `Scrolling did not finish within ${deadline}ms` },
+    (r) => r.stopped_reason === 'deadline');
 }
 
 // --- Avvia la connessione + registra l'instrumentation ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "chrome-bridge-mcp",
   "mcpName": "io.github.frsorrentino/chrome-bridge",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "type": "module",
   "description": "MCP server with 59 tools for browser automation via Chrome extension. Works on ChromeOS/Crostini.",
   "main": "server/index.js",

package/server/index.js

@@ -64,6 +64,10 @@ async function main() {
       'For more than one field use fill_form once (with submit_selector to submit in the same call) instead of repeated type_text: one turn instead of N.',
       'For tables use extract_table (server-side where/columns filtering) or extract, never read_page: read_page on a big table costs tens of thousands of tokens for data you filter anyway.',
       'To read detail in a screenshot, crop and zoom with element_screenshot (selector or region, scale) instead of taking another full one; to check an outcome, assert or wait_for poll for you — one call, no screenshot.',
+      // Il blocco più frequente sul campo (Meta Ads Manager, 23/09/2026): tre
+      // attese scadute e due screenshot falliti prima di capire che la
+      // finestra era dietro un'altra.
+      'A tab in a minimized, covered or background window does not render: screenshots fail and page timers slow down. get_page_info reports visibility; page_hidden in a result means the same. Bring the window on screen, or create_tab new_window with bounds.',
     ].join(' '),
   });
 

package/server/protocol.js

@@ -92,12 +92,15 @@ export const MessageType = Object.freeze({
 });
 
 // Versione
-export const VERSION               = '1.18.0';
+export const VERSION               = '1.19.0';
 
 // Configurazione
 export const DEFAULT_PORT          = 8765;
 export const COMMAND_TIMEOUT_MS    = 30000;  // 30s per comandi normali
-export const SCREENSHOT_TIMEOUT_MS = 10000;  // 10s per screenshot
+// Più del timer interno di captureVisible (10 s, dopo il pacer da 520 ms):
+// a parità vinceva il trasporto col messaggio generico «the tab may be busy»,
+// e quello utile («the window is not rendering frames») non arrivava mai.
+export const SCREENSHOT_TIMEOUT_MS = 15000;
 export const PING_INTERVAL_MS      = 15000;  // 15s heartbeat
 export const IDENT_TIMEOUT_MS      = 5000;   // tempo max per identificarsi
 export const PENDING_RELAY_TTL_MS  = 150000; // deve superare il timeout comando più lungo (120s full_page_screenshot)

package/server/tools.js

@@ -472,17 +472,73 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
     }
   };
 
-  // Mappa ref → selector per tab, popolata da get_interactives.
-  // Permette click/type_text/hover per ref (n1, n2…) senza ripetere selettori lunghi.
+  // Registro ref → selector per tab, popolato da get_interactives, dalla
+  // preview di navigate e dai vicini di find_text. Permette click/type_text/
+  // hover per ref (n1, n2…) senza ripetere selettori lunghi.
+  // Un selettore tiene lo stesso ref finché la pagina non cambia, e un numero
+  // non viene mai riassegnato: prima ogni chiamata di scoperta ripartiva da n1
+  // sulla stessa mappa, e dopo un find_text n3 indicava un altro elemento —
+  // il click andava a segno sull'elemento sbagliato senza errori.
   const interactivesRefs = new Map();
+  const REFS_MAX = 2000;
 
   const refsKey = (tab_id) => tab_id ?? sessionTabId ?? 'active';
 
+  function refRegistry(tab_id) {
+    const key = refsKey(tab_id);
+    let reg = interactivesRefs.get(key);
+    if (!reg) {
+      reg = { next: 1, floor: 1, bySel: new Map(), byRef: new Map() };
+      interactivesRefs.set(key, reg);
+    }
+    return reg;
+  }
+
+  // Assegna i ref agli elementi (in place). Solo gli elementi con selector
+  // ricevono un ref: senza, non ci sarebbe nulla da risolvere.
+  function assignRefs(tab_id, elements) {
+    const reg = refRegistry(tab_id);
+    for (const e of elements) {
+      if (!e.selector) continue;
+      let ref = reg.bySel.get(e.selector);
+      if (!ref) {
+        ref = `n${reg.next++}`;
+        reg.bySel.set(e.selector, ref);
+        reg.byRef.set(ref, e.selector);
+      }
+      e.ref = ref;
+    }
+    while (reg.byRef.size > REFS_MAX) {
+      const [oldRef, oldSel] = reg.byRef.entries().next().value;
+      reg.byRef.delete(oldRef);
+      reg.bySel.delete(oldSel);
+    }
+    return reg.byRef.size;
+  }
+
+  // Una navigazione cambia pagina: i selettori vecchi potrebbero trovare altro.
+  // La mappa si svuota ma il contatore no, così un ref vecchio dà errore
+  // invece di indicare un elemento nuovo con lo stesso numero.
+  function resetRefs(tab_id) {
+    const reg = refRegistry(tab_id);
+    reg.bySel.clear();
+    reg.byRef.clear();
+    reg.floor = reg.next;
+  }
+
   function resolveTarget(selector, ref, tab_id) {
     if (selector) return selector;
     if (ref) {
-      const sel = interactivesRefs.get(refsKey(tab_id))?.get(ref);
-      if (!sel) throw new Error(`Unknown ref ${ref} — run get_interactives first`);
+      const reg = interactivesRefs.get(refsKey(tab_id));
+      const sel = reg?.byRef.get(ref);
+      if (!sel) {
+        const num = Number(String(ref).replace(/^n/, ''));
+        const why = !reg || reg.next === 1 ? 'no refs issued for this tab yet'
+          : num >= reg.next ? `refs issued so far go up to n${reg.next - 1}`
+            : num < reg.floor ? 'it was issued before the last navigate, which resets refs'
+              : 'it was evicted from the ref cache';
+        throw new Error(`Unknown ref ${ref} (${why}) — run get_interactives or find_text again`);
+      }
       return sel;
     }
     throw new Error('Either selector or ref is required');
@@ -517,13 +573,9 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
   async function interactivesPreview(tab_id, limit = 12) {
     try {
       const data = await send(MessageType.GET_INTERACTIVES, { limit, visible_only: true, tab_id });
-      const refMap = new Map();
-      (data?.elements ?? []).forEach((e, i) => {
-        e.ref = `n${i + 1}`;
-        if (e.selector) refMap.set(e.ref, e.selector);
-      });
-      interactivesRefs.set(refsKey(tab_id), refMap);
-      return refMap.size ? truncateText(interactivesLines(data), 1500) : null;
+      const elements = data?.elements ?? [];
+      assignRefs(tab_id, elements);
+      return elements.some((e) => e.ref) ? truncateText(interactivesLines(data), 1500) : null;
     } catch { return null; }
   }
 
@@ -612,6 +664,7 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
       const data = await send(MessageType.NAVIGATE, { url, tab_id });
       // Il tab navigato diventa il default di sessione per i comandi successivi
       if (data?.tabId != null) sessionTabId = data.tabId;
+      resetRefs(data?.tabId ?? tab_id);
       const preview = await interactivesPreview(data?.tabId ?? tab_id);
       return {
         content: [{
@@ -623,6 +676,8 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
   );
 
   // --- screenshot ---
+  // Larghezze dei preset, le stesse di viewport_resize nell'estensione.
+  const PRESET_WIDTHS = { mobile: 375, tablet: 768, desktop: 1440 };
   server.tool(
     'screenshot',
     'Screenshot of the visible viewport only (PNG), at the current scroll position, or one per viewport preset with presets. Read-only. '
@@ -631,7 +686,7 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
     {
       tab_id: tabId,
       save_to: saveToField('the PNG'),
-      presets: z.array(z.enum(['mobile', 'tablet', 'desktop'])).optional().describe('One capture per preset, window restored; save_to = directory, one file each'),
+      presets: z.array(z.enum(['mobile', 'tablet', 'desktop'])).optional().describe('Resizes the window per preset, then restores it; not phone emulation. A refused width is reported, not shot. save_to = directory'),
     },
     async ({ tab_id, save_to, presets }) => {
       guardWrite(save_to);
@@ -643,10 +698,24 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
         const notes = [];
         try {
           for (const preset of presets) {
-            await send(MessageType.VIEWPORT_RESIZE, { preset, tab_id });
+            const resized = await send(MessageType.VIEWPORT_RESIZE, { preset, tab_id });
             await new Promise((r) => setTimeout(r, 400));
             const shot = await send(MessageType.SCREENSHOT, { tab_id });
             if (!shot?.image) { notes.push(`${preset}: no image`); continue; }
+            // presets ridimensiona la finestra, non emula un dispositivo: il
+            // window manager può imporre una larghezza minima o ignorare la
+            // richiesta. Un'immagine desktop etichettata «mobile» porta a
+            // conclusioni sbagliate (2226 px su med-systems.it, 23/09/2026):
+            // meglio nessuna immagine e una nota esplicita.
+            const got = shot.viewport?.width;
+            const want = PRESET_WIDTHS[preset];
+            if (got && want && Math.abs(got - want) > Math.max(40, want * 0.15)) {
+              const zoom = resized?.zoom && resized.zoom !== 1 ? `, page zoom ${Math.round(resized.zoom * 100)}%` : '';
+              notes.push(`${preset}: NOT APPLIED — viewport stayed ${got}×${shot.viewport.height} CSS px (asked ~${want}${zoom}); `
+                + 'the window manager refused the width. No capture saved: this would not be a ' + preset + ' rendering. '
+                + 'Device emulation needs a headless browser.');
+              continue;
+            }
             if (save_to) {
               await mkdir(save_to, { recursive: true });
               const path = join(save_to, `${preset}.png`);
@@ -1083,12 +1152,13 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
       max_scrolls: z.number().optional().default(20).describe('Cap on scroll steps, so an infinite feed terminates'),
       step_px: z.number().optional().describe('px per step, default viewport height'),
       settle_ms: z.number().optional().default(400).describe('Pause ms after each step'),
+      container: z.string().optional().describe('until: selector that scrolls; default the document, or the largest scrollable element if the document does not scroll'),
       tab_id: tabId,
       frame_id: frameId,
     },
-    async ({ action, selector, x, y, behavior, offset_y, until, max_scrolls, step_px, settle_ms, tab_id, frame_id }) => {
+    async ({ action, selector, x, y, behavior, offset_y, until, max_scrolls, step_px, settle_ms, container, tab_id, frame_id }) => {
       const data = (action ?? 'to') === 'until'
-        ? await send(MessageType.SCROLL_UNTIL, { until, selector, max_scrolls, step_px, settle_ms, tab_id })
+        ? await send(MessageType.SCROLL_UNTIL, { until, selector, container, max_scrolls, step_px, settle_ms, tab_id })
         : await send(MessageType.SCROLL_TO, { selector, x, y, behavior, offset_y, tab_id, frame_id });
       return { content: [{ type: 'text', text: jsonText(data) }] };
     }
@@ -1502,12 +1572,7 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
             .slice(0, 5)
             .map((c) => c.e);
           if (els.length) {
-            const refMap = new Map();
-            els.forEach((e, i) => {
-              e.ref = `n${i + 1}`;
-              if (e.selector) refMap.set(e.ref, e.selector);
-            });
-            interactivesRefs.set(refsKey(tab_id), refMap);
+            assignRefs(tab_id, els);
             near = truncateText(interactivesLines({ count: els.length, elements: els, note: 'near first match' }), 1200);
           }
         } catch {}
@@ -2200,13 +2265,8 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
     },
     async ({ scope, limit, visible_only, format, frame_id, tab_id }) => {
       const data = await send(MessageType.GET_INTERACTIVES, { scope, limit, visible_only, frame_id, tab_id });
-      // Assegna ref n1..nN e memorizza la mappa ref → selector per click/type_text/hover
-      const refMap = new Map();
-      (data?.elements ?? []).forEach((e, i) => {
-        e.ref = `n${i + 1}`;
-        if (e.selector) refMap.set(e.ref, e.selector);
-      });
-      interactivesRefs.set(refsKey(tab_id), refMap);
+      // Ref stabili per selettore, memorizzati per click/type_text/hover
+      assignRefs(tab_id, data?.elements ?? []);
       if ((format ?? 'lines') === 'json') {
         return { content: [{ type: 'text', text: jsonText(data) }] };
       }

package/skills/chrome-bridge/SKILL.md

@@ -150,8 +150,10 @@ highlighted diff; zoom into a region with `element_screenshot({region, scale:2})
 ### Three viewports
 Triggers: "check it on mobile/tablet/desktop", «com'è su telefono?».
 `screenshot({presets:['mobile','tablet','desktop'], save_to:'./shots'})`: one
-call, one file per viewport, window restored. Report overflow, overlapping
-elements, hidden CTAs. Dark mode: `emulate_media({colorScheme:'dark'})`.
+call, one file per viewport, window restored. Presets resize the window and
+do not emulate a phone: a width the window manager refuses comes back as
+`NOT APPLIED`, with no image — say so instead of judging the mobile layout.
+Report overflow, overlapping elements, hidden CTAs. Dark mode: `emulate_media({colorScheme:'dark'})`.
 Print stylesheet: `emulate_media({printMode:true})` then `screenshot`.
 
 ### Accessibility and keyboard navigation
@@ -264,6 +266,21 @@ Triggers: "download the orders export and tell me…".
 `click` the export button → `manage_downloads({action:'wait_for_complete'})` → read the file
 with Claude Code. Spam in signups: `extract_table({where:{email:'/\\.ru$|xn--/'}})`.
 
+### Heavy web apps (Meta Ads Manager, Google Ads, big back offices)
+Triggers: "change the campaign budget", "read the ad set breakdown", «modifica
+la campagna su Ads Manager», «leggi i dati dell'inserzione».
+Keep the tab visible first: `get_page_info` must say `visibility: 'visible'`,
+else `create_tab({url, new_window:true, left, top, width, height})` on screen.
+Menus without ARIA roles: `find_text({text})` on the label, not
+`get_interactives` scoped by role. The app scrolls inside a panel:
+`scroll({action:'until', container})` (it picks the largest scrollable panel
+when the page itself does not scroll). Virtualized lists render the next rows
+only after a frame: scroll in one call, click in the next. Fields that save on
+Enter: `type_text` then `press_key({key:'Enter'})`. Several clicks on a React
+UI: one call per click, or `execute_js` with about 350 ms between them. A
+button that opens `window.open('')` navigates the tab away: override
+`window.open` with `execute_js` before clicking.
+
 ### Email deliverability
 Triggers: "do the site emails land in spam?". `navigate('https://www.mail-tester.com')`
 → `clipboard({action:'read'})` after copying the address → send from the site