chrome-bridge-mcp 1.16.1 → 1.18.0

package/README.md

@@ -40,20 +40,34 @@ element refs, `click(ref="n1")` follows with no discovery turn in between.
 For `execute_js`, enable **Allow user scripts** in `chrome://extensions` →
 Chrome Bridge → Details (on Chrome 135-137, enable Developer Mode instead).
 
+**As a plugin, without a clone:** in Claude Code, `/plugin marketplace add
+frsorrentino/chrome-bridge` then `/plugin install chrome-bridge@chrome-bridge`
+registers the MCP server from npm (all capabilities) together with the recipes
+skill; clients that read [Agent Plugins 1.0](https://agent-plugins.org) get the
+same from `plugin.json` + `mcp.json`. The extension still comes from the Web
+Store or `extension/`. Pick one path: the plugin and `install.sh` would
+register the same server twice.
+
 ## Why Chrome Bridge?
 
 | | Chrome Bridge | Claude in Chrome | Chrome DevTools MCP | Playwright MCP |
 |---|---|---|---|---|
 | **ChromeOS / Crostini** | **Yes** (real host) | No | Container only | Container only |
-| **Tools** | **59** (38 core) | ~20 | ~50 | 23 core (71 total) |
+| **Tools** | **59** (38 core) | 22 | 29 default (56 with flags) | 24 core (71 total) |
 | **Requires paid plan** | **No** | Yes (Pro+) | No | No |
 | **Network mocking** | **Yes** (stub/headers) | No | No | Yes |
 | **Visual regression** | **Yes** (`screenshot_diff`) | No | No | No |
-| **Audits (a11y/SEO/sec)** | **Yes** (one call, report on disk) | No | Partial | No |
+| **Audits (a11y/SEO/sec)** | **Yes** (one call, report on disk) | No | Lighthouse | No |
 | **Headless / CI** | **Yes** | No | Yes | Yes |
 | **GIF / video** | No | **Yes** | Partial | No |
 | **Breakpoints / heap** | No | No | **Yes** | No |
 
+Codex for Chrome (OpenAI, May 2026) sits in the Claude in Chrome column: an
+official extension with the `debugger` permission, macOS and Windows only,
+the ChatGPT app required. Claude in Chrome documents Linux desktop since
+September 2026; ChromeOS and WSL stay out. Competitor figures measured on
+2026-09-01 and 2026-09-11 (`docs/analisi-2026-09-11-concorrenti.md`).
+
 It wins on **round trips, not payload size**: short element refs instead of the
 screenshot-and-click loop, `fill_form` filling N fields in one call, table
 filtering done server-side. Per single turn it actually costs slightly *more*.
@@ -141,6 +155,8 @@ Environment variables, each with a matching CLI flag:
 | `CHROME_BRIDGE_HOST` / `--host` | `127.0.0.1` | `0.0.0.0` **only** where the browser lives outside the container (ChromeOS/Crostini port-forward) — and only with a token |
 | `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_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
 `chrome-extension://` origin, and — when a token is set — requires it on both
@@ -172,7 +188,9 @@ paste into a chat.
 ## Documentation
 
 - [docs/TOOLS.md](docs/TOOLS.md) — all 59 tools, by group
+- [docs/CAPABILITIES.md](docs/CAPABILITIES.md) — what the bridge gets past and what it does not, one dated state per wall
 - [docs/EFFICIENCY.md](docs/EFFICIENCY.md) — the benchmark and the design behind it
+- [docs/PERFORMANCE.md](docs/PERFORMANCE.md) — latency per tool on the real path, `npm run bench:latency`
 - [bench/RESULTS.md](bench/RESULTS.md) — raw runs and inclusion rule
 - [CHANGELOG.md](CHANGELOG.md)
 
@@ -181,7 +199,9 @@ paste into a chat.
 `npm test` (Chrome-free, ~22s) · `npm run test:e2e` (needs Chrome and a
 connected extension; with a bridge already on 8765:
 `CHROME_BRIDGE_PORT=8799 node test/test-devtools.js --launch`, which opens
-its own Chromium with `extension/`) · `npm run measure` (schema cost).
+its own Chromium with `extension/`) · `npm run measure` (schema cost) ·
+`npm run bench:latency` (milliseconds per tool, launches its own Chromium,
+writes `docs/PERFORMANCE.md`).
 
 ## License
 

package/extension/lib/capture-pacing.js

@@ -0,0 +1,17 @@
+/**
+ * Chrome concede 2 captureVisibleTab al secondo per estensione; la terza entro
+ * il secondo fallisce con MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND. Invece di
+ * far vedere la quota al modello, ogni cattura aspetta il tempo che manca a
+ * 520 ms dalla precedente. Orologio e sleep iniettabili per i test.
+ */
+export function createPacer({ minIntervalMs = 520, now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  let last = -Infinity;
+  const pace = async () => {
+    const wait = Math.max(0, last + minIntervalMs - now());
+    if (wait > 0) await sleep(wait);
+    last = now();
+    return wait;
+  };
+  pace.minIntervalMs = minIntervalMs;
+  return pace;
+}

package/extension/lib/page-fingerprint.js

@@ -0,0 +1,36 @@
+/**
+ * Impronta della pagina: pochi interi che un'azione può cambiare. Il server
+ * la prende prima e dopo click/fill_form e riporta solo le differenze in
+ * page_changed: "il menu si è aperto" senza screenshot.
+ *
+ * Autocontenuta apposta: chrome.scripting.executeScript ne serializza il
+ * sorgente e la esegue nella pagina, dove niente di questo modulo esiste.
+ * Prende `doc` per essere testabile su un DOM finto (test/unit).
+ */
+export function pageFingerprint(doc) {
+  const d = doc || document;
+  const count = (sel) => { try { return d.querySelectorAll(sel).length; } catch { return 0; } };
+  let checked = 0;
+  try { for (const el of d.querySelectorAll('input')) if (el.checked) checked += 1; } catch { /* nessun input */ }
+  let focus = 'body';
+  const a = d.activeElement;
+  if (a && a.tagName) {
+    const tag = a.tagName.toLowerCase();
+    const name = a.getAttribute ? a.getAttribute('name') : null;
+    focus = a.id ? `${tag}#${a.id}` : (name ? `${tag}[name="${name}"]` : tag);
+  }
+  const body = d.body;
+  const text = body ? (typeof body.innerText === 'string' ? body.innerText : (body.textContent || '')).length : 0;
+  return {
+    url: d.location ? d.location.href : null,
+    title: d.title || '',
+    nodes: d.getElementsByTagName('*').length,
+    text,
+    open: count('[open]'),
+    expanded: count('[aria-expanded="true"]'),
+    checked,
+    selected: count('[aria-selected="true"], [aria-pressed="true"]'),
+    dialogs: count('dialog[open], [role="dialog"], [role="alertdialog"]'),
+    focus,
+  };
+}

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Chrome Bridge for Claude Code",
-  "version": "1.16.1",
+  "version": "1.18.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

@@ -7,6 +7,8 @@
 
 import './telemetry.js';
 import { buildMarkdown } from './lib/page-markdown.js';
+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';
 const { pushError } = globalThis.__cbTelemetry;
@@ -448,6 +450,8 @@ async function executeCommand(msg) {
       return await cmdKeyboardWalk(params);
     case 'handoff':
       return await cmdHandoff(params);
+    case 'page_fingerprint':
+      return await cmdPageFingerprint(params);
     case 'watch':
       return await cmdWatch(params);
     case 'observe':
@@ -586,8 +590,13 @@ async function runViaFunction(target, code) {
 // Su ChromeOS una finestra totalmente occlusa/congelata può non produrre mai
 // un frame: la promise di captureVisibleTab resterebbe pendente per sempre.
 // Meglio un errore parlante dopo 10s che un comando appeso.
+// Quota Chrome: 2 catture al secondo. Il pacer distanzia le chiamate di
+// 520 ms invece di far comparire MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND al
+// secondo screenshot ravvicinato (trovato dal bench di latenza, 2026-09-11).
+const paceCapture = createPacer();
 
-function captureVisible(windowId, options = { format: 'png' }) {
+async function captureVisible(windowId, options = { format: 'png' }) {
+  await paceCapture();
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
       reject(new Error('Capture timed out after 10s: the window is not rendering frames (fully occluded, minimized, or frozen). Bring the Chrome window at least partially on screen and retry.'));
@@ -674,7 +683,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,
@@ -682,8 +691,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
@@ -703,7 +721,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 }) {
@@ -896,13 +914,17 @@ async function cmdTypeText({ selector, text, mode = 'set', tab_id, frame_id }) {
           await sleep(10);
         }
         el.dispatchEvent(new Event('change', { bubbles: true }));
-        return { typed: true, tagName: tag, mode: 'keys' };
+        const afterKeys = String(getValue() ?? '');
+        return { typed: true, tagName: tag, mode: 'keys', value_after: afterKeys, mismatch: !afterKeys.endsWith(txt) };
       }
 
       setValue(txt);
       el.dispatchEvent(new Event('input', { bubbles: true }));
       el.dispatchEvent(new Event('change', { bubbles: true }));
-      return { typed: true, tagName: tag };
+      // Rilettura: un campo controllato che scarta il valore risponde
+      // «ok» uguale, e il modello non ha modo di saperlo senza questo.
+      const after = String(getValue() ?? '');
+      return { typed: true, tagName: tag, value_after: after, mismatch: after !== txt };
     },
     args: [selector, text, mode],
     world: 'MAIN',
@@ -911,6 +933,18 @@ async function cmdTypeText({ selector, text, mode = 'set', tab_id, frame_id }) {
   return results?.[0]?.result ?? { typed: true };
 }
 
+// Impronta per page_changed: pochi interi letti nell'ISOLATED world (nessuna
+// CSP di mezzo), prima e dopo un'azione. Vedi lib/page-fingerprint.js.
+async function cmdPageFingerprint({ tab_id, frame_id }) {
+  const tabId = await resolveTabId(tab_id);
+  const results = await chrome.scripting.executeScript({
+    target: scriptTarget(tabId, frame_id),
+    func: pageFingerprint,
+    args: [null],
+  });
+  return results?.[0]?.result ?? null;
+}
+
 async function cmdReadPage({ mode = 'text', tab_id, frame_id }) {
   const tabId = await resolveTabId(tab_id);
 
@@ -1164,12 +1198,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') {
@@ -1879,6 +1927,7 @@ async function cmdFillForm({ fields, submit_selector, tab_id, frame_id }) {
           const type = (el.type || '').toLowerCase();
           const disabled = el.disabled;
           const readOnly = el.readOnly;
+          let chosen = null;
 
           if (disabled || readOnly) {
             report.push({ selector, success: true, tagName: tag, type, warning: disabled ? 'disabled' : 'readonly' });
@@ -1891,6 +1940,7 @@ async function cmdFillForm({ fields, submit_selector, tab_id, frame_id }) {
             for (const opt of el.options) {
               if (opt.value === value || opt.textContent.trim() === value) {
                 el.value = opt.value;
+                chosen = opt.value;
                 found = true;
                 break;
               }
@@ -1916,7 +1966,17 @@ async function cmdFillForm({ fields, submit_selector, tab_id, frame_id }) {
           el.dispatchEvent(new Event('focus', { bubbles: true }));
           el.dispatchEvent(new Event('input', { bubbles: true }));
           el.dispatchEvent(new Event('change', { bubbles: true }));
-          report.push({ selector, success: true, tagName: tag, type: type || tag });
+          // Rilettura per campo: l'effetto, non l'azione
+          const entry = { selector, success: true, tagName: tag, type: type || tag };
+          if (tag === 'input' && (type === 'checkbox' || type === 'radio')) {
+            const want = value === 'true' || value === '1';
+            entry.checked_after = el.checked; entry.mismatch = el.checked !== want;
+          } else if (tag === 'select') {
+            entry.value_after = el.value; entry.mismatch = el.value !== chosen;
+          } else {
+            entry.value_after = String(el.value ?? ''); entry.mismatch = String(el.value ?? '') !== String(value);
+          }
+          report.push(entry);
         } catch (e) {
           report.push({ selector, success: false, error: e.message });
         }
@@ -2371,7 +2431,7 @@ async function cmdWatch({ action = 'add', name, selector, text, value_of, until,
 
 const handoffs = new Map(); // tabId → { id, resolve, timer, onNav }
 
-function handoffBanner(id, message, pick) {
+function handoffBanner(id, message, pick, ask, pickMax) {
   const old = document.getElementById('cb-handoff-host');
   if (old) old.remove();
   const host = document.createElement('div');
@@ -2383,11 +2443,27 @@ function handoffBanner(id, message, pick) {
     .bar b{color:#ffb454}.bar span{flex:1}
     button{font:inherit;padding:6px 14px;border:0;border-radius:6px;cursor:pointer;background:#ffb454;color:#1a1a1a;font-weight:600}
     button.sec{background:#444;color:#fff}
-  </style><div class="bar"><b>Claude</b><span></span>${pick ? '<button class="pick">Pick element</button>' : ''}<button class="done">Done</button><button class="sec cancel">Cancel</button></div>`;
+    input.ask{font:inherit;padding:6px 10px;border:0;border-radius:6px;min-width:220px;background:#fff;color:#1a1a1a}
+  </style><div class="bar"><b>Claude</b><span></span>${ask ? '<input class="ask" type="text" placeholder="Your reply">' : ''}${pick ? '<button class="pick">Pick element</button>' : ''}<button class="done">Done</button><button class="sec cancel">Cancel</button></div>`;
   root.querySelector('span').textContent = message;
   document.documentElement.appendChild(host);
-  const finish = (result) => { host.remove(); cleanupPick(); chrome.runtime.sendMessage({ type: 'cb_handoff_done', id, result }); };
-  root.querySelector('.done').onclick = () => finish({ done: true, action: 'done' });
+  // ask: la risposta scritta; pick_max: gli elementi indicati, con contorno
+  // finché il banner resta. Done chiude in entrambi i casi (Invio nella casella).
+  const picks = []; const marked = [];
+  const askInput = root.querySelector('input.ask');
+  const answerOf = () => (askInput ? askInput.value : undefined);
+  const finish = (result) => { host.remove(); cleanupPick(); for (const m of marked) m.style.outline = m.__cbOutline ?? ''; chrome.runtime.sendMessage({ type: 'cb_handoff_done', id, result }); };
+  const done = () => finish(picks.length
+    ? { done: true, action: 'picked', answer: answerOf(), picked: picks[0], picked_all: picks }
+    : { done: true, action: 'done', answer: answerOf() });
+  const addPick = (el, p) => {
+    picks.push(p);
+    if (!marked.includes(el)) { el.__cbOutline = el.style.outline; el.style.outline = '2px solid #ffb454'; marked.push(el); }
+    if (picks.length >= pickMax) { done(); return; }
+    root.querySelector('span').textContent = `${message} — ${picks.length}/${pickMax} picked, click more or Done`;
+  };
+  root.querySelector('.done').onclick = done;
+  if (askInput) { askInput.onkeydown = (e) => { if (e.key === 'Enter') done(); }; setTimeout(() => askInput.focus(), 0); }
   root.querySelector('.cancel').onclick = () => finish({ done: false, action: 'cancel' });
   let box = null; let onMove = null; let onClick = null;
   function cleanupPick() {
@@ -2415,7 +2491,7 @@ function handoffBanner(id, message, pick) {
   };
   const pickBtn = root.querySelector('.pick');
   if (pickBtn) pickBtn.onclick = () => {
-    root.querySelector('span').textContent = `${message} — now click the element`;
+    root.querySelector('span').textContent = `${message} — ${pickMax > 1 ? `click up to ${pickMax} elements, then Done` : 'now click the element'}`;
     box = document.createElement('div');
     box.style.cssText = 'position:fixed;pointer-events:none;z-index:2147483646;border:2px solid #ffb454;background:rgba(255,180,84,.15);transition:all .05s';
     document.documentElement.appendChild(box);
@@ -2435,7 +2511,7 @@ function handoffBanner(id, message, pick) {
       const isToggle = el.tagName === 'INPUT' && /^(checkbox|radio)$/.test(el.type);
       const label = (labelFor?.textContent || el.closest('label')?.textContent || el.getAttribute('aria-label') || '').trim().replace(/\s+/g, ' ');
       const text = (isToggle ? label || el.name : (el.innerText || el.value || el.getAttribute('aria-label') || label || '')).trim().replace(/\s+/g, ' ').slice(0, 80);
-      finish({ done: true, action: 'picked', picked: { selector: selectorOf(el), tag: el.tagName.toLowerCase(), text, rect: { x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height) } } });
+      addPick(el, { selector: selectorOf(el), tag: el.tagName.toLowerCase(), text, rect: { x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height) } });
     };
     document.addEventListener('mousemove', onMove, true);
     document.addEventListener('click', onClick, true);
@@ -2443,12 +2519,12 @@ function handoffBanner(id, message, pick) {
   return true;
 }
 
-async function cmdHandoff({ message, pick_element = false, timeout = 300000, tab_id }) {
+async function cmdHandoff({ message, pick_element = false, ask = false, pick_max = 1, timeout = 300000, tab_id }) {
   if (!message) throw new Error('Missing required parameter: message');
   const tabId = await resolveTabId(tab_id);
   if (handoffs.has(tabId)) throw new Error('A handoff is already waiting on this tab');
   const id = `h${Date.now()}`;
-  const inject = () => chrome.scripting.executeScript({ target: { tabId }, func: handoffBanner, args: [id, String(message), !!pick_element] });
+  const inject = () => chrome.scripting.executeScript({ target: { tabId }, func: handoffBanner, args: [id, String(message), !!pick_element, !!ask, Math.max(1, Number(pick_max) || 1)] });
   try { await inject(); } catch (err) { throw new Error(`Cannot show the handoff banner on this page (${err.message}) — chrome:// and store pages are not injectable`); }
   await chrome.tabs.update(tabId, { active: true }).catch(() => {});
   return await new Promise((resolve) => {
@@ -4508,9 +4584,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 ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "chrome-bridge-mcp",
   "mcpName": "io.github.frsorrentino/chrome-bridge",
-  "version": "1.16.1",
+  "version": "1.18.0",
   "type": "module",
   "description": "MCP server with 59 tools for browser automation via Chrome extension. Works on ChromeOS/Crostini.",
   "main": "server/index.js",
@@ -15,7 +15,8 @@
     "test:unit": "node --test test/unit/*.test.js",
     "test:e2e": "node test/test-devtools.js",
     "test:e2e:launch": "CHROME_BRIDGE_PORT=8799 node test/test-devtools.js --launch",
-    "measure": "node tools/measure-schema.mjs"
+    "measure": "node tools/measure-schema.mjs",
+    "bench:latency": "node bench/latency.mjs"
   },
   "keywords": [
     "mcp",

package/server/cli.js

@@ -22,6 +22,7 @@ import { consoleLines, networkLines, interactivesLines, linksLines } from './for
 import { runAssert } from './assertions.js';
 import { checkLinksBatch } from './link-checker.js';
 import { evaluateSecurityHeaders } from './security-headers.js';
+import { windowLayout } from './layouts.js';
 import { toHar } from './har.js';
 import { decodeTrackingRequests, trackingLines } from './trackers.js';
 import { parseRedirectCsv, checkRedirects, redirectLines } from './redirects.js';
@@ -36,7 +37,7 @@ const INTERNAL_TYPES = new Set([
 ]);
 
 // Comandi virtuali: logica lato CLI (come i corrispondenti tool MCP lato server)
-const VIRTUAL_COMMANDS = new Set(['status', 'check_links', 'security_headers', 'replay', 'assert', 'track', 'redirects', 'audit', 'export', 'evidence']);
+const VIRTUAL_COMMANDS = new Set(['status', 'window_layout', 'check_links', 'security_headers', 'replay', 'assert', 'track', 'redirects', 'audit', 'export', 'evidence']);
 
 const ALIASES = { tabs: 'get_tabs', js: 'execute_js', console: 'read_console', network: 'monitor_network', interactives: 'get_interactives' };
 
@@ -118,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));
           });
@@ -250,6 +254,10 @@ async function run(client, command, params, opts) {
     return JSON.stringify(await runAssert(client.sendCommand, params));
   }
   // Comandi virtuali
+  if (command === 'window_layout') {
+    if (!['save', 'restore', 'list', 'delete'].includes(params.action)) throw new Error('window_layout needs --action save|restore|list|delete (and --name for all but list)');
+    return JSON.stringify(await windowLayout(client.sendCommand, params));
+  }
   if (command === 'status') {
     const tabs = await client.sendCommand(MessageType.GET_TABS);
     return `server=ok extension=connected tabs=${Array.isArray(tabs) ? tabs.length : 0}`;

package/server/effect.js

@@ -0,0 +1,22 @@
+/**
+ * Delta fra due impronte di pagina (extension/lib/page-fingerprint.js), prima
+ * e dopo un'azione. Solo ciò che è cambiato, con segno: null quando la pagina
+ * è stabile, così page_changed costa zero byte nel caso comune. Un'impronta
+ * parziale (estensione vecchia: solo url/title) confronta solo i campi che ha.
+ */
+
+const COUNTS = ['nodes', 'text', 'open', 'expanded', 'checked', 'selected', 'dialogs'];
+
+export function fingerprintDelta(before, after) {
+  if (!before || !after) return null;
+  const d = {};
+  if (before.url !== undefined && after.url !== undefined && after.url !== before.url) d.url = after.url;
+  if (before.title !== undefined && after.title !== undefined && after.title !== before.title) d.title = after.title;
+  for (const k of COUNTS) {
+    if (typeof before[k] !== 'number' || typeof after[k] !== 'number') continue;
+    const diff = after[k] - before[k];
+    if (diff !== 0) d[k] = `${diff > 0 ? '+' : ''}${diff}`;
+  }
+  if (typeof before.focus === 'string' && typeof after.focus === 'string' && after.focus !== before.focus) d.focus = after.focus;
+  return Object.keys(d).length ? d : null;
+}

package/server/index.js

@@ -31,6 +31,15 @@ const PORT = process.env.CHROME_BRIDGE_PORT
 
 // Capability: default = solo set core (30 tool). --caps audits,visual o
 // CHROME_BRIDGE_CAPS attivano i gruppi opt-in; "all" registra tutto.
+// Interruttori di sicurezza (README, «Configuration and security»).
+function parseSecurity() {
+  const on = (v) => v != null && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
+  return {
+    noJs: process.argv.includes('--no-js') || on(process.env.CHROME_BRIDGE_NO_JS),
+    writeRoot: argValue('--write-root') ?? process.env.CHROME_BRIDGE_WRITE_ROOT ?? null,
+  };
+}
+
 function parseCaps() {
   const i = process.argv.indexOf('--caps');
   if (i !== -1 && process.argv[i + 1]) return process.argv[i + 1];
@@ -94,7 +103,7 @@ async function main() {
   }
 
   // 3. Registra i tool MCP (filtrati per capability)
-  session.tools = registerTools(mcpServer, wsManager, parseCaps());
+  session.tools = registerTools(mcpServer, wsManager, parseCaps(), parseSecurity());
 
   // 4. Avvia il trasporto stdio MCP
   const transport = new StdioServerTransport();

package/server/layouts.js

@@ -0,0 +1,134 @@
+/**
+ * window_layout: salvare e ripristinare disposizioni di finestre per nome.
+ *
+ * Una sola implementazione per il tool MCP (tools.js) e per la CLI (cli.js):
+ * prima viveva inline nel tool e la CLI non la conosceva, e `claude-master
+ * layout save` usciva con «Unknown command: window_layout».
+ *
+ * Tutto lato server, componendo GET_TABS(include_windows) e VIEWPORT_RESIZE:
+ * nessun comando nuovo verso l'estensione. Gli id delle finestre non
+ * sopravvivono al riavvio del browser: il ripristino riconosce le finestre
+ * dagli URL delle loro schede (miglior sovrapposizione, a parità di tipo).
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { MessageType } from './protocol.js';
+
+export const LAYOUTS_FILE = process.env.CHROME_BRIDGE_LAYOUTS_FILE
+  || join(homedir(), '.config', 'chrome-bridge', 'layouts.json');
+
+/**
+ * @param {(type: string, params?: object) => Promise<any>} send  invio di un comando all'estensione
+ * @param {{ action: 'save'|'restore'|'list'|'delete', name?: string }} p
+ * @returns {Promise<object>} dati puri (il tool MCP li serializza, la CLI li stampa)
+ */
+export async function windowLayout(send, { action, name }) {
+  const readLayouts = async () => {
+    try { return JSON.parse(await readFile(LAYOUTS_FILE, 'utf8')); } catch { return {}; }
+  };
+
+  if (action === 'list') {
+    const all = await readLayouts();
+    const rows = Object.entries(all).map(([n, l]) => ({ name: n, windows: l.windows.length, savedAt: l.savedAt }));
+    return { layouts: rows };
+  }
+
+  if (!name || !/^[\w-]+$/.test(name)) throw new Error('name is required and must match [\\w-]+');
+
+  if (action === 'delete') {
+    const all = await readLayouts();
+    const existed = Boolean(all[name]);
+    delete all[name];
+    await mkdir(dirname(LAYOUTS_FILE), { recursive: true });
+    await writeFile(LAYOUTS_FILE, JSON.stringify(all, null, 2));
+    return { deleted: name, existed };
+  }
+
+  // save e restore hanno bisogno della fotografia corrente
+  const snap = await send(MessageType.GET_TABS, { include_windows: true });
+  if (Array.isArray(snap) || !snap?.windows) {
+    // Un'estensione < 1.14.0 risponde con il solo array di schede: meglio
+    // dirlo che fallire su una proprietà mancante.
+    throw new Error('window_layout needs extension >= 1.14.0: get_tabs returned no window geometry');
+  }
+  const urlsByWindow = new Map();
+  for (const t of snap.tabs || []) {
+    if (!urlsByWindow.has(t.windowId)) urlsByWindow.set(t.windowId, []);
+    urlsByWindow.get(t.windowId).push(t.url || '');
+  }
+
+  if (action === 'save') {
+    const all = await readLayouts();
+    all[name] = {
+      savedAt: new Date().toISOString(),
+      windows: snap.windows.map((w) => ({
+        type: w.type,
+        state: w.state,
+        left: w.left, top: w.top, width: w.width, height: w.height,
+        tabs: urlsByWindow.get(w.id) || [],
+      })),
+    };
+    await mkdir(dirname(LAYOUTS_FILE), { recursive: true });
+    await writeFile(LAYOUTS_FILE, JSON.stringify(all, null, 2));
+    return { saved: name, windows: all[name].windows.length };
+  }
+
+  // restore
+  const all = await readLayouts();
+  const layout = all[name];
+  if (!layout) {
+    throw new Error(`Layout "${name}" not found — saved: ${Object.keys(all).join(', ') || 'none'}`);
+  }
+
+  // Matching: sovrapposizione degli URL (Jaccard), a parità di tipo. Greedy
+  // sulla coppia migliore. Gli id non entrano mai: non sopravvivono al
+  // riavvio del browser.
+  const current = snap.windows.map((w) => ({ ...w, urls: new Set(urlsByWindow.get(w.id) || []) }));
+  const pairs = [];
+  layout.windows.forEach((savedWin, si) => {
+    current.forEach((cur, ci) => {
+      if (savedWin.type !== cur.type) return;
+      const savedUrls = new Set(savedWin.tabs);
+      let shared = 0;
+      for (const u of savedUrls) if (cur.urls.has(u)) shared += 1;
+      const union = new Set([...savedUrls, ...cur.urls]).size || 1;
+      const score = shared / union;
+      if (score > 0) pairs.push({ si, ci, score });
+    });
+  });
+  pairs.sort((a, b) => b.score - a.score);
+
+  const usedSaved = new Set();
+  const usedCurrent = new Set();
+  const results = [];
+  for (const { si, ci, score } of pairs) {
+    if (usedSaved.has(si) || usedCurrent.has(ci)) continue;
+    usedSaved.add(si); usedCurrent.add(ci);
+    const savedWin = layout.windows[si];
+    const cur = current[ci];
+    const anyTab = (snap.tabs || []).find((t) => t.windowId === cur.id);
+    if (!anyTab) { results.push({ window_id: cur.id, error: 'no tab to address the window with' }); continue; }
+    // Una finestra da massimizzare riceve SOLO lo stato: i bounds verrebbero
+    // accettati e ignorati, e il confronto richiesto/ottenuto mentirebbe.
+    const params = savedWin.state === 'normal'
+      ? { tab_id: anyTab.id, left: savedWin.left, top: savedWin.top, width: savedWin.width, height: savedWin.height, state: 'normal' }
+      : { tab_id: anyTab.id, state: savedWin.state };
+    try {
+      const r = await send(MessageType.VIEWPORT_RESIZE, params);
+      results.push({ window_id: cur.id, score: Number(score.toFixed(2)), requested: params, window: r?.window ?? r?.actual ?? null });
+    } catch (e) {
+      results.push({ window_id: cur.id, score: Number(score.toFixed(2)), error: e.message });
+    }
+  }
+
+  const unmatchedSaved = layout.windows.filter((_, i) => !usedSaved.has(i)).length;
+  const unmatchedCurrent = current.filter((_, i) => !usedCurrent.has(i)).map((w) => w.id);
+  return {
+    restored: name,
+    matched: results.length,
+    unmatched_saved: unmatchedSaved,
+    unmatched_current: unmatchedCurrent,
+    results,
+  };
+}

package/server/protocol.js

@@ -71,6 +71,7 @@ export const MessageType = Object.freeze({
   DISMISS_OVERLAYS:      'dismiss_overlays',
   KEYBOARD_WALK:         'keyboard_walk',
   HANDOFF:               'handoff',
+  PAGE_FINGERPRINT:      'page_fingerprint',
   WATCH:                 'watch',
   OBSERVE:               'observe',
   READ_FORM:             'read_form',
@@ -91,7 +92,7 @@ export const MessageType = Object.freeze({
 });
 
 // Versione
-export const VERSION               = '1.16.1';
+export const VERSION               = '1.18.0';
 
 // Configurazione
 export const DEFAULT_PORT          = 8765;

package/server/tools.js

@@ -7,7 +7,7 @@
 
 import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { basename, dirname, extname, join } from 'node:path';
+import { basename, dirname, extname, join, resolve, sep } from 'node:path';
 import { parse as parseHtml } from 'node-html-parser';
 import { z } from 'zod';
 import { runAssert } from './assertions.js';
@@ -21,17 +21,25 @@ import { runAudit, summarizeAudit, auditReport, AUDIT_KINDS, DEFAULT_KINDS } fro
 import { toPlaywrightTest } from './playwright-export.js';
 import { createResolver } from './sourcemaps.js';
 import { evaluateSecurityHeaders } from './security-headers.js';
+import { windowLayout } from './layouts.js';
+import { fingerprintDelta } from './effect.js';
 import { consoleLines, networkLines, interactivesLines, linksLines } from './formatters.js';
 
 const SESSIONS_DIR = join(homedir(), '.config', 'chrome-bridge', 'sessions');
 // Sovrascrivibile nei test: i layout sono un file solo, non una directory.
-const LAYOUTS_FILE = process.env.CHROME_BRIDGE_LAYOUTS_FILE
-  || join(homedir(), '.config', 'chrome-bridge', 'layouts.json');
 const RECORDINGS_DIR = process.env.CHROME_BRIDGE_RECORD_DIR || join(homedir(), '.config', 'chrome-bridge', 'recordings');
 const FIXTURES_DIR = process.env.CHROME_BRIDGE_FIXTURES_DIR || join(homedir(), '.config', 'chrome-bridge', 'fixtures');
 
 // Comandi rumore per un replay: letture interne (tabSnapshot) o senza effetto
-const RECORD_EXCLUDE = new Set([MessageType.GET_TABS]);
+const RECORD_EXCLUDE = new Set([MessageType.GET_TABS, MessageType.PAGE_FINGERPRINT]);
+
+// CHROME_BRIDGE_NO_JS: i tool che eseguono codice arbitrario nella pagina.
+// inject_css non c'è: il CSS non esegue niente. wait_for(condition=function)
+// e le URL javascript:/data: sono rifiutate nel handler, non qui.
+const JS_TOOLS = new Set(['execute_js', 'modify_dom']);
+// Sotto CHROME_BRIDGE_WRITE_ROOT lo stato del server resta scrivibile: non è un
+// percorso scelto dal modello.
+const STATE_DIRS = [join(homedir(), '.config', 'chrome-bridge'), SESSIONS_DIR, RECORDINGS_DIR, FIXTURES_DIR];
 
 // `hint` è il parametro REALE del tool chiamante che riduce i dati. Suggerire
 // max_length quando 56 tool su 59 non lo espongono mandava il modello a
@@ -105,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]) => {
@@ -328,6 +364,7 @@ export const TOOL_ANNOTATIONS = {
  * @param {import('@modelcontextprotocol/sdk/server/index.js').McpServer} server - MCP Server
  * @param {import('./ws-manager.js').WSManager} wsManager - WebSocket manager
  * @param {string} [caps='all'] - 'all', 'core', o lista di gruppi "audits,visual"
+ * @param {{noJs?: boolean, writeRoot?: string|null}} [options] - CHROME_BRIDGE_NO_JS / CHROME_BRIDGE_WRITE_ROOT
  */
 /** Procedura leggibile da un'osservazione: un passo per riga, i campi sensibili marcati come passo umano. */
 function observedProcedure(name, d) {
@@ -345,8 +382,20 @@ function observedProcedure(name, d) {
   return lines.join('\n') + '\n';
 }
 
-export function registerTools(server, wsManager, caps = 'all') {
+export function registerTools(server, wsManager, caps = 'all', options = {}) {
   const startedAt = Date.now();
+  const noJs = Boolean(options.noJs);
+  const WRITE_ROOT = options.writeRoot ? resolve(String(options.writeRoot)) : null;
+  // Rifiuta PRIMA del comando all'estensione: niente screenshot fatto per un
+  // file che non verrà scritto. Il percorso torna com'è, così i chiamanti
+  // possono usarlo inline.
+  const guardWrite = (p) => {
+    if (!WRITE_ROOT || p == null) return p;
+    const abs = resolve(String(p));
+    const inside = (root) => abs === root || abs.startsWith(root + sep);
+    if (inside(WRITE_ROOT) || STATE_DIRS.some((d) => inside(resolve(d)))) return p;
+    throw new Error(`Refusing to write ${abs}: outside CHROME_BRIDGE_WRITE_ROOT (${WRITE_ROOT})`);
+  };
   const activeCaps = caps === 'all'
     ? ['core', ...Object.keys(TOOL_CAPS)]
     : ['core', ...String(caps).split(',').map((s) => s.trim()).filter((s) => s && s !== 'core')];
@@ -362,6 +411,7 @@ export function registerTools(server, wsManager, caps = 'all') {
       : null;
     server = {
       tool(name, desc, schema, handler) {
+        if (noJs && JS_TOOLS.has(name)) return;
         if (enabled) {
           const group = TOOL_TO_CAP.get(name);
           if (group && !enabled.has(group) && !enabled.has('all')) return;
@@ -438,8 +488,15 @@ export function registerTools(server, wsManager, caps = 'all') {
     throw new Error('Either selector or ref is required');
   }
 
-  // Snapshot url/title del tab target, per il delta post-azione.
+  // Impronta della pagina per il delta post-azione (page_changed): DOM in
+  // pochi interi più url/title. Un'estensione vecchia o una pagina non
+  // iniettabile (chrome://) tornano a url/title da get_tabs: nessun errore,
+  // solo meno dettaglio.
   async function tabSnapshot(tab_id) {
+    try {
+      const fp = await send(MessageType.PAGE_FINGERPRINT, { tab_id });
+      if (fp && typeof fp === 'object') return fp;
+    } catch { /* fallback sotto */ }
     try {
       const tabs = await send(MessageType.GET_TABS);
       const list = Array.isArray(tabs) ? tabs : [];
@@ -449,16 +506,11 @@ export function registerTools(server, wsManager, caps = 'all') {
     } catch { return null; }
   }
 
-  // Delta compatto dopo un'azione: presente solo se url/title sono cambiati.
-  // Costa pochi token quando scatta, zero quando la pagina è stabile, e
-  // risparmia al client un giro di ispezione per capire "cosa è successo".
-  function pageDelta(before, after) {
-    if (!before || !after) return null;
-    const delta = {};
-    if (after.url !== before.url) delta.url = after.url;
-    if (after.title !== before.title) delta.title = after.title;
-    return Object.keys(delta).length ? delta : null;
-  }
+  // Delta compatto dopo un'azione: solo ciò che è cambiato (url, title, conteggi
+  // DOM con segno, fuoco). Costa pochi token quando scatta, zero quando la
+  // pagina è stabile, e risparmia al client lo screenshot per capire "cosa è
+  // successo".
+  const pageDelta = fingerprintDelta;
 
   // Anteprima compatta dei primi interactives (con ref), allegata a navigate:
   // il client può agire subito senza un giro di discovery. Cappata e best-effort.
@@ -493,6 +545,8 @@ export function registerTools(server, wsManager, caps = 'all') {
             extension_version: wsManager.extVersion ?? null,
             // Un agente che non trova accessibility_audit non aveva modo di
             // scoprire che esiste ma è in un gruppo disattivato.
+            js_evaluation: !noJs,
+            write_root: WRITE_ROOT,
             caps_active: activeCaps,
             caps_available: ['core', ...Object.keys(TOOL_CAPS)],
             session_tab_id: sessionTabId,
@@ -508,21 +562,38 @@ export function registerTools(server, wsManager, caps = 'all') {
   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 }) }] };
     }
   );
 
@@ -535,6 +606,9 @@ export function registerTools(server, wsManager, caps = 'all') {
       tab_id: tabId,
     },
     async ({ url, tab_id }) => {
+      if (noJs && /^\s*(javascript|data|vbscript):/i.test(url)) {
+        throw new Error(`Refusing to navigate to ${url.slice(0, 40)}: JavaScript evaluation is disabled (CHROME_BRIDGE_NO_JS)`);
+      }
       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;
@@ -560,6 +634,7 @@ export function registerTools(server, wsManager, caps = 'all') {
       presets: z.array(z.enum(['mobile', 'tablet', 'desktop'])).optional().describe('One capture per preset, window restored; save_to = directory, one file each'),
     },
     async ({ tab_id, save_to, presets }) => {
+      guardWrite(save_to);
       // Matrice responsive: viewport_resize + screenshot per preset erano 2N
       // turni; qui è una chiamata, e la finestra torna com'era.
       if (presets?.length) {
@@ -615,21 +690,25 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- 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) }] };
     }
   );
 
@@ -637,7 +716,8 @@ export function registerTools(server, wsManager, caps = 'all') {
   server.tool(
     'click',
     'Click an element by CSS selector or by a ref (n1, n2…) from get_interactives or navigate. A real pointer sequence: it can submit, '
-      + 'open a dialog or navigate — use wait_after. Not idempotent; a native confirm() blocks the bridge: handle_dialogs first.',
+      + 'open a dialog or navigate — use wait_after. Not idempotent; a native confirm() blocks the bridge: handle_dialogs first. '
+      + 'Returns page_changed (url, title and DOM deltas: nodes, text, open, expanded, checked, dialogs, focus): the effect, without a screenshot.',
     {
       selector: z.string().optional().describe('CSS selector; ">>>" pierces shadow DOM. Ignored when ref is given'),
       ref:      z.string().optional().describe('From get_interactives, e.g. "n3"'),
@@ -654,6 +734,9 @@ export function registerTools(server, wsManager, caps = 'all') {
       const data = await send(MessageType.CLICK, { selector: target, force, button: button ?? 'left', count: count ?? 1, frame_id, tab_id });
       // Niente attesa se il click non è andato a buon fine (es. elemento occluso)
       const waited = data?.occluded ? null : await applyWaitAfter(send, wait_after, tab_id);
+      // Senza wait_after un breve settle: i framework aggiornano il DOM dopo il
+      // click, non dentro; senza, l'impronta "dopo" vedrebbe quella "prima".
+      if (!data?.occluded && (wait_after ?? 'none') === 'none') await new Promise((r) => setTimeout(r, 150));
       const changed = data?.occluded ? null : pageDelta(before, await tabSnapshot(tab_id));
       const out = { ...data, ...(waited && { wait_after: waited }), ...(changed && { page_changed: changed }) };
       return {
@@ -670,7 +753,8 @@ export function registerTools(server, wsManager, caps = 'all') {
     'type_text',
     'Put text into an input, textarea or contenteditable, by selector or ref. Replaces the whole value through the '
       + 'native setter (React/Vue controlled inputs register it) and fires input and change. mode=keys emits '
-      + 'keydown/input/keyup per character for autocomplete and masked fields: slower, use it only when mode=set leaves the field empty.',
+      + 'keydown/input/keyup per character for autocomplete and masked fields: slower, use it only when mode=set leaves the field empty. '
+      + 'Returns value_after; mismatch=true means the field did not keep the value: retry with mode=keys.',
     {
       selector: z.string().optional().describe('CSS selector; ">>>" pierces shadow DOM. Ignored when ref is given'),
       ref:      z.string().optional().describe('From get_interactives, e.g. "n3"'),
@@ -685,10 +769,13 @@ export function registerTools(server, wsManager, caps = 'all') {
       const data = await send(MessageType.TYPE_TEXT, { selector: target, text, mode, tab_id, frame_id });
       const waited = await applyWaitAfter(send, wait_after, tab_id);
       const out = waited ? { ...data, wait_after: waited } : data;
+      const warn = data?.mismatch
+        ? `\nthe field did not keep the value (value_after=${JSON.stringify(data.value_after ?? null)}): retry with mode=keys; if it still differs, the page rewrites it`
+        : '';
       return {
         content: [{
           type: 'text',
-          text: jsonText(out),
+          text: jsonText(out) + warn,
         }],
       };
     }
@@ -708,6 +795,7 @@ export function registerTools(server, wsManager, caps = 'all') {
       save_to:    saveToField('the page'),
     },
     async ({ mode, tab_id, frame_id, max_length, save_to }) => {
+      guardWrite(save_to);
       const data = await send(MessageType.READ_PAGE, { mode, tab_id, frame_id });
       const text = typeof data === 'string' ? data : JSON.stringify(data);
       if (save_to) return savedSummary(save_to, Buffer.from(text, 'utf8'), { mode: mode ?? 'text' });
@@ -963,6 +1051,7 @@ export function registerTools(server, wsManager, caps = 'all') {
           text, selector, timeout: timeout ?? 10000, interval: interval ?? 200, tab_id, frame_id,
         });
       } else if (condition === 'function') {
+        if (noJs) throw new Error('wait_for condition=function evaluates JavaScript, which is disabled (CHROME_BRIDGE_NO_JS): use condition=element or text');
         data = await send(MessageType.WAIT_FOR_FUNCTION, {
           expression, timeout: timeout ?? 10000, polling_ms: interval ?? 100, tab_id, frame_id,
         });
@@ -1039,7 +1128,8 @@ export function registerTools(server, wsManager, caps = 'all') {
   server.tool(
     'fill_form',
     'Batch fill form fields with React-compatible events. Handles input, select, checkbox, radio, and textarea. '
-    + 'With submit_selector it also submits, so a repeated call submits twice — not safe to retry blindly.',
+    + 'With submit_selector it also submits, so a repeated call submits twice — not safe to retry blindly. '
+    + 'Each field reports value_after and mismatch; page_changed carries the DOM delta.',
     {
       fields: z.array(z.object({
         selector: z.string(),
@@ -1056,10 +1146,14 @@ export function registerTools(server, wsManager, caps = 'all') {
       const waited = await applyWaitAfter(send, wait_after, tab_id);
       const changed = pageDelta(before, await tabSnapshot(tab_id));
       const out = { ...data, ...(waited && { wait_after: waited }), ...(changed && { page_changed: changed }) };
+      // I campi che non hanno tenuto il valore in testa, in chiaro: sono la
+      // riga che il modello deve leggere prima del JSON.
+      const mism = (data?.fields ?? []).filter((f) => f && f.mismatch);
+      const head = mism.length ? mism.map((f) => `mismatch: ${f.selector} (${'checked_after' in f ? `checked_after=${f.checked_after}` : `value_after=${JSON.stringify(f.value_after ?? null)}`})`).join('\n') + '\n' : '';
       return {
         content: [{
           type: 'text',
-          text: jsonText(out),
+          text: head + jsonText(out),
         }],
       };
     }
@@ -1322,6 +1416,7 @@ export function registerTools(server, wsManager, caps = 'all') {
         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) }] };
@@ -1615,18 +1710,25 @@ export function registerTools(server, wsManager, caps = 'all') {
     'handoff',
     'Hand the browser to the user for what only a person can do — 2FA, CAPTCHA, login, a choice — and wait: a banner in the page shows your '
       + 'message with Done/Cancel, the call returns on click or timeout, redirects included. pick_element: the user clicks an element and you get '
-      + 'its selector. Never type credentials yourself.',
+      + 'its selector. Never type credentials yourself. ask: the user types a reply in the banner ("which of the three?") and you get it as answer. '
+      + 'pick_max: with pick_element, up to N elements; the user presses Done when finished.',
     {
       message: z.string().describe('What the user should do, one line'),
       pick_element: z.boolean().optional().default(false).describe('Ask the user to click an element; returns its selector, text and box'),
+      ask: z.boolean().optional().default(false).describe('Show a text box in the banner; the reply comes back as answer'),
+      pick_max: z.number().optional().default(1).describe('With pick_element: up to N elements, the user presses Done when finished'),
       timeout: z.number().optional().default(300000).describe('ms to wait for the click, default 5 min'),
       tab_id: tabId,
     },
-    async ({ message, pick_element, timeout, tab_id }) => {
-      const d = await send(MessageType.HANDOFF, { message, pick_element, timeout, tab_id });
+    async ({ message, pick_element, ask, pick_max, timeout, tab_id }) => {
+      const d = await send(MessageType.HANDOFF, { message, pick_element, ask, pick_max, timeout, tab_id });
       const lines = [`handoff ${d.action}${d.url ? ` url=${d.url}` : ''}`];
-      if (d.picked) {
-        lines.push(`picked ${d.picked.selector}\t${d.picked.tag}\t${d.picked.text}\t@${d.picked.rect.x},${d.picked.rect.y} ${d.picked.rect.width}x${d.picked.rect.height}`);
+      if (ask && typeof d.answer === 'string' && d.answer.trim()) lines.push(`answer: ${d.answer.trim()}`);
+      const fmt = (p) => `${p.selector}\t${p.tag}\t${p.text}\t@${p.rect.x},${p.rect.y} ${p.rect.width}x${p.rect.height}`;
+      if (Array.isArray(d.picked_all) && d.picked_all.length) {
+        d.picked_all.forEach((p, i) => lines.push(`picked ${i + 1}/${d.picked_all.length} ${fmt(p)}`));
+      } else if (d.picked) {
+        lines.push(`picked ${fmt(d.picked)}`);
       }
       if (d.action === 'timeout') lines.push('the user did not click within the timeout: ask before retrying');
       return { content: [{ type: 'text', text: lines.join('\n') }] };
@@ -1697,6 +1799,7 @@ export function registerTools(server, wsManager, caps = 'all') {
       tab_id: tabId,
     },
     async ({ kinds, save_to, scope, max_links, tab_id }) => {
+      guardWrite(save_to);
       const info = await send(MessageType.GET_PAGE_INFO, { tab_id });
       const results = await runAudit(send, { kinds, scope, max_links, tab_id });
       const summary = summarizeAudit(results);
@@ -1866,6 +1969,7 @@ export function registerTools(server, wsManager, caps = 'all') {
       tab_id: tabId,
     },
     async ({ output_path, tab_id }) => {
+      guardWrite(output_path);
       const data = await send(MessageType.SAVE_PAGE, { tab_id });
       await writeFile(output_path, Buffer.from(data.mhtml_b64, 'base64'));
       return { content: [{ type: 'text', text: jsonText({ saved: output_path, size: data.size }) }] };
@@ -1887,6 +1991,7 @@ export function registerTools(server, wsManager, caps = 'all') {
       max_length: z.number().optional().default(DEFAULT_MAX_OUTPUT).describe('Max chars of body returned inline'),
     },
     async ({ url, method, headers, body, save_to, max_length }) => {
+      guardWrite(save_to);
       const data = await send(MessageType.HTTP_REQUEST, { url, method, headers, body, binary: Boolean(save_to) });
 
       if (save_to) {
@@ -1988,120 +2093,7 @@ export function registerTools(server, wsManager, caps = 'all') {
       action: z.enum(['save', 'restore', 'list', 'delete']).describe('save snapshots every window; restore repositions the recognised ones'),
       name: z.string().optional().describe('Layout name, required except for list'),
     },
-    async ({ action, name }) => {
-      const readLayouts = async () => {
-        try { return JSON.parse(await readFile(LAYOUTS_FILE, 'utf8')); } catch { return {}; }
-      };
-
-      if (action === 'list') {
-        const all = await readLayouts();
-        const rows = Object.entries(all).map(([n, l]) => ({ name: n, windows: l.windows.length, savedAt: l.savedAt }));
-        return { content: [{ type: 'text', text: jsonText({ layouts: rows }) }] };
-      }
-
-      if (!name || !/^[\w-]+$/.test(name)) throw new Error('name is required and must match [\\w-]+');
-
-      if (action === 'delete') {
-        const all = await readLayouts();
-        const existed = Boolean(all[name]);
-        delete all[name];
-        await mkdir(dirname(LAYOUTS_FILE), { recursive: true });
-        await writeFile(LAYOUTS_FILE, JSON.stringify(all, null, 2));
-        return { content: [{ type: 'text', text: jsonText({ deleted: name, existed }) }] };
-      }
-
-      // save e restore hanno bisogno della fotografia corrente
-      const snap = await send(MessageType.GET_TABS, { include_windows: true });
-      if (Array.isArray(snap) || !snap?.windows) {
-        // Un'estensione < 1.14.0 risponde con il solo array di schede: meglio
-        // dirlo che fallire su una proprietà mancante.
-        throw new Error('window_layout needs extension >= 1.14.0: get_tabs returned no window geometry');
-      }
-      const urlsByWindow = new Map();
-      for (const t of snap.tabs || []) {
-        if (!urlsByWindow.has(t.windowId)) urlsByWindow.set(t.windowId, []);
-        urlsByWindow.get(t.windowId).push(t.url || '');
-      }
-
-      if (action === 'save') {
-        const all = await readLayouts();
-        all[name] = {
-          savedAt: new Date().toISOString(),
-          windows: snap.windows.map((w) => ({
-            type: w.type,
-            state: w.state,
-            left: w.left, top: w.top, width: w.width, height: w.height,
-            tabs: urlsByWindow.get(w.id) || [],
-          })),
-        };
-        await mkdir(dirname(LAYOUTS_FILE), { recursive: true });
-        await writeFile(LAYOUTS_FILE, JSON.stringify(all, null, 2));
-        return { content: [{ type: 'text', text: jsonText({ saved: name, windows: all[name].windows.length }) }] };
-      }
-
-      // restore
-      const all = await readLayouts();
-      const layout = all[name];
-      if (!layout) {
-        throw new Error(`Layout "${name}" not found — saved: ${Object.keys(all).join(', ') || 'none'}`);
-      }
-
-      // Matching: sovrapposizione degli URL (Jaccard), a parità di tipo. Greedy
-      // sulla coppia migliore. Gli id non entrano mai: non sopravvivono al
-      // riavvio del browser.
-      const current = snap.windows.map((w) => ({ ...w, urls: new Set(urlsByWindow.get(w.id) || []) }));
-      const pairs = [];
-      layout.windows.forEach((savedWin, si) => {
-        current.forEach((cur, ci) => {
-          if (savedWin.type !== cur.type) return;
-          const savedUrls = new Set(savedWin.tabs);
-          let shared = 0;
-          for (const u of savedUrls) if (cur.urls.has(u)) shared += 1;
-          const union = new Set([...savedUrls, ...cur.urls]).size || 1;
-          const score = shared / union;
-          if (score > 0) pairs.push({ si, ci, score });
-        });
-      });
-      pairs.sort((a, b) => b.score - a.score);
-
-      const usedSaved = new Set();
-      const usedCurrent = new Set();
-      const results = [];
-      for (const { si, ci, score } of pairs) {
-        if (usedSaved.has(si) || usedCurrent.has(ci)) continue;
-        usedSaved.add(si); usedCurrent.add(ci);
-        const savedWin = layout.windows[si];
-        const cur = current[ci];
-        const anyTab = (snap.tabs || []).find((t) => t.windowId === cur.id);
-        if (!anyTab) { results.push({ window_id: cur.id, error: 'no tab to address the window with' }); continue; }
-        // Una finestra da massimizzare riceve SOLO lo stato: i bounds verrebbero
-        // accettati e ignorati, e il confronto richiesto/ottenuto mentirebbe.
-        const params = savedWin.state === 'normal'
-          ? { tab_id: anyTab.id, left: savedWin.left, top: savedWin.top, width: savedWin.width, height: savedWin.height, state: 'normal' }
-          : { tab_id: anyTab.id, state: savedWin.state };
-        try {
-          const r = await send(MessageType.VIEWPORT_RESIZE, params);
-          results.push({ window_id: cur.id, score: Number(score.toFixed(2)), requested: params, window: r?.window ?? r?.actual ?? null });
-        } catch (e) {
-          results.push({ window_id: cur.id, score: Number(score.toFixed(2)), error: e.message });
-        }
-      }
-
-      const unmatchedSaved = layout.windows.filter((_, i) => !usedSaved.has(i)).length;
-      const unmatchedCurrent = current.filter((_, i) => !usedCurrent.has(i)).map((w) => w.id);
-      return {
-        content: [{
-          type: 'text',
-          text: jsonText({
-            restored: name,
-            matched: results.length,
-            unmatched_saved: unmatchedSaved,
-            unmatched_current: unmatchedCurrent,
-            results,
-          }),
-        }],
-      };
-    }
+    async ({ action, name }) => ({ content: [{ type: 'text', text: jsonText(await windowLayout(send, { action, name })) }] })
   );
 
   // --- http_auth ---
@@ -2246,6 +2238,7 @@ export function registerTools(server, wsManager, caps = 'all') {
       save_to: saveToField('the records as JSON'),
     },
     async ({ item_selector, fields, max_items, format, tab_id, max_length , save_to }) => {
+      guardWrite(save_to);
       max_length = max_length ?? DEFAULT_MAX_OUTPUT;
       const html = await send(MessageType.READ_PAGE, { mode: 'html', tab_id });
       if (typeof html !== 'string') throw new Error('Could not read page HTML');
@@ -2314,6 +2307,8 @@ export function registerTools(server, wsManager, caps = 'all') {
       tab_id: tabId,
     },
     async ({ action, name, save_to, values, tab_id }) => {
+      guardWrite(save_to);
+      if (name && name.endsWith('.jsonl')) guardWrite(name);
       // "Guarda come faccio": la procedura la esegue l'umano nel suo browser,
       // noi la trascriviamo — mai i valori dei campi sensibili — nello stesso
       // jsonl che replay esegue, più un .md leggibile con i passi umani marcati.