chrome-bridge-mcp 1.17.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.17.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
@@ -683,7 +733,7 @@ async function bitmapToBase64Capped(bitmap, maxSide = MAX_IMAGE_SIDE) {
 
 // --- Implementazione comandi ---
 
-async function cmdGetTabs({ include_windows = false } = {}) {
+async function cmdGetTabs({ include_windows = false, ended } = {}) {
   const tabs = await chrome.tabs.query({});
   const list = tabs.map((t) => ({
     id: t.id,
@@ -691,8 +741,17 @@ async function cmdGetTabs({ include_windows = false } = {}) {
     title: t.title,
     active: t.active,
     windowId: t.windowId,
+    // Una scheda scartata da Chrome (memory saver) esiste ancora ma non ha un
+    // renderer: execute_js e compagni falliscono finché non torna in primo piano.
+    ...(t.discarded ? { discarded: true } : {}),
   }));
-  if (!include_windows) return list;
+  // ended = id che il server sa suoi e non trova più: la forma ad array resta
+  // quella di sempre per chi non lo chiede.
+  const open = new Set(list.map((t) => t.id));
+  const endings = Array.isArray(ended) && ended.length
+    ? Object.fromEntries(ended.filter((id) => !open.has(id)).map((id) => [id, tabEndings.get(id) ?? { reason: 'unknown' }]))
+    : null;
+  if (!include_windows) return endings ? { tabs: list, ended: endings } : list;
 
   // Senza geometria e stato non si può decidere dove mettere una finestra: si
   // può solo indovinare. `left` in particolare è ciò che identifica il monitor
@@ -712,7 +771,7 @@ async function cmdGetTabs({ include_windows = false } = {}) {
     // provarci.
     scriptable: (w.tabs || []).some((t) => /^(https?|file):/i.test(t.url || '')),
   }));
-  return { tabs: list, windows };
+  return endings ? { tabs: list, windows, ended: endings } : { tabs: list, windows };
 }
 
 async function cmdNavigate({ url, tab_id }) {
@@ -1161,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,
@@ -1189,12 +1255,26 @@ async function cmdMoveTab({ tab_id, window_id, new_window = false, window_type,
   };
 }
 
+// Perché una scheda non c'è più: «No tab with id» da solo non distingue una
+// chiusura a mano da una sostituzione. In memoria e limitato: se il service
+// worker riparte il registro si svuota e il motivo torna 'unknown'.
+const tabEndings = new Map();
+const TAB_ENDINGS_MAX = 200;
+const bridgeClosing = new Set();
+
+function recordTabEnding(tabId, ending) {
+  if (bridgeClosing.delete(tabId) && ending.reason === 'closed') ending = { reason: 'closed_by_bridge' };
+  tabEndings.set(tabId, { ...ending, at: new Date().toISOString() });
+  if (tabEndings.size > TAB_ENDINGS_MAX) tabEndings.delete(tabEndings.keys().next().value);
+}
+
 async function cmdTabAction({ action, tab_id, bypass_cache = false }) {
   if (!action) throw new Error('Missing required parameter: action');
   const tabId = await resolveTabId(tab_id);
 
   if (action === 'close') {
-    await chrome.tabs.remove(tabId);
+    bridgeClosing.add(tabId);
+    try { await chrome.tabs.remove(tabId); } catch (e) { bridgeClosing.delete(tabId); throw e; }
     return { action, closed: tabId };
   }
   if (action === 'discard') {
@@ -1321,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,
@@ -1731,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) {
@@ -1783,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 ---
@@ -2035,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.
@@ -3513,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',
   });
@@ -4425,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();
@@ -4454,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 }) {
@@ -4561,9 +4617,16 @@ async function cmdHttpAuth({ action, username, password }) {
 
 // --- Tab lifecycle: cleanup injection state ---
 
-chrome.tabs.onRemoved.addListener((tabId) => {
+chrome.tabs.onRemoved.addListener((tabId, info) => {
   browserNetLog.delete(tabId);
   mainFrameHeaders.delete(tabId);
+  recordTabEnding(tabId, { reason: info?.isWindowClosing ? 'window_closed' : 'closed' });
+});
+
+// Chrome sostituisce l'id quando rimpiazza la scheda (prerender, alcuni
+// discard): per chi teneva il vecchio id è una scheda sparita senza chiusura.
+chrome.tabs.onReplaced.addListener((addedTabId, removedTabId) => {
+  recordTabEnding(removedTabId, { reason: 'replaced', replaced_by: addedTabId });
 });
 
 // --- get_interactives ---
@@ -4677,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.17.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/cli.js

@@ -119,10 +119,13 @@ function connect(port) {
         sendCommand(type, params = {}) {
           return new Promise((res, rej) => {
             const command = createCommand(type, params);
+            // Come ws-manager: un timeout chiesto dal comando alza quello di trasporto.
+            const asked = Number(params?.timeout);
+            const timeout = Number.isFinite(asked) && asked > 0 ? Math.max(getTimeout(type), asked + 5000) : getTimeout(type);
             const timer = setTimeout(() => {
               pending.delete(command.id);
-              rej(new Error(`Command ${type} timed out after ${getTimeout(type)}ms`));
-            }, getTimeout(type));
+              rej(new Error(`Command ${type} timed out after ${timeout}ms`));
+            }, timeout);
             pending.set(command.id, { res, rej, timer });
             ws.send(JSON.stringify(command));
           });

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.17.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

@@ -113,6 +113,34 @@ function fitArray(items, max, serialize) {
   return items.slice(0, lo);
 }
 
+/**
+ * Output di execute_js sotto `max` senza rompere il JSON: tagliare la
+ * serializzazione a metà stringa dava «Invalid control character» a chi la
+ * parsava. Una stringa si accorcia dentro il suo valore, un array per elementi
+ * (jsonText), il resto diventa un prefisso dichiarato come tale.
+ */
+export function jsResultText(data, max) {
+  const text = JSON.stringify(data);
+  if (text == null || text.length <= max) return text;
+  const hint = 'raise max_length, or save_to for the whole result';
+  const value = data?.result;
+  const wrap = (field, cut, total) => JSON.stringify({ [field]: cut, truncated: true, total_chars: total, hint });
+  const fitString = (field, full) => {
+    // Gli escape JSON allungano la stringa: il prefisso più lungo che sta nel
+    // tetto si cerca sulla serializzazione, non sui caratteri grezzi.
+    let lo = 0;
+    let hi = Math.min(full.length, max);
+    while (lo < hi) {
+      const mid = Math.ceil((lo + hi) / 2);
+      if (wrap(field, full.slice(0, mid), full.length).length <= max) lo = mid; else hi = mid - 1;
+    }
+    return wrap(field, full.slice(0, lo), full.length);
+  };
+  if (typeof value === 'string') return fitString('result', value);
+  if (Array.isArray(value)) return jsonText(data, max, hint);
+  return fitString('result_json_prefix', JSON.stringify(value));
+}
+
 /** Una riga (oggetto colonna→valore o array di celle) soddisfa il filtro where. */
 function tableRowMatches(row, where) {
   return Object.entries(where).every(([col, needle]) => {
@@ -444,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');
@@ -489,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; }
   }
 
@@ -534,21 +614,38 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
   server.tool(
     'get_tabs',
     'List every open tab with id, url, title, active flag and mine (created by this session). Read-only. Find a tab_id when the implicit '
-      + 'target is not the one you mean. include_windows adds position, size, state and type of each window — needed before moving or tiling.',
+      + 'target is not the one you mean. include_windows adds position, size, state and type of each window — needed before moving or tiling. '
+      + 'Session tabs gone since the last call come back once in closed_session_tabs with the reason (closed, window_closed, replaced, closed_by_bridge).',
     {
       include_windows: z.boolean().optional().default(false)
         .describe('Also return the windows with bounds, state, type and tab count'),
     },
     async ({ include_windows }) => {
-      const data = await send(MessageType.GET_TABS, { include_windows: include_windows === true });
+      // `ended` = le schede che il server sa sue: l'estensione dà il motivo di
+      // quelle che non trova più. Senza schede di sessione la risposta resta
+      // quella di sempre.
+      const data = await send(MessageType.GET_TABS, {
+        include_windows: include_windows === true,
+        ...(ownedTabs.size ? { ended: [...ownedTabs] } : {}),
+      });
       const list = Array.isArray(data) ? data : (data?.tabs ?? []);
+      const windows = Array.isArray(data) ? null : data?.windows;
       for (const t of list) if (ownedTabs.has(t.id)) t.mine = true;
-      return {
-        content: [{
-          type: 'text',
-          text: jsonText(data),
-        }],
-      };
+      const missing = [...ownedTabs].filter((id) => !list.some((t) => t.id === id));
+      const shaped = windows ? { tabs: list, windows } : list;
+      if (!missing.length) return { content: [{ type: 'text', text: jsonText(shaped) }] };
+
+      // Un'estensione precedente ignora `ended` e risponde con l'array: motivo ignoto.
+      const ended = (!Array.isArray(data) && data?.ended) || {};
+      const closed = missing.map((id) => ({ id, ...(ended[id] ?? { reason: 'unknown' }) }));
+      for (const c of closed) {
+        ownedTabs.delete(c.id);
+        const successor = c.replaced_by != null ? list.find((t) => t.id === c.replaced_by) : null;
+        // Scheda sostituita da Chrome: resta della sessione con il nuovo id.
+        if (successor) { ownedTabs.add(successor.id); successor.mine = true; }
+        if (sessionTabId === c.id) sessionTabId = successor?.id ?? null;
+      }
+      return { content: [{ type: 'text', text: jsonText({ tabs: list, ...(windows ? { windows } : {}), closed_session_tabs: closed }) }] };
     }
   );
 
@@ -567,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: [{
@@ -578,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. '
@@ -586,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);
@@ -598,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`);
@@ -645,21 +759,25 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
   // --- execute_js ---
   server.tool(
     'execute_js',
-    'Run JavaScript in the page (MAIN world). Requires the extension\'s "Allow user scripts" toggle; errors explain setup if disabled.',
+    'Run JavaScript in the page (MAIN world). Requires the extension\'s "Allow user scripts" toggle; errors explain setup if disabled. '
+      + 'A promise is awaited up to timeout. A cut result stays valid JSON and says truncated; save_to writes the whole result to disk.',
     {
       code:       z.string().describe('JS evaluated in the page; the value of the last expression is returned'),
       tab_id:     tabId,
       frame_id:   frameId,
       max_length: z.number().optional().default(20000).describe('Max output chars'),
+      timeout:    z.number().optional().describe('Max ms to wait for the result (default 30000); raise it for long async work'),
+      save_to:    saveToField('the result (a string as is, anything else as JSON)'),
     },
-    async ({ code, tab_id, frame_id, max_length }) => {
-      const data = await send(MessageType.EXECUTE_JS, { code, tab_id, frame_id });
-      return {
-        content: [{
-          type: 'text',
-          text: truncateText(JSON.stringify(data), max_length ?? DEFAULT_MAX_OUTPUT, 'max_length'),
-        }],
-      };
+    async ({ code, tab_id, frame_id, max_length, timeout, save_to }) => {
+      guardWrite(save_to);
+      const data = await send(MessageType.EXECUTE_JS, { code, tab_id, frame_id, ...(timeout ? { timeout } : {}) });
+      if (save_to) {
+        const value = data?.result;
+        const isString = typeof value === 'string';
+        return savedSummary(save_to, Buffer.from(isString ? value : JSON.stringify(value ?? null), 'utf8'), { format: isString ? 'text' : 'json' });
+      }
+      return { content: [{ type: 'text', text: jsResultText(data, max_length ?? DEFAULT_MAX_OUTPUT) }] };
     }
   );
 
@@ -1034,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) }] };
     }
@@ -1367,6 +1486,7 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
         return { content: [{ type: 'text', text: jsonText({ closed }) }] };
       }
       const data = await send(MessageType.TAB_ACTION, { action, bypass_cache, tab_id });
+      if (action === 'close') ownedTabs.delete(data?.closed ?? tab_id ?? sessionTabId);
       if (action === 'close' && (tab_id == null || tab_id === sessionTabId)) sessionTabId = null;
       if (action === 'activate' && tab_id != null) sessionTabId = tab_id;
       return { content: [{ type: 'text', text: jsonText(data) }] };
@@ -1452,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 {}
@@ -2150,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