chrome-bridge-mcp 1.18.0 → 1.20.0

package/README.md

@@ -156,6 +156,7 @@ Environment variables, each with a matching CLI flag:
 | `CHROME_BRIDGE_TOKEN` | unset | Required on both `ext_init` and `relay_init`. Strongly recommended whenever the bind isn't loopback |
 | `CHROME_BRIDGE_CAPS` / `--caps` | `core` | `core`, `audits`, `visual`, `network`, `storage`, `dom`, `files`, `all`. `install.sh` uses `all` |
 | `CHROME_BRIDGE_NO_JS` / `--no-js` | unset | No arbitrary JavaScript in the page: `execute_js` and `modify_dom` leave the schema, `wait_for(condition=function)` and `javascript:`/`data:` URLs are refused. `get_status` reports `js_evaluation` |
+| `CHROME_BRIDGE_OBSERVE` | unset | `off` stops the local error log below. The plugin sets `hook`: its hooks keep the log and the server stays out of it |
 | `CHROME_BRIDGE_WRITE_ROOT` / `--write-root` | unset | Every path the model chooses (`save_to`, `output_path`, exports) must be under this directory, checked before the browser does any work; the server's own state under `~/.config/chrome-bridge` stays writable. The CLI is your shell and is not restricted |
 
 The bridge binds loopback, accepts extension connections only from a
@@ -171,6 +172,31 @@ exports and screenshots are **not** redacted and may carry cookies, tokens or
 personal data. Don't point the automation at pages holding secrets you wouldn't
 paste into a chat.
 
+### Local error log
+
+When one of its own tools fails, chrome-bridge adds a line to a **local** file,
+`${XDG_STATE_HOME:-~/.local/state}/claude-observe/chrome-bridge.jsonl` (mode
+0600, in a 0700 folder), in the [claude-observe](https://github.com/frsorrentino/claude-observe)
+format (the plugin's copy is in `observe/`). With the plugin, a `PostToolUseFailure` hook writes it; with the npm
+server alone, the server does. The same error seen again is one line with a
+count.
+
+- **Kept:** the tool name, the error text after scrubbing (your home folder
+  becomes `~`; emails, URL queries, secrets and typed values are removed), the
+  names of the parameters and the length of text values, the chrome-bridge
+  version, the OS, the name of the working folder and of the Claude Code config
+  folder. With the plugin, also the Claude Code and model versions, the
+  session id and the names of the last three tools called.
+- **Never kept:** parameter values — no URLs, selectors, typed text or page
+  content.
+- **Nothing leaves your computer** unless you say yes. With the plugin, after a
+  few errors have piled up Claude may offer, at a natural moment, to send them
+  as one GitHub issue: it shows you the anonymized text first and sends it only
+  after your confirmation. The server alone never sends or offers anything.
+- **Turn it off:** `{"enabled": false}` in `~/.config/claude-observe/config.json`
+  (every plugin that uses claude-observe), or `CHROME_BRIDGE_OBSERVE=off` for
+  the server. Keep the log but stop the offers: `{"propose": false}`.
+
 ## Troubleshooting
 
 | Symptom | Cause / fix |
@@ -180,7 +206,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/element-label.js

@@ -0,0 +1,60 @@
+/**
+ * labelOf: il nome con cui un utente riconosce un elemento interattivo.
+ * Prima get_interactives prendeva aria-label || value || textContent: i campi
+ * con <label for>, <label> avvolgente o aria-labelledby uscivano senza nome
+ * (httpbin.org/forms/post: Customer name, Telephone, E-mail…) e radio e
+ * checkbox mostravano il value («small», «bacon») invece del testo visibile.
+ *
+ * Ordine: aria-label, aria-labelledby, <label> (el.labels copre for e
+ * avvolgente), testo o value per bottoni e altri elementi che non sono campi,
+ * title, placeholder. Spazi normalizzati, 80 caratteri.
+ *
+ * Non è un modulo ES: chrome.scripting serializza solo la funzione iniettata,
+ * quindi get_interactives inietta prima questo file (files:, world MAIN) e poi
+ * usa globalThis.__cbLabelOf. Nei test Node si importa per side effect, come
+ * stack-detect.js.
+ */
+(() => {
+  const clean = (s) => String(s || '').replace(/\s+/g, ' ').trim().slice(0, 80);
+  // Nel testo di un <label> avvolgente non entrano il campo stesso né le
+  // opzioni di una select: «Size <select>…» deve dare «Size».
+  const SKIP = new Set(['INPUT', 'SELECT', 'TEXTAREA', 'SCRIPT', 'STYLE', '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 BUTTON_INPUT = /^(submit|button|reset)$/i;
+
+  function labelOf(el, doc) {
+    const d = doc || el.ownerDocument;
+    const attr = (n) => (el.getAttribute(n) || '').trim();
+
+    const aria = clean(attr('aria-label'));
+    if (aria) return aria;
+
+    const ids = attr('aria-labelledby').split(/\s+/).filter(Boolean);
+    if (ids.length && d) {
+      const t = clean(ids.map((id) => { const n = d.getElementById(id); return n ? n.textContent : ''; }).join(' '));
+      if (t) return t;
+    }
+
+    for (const lab of el.labels || []) {
+      const t = clean(textOf(lab));
+      if (t) return t;
+    }
+
+    const tag = el.tagName;
+    const isField = tag === 'SELECT' || tag === 'TEXTAREA' || (tag === 'INPUT' && !BUTTON_INPUT.test(el.getAttribute('type') || ''));
+    if (!isField) {
+      const t = clean(tag === 'INPUT' ? el.value : el.textContent);
+      if (t) return t;
+    }
+
+    return clean(attr('title')) || clean(attr('placeholder'));
+  }
+
+  globalThis.__cbLabelOf = labelOf;
+})();

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.20.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 }) {
@@ -4600,11 +4633,14 @@ chrome.tabs.onReplaced.addListener((addedTabId, removedTabId) => {
 
 async function cmdGetInteractives({ scope, limit = 100, visible_only = true, tab_id, frame_id }) {
   const tabId = await resolveTabId(tab_id);
+  // labelOf vive in un file a sé (testato in test/unit): va iniettato prima
+  await chrome.scripting.executeScript({ target: scriptTarget(tabId, frame_id), files: ['lib/element-label.js'], world: 'MAIN' });
   const results = await chrome.scripting.executeScript({
     target: scriptTarget(tabId, frame_id),
     func: (scopeSel, lim, visibleOnly) => {
       const root = scopeSel ? document.querySelector(scopeSel) : document;
       if (!root) return { count: 0, elements: [], note: 'Scope element not found' };
+      const labelOf = globalThis.__cbLabelOf;
 
       // Selettore stabile e riusabile: id > data-testid > path nth-of-type
       const stableSelector = (el) => {
@@ -4644,7 +4680,7 @@ async function cmdGetInteractives({ scope, limit = 100, visible_only = true, tab
           const top = document.elementFromPoint(cx, cy);
           occluded = !!top && top !== el && !el.contains(top) && !top.contains(el);
         }
-        const label = (el.getAttribute('aria-label') || el.value || el.textContent || el.getAttribute('title') || el.getAttribute('placeholder') || '').trim().replace(/\s+/g, ' ').substring(0, 80);
+        const label = labelOf(el, document);
         out.push({
           selector: stableSelector(el),
           tag: el.tagName.toLowerCase(),
@@ -4707,52 +4743,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.20.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

@@ -12,6 +12,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { WSManager } from './ws-manager.js';
 import { registerTools } from './tools.js';
+import { createObserver } from './observe.js';
 import { launchBrowser } from './launcher.js';
 import { DEFAULT_PORT, VERSION } from './protocol.js';
 
@@ -64,6 +65,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(' '),
   });
 
@@ -103,7 +108,10 @@ async function main() {
   }
 
   // 3. Registra i tool MCP (filtrati per capability)
-  session.tools = registerTools(mcpServer, wsManager, parseCaps(), parseSecurity());
+  // Errori dei tool annotati in locale (formato claude-observe) quando nessun
+  // hook del plugin li vede: vedi server/observe.js.
+  const observe = createObserver({ version: VERSION });
+  session.tools = registerTools(mcpServer, wsManager, parseCaps(), { ...parseSecurity(), observe });
 
   // 4. Avvia il trasporto stdio MCP
   const transport = new StdioServerTransport();

package/server/observe.js

@@ -0,0 +1,314 @@
+/**
+ * Errori dei tool annotati in locale quando il server gira senza il plugin
+ * (npm, cartella locale): nessun hook di Claude Code li vede, quindi li
+ * scrive il server stesso, nel formato di claude-observe (FORMAT.md, v1).
+ *
+ * Con il plugin installato gli errori li scrive l'hook PostToolUseFailure
+ * (observe/observe.py), che ha anche il contesto della sessione; il plugin
+ * passa CHROME_BRIDGE_OBSERVE=hook e qui non si scrive nulla, altrimenti ogni
+ * errore conterebbe due volte.
+ *
+ * Stesse regole della copia Python, perché i record finiscono nello stesso
+ * file e si deduplicano per id:
+ * - id = <tool[:12]>-<sha256(tool + "\0" + key)[:8]>, key = errore normalizzato;
+ * - dei parametri solo nomi dei campi e lunghezze, mai i valori;
+ * - errore ripulito (home, email, query degli URL, segreti, valori digitati);
+ * - due lock, in quest'ordine: flock su <dir>/.lock dove c'è flock(1), poi
+ *   sempre la cartella <plugin>.jsonl.lock creata con mkdir; file 0600 in una
+ *   cartella 0700, sostituzione atomica;
+ * - lock occupato oltre l'attesa: la voce va in <plugin>.pending.jsonl con
+ *   una scrittura in append, e la incorpora il prossimo che ha il lock;
+ * - un file con record di formato più nuovo non si riscrive.
+ * scrub e normalize sono il porting di quelle di observe.py: il test
+ * observe-parity li confronta sugli stessi testi.
+ */
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import {
+  appendFileSync, chmodSync, closeSync, mkdirSync, openSync, readFileSync, renameSync, rmdirSync, statSync,
+  unlinkSync, writeSync,
+} from 'node:fs';
+import { homedir, release, type } from 'node:os';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const TOOL = 'chrome-bridge';
+export const FORMAT = 1;
+const MCP_PREFIX = 'mcp__chrome-bridge__';
+const DEFAULTS = { enabled: true, dir: '', max_records: 2000, max_days: 90 };
+
+// \w di Python è Unicode: qui lo stesso insieme, esplicito.
+const W = '[\\p{L}\\p{N}_]';
+
+export function scrub(text, limit = 300) {
+  let t = String(text ?? '');
+  const home = homedir();
+  if (home && home !== '/') t = t.split(home).join('~');
+  t = t.replace(new RegExp(`(?:${W}|[.+-])+@(?:${W}|-)+\\.(?:${W}|[.-])+`, 'gu'), '<EMAIL>');
+  t = t.replace(/(https?:\/\/[^/\s?#"'»]+)[^\s"'»]*/gu, '$1/…');
+  t = t.replace(/\b(token|password|passwd|secret|api[_-]?key|authorization|bearer)("?\s*[:=]\s*|\s+)\S+/giu, '$1$2<SECRET>');
+  t = t.replace(/\b(value_after|value|text)("?\s*[:=]?\s*)("[^"]*"|'[^']*'|«[^»]*»)/giu, '$1$2<STR>');
+  t = t.replace(/\b(?=[A-Za-z0-9_\-+/]*\d)(?=[A-Za-z0-9_\-+/]*[A-Za-z])[A-Za-z0-9_\-+/=]{24,}\b/gu, '<SECRET>');
+  return Array.from(t).slice(0, limit).join('');
+}
+
+export function normalize(text) {
+  let t = scrub(text, 400);
+  t = t.replace(/«[^»]*»|"[^"]*"|'[^']*'/gu, '<STR>');
+  t = t.replace(new RegExp(`(~|\\.{0,2})/(?:${W}|[.\\-/~<>…])+`, 'gu'), '<PATH>');
+  t = t.replace(/\d+/gu, '<N>');
+  return Array.from(t.replace(/\s+/gu, ' ').trim()).slice(0, 300).join('');
+}
+
+// Di tool_input solo la forma: nomi dei campi, lunghezza dei testi, tipo del resto.
+export function shape(input) {
+  const out = {};
+  for (const [k, v] of Object.entries(input ?? {})) {
+    if (typeof v === 'string') out[k] = Array.from(v).length;
+    else if (typeof v === 'boolean') out[k] = 'bool';
+    else if (typeof v === 'number') out[k] = 'number';
+    else if (Array.isArray(v)) out[k] = `list[${v.length}]`;
+    else if (v && typeof v === 'object') out[k] = `object[${Object.keys(v).length}]`;
+    else out[k] = 'null';
+  }
+  return out;
+}
+
+export function rid(tool, key) {
+  return `${tool.slice(0, 12)}-${createHash('sha256').update(`${tool}\0${key}`).digest('hex').slice(0, 8)}`;
+}
+
+const expand = (p, env) => String(p ?? '')
+  .replace(/^~(?=$|\/)/, homedir())
+  .replace(/\$\{(\w+)\}|\$(\w+)/g, (m, a, b) => env[a ?? b] ?? m);
+
+export function loadConfig(env = process.env) {
+  const base = env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  const path = env.CLAUDE_OBSERVE_CONFIG || join(base, 'claude-observe', 'config.json');
+  try {
+    return { ...DEFAULTS, ...(JSON.parse(readFileSync(path, 'utf8')) || {}) };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+export function boxDir(config, env = process.env) {
+  if (config.dir) return expand(config.dir, env);
+  return join(env.XDG_STATE_HOME || join(homedir(), '.local', 'state'), 'claude-observe');
+}
+
+// L'account è la cartella di config di Claude Code: il confine fra organizzazioni.
+function accountName(env) {
+  return basename(env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'));
+}
+
+/** Il record come lo scriverebbe record_external/record di observe.py, più la forma dei parametri. */
+export function buildEntry({ name, args, message, durationMs, version, env = process.env, cwd = process.cwd() }) {
+  const call = name.startsWith(MCP_PREFIX) ? name : `${MCP_PREFIX}${name}`;
+  const err = String(message ?? '');
+  const key = normalize(`${call} ${err}`);
+  const context = { tool_version: version || '', os: `${type()} ${release()}` };
+  return {
+    id: rid(TOOL, key),
+    fields: {
+      context, source: 'server', kind: 'error', call, error: scrub(err), key,
+      account: accountName(env), project: basename(cwd),
+    },
+    example: { input_shape: shape(args), error_raw: scrub(err), duration_ms: durationMs ?? null, context },
+  };
+}
+
+function readRecords(path) {
+  let text = '';
+  try { text = readFileSync(path, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { /* riga rotta: si salta, come observe.py */ }
+  }
+  return out;
+}
+
+function rotate(recs, config, now) {
+  const days = Number(config.max_days) || 90;
+  const cap = Number(config.max_records) || 2000;
+  let kept = recs.filter((r) => now - Number(r.last_seen || 0) <= days * 86400);
+  if (kept.length > cap) {
+    // Come observe.py: prima i record chiusi, poi i più vecchi.
+    kept.sort((a, b) => ((a.status !== 'done') - (b.status !== 'done')) || (Number(a.last_seen || 0) - Number(b.last_seen || 0)));
+    kept = kept.slice(kept.length - cap);
+  }
+  return kept;
+}
+
+// Aggiunge o aggiorna il record nella lista: la stessa logica di apply() in
+// observe.py (count, last_seen, fino a tre esempi, campi scritti a mano).
+function applyRecord(recs, id, fields, example, now) {
+  let r = recs.find((x) => x.id === id);
+  if (!r) {
+    r = {
+      v: FORMAT, id, tool: TOOL, count: 0, first_seen: now, examples: [], workaround: null,
+      class: null, status: 'new', ...fields,
+    };
+    recs.push(r);
+  } else {
+    for (const k of ['workaround', 'class', 'note', 'context']) if (fields[k]) r[k] = fields[k];
+    if (r.status === 'done' && String(fields.source || '').startsWith('hook')) r.status = 'new';
+  }
+  r.count = Number(r.count || 0) + (example != null || !r.count ? 1 : 0);
+  r.last_seen = Math.max(Number(r.last_seen || 0), now);
+  if (example != null) r.examples = [...(r.examples || []).slice(-2), { ...example, at: now }];
+  return r;
+}
+
+const pendingPath = (dir) => join(dir, `${TOOL}.pending.jsonl`);
+
+/**
+ * Legge, incorpora le voci in attesa, aggiorna e riscrive il file. Va
+ * chiamata con i lock presi. null = file di formato più nuovo, non toccato.
+ */
+export function applyEntry(dir, entry, config, nowSec = Date.now() / 1000) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const path = join(dir, `${TOOL}.jsonl`);
+  const recs = readRecords(path);
+  // Le voci rimaste in attesa (lock occupato, FORMAT.md «Pending»): si
+  // spostano da parte e si applicano come appena registrate; il file preso si
+  // cancella solo dopo la riscrittura.
+  const pending = pendingPath(dir);
+  let taken = null;
+  try {
+    const t = `${join(dir, `${TOOL}.pending`)}.${process.pid}.taking`;
+    renameSync(pending, t);
+    taken = t;
+  } catch { /* nessuna voce in attesa */ }
+  const takenText = taken ? readFileSync(taken, 'utf8') : '';
+  // Un file scritto da una copia più nuova (formato incompatibile): non si
+  // tocca, e le voci prese tornano in attesa.
+  if (recs.some((r) => Number(r.v || 1) > FORMAT)) {
+    if (taken) { appendFileSync(pending, takenText, { mode: 0o600 }); unlinkSync(taken); }
+    return null;
+  }
+  for (const line of takenText.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (Number(e.v || 1) <= FORMAT && e.id) applyRecord(recs, e.id, e.fields || {}, e.example ?? null, Number(e.at) || nowSec);
+    } catch { /* riga rotta: si salta */ }
+  }
+  const r = entry ? applyRecord(recs, entry.id, entry.fields, entry.example, Math.round(nowSec * 1000) / 1000) : null;
+  const kept = rotate(recs, config, nowSec);
+  const tmp = `${path}.tmp`;
+  const fd = openSync(tmp, 'w', 0o600);
+  try {
+    writeSync(fd, kept.map((x) => JSON.stringify(x)).join('\n') + (kept.length ? '\n' : ''));
+  } finally {
+    closeSync(fd);
+  }
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, path);
+  if (taken) unlinkSync(taken);
+  return r ?? true;
+}
+
+/**
+ * Lock occupato oltre l'attesa: la voce non si perde, va in
+ * <plugin>.pending.jsonl con UNA scrittura in append (atomica senza lock per
+ * righe così piccole). La incorpora il prossimo scrittore che ha il lock.
+ */
+export function appendPending(dir, entry, nowSec = Date.now() / 1000) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const line = JSON.stringify({
+    v: FORMAT, tool: TOOL, id: entry.id, fields: entry.fields, example: entry.example ?? null,
+    at: Math.round(nowSec * 1000) / 1000,
+  }) + '\n';
+  const fd = openSync(pendingPath(dir), 'a', 0o600);
+  try { writeSync(fd, line); } finally { closeSync(fd); }
+}
+
+// Secondo lock del protocollo (FORMAT.md, «Lock»), sempre preso: la cartella
+// <plugin>.jsonl.lock creata con mkdir, atomica ovunque. Chi non ha flock(1)
+// prende solo questa. Una cartella più vecchia di 10 s è di un processo
+// morto; l'attesa complessiva si ferma a deadline (circa 3 s dall'inizio).
+export const LOCK_WAIT_MS = 3000;
+const LOCK_STALE_MS = 10000;
+export const BUSY = Symbol('lock busy');
+
+export async function withDirLock(dir, fn, deadline = Date.now() + LOCK_WAIT_MS) {
+  const lock = join(dir, `${TOOL}.jsonl.lock`);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  for (;;) {
+    try { mkdirSync(lock); break; } catch {
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) { rmdirSync(lock); continue; }
+      } catch { continue; /* sparita nel frattempo: si riprova subito */ }
+      if (Date.now() > deadline) return BUSY;
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }
+  try { return fn(); } finally { try { rmdirSync(lock); } catch { /* già tolta */ } }
+}
+
+const SELF = fileURLToPath(import.meta.url);
+// Codici d'uscita del figlio: lock occupato (flock -E o cartella) contro
+// guasto vero. Solo il primo manda la voce in attesa.
+const EXIT_BUSY = 75;
+
+// Primo lock, dove c'è flock(1): la scrittura gira in un figlio sotto
+// `flock -x <dir>/.lock`, lo stesso lock di fcntl.flock in observe.py. Le
+// copie distribuite fino ad a787654 prendono solo quello: così nuove e vecchie
+// convivono. Dentro, il figlio prende la cartella di lock e scrive.
+function writeUnderFlock(dir, entry, env, deadline) {
+  const wait = String(Math.max(1, Math.ceil((deadline - Date.now()) / 1000)));
+  return new Promise((resolve) => {
+    const child = spawn('flock', ['-x', '-w', wait, '-E', String(EXIT_BUSY), join(dir, '.lock'), process.execPath, SELF, '--write'], {
+      stdio: ['pipe', 'ignore', 'ignore'], env,
+    });
+    child.on('error', () => resolve('no-flock'));
+    child.on('exit', (code) => resolve(code === 0 ? 'ok' : code === EXIT_BUSY ? 'busy' : 'failed'));
+    child.stdin.end(JSON.stringify({ dir, entry, deadline }));
+  });
+}
+
+/**
+ * L'osservatore del server, o null quando non deve scrivere: il plugin ha già
+ * l'hook (CHROME_BRIDGE_OBSERVE=hook) o l'utente l'ha spento (=off).
+ */
+export function createObserver({ env = process.env, version = '' } = {}) {
+  const mode = String(env.CHROME_BRIDGE_OBSERVE ?? '').toLowerCase();
+  if (['hook', 'off', '0', 'false', 'no'].includes(mode)) return null;
+  let chain = Promise.resolve();
+  return {
+    error(name, args, message, durationMs) {
+      chain = chain.then(async () => {
+        const config = loadConfig(env);
+        if (config.enabled === false || config.tools?.[TOOL]?.enabled === false) return;
+        const dir = boxDir(config, env);
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const entry = buildEntry({ name, args, message, durationMs, version, env });
+        const deadline = Date.now() + LOCK_WAIT_MS;
+        let how = await writeUnderFlock(dir, entry, env, deadline);
+        if (how === 'no-flock') {
+          how = (await withDirLock(dir, () => applyEntry(dir, entry, config), deadline)) === BUSY ? 'busy' : 'ok';
+        }
+        if (how === 'busy') appendPending(dir, entry);
+      }).catch(() => { /* annotare un errore non deve mai produrne un altro */ });
+      return chain;
+    },
+  };
+}
+
+// Modalità figlio: `node observe.js --write` con {dir, entry, deadline} su stdin.
+if (process.argv[1] === SELF && process.argv[2] === '--write') {
+  let input = '';
+  process.stdin.on('data', (d) => { input += d; });
+  process.stdin.on('end', () => {
+    try {
+      const { dir, entry, deadline } = JSON.parse(input);
+      withDirLock(dir, () => applyEntry(dir, entry, loadConfig(process.env)), deadline)
+        .then((r) => process.exit(r === BUSY ? EXIT_BUSY : 0), () => process.exit(1));
+    } catch {
+      process.exit(1);
+    }
+  });
+}

package/server/protocol.js

@@ -92,12 +92,15 @@ export const MessageType = Object.freeze({
 });
 
 // Versione
-export const VERSION               = '1.18.0';
+export const VERSION               = '1.20.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

@@ -400,6 +400,25 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
     ? ['core', ...Object.keys(TOOL_CAPS)]
     : ['core', ...String(caps).split(',').map((s) => s.trim()).filter((s) => s && s !== 'core')];
 
+  // Un errore del tool (eccezione, o risultato isError) va all'osservatore,
+  // che lo annota in locale senza i valori dei parametri (server/observe.js).
+  // L'errore arriva comunque al chiamante, uguale.
+  const observer = options.observe ?? null;
+  const observed = (name, handler) => (observer ? async (args, extra) => {
+    const t0 = Date.now();
+    try {
+      const out = await handler(args, extra);
+      if (out?.isError) {
+        const text = (out.content ?? []).find((c) => c.type === 'text')?.text ?? '';
+        observer.error(name, args, text, Date.now() - t0);
+      }
+      return out;
+    } catch (err) {
+      observer.error(name, args, err?.message ?? String(err), Date.now() - t0);
+      throw err;
+    }
+  } : handler);
+
   // Ogni registrazione passa da qui: il filtro capability scarta i tool opt-in
   // fuori dai gruppi attivi, e le annotations vengono applicate da TOOL_ANNOTATIONS.
   // Un solo wrapper per entrambe le cose, altrimenti con caps != 'all' le
@@ -417,10 +436,11 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
           if (group && !enabled.has(group) && !enabled.has('all')) return;
         }
         const annotations = TOOL_ANNOTATIONS[name];
+        const run = observed(name, handler);
         // Un tool senza voce resta registrato (meglio di un crash all'avvio):
         // è il test tool-annotations a segnalarlo.
-        if (annotations) target.tool(name, desc, schema, annotations, handler);
-        else target.tool(name, desc, schema, handler);
+        if (annotations) target.tool(name, desc, schema, annotations, run);
+        else target.tool(name, desc, schema, run);
       },
     };
   }
@@ -472,17 +492,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 +593,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 +684,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 +696,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 +706,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 +718,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 +1172,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 +1592,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 +2285,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