chrome-bridge-mcp 1.14.0 → 1.15.1

package/README.md

@@ -1,12 +1,12 @@
 # Chrome Bridge
 
-![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-brightgreen) ![Chrome 135+](https://img.shields.io/badge/chrome-%E2%89%A5135-blue) ![Tests](https://img.shields.io/badge/tests-174%20unit%20%2B%20e2e-brightgreen) [![Chrome Web Store](https://img.shields.io/badge/web%20store-published-blue)](https://chromewebstore.google.com/detail/chrome-bridge-for-claude/bioknpaeahidbelaljjohjofiloeodmb)
+![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-brightgreen) ![Chrome 135+](https://img.shields.io/badge/chrome-%E2%89%A5135-blue) ![Tests](https://img.shields.io/badge/tests-187%20unit%20%2B%20e2e-brightgreen) [![Chrome Web Store](https://img.shields.io/badge/web%20store-published-blue)](https://chromewebstore.google.com/detail/chrome-bridge-for-claude/bioknpaeahidbelaljjohjofiloeodmb)
 
 **An MCP server that gives Claude Code your real, logged-in Chrome — measured
 2.75× fewer turns and 2.28× lower cost than the official "Claude in Chrome"
 extension on a form-filling task, with ~3× the toolset and no paid plan.**
 
-62 web-development tools (navigation, DOM inspection, visual regression, audits,
+63 web-development tools (navigation, DOM inspection, visual regression, audits,
 network mocking) over a local WebSocket bridge, plus a headless instance for CI.
 Self-hosted, local-only.
 
@@ -43,7 +43,7 @@ Chrome Bridge → Details (on Chrome 135-137, enable Developer Mode instead).
 | | Chrome Bridge | Claude in Chrome | Chrome DevTools MCP | Playwright MCP |
 |---|---|---|---|---|
 | **ChromeOS / Crostini** | **Yes** (real host) | No | Container only | Container only |
-| **Tools** | **62** (33 core) | ~20 | ~50 | 23 core (71 total) |
+| **Tools** | **63** (34 core) | ~20 | ~50 | 23 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 |
@@ -87,7 +87,7 @@ user-script toggle isn't available.
 
 ## Tools
 
-62 in total, in seven groups. Only `core` (33 tools) loads by default; the rest
+63 in total, in seven groups. Only `core` (34 tools) loads by default; the rest
 are opt-in via `--caps`.
 
 | Group | N | What's in it |
@@ -153,7 +153,7 @@ paste into a chat.
 
 ## Documentation
 
-- [docs/TOOLS.md](docs/TOOLS.md) — all 62 tools, by group
+- [docs/TOOLS.md](docs/TOOLS.md) — all 63 tools, by group
 - [docs/EFFICIENCY.md](docs/EFFICIENCY.md) — the benchmark and the design behind it
 - [bench/RESULTS.md](bench/RESULTS.md) — raw runs and inclusion rule
 - [CHANGELOG.md](CHANGELOG.md)

package/extension/lib/download-state.js

@@ -0,0 +1,43 @@
+/**
+ * Legge lo stato reale di un download.
+ *
+ * `chrome.downloads.download()` restituisce un id e basta: dire "started: true"
+ * e fermarsi lì è come fidarsi di un HTTP 200 senza guardare il corpo. Su
+ * ChromeOS, con l'impostazione «Chiedi dove salvare ogni file» attiva, Chrome
+ * ignora `saveAs: false` e apre il selettore: il file viene scaricato per intero
+ * ma non viene scritto da nessuna parte finché un umano non sceglie.
+ *
+ * La firma di quella condizione è precisa e verificata dal vivo:
+ * `state: 'in_progress'`, `filename: ''`, `bytesReceived === totalBytes`.
+ * Senza distinguerla, un agente aspetta un file che non arriverà mai da solo.
+ */
+export function classifyDownload(item) {
+  if (!item) return { state: 'unknown', done: false, reason: 'download not found' };
+
+  const { state, filename, bytesReceived = 0, totalBytes = 0, error } = item;
+
+  if (state === 'complete') return { state: 'complete', done: true, filename };
+  if (state === 'interrupted') {
+    return { state: 'interrupted', done: true, error: error || 'interrupted', filename };
+  }
+
+  // Nessuna destinazione decisa: il selettore è aperto e aspetta una persona.
+  if (!filename) {
+    const fetched = totalBytes > 0 && bytesReceived >= totalBytes;
+    return {
+      state: 'waiting_for_user',
+      done: false,
+      bytes: { received: bytesReceived, total: totalBytes },
+      reason: fetched
+        ? 'bytes fetched, but Chrome is asking where to save — the "Ask where to save each file" setting overrides saveAs:false'
+        : 'no destination chosen yet — Chrome is showing the save dialog',
+    };
+  }
+
+  return {
+    state: 'in_progress',
+    done: false,
+    filename,
+    bytes: { received: bytesReceived, total: totalBytes },
+  };
+}

package/extension/manifest.json

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

package/extension/service-worker.js

@@ -8,6 +8,7 @@
 import './telemetry.js';
 import { buildMarkdown } from './lib/page-markdown.js';
 import { computeTiles } from './lib/tile-layout.js';
+import { classifyDownload } from './lib/download-state.js';
 const { pushError } = globalThis.__cbTelemetry;
 
 const DEFAULT_PORT = 8765;
@@ -941,7 +942,24 @@ async function cmdReadPage({ mode = 'text', tab_id, frame_id }) {
 
 // --- create_tab ---
 
-async function cmdCreateTab({ url, active = true }) {
+async function cmdCreateTab({ url, active = true, new_window = false, left, top, width, height }) {
+  if (new_window) {
+    // windows.create con i bounds apre direttamente sul monitor scelto: left è
+    // la coordinata sulla scrivania virtuale, quindi è ciò che sceglie lo schermo.
+    const winOpts = { focused: active !== false };
+    if (url) winOpts.url = url;
+    for (const [k, v] of [['left', left], ['top', top], ['width', width], ['height', height]]) {
+      if (typeof v === 'number') winOpts[k] = v;
+    }
+    const win = await chrome.windows.create(winOpts);
+    const tab = (win.tabs || [])[0];
+    if (url && tab) {
+      await waitForComplete(tab.id);
+      const updated = await chrome.tabs.get(tab.id);
+      return { id: updated.id, url: updated.url, title: updated.title, window_id: win.id };
+    }
+    return { id: tab?.id, url: tab?.url || 'chrome://newtab', title: tab?.title || '', window_id: win.id };
+  }
   const opts = { active };
   if (url) opts.url = url;
   const tab = await chrome.tabs.create(opts);
@@ -1075,11 +1093,36 @@ async function cmdTileWindows({ window_ids, reference_window_id, layout = 'grid'
   };
 }
 
-async function cmdMoveTab({ tab_id, window_id, index = -1 }) {
+async function cmdMoveTab({ tab_id, window_id, new_window = false, window_type, left, top, width, height, index = -1 }) {
   if (typeof tab_id !== 'number') throw new Error('Missing required parameter: tab_id');
-  if (typeof window_id !== 'number') throw new Error('Missing required parameter: window_id');
+  if (typeof window_id !== 'number' && !new_window) throw new Error('Provide window_id or new_window: true');
 
   const before = await chrome.tabs.get(tab_id);
+
+  if (new_window) {
+    // tabs.move vuole una finestra che esiste già; per estrarre in una finestra
+    // nuova (e posizionata) l'unica via è windows.create({tabId}). windows.create
+    // conosce solo normal e popup: le finestre app sono della SWA, non nostre —
+    // popup è il massimo di "finestra terminale" ottenibile da un'estensione.
+    const winOpts = { tabId: tab_id };
+    if (window_type === 'popup') winOpts.type = 'popup';
+    for (const [k, v] of [['left', left], ['top', top], ['width', width], ['height', height]]) {
+      if (typeof v === 'number') winOpts[k] = v;
+    }
+    const win = await chrome.windows.create(winOpts);
+    return {
+      moved: tab_id,
+      url: before.url,
+      from_window: before.windowId,
+      to_window: win.id,
+      // Il tipo lo dice Chrome, non la richiesta: se popup viene declassato a
+      // normal il chiamante deve vederlo da qui.
+      window_type: win.type,
+      new_window: true,
+      index: 0,
+      same_window: before.windowId === win.id,
+    };
+  }
   const moved = await chrome.tabs.move(tab_id, { windowId: window_id, index });
   const tab = Array.isArray(moved) ? moved[0] : moved;
 
@@ -1103,6 +1146,21 @@ async function cmdTabAction({ action, tab_id, bypass_cache = false }) {
     await chrome.tabs.remove(tabId);
     return { action, closed: tabId };
   }
+  if (action === 'discard') {
+    // La scheda resta nella barra e si ricarica al focus: il processo muore, la
+    // RAM torna. La tmux session dietro un terminale non c'entra: vive nel
+    // container, non nel renderer.
+    const t = await chrome.tabs.discard(tabId);
+    return { action, tabId: t?.id ?? tabId, discarded: true };
+  }
+  if (action === 'mute' || action === 'unmute') {
+    await chrome.tabs.update(tabId, { muted: action === 'mute' });
+    return { action, tabId, muted: action === 'mute' };
+  }
+  if (action === 'duplicate') {
+    const d = await chrome.tabs.duplicate(tabId);
+    return { action, source: tabId, duplicated: d.id, window_id: d.windowId };
+  }
   if (action === 'activate') {
     const tab = await chrome.tabs.get(tabId);
     await chrome.tabs.update(tabId, { active: true });
@@ -1859,7 +1917,7 @@ async function cmdViewportResize({ preset, width, height, left, top, state, read
     if (Object.keys(updateOpts).length === 0) {
       if (state) {
         const w = await chrome.windows.get(tab.windowId);
-        return { requested: { state }, actual: { left: w.left, top: w.top, width: w.width, height: w.height, state: w.state } };
+        return { requested: { state }, window: { left: w.left, top: w.top, width: w.width, height: w.height, state: w.state } };
       }
       throw new Error('Provide preset, width, height, left, top or state');
     }
@@ -1869,24 +1927,40 @@ async function cmdViewportResize({ preset, width, height, left, top, state, read
     await new Promise((r) => setTimeout(r, 200));
   }
 
-  const results = await chrome.scripting.executeScript({
-    target: { tabId },
-    func: () => ({
-      viewportWidth: window.innerWidth,
-      viewportHeight: window.innerHeight,
-      devicePixelRatio: window.devicePixelRatio,
-    }),
-    world: 'MAIN',
-  });
-  const actual = results?.[0]?.result ?? {};
-  if (read_only) return { actual };
-  const win = await chrome.windows.get(tab.windowId);
+  // La misura del viewport passa da un'injection, e `chrome://` e
+  // `chrome-untrusted://` la rifiutano: le finestre del Terminale e di
+  // media-app sono esattamente quelle. Prima questo errore veniva propagato e
+  // il tool falliva DOPO aver spostato la finestra — l'azione riuscita
+  // riportata come guasto, che è il modo di far ritentare chi chiama qualcosa
+  // che è già successo. La geometria della finestra non richiede injection:
+  // arriva da chrome.windows.get e c'è sempre.
+  let actual = {};
+  let viewport_error = null;
+  try {
+    const results = await chrome.scripting.executeScript({
+      target: { tabId },
+      func: () => ({
+        viewportWidth: window.innerWidth,
+        viewportHeight: window.innerHeight,
+        devicePixelRatio: window.devicePixelRatio,
+      }),
+      world: 'MAIN',
+    });
+    actual = results?.[0]?.result ?? {};
+  } catch (e) {
+    viewport_error = e.message;
+  }
+  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 };
+  const win = winNow;
   return {
     requested: { width: targetW, height: targetH, preset: preset || null, left, top, state },
     actual,
+    viewport_error,
     // Il window manager può accettare e ignorare: senza il confronto una
     // finestra rimasta ferma passerebbe per spostata.
-    window: { left: win.left, top: win.top, width: win.width, height: win.height, state: win.state },
+    window: geometry,
   };
 }
 
@@ -3626,9 +3700,25 @@ async function cmdSetGeolocation({ latitude, longitude, accuracy = 10, reset = f
 
 // --- manage_downloads ---
 
-async function cmdManageDownloads({ action, timeout = 30000, limit = 10 }) {
+async function cmdManageDownloads({ action, url, filename, timeout = 30000, limit = 10 }) {
   if (!action) throw new Error('Missing required parameter: action');
 
+  if (action === 'download') {
+    if (!url) throw new Error('action=download requires url');
+    // Parte dal browser, quindi con i cookie di sessione dell'origine: un file
+    // dietro login si scarica senza far passare i byte dal bridge.
+    const opts = { url, saveAs: false };
+    if (filename) opts.filename = filename;
+    const id = await chrome.downloads.download(opts);
+    // Non basta l'id: su ChromeOS l'impostazione «Chiedi dove salvare ogni file»
+    // scavalca saveAs:false e apre il selettore, quindi il download resta fermo
+    // ad aspettare una persona. Una breve occhiata allo stato reale distingue
+    // "partito" da "in attesa di te".
+    await new Promise((r) => setTimeout(r, 600));
+    const [item] = await chrome.downloads.search({ id });
+    return { id, url, ...classifyDownload(item) };
+  }
+
   if (action === 'list') {
     const items = await chrome.downloads.search({ orderBy: ['-startTime'], limit });
     return {

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "chrome-bridge-mcp",
   "mcpName": "io.github.frsorrentino/chrome-bridge",
-  "version": "1.14.0",
+  "version": "1.15.1",
   "type": "module",
-  "description": "MCP server with 62 tools for browser automation via Chrome extension. Works on ChromeOS/Crostini.",
+  "description": "MCP server with 63 tools for browser automation via Chrome extension. Works on ChromeOS/Crostini.",
   "main": "server/index.js",
   "bin": {
     "chrome-bridge-mcp": "server/index.js",

package/server/protocol.js

@@ -84,7 +84,7 @@ export const MessageType = Object.freeze({
 });
 
 // Versione
-export const VERSION               = '1.14.0';
+export const VERSION               = '1.15.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, extname, join } from 'node:path';
+import { basename, dirname, extname, join } from 'node:path';
 import { parse as parseHtml } from 'node-html-parser';
 import { z } from 'zod';
 import { runAssert } from './assertions.js';
@@ -19,6 +19,9 @@ import { evaluateSecurityHeaders } from './security-headers.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');
 
 // Comandi rumore per un replay: letture interne (tabSnapshot) o senza effetto
@@ -291,6 +294,7 @@ export const TOOL_ANNOTATIONS = {
   create_tab: rw({ open: true }),
   move_tab: rw({ idempotent: true }),   // rispostare dove è già = stesso esito
   tile_windows: rw({ idempotent: true }),
+  window_layout: rw({ destructive: true, idempotent: true }),  // save sovrascrive l'omonimo, restore sposta finestre
   navigate: rw({ idempotent: true, open: true }),
   tab_action: rw({ destructive: true, open: true }),  // close chiude una tab dell'utente
 
@@ -876,9 +880,14 @@ export function registerTools(server, wsManager, caps = 'all') {
     {
       url: z.string().optional().describe('URL to open (default: new tab page)'),
       active: z.boolean().optional().default(true).describe('false opens the tab in the background, leaving the current one focused'),
+      new_window: z.boolean().optional().default(false).describe('Open in a fresh window instead of a tab; with left/top it lands on the chosen monitor'),
+      left: z.number().optional().describe('Window x on the virtual desktop (new_window)'),
+      top: z.number().optional().describe('Window y (new_window)'),
+      width: z.number().optional().describe('Window width px (new_window)'),
+      height: z.number().optional().describe('Window height px (new_window)'),
     },
-    async ({ url, active }) => {
-      const data = await send(MessageType.CREATE_TAB, { url, active });
+    async ({ url, active, new_window, left, top, width, height }) => {
+      const data = await send(MessageType.CREATE_TAB, { url, active, new_window: new_window === true || undefined, left, top, width, height });
       if (data?.id != null) sessionTabId = data.id;
       return {
         content: [{
@@ -1340,9 +1349,12 @@ export function registerTools(server, wsManager, caps = 'all') {
     'tab_action',
     'Tab lifecycle: close, activate (focus), reload (optional cache bypass), back, forward. close discards the '
       + 'tab and anything unsaved in it, and cannot be undone — it may be a tab the user is working in. '
-      + 'reload and navigation drop injected CSS, emulations and page hooks.',
+      + 'reload and navigation drop injected CSS, emulations and page hooks. duplicate works where create_tab is '
+      + 'forbidden (chrome-untrusted://, verified on a ChromeOS Terminal tab) and lands in the source tab\'s own '
+      + 'window, app windows included — the only way to open a new Terminal session inside the Terminal window. '
+      + 'discard replaces the tab id: the result carries the new one, saved ids go stale.',
     {
-      action: z.enum(['close', 'activate', 'reload', 'back', 'forward']).describe('close cannot be undone; reload drops injected CSS and page hooks'),
+      action: z.enum(['close', 'activate', 'reload', 'back', 'forward', 'discard', 'mute', 'unmute', 'duplicate']).describe('close cannot be undone; discard frees memory, the tab reloads on focus; reload drops injected CSS and hooks'),
       bypass_cache: z.boolean().optional().default(false).describe('reload only'),
       tab_id: tabId,
     },
@@ -1657,14 +1669,20 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- manage_downloads ---
   server.tool(
     'manage_downloads',
-    'List downloads or wait for one to complete. Files land in the browser Downloads folder, not on the server.',
+    'List downloads, start one, or wait for the newest to finish. Files land in the browser Downloads folder, '
+      + 'not on the server. action=download reports the download\'s real state rather than just an id: with '
+      + 'Chrome set to ask where to save each file, saveAs:false is overridden and it comes back as '
+      + 'waiting_for_user — every byte fetched, no destination chosen, and nothing will move until someone picks one.',
     {
-      action: z.enum(['list', 'wait_for_complete']).describe('wait_for_complete blocks until the newest download finishes or times out'),
+      action: z.enum(['list', 'wait_for_complete', 'download']).describe('download fetches with the browser cookie jar and reports the real state; wait_for_complete blocks until the newest finishes'),
+      url: z.string().optional().describe('What to download (action=download); sent with the session cookies of its origin'),
+      filename: z.string().optional().describe('Relative path inside the Downloads folder (action=download)'),
       timeout: z.number().optional().default(30000).describe('Max ms (wait_for_complete)'),
       limit: z.number().optional().default(10).describe('Max download entries returned, newest first'),
     },
-    async ({ action, timeout, limit }) => {
-      const data = await send(MessageType.MANAGE_DOWNLOADS, { action, timeout, limit });
+    async ({ action, url, filename, timeout, limit }) => {
+      if (action === 'download' && !url) throw new Error('action=download requires url');
+      const data = await send(MessageType.MANAGE_DOWNLOADS, { action, url, filename, timeout, limit });
       return { content: [{ type: 'text', text: jsonText(data) }] };
     }
   );
@@ -1745,17 +1763,30 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- move_tab ---
   server.tool(
     'move_tab',
-    'Move an existing tab into another window (chrome.tabs.move), e.g. to consolidate windows that were '
-      + 'each opened separately. Does not create or close anything: the tab keeps its id, its history and its '
-      + 'page state. Both windows must be normal browser windows — Chrome refuses to move a tab into a popup or '
-      + 'an app window, and the refusal is reported verbatim rather than retried.',
+    'Move an existing tab into another window (chrome.tabs.move). Nothing is created or closed: the tab keeps '
+      + 'its id, history and page state, and this works even on chrome-untrusted:// tabs where creating one is '
+      + 'forbidden — verified on a ChromeOS Terminal tab. The **destination** must be a normal window: moving out '
+      + 'of an app or popup window is fine, moving into one is refused with "Tabs can only be moved to and from '
+      + 'normal windows". So a ChromeOS Terminal session can be pulled out to its own window (new_window, then '
+      + 'position it with viewport_resize) but cannot be merged back into the Terminal window — the closest look '
+      + 'is window_type popup: no tab strip, no omnibox, visually a terminal window. An extension cannot create '
+      + 'app windows: normal and popup are all Chrome offers.',
     {
       tab_id: z.number().describe('Tab to move; get it from get_tabs'),
-      window_id: z.number().describe('Destination window; get_tabs reports windowId for every tab'),
+      window_id: z.number().optional().describe('Destination window; get_tabs reports windowId for every tab'),
+      new_window: z.boolean().optional().default(false).describe('Extract the tab into a fresh window instead — tabs.move needs an existing window, this does not'),
+      window_type: z.enum(['normal', 'popup']).optional().default('normal').describe('new_window only: popup has no tab strip and no omnibox — the terminal-window look for detached chrome-untrusted://terminal tabs'),
+      left: z.number().optional().describe('New window x (new_window)'),
+      top: z.number().optional().describe('New window y (new_window)'),
+      width: z.number().optional().describe('New window width px (new_window)'),
+      height: z.number().optional().describe('New window height px (new_window)'),
       index: z.number().optional().default(-1).describe('Position in the destination window; -1 appends at the end'),
     },
-    async ({ tab_id, window_id, index }) => {
-      const data = await send(MessageType.MOVE_TAB, { tab_id, window_id, index: index ?? -1 });
+    async ({ tab_id, window_id, new_window, window_type, left, top, width, height, index }) => {
+      if (window_id == null && new_window !== true) {
+        throw new Error('Provide window_id (an existing window) or new_window: true');
+      }
+      const data = await send(MessageType.MOVE_TAB, { tab_id, window_id, new_window: new_window === true || undefined, window_type, left, top, width, height, index: index ?? -1 });
       return { content: [{ type: 'text', text: jsonText(data) }] };
     }
   );
@@ -1786,6 +1817,133 @@ export function registerTools(server, wsManager, caps = 'all') {
     }
   );
 
+  // --- window_layout ---
+  server.tool(
+    'window_layout',
+    'Save the current window arrangement under a name, restore one, list or delete saved ones. save overwrites '
+      + 'a same-named layout without asking. Window ids do not survive a browser restart, so restore recognises '
+      + 'windows by the overlap of their tab URLs (same type required) and repositions the best match — windows '
+      + 'it cannot recognise are reported, not guessed. Needs extension >= 1.14.0 for window geometry.',
+    {
+      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,
+          }),
+        }],
+      };
+    }
+  );
+
   // --- set_zoom ---
   server.tool(
     'set_zoom',